Business Unit Search

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

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

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

Business Unit Search is deactivated for a Project, by default.

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

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

Representations

BusinessUnitSearchRequest

BusinessUnitPagedSearchResponse -BusinessUnitSearchResult

BusinessUnitSearchIndexingStatusResponse -BusinessUnitIndexingProgress -BusinessUnitIndexingStatus

BusinessUnitSearchRequest

`query` SearchQuery	The Business Unit 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": "plumbing"
    }
  }
}

BusinessUnitPagedSearchResponse

`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 BusinessUnitSearchResult	Search result containing the Business Units 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
}

BusinessUnitSearchResult

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

BusinessUnitSearchIndexingStatusResponse

`status` BusinessUnitIndexingStatus	Current status of indexing the Business Unit Search.
`states` BusinessUnitIndexingProgress	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"
}

BusinessUnitIndexingProgress

`indexed` Int	The number of Business Units successfully indexed.
`failed` Int	The number of Business Units that failed to be indexed.
`estimatedTotal` Int	The estimated total number of Business Units to be indexed.

BusinessUnitIndexingStatus

The current indexing status of Business Unit Search.

Scheduled: Indexing is scheduled.
Indexing: Indexing is in progress.
Ready: Indexing is complete and the Search Business Units endpoint returns up-to-date results.
Failed: Indexing failed due to an internal error.

Search Business Units

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

POST

https://api.{region}.commercetools.com/{projectKey}/business-units/search

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

OAuth 2.0 Scopes:

view_business_units:{projectKey}

Path parameters:

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

Request Body:BusinessUnitSearchRequestasapplication/json

Response:

200BusinessUnitPagedSearchResponseasapplication/json

200 Response Example: BusinessUnitPagedSearchResponsejson

{
  "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}/business-units/search/indexing-status

Returns the indexing status of the Business Unit 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:

200BusinessUnitSearchIndexingStatusResponseasapplication/json

Request Example:cURL

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

200 Response Example: BusinessUnitSearchIndexingStatusResponsejson

{
  "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 Business Unit Search index exists

HEAD

https://api.{region}.commercetools.com/{projectKey}/business-units/search

Checks whether a search index of Business Units exists for a Project. Returns a 200 OK if an index exists; otherwise, returns a 409 Conflict.

OAuth 2.0 Scopes:

view_business_units:{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 Business Units endpoint is fully operational.

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/business-units/search -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Searchable Business Unit fields

The following list contains the Business Unit fields that are supported in query expressions for a BusinessUnitSearchRequest.

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
`createdAt`	dateTime	Business Units created at a certain date and time.
`lastModifiedAt`	dateTime	Business Units last modified at any of its fields at a certain date and time.
`version`	long	Business Units with a certain version of the resource.

Example:

Find Business Units created 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`	Business Units with a certain string in the combination of all Address fields.
`addresses.city`	Business Units with a certain string in the `city` field of all the Business Unit's addresses.
`addresses.company`	Business Units with a certain string in the `company` field of all the Business Unit's addresses.
`addresses.country`	Business Units with a certain string in the `country` field of all the Business Unit's addresses.
`addresses.firstName`	Business Units with a certain string in the `firstName` field of all the Business Unit's addresses.
`addresses.lastName`	Business Units with a certain string in the `lastName` field of all the Business Unit's addresses.
`addresses.mobile`	Business Units with a certain string in the `mobile` field of all the Business Unit's addresses.
`addresses.phone`	Business Units with a certain string in the `phone` field of all the Business Unit's addresses.
`addresses.postalCode`	Business Units with a certain string in the `postalCode` field of all the Business Unit's addresses.
`all`	Business Units with a certain string in any of the Business Unit's fields. Does not support wildcard queries.
`contactEmail`	Business Units with a certain contact email.
`key`	Business Units with a certain key.
`topLevelUnitKey`	Business Units with a certain top level unit key.
`parentUnitKey`	Business Units with a certain parent unit key.
`name`	Business Units with a certain name.

Examples:

Find Business Units with the name containing Plumbing (case insensitive):

Requestjson

{
  "query": {
    "fullText": {
      "field": "name",
      "value": "plumbing"
    }
  }
}

Find Business Units mentioning "example" in any field. This query will not only find "example" in fields like name, but also in contactEmail 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
`unitType`	a Business Unit with a specific `unitType`.
`stores.key`	a Business Unit of a specific Store identified by its `key`.
`storeMode`	a Business Unit with a specific `storeMode`.

Example:

Find Business Units with the unitType Division

Requestjson

{
  "query": {
    "exact": {
      "field": "unitType",
      "value": "Division"
    }
  }
}

Custom Fields

In addition to the standard fields on a Business Unit, you can also search for its Custom Fields, if any. custom.<field-name> queries for Business Units 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 Business Units with an enum type Custom Field accountPlan to the enum key of silver.

Requestjson

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