Customer Search

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": {
    "fullText": {
      "field": "all",
      "value": "john"
    }
  }
}

CustomerPagedSearchResponse

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

CustomerSearchIndexingStatusResponse

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

CustomerIndexingStatus

Search Customers

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

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

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.

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.

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.

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.

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