Documentation

Customer Search

Elevate, May 20-22-2025, Miami Beach, Florida

Search across a large number of Customers in a Project using a high-performance, ID-first API.

  • After completing this page, you should be able to:

    • Activate Customer Search in your Project
    • Create search queries and use the Customer Search API to find specific Customers

    • Time to complete page: 10 minutes

    You’re likely aware that the Merchant Center allows you to efficiently search for customers. But what if you want to build your own back-office application with similar flexibility? Good news—you can! The Customer Search API enables you to locate specific customer IDs using query expressions, much like the Product Search feature covered in the previous chapter. This ID-first approach ensures fast and efficient results.

    Just like Product Search, Customer Search needs to be activated for your Project. This can be done directly in the Merchant Center (by navigating to Customers ➜ Customer list ➜ Index my Customers now) or by submitting an update request to your Project endpoint:

    Activate Customer Search endpoint
    // Ensure all necessary imports are included and the API client is instantiated as demonstrated in the first example.

System.out.println(
  "Customer Search status: " +
  apiRoot
    .post(
      ProjectUpdateBuilder
        .of()
        .version(project.getVersion())
        .actions(
          ProjectChangeCustomerSearchStatusActionBuilder
            .of()
            .status(CustomerSearchStatus.ACTIVATED)
            .build()
        )
        .build()
    )
    .executeBlocking()
    .getBody()
    .getSearchIndexing()
    .getCustomers()
    .getStatus()
);
apiRoot.close();

    Once activated, give it a few minutes to index the Customer data. You can check the progress of indexing by going to the Customer list in the Merchant Center or by sending a request to the API itself:

    Check indexing progress
    // Ensure all necessary imports are included and the API client is instantiated as demonstrated in the first example.

System.out.println(
  "Customer Search indexing status: " +
  apiRoot
    .customers()
    .searchIndexingStatus()
    .get()
    .executeBlocking()
    .getBody()
    .getStatus()
);
apiRoot.close();

    Response:

    Customer Search indexing status: Indexing

    Once the status says Ready we can proceed with creating our first CustomerSearchRequest. The query syntax is very similar to Product Search, we can use the same expressions as well as compound them. Let us look for all customers whose first name starts with “Seba” and they have either “Street” or “Road” in one of their addresses:

    Create a Customer Search Request
    // Ensure all necessary imports are included and the API client is instantiated as demonstrated in the first example.

// Build search request
var searchRequest = CustomerSearchRequestBuilder
  .of()
  .query(
    SearchAndExpressionBuilder
      .of()
      .and(
        SearchPrefixExpressionBuilder
          .of()
          .prefix(
            SearchAnyValueBuilder.of().value("Seba").field("firstName").build()
          )
          .build()
      )
      .plusAnd(
        SearchOrExpressionBuilder
          .of()
          .or(
            SearchWildCardExpressionBuilder
              .of()
              .wildcard(
                SearchAnyValueBuilder
                  .of()
                  .value("*Street*")
                  .field("addresses.all")
                  .build()
              )
              .build()
          )
          .plusOr(
            SearchWildCardExpressionBuilder
              .of()
              .wildcard(
                SearchAnyValueBuilder
                  .of()
                  .value("*Road*")
                  .field("addresses.all")
                  .build()
              )
              .build()
          )
          .build()
      )
      .build()
  )
  .build();

// Perform Customer search
CustomerPagedSearchResponse searchResponse = apiRoot
  .customers()
  .search()
  .post(searchRequest)
  .executeBlocking()
  .getBody();

// Close API client
apiRoot.close();

System.out.println("Found Customers:");
// Print all product names in English
searchResponse
  .getResults()
  .forEach(customer -> {
    System.out.println(
      "Customer ID: " +
      customer.getId() +
      " Relevance: " +
      customer.getRelevance()
    );
  });

    Result:

    Found Customers:
Customer ID: 10e90725-13a9-430a-b3f5-6e116c0dabef Relevance: 2.0
Customer ID: a1e5d426-9c47-4881-a482-cb150fc032b2 Relevance: 2.0

    The result reinforces the point made earlier in this chapter about the ID-first nature of the Customer Search API. It only provides the ID of each found Customer along with the relevance score, indicating how close each Customer matches the search query. This means that if you want to see more details about found Customers, you have to fetch each Customer by their ID.

    Test your knowledge