Customer Search
The Customer Search API allows merchants to search across a large number of Customers within a Project, supporting back-office use cases.
Customer Search is available only in the Google Cloud and AWS Regions.
The Customer Search API is designed to be ID-first. This means that to provide the best performance, only Customer IDs are returned. You can then use local caches or a Get Customer by ID request to fetch the entire Customer resource. The intended use case for this API is to manage a large number of customers by a back-office application. It is not intended for searching through customer data in a storefront application.
Activation of the API
The Customer Search API is not active for the Project by default. If the API is deactivated for your Project, the Search Customers endpoint returns a 404 Not Found error.
To activate the API for your Projects, please choose one of the following options:
- using the Change Customer Search Status update action on the Project API.
- using the Merchant Center by navigating to Customers > Customer List.
Automatic deactivation
The Customer Search API is automatically deactivated for a Project if there have been no calls to the Search Customers endpoint in the last 30 days. The API can be reactivated again using any of the options listed in Activation of the API.
Representations
CustomerSearchRequest
query | The Customer search query. |
sort Array of SearchSorting | Controls how results to your query are sorted. If not provided, the results are sorted by relevance in descending order. |
limit Int | The maximum number of search results to be returned. Default:20 Maximum: 100 |
offset Int | The number of search results to be skipped in the response for pagination. Default:0 Maximum: 9 900 |
{"query": {"fullText": {"field": "all","value": "john"}}}
CustomerPagedSearchResponse
total Int | Total number of results matching the query. |
limit Int | Number of results requested. Maximum:100 |
offset Int | Number of elements skipped. Maximum:9 900 |
results Array of CustomerSearchResult | Search result containing the Customers matching the search query. |
{"results": [{"id": "e41337a0-ea96-4ddc-a9a4-d267976f21e0","relevance": 0.9264881},{"id": "05cd5998-015c-4232-8943-ff8a1880bcbc","relevance": 0.6989829},{"id": "09c3c5a2-6569-49dd-b021-af5de4cf4b02","relevance": 0.6989829}],"limit": 100,"offset": 0,"total": 3}
CustomerSearchResult
id String |
|
relevance Float | How closely this customer matches the search query. |
CustomerSearchIndexingStatusResponse
status | Current status of indexing the Customer Search. |
states | Progress of indexing. Only available when indexing is in progress. |
startedAt | Date and time (UTC) when the last indexing started. |
retryCount Int | Indicates how many times the system tried to start indexing after failed attempts. The counter is set to null after an indexing finished successfully. |
lastModifiedAt | Time when the status was last modified. |
{"status": "Indexing","states": {"indexed": 43242,"failed": 0,"estimatedTotal": 100000},"startedAt": "2023-08-15T12:56:07.89Z","retryCount": 2,"lastModifiedAt": "2023-08-15T12:56:07.89Z"}
CustomerIndexingProgress
indexed Int | The number of Customers successfully indexed. |
failed Int | The number of Customers that failed to be indexed. |
estimatedTotal Int | The estimated total number of Customers to be indexed. |
CustomerIndexingStatus
The current indexing status of Customer Search.
Scheduled
Indexing is scheduled.
Indexing
Indexing is in progress.
Ready
Indexing is complete and the Search Customers endpoint returns up-to-date results.
Failed
Indexing failed due to an internal error.
Search Customers
If this endpoint responds with 404 Not Found error, the feature has been deactivated due to inactivity and must be reactivated before API requests will succeed.
Use the Get Customer Search indexing status endpoint to check the indexing progress and its status. Alternatively, use the Check if Customer Search index exists endpoint to see if there is an index available.
view_customers:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
application/json
application/json
{"results": [{"id": "e41337a0-ea96-4ddc-a9a4-d267976f21e0","relevance": 0.9264881},{"id": "05cd5998-015c-4232-8943-ff8a1880bcbc","relevance": 0.6989829},{"id": "09c3c5a2-6569-49dd-b021-af5de4cf4b02","relevance": 0.6989829}],"limit": 100,"offset": 0,"total": 3}
Get indexing status
This endpoint returns the indexing status of the Customer Search. It can be used to view the progress of the indexing process which has to be complete before you can use the Search Customers endpoint.
view_project_settings:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/customers/search/indexing-status -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
{"status": "Indexing","states": {"indexed": 43242,"failed": 0,"estimatedTotal": 100000},"startedAt": "2023-08-15T12:56:07.89Z","retryCount": 2,"lastModifiedAt": "2023-08-15T12:56:07.89Z"}
Check if Customer Search index exists
Checks whether a search index for the Project's Customers exists.
Returns a 200 OK
status if the index exists or 404 Not Found
otherwise.
view_customers:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
The search index exists and the Search Customers endpoint is fully operational.
curl --head https://api.{region}.commercetools.com/{projectKey}/customers/search -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
Searchable Customer fields
The following list contains the Customer fields that are supported in query expressions for a CustomerSearchRequest.
Number and date fields
Use the following fields in exact, exists, and range query expressions. Data type indicates the type of field for the field.
Standard field | Data type | Query for |
---|---|---|
dateOfBirth | date | Customers with a certain date of birth. |
createdAt | datetime | Customers created at a certain date and time. |
lastModifiedAt | dateTime | Customers last modified at any of its fields at a certain date and time. |
version | long | Customers with a certain version of the resource. |
Example:
Find Customers signed up in December 2023:
{"query": {"range": {"field": "createdAt","gte": "2023-12-01T00:00:00.000Z","lt": "2024-01-01T00:00:00.000Z"}}}
Text fields
Use the following text type fields in exact, fullText, prefix, wildcard, and exists query expressions.
Standard field | Query for |
---|---|
addresses.all | Customers with a certain string in the combination of all Address fields. |
addresses.city | Customers with a certain string in the city field of all the Customer's addresses. |
addresses.company | Customers with a certain string in the company field of all the Customer's addresses. |
addresses.country | Customers with a certain string in the country field of all the Customer's addresses. |
addresses.firstName | Customers with a certain string in the firstName field of all the Customer's addresses. |
addresses.lastName | Customers with a certain string in the lastName field of all the Customer's addresses. |
addresses.mobile | Customers with a certain string in the mobile field of all the Customer's addresses. |
addresses.phone | Customers with a certain string in the phone field of all the Customer's addresses. |
addresses.postalCode | Customers with a certain string in the postalCode field of all the Customer's addresses. |
all | Customers with a certain string in any of the Customer's fields. Does not support wildcard queries. |
companyName | Customers working for a certain company. |
email | Customers with a certain email address. |
firstName | Customers with a certain first name. |
lastName | Customers with a certain last name. |
middleName | Customers with a certain middle name. |
fullName | Customers with a certain string in their full name as a combination of firstName , middleName , and lastName fields. |
Examples:
Find Customers with the first name of John (case insensitive):
{"query": {"fullText": {"field": "firstName","value": "john"}}}
Find Customers mentioning "example" in any field. This query will not only find "example" in fields like companyName
, but also in email
addresses like email@example.com.
{"query": {"fullText": {"field": "all","value": "example"}}}
Keyword fields
Use the following keyword type fields, containing unique IDs or keys, in exact, prefix, wildcard, and exists query expressions. To query for multiple values of the same field or for several fields in the same request, combine the query expressions with a compound expression.
Standard field | Query for |
---|---|
id | a Customer with a specific id . |
key | a Customer with a specific key . |
customerNumber | a Customer with a specific customerNumber . |
externalId | a Customer with a specific externalId . |
vatId | a Customer with a specific vatId . |
customerGroup.id | Customers with a specific CustomerGroup identified by its id . |
stores.key | Customers of a specific Store identified by its key . |
Example:
Find Customers associated with one of the specified Stores:
{"query": {"or": [{"exact": {"field": "stores.key","value": "store1"}},{"exact": {"field": "stores.key","value": "store2"}},{"exact": {"field": "stores.key","value": "store3"}}]}}
Custom Fields
In addition to the standard fields on a Customer, you can also search for its Custom Fields, if any. custom.<field-name>
queries for Customers with a Custom Field of a specific name, and the SearchFieldType determines the data type of the field.
The ltext
SearchFieldType is not supported.
To query enum
and lenum
SearchFieldTypes, use the key
of the enum value.
Example: An exact query to find Customers with an enum type Custom Field accountPlan
to the enum key of silver
.
{"query": {"exact": {"field": "custom.accountPlan.key","value": "silver","fieldType": "enum"}}}