Product Search

In contrast to Product Projection Search, Product Search supports searching through Products across Stores (up to 15 000 per Product), Product Selections (up to 15 000 per Product), and Standalone Prices (up to 10 000 per Product).
Those limits are soft, but if you go beyond the limits for Stores or Product Selections, the API will return non-deterministic results. For a large number of Standalone Prices, the API applies some sorting algorithm before returning a result.

The Product Search API accepts queries expressed in the search query language.

The API supports only those Locales configured in the Project. Queries for Locales not configured in the Project do not return any result.

For performance reasons, there are some limitations that are imposed by the API. Follow our performance tips to minimize the response times for the Product Search API.

Data integration

The Product Search API is designed to be ID-first to provide high performance. This means that the query result contains only Product IDs (together with matching Product Variant IDs when requested) by default, but not the entire resource. This design prefers lower response times over completeness of data, which can be achieved through additional methods as recommended in this section. To integrate the search results of this API with more product data, you have application-side as well as API-wise options.

With application-side caches

If possible, use application-side caches to store the IDs and SKUs returned with the search results together with the corresponding product data.

With Product Projection API

We recommend using the product GraphQL query with the returned Product IDs to retrieve the data you exactly require for your use case.

You can also use the Get ProductProjection by ID endpoint of the Product Projection API to fetch the entire product data of a matching Product.

With Product Projection parameters BETA

If the above retrieval and caching options are not feasible for your use case, the Product Search API also provides some built-in integration with the Product Projection API.

To retrieve the projected product data in an additional productProjection field in the ProductSearchResult, provide the productProjectionParameters field with the ProductSearchRequest.

Set this field to {} to get the full ProductProjection included in the ProductSearchResult, or add query parameters according to your needs, for example {"priceCurrency": "USD"}, to perform Product price selection on the returned ProductProjection.

This integration option calls the Product Projection API and enriches the search result with the data returned by the API call. Because of this additional API call, the search request takes longer to respond to than a request without the parameters.

Activation of the feature

The Product Search feature is not active for the Project by default. Before first use, you have to activate it by using the Change Product Search Indexing Enabled update action with mode: ProductsSearch on the Update Project endpoint.

{
  "action": "changeProductSearchIndexingEnabled",
  "enabled": true,
  "mode": "ProductsSearch"
}

As soon as the Product Search feature is activated for your Project, its Products get indexed, and the Search Products endpoint will become fully functional soon after.

Automatic deactivation

The Product Search feature will be deactivated for a Project automatically if there have been no calls against the Search Products endpoint for the duration of 30 consecutive days. The feature can be reactivated again as described above.

Representations

Search Products

Searchable Product fields

This section lists the fields of the Product search index that can be used for the field property in simple expressions. For standard fields on Products, the type of field determines which simple expressions are supported for the field.

The variants.* fields contain the data for all Product Variants (including the Master Variant) for a Product.

The variants.prices.* fields contain either Embedded Prices or Standalone Prices, depending on the Product's priceMode.

Attributes

The SearchFieldType of the Attribute determines in which simple expressions you can use the Attribute specified by:

variants.attributes.<attribute-name>

To query for multiple values of the same field or for several Attributes in the same request, combine the simple expressions with a compound expression.

Boolean fields

Use the following boolean type fields on Products in exact and exists expressions.

Number and date fields

Use the following fields in exact, exists, and range expressions. Data type indicates the type of field for the field.

Keyword fields

Use the following keyword type fields, containing unique IDs or keys, in exact, prefix, wildcard, and exists expressions. To query for multiple values of the same field or for several fields in the same request, combine the simple expressions with a compound expression.

Text and localized text fields

Use the following localizedText type fields in exact, fullText, prefix, wildcard, and exists expressions.

Example query:

The following example demonstrates how to find Product Variants with a price of EUR 22.22:

{
  "query": {
    "and": [
      {
        "exact": {
          "field": "variants.prices.currencyCode",
          "value": "EUR"
        }
      },
      {
        "exact": {
          "field": "variants.prices.centAmount",
          "value": 2222
        }
      }
    ]
  }
}

Matching variants

For query expressions on searchable fields that refer to the Product as a whole (for example, categories, key, slug), all variants of the Products returned in the ProductSearchResult match the query expression by default.

For query expressions on Product Variant-specific searchable fields, (for example, variants.attributes.*, variants.prices.*), the expression may match only for certain Product Variants.

To find out which of the Product Variants match the search query, we recommend setting markMatchingVariants to true in the ProductSearchRequest. This will cause the response to include the matchingVariants field which contains the id and sku of the Product Variants that match the query.

  ...
        {
            "id": "{{ID-of-the-matching-Product}}",
            "matchingVariants": {
                "allMatched": false,
                "matchedVariants": [
                    {
                        "id": 1,
                        "sku": "CSKW-093"
                    },
                    {
                        "id": 5,
                        "sku": "CSKP-0932"
                    },
                    {
                        "id": 8,
                        "sku": "CSKG-023"
                    }
                ]
            }
        },
  ...

If all Product Variants match the search query, each item in the search result will contain a matchingVariants object with allMatched set to true, but it will not explicitly list all variants.

  ...
        {
            "id": "{{ID-of-the-matching-Product}}",
            "matchingVariants": {
                "allMatched": true,
                "matchedVariants": []
            }
        },
  ...

For a not expression, the API returns only the Products for which no Product Variant matches the nested simple expressions.

For example, you want to search for Products that don't have the commonSize attribute set. The following not-exists expression will return only Products for which none of the Product Variants have the commonSize attribute set. The API will not return Products that have at least one variant with this attribute.

{
  "query": {
    "not": [
      {
        "exists": {
          "field": "variants.attributes.commonSize.key",
          "fieldType": "enum"
        }
      }
    ]
  }
}

Query validation

During query validation, the API analyzes the search query and evaluates its expressions and the validity of its searchable fields.

Field levels

For query validation, the API organizes the indexed product information into three different levels:

Validation of compound expressions

To ensure valid search results, the API enforces field-level constraints on compound expressions. All criteria within a compound expression must refer to the same field level. Queries violating this constraint will be rejected with a 400 status code, indicating an invalid combination of criteria.

Facets BETA

Facets give you statistical information about your data. It answers questions like "how many t-shirts of size XL are there?" or "how many TVs are there that cost between US$500 and $600?" The first question is answered by a distinct facet, and the second one by a ranges facet. Each facet has a name assigned to it, so it can be found in the ProductSearchFacetResult.

Distinct facets

The distinct facet counts occurrences of distinct values.

Ranges facets

The ranges facet counts Products that have values within a specified range. These values must be numeric or of type DateTime. You can specify ranges using from and to. Open ranges can be specified by omitting either the from or to values.

Count facets

The count facet counts the number of Products (or Product Variants).

Operations on facets

You can modify facets with following operations to filter and sort them, for instance.

Sorting

Sorting allows you to control how the results of your search query are sorted. If no sort is specified, the results are sorted by relevance score in descending order. Compound sorting (also known as multi-sort) is applied when you specify multiple sort expressions in order of priority, with each expression having its own sort direction. See the following example:

{
  "sort": [
    {
      "field": "variants.prices.centAmount",
      "order": "asc",
      "mode": "min"
    },
    {
      "field": "score",
      "order": "desc"
    }
  ]
}

{
  "sort": [
    {
      "field": "categoryOrderHints.64daee6a-c0e1-42e5-b7a4-a597610b1218",
      "order": "desc"
    }
  ]
}

For more information about sorting Product Search results, see the documentation for the search query language.

Pagination

Pagination allows you to retrieve a large number of search results by requesting them page by page. For more information about pagination, see the documentation for the search query language.

Product indexing

On average, Products are indexed every 15 minutes. Depending on the amount of data to update, the actual delay—until the product data is up-to-date—can be higher.

Prices

The Product's priceMode determines which Prices are indexed in the variants.prices field.
For the Embedded ProductPriceMode, the API indexes Embedded Prices; for Standalone, the API indexes the Standalone Prices associated with the Product Variant.

The API uses the variants.prices field for sorting, filtering, and faceting on Products, but its content is only retrievable through data integration with Product Projection parameters for Embedded Prices. Standalone Prices cannot be retrieved through the Product Search API.

To ensure good performance of the API, the number of Standalone Prices indexed per Product is limited to 10 000. For Products with Standalone Prices that exceed this limit, the system indexes a selection of the Prices as explained in the Large number of Standalone Prices section.

Only one valid price for each price scope (currency, country, customerGroup, and distributionChannel) is actually indexed. Like other attributes, this process operates on an eventually consistent basis, meaning that invalid prices might still be present in the index immediately after an update. When trying later, the price will be updated.

In case of multiple prices for the same scope, the one with the narrower (valid) time range is always selected over the price without time ranges.

If Price selection parameters are provided in the ProductSearchProjectionParams, the price field in the returned Product Projections is determined by price selection.

Localized content

To support exact, full text, prefix, and wildcard expressions, the Product Search API analyzes the localized product data specific to the supported languages.