Customer Search

Customer Search enables merchants to search across a large number of Customers in a Project, supporting back-office use cases.

The Customer Search API is designed to be ID-first—returning only Customer IDs—to provide the best performance. To fetch a Customer, use local caches or the Get a Customer by ID endpoint.

In addition to the Merchant Center, the feature also lets you search for Customers in other back-office applications. It is not intended for searching through customers in a storefront.

Customer Search is deactivated for a Project, by default.

To activate, use the Change Customer Search status update action on the Project API or index the Customers in the Merchant Center (by navigating to Customers > Customer list).

If no calls have been made to the Search Customers endpoint in the last 30 days, the feature is automatically deactivated for a Project and must be reactivated.

Representations

CustomerSearchRequest

CustomerPagedSearchResponse -CustomerSearchResult

CustomerSearchIndexingStatusResponse -CustomerIndexingProgress -CustomerIndexingStatus

CustomerSearchRequest

`query` SearchQuery	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`

Example: json

{
  "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.

Example: 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
}

CustomerSearchResult

`id` String	`id` of the Customer matching the search query.
`relevance` Float	How closely this customer matches the search query.

CustomerSearchIndexingStatusResponse

`status` CustomerIndexingStatus	Current status of indexing the Customer Search.
`states` CustomerIndexingProgress	Progress of indexing. Only available when indexing is in progress.
`startedAt` DateTime	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` DateTime	Time when the status was last modified.

Example: json

{
  "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

To check if an index is available, use the Check if Customer Search index exists endpoint. To check the indexing progress and status, use the Get indexing status endpoint.

POST

https://api.{region}.commercetools.com/{projectKey}/customers/search

A SearchNotReady error is returned if the indexing is in progress or the feature is deactivated. If deactivated, you can reactivate it.

OAuth 2.0 Scopes:

view_customers:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Request Body:CustomerSearchRequestasapplication/json

Response:

200CustomerPagedSearchResponseasapplication/json

200 Response Example: CustomerPagedSearchResponsejson

{
  "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

GET

https://api.{region}.commercetools.com/{projectKey}/customers/search/indexing-status

Returns the indexing status of the Customer Search for a Project.

OAuth 2.0 Scopes:

view_project_settings:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Response:

200CustomerSearchIndexingStatusResponseasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/customers/search/indexing-status -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: CustomerSearchIndexingStatusResponsejson

{
  "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

HEAD

https://api.{region}.commercetools.com/{projectKey}/customers/search

Checks whether a search index of Customers exists for a Project. If an index exists, a 200 OK is returned; otherwise, a 409 Conflict.

OAuth 2.0 Scopes:

view_customers:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Response:

200

A search index exists and the Search Customers endpoint is fully operational.

Request Example:cURL

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:

Requestjson

{
  "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):

Requestjson

{
  "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.

Requestjson

{
  "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:

Requestjson

{
  "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.

Requestjson

{
  "query": {
    "exact": {
      "field": "custom.accountPlan.key",
      "value": "silver",
      "fieldType": "enum"
    }
  }
}