Documentation

Product Projection Search

Product projections can be retrieved using full-text search, filtering, and faceting.

This endpoint provides high performance search queries over ProductProjections and is typically used to build Storefront Search functionalities that improve the discoverability of products for your customers. To optimize the usage of this endpoint for your project, check our performance tips.
This API does not support filtering, faceting, and sorting for Standalone Prices.
Existing filters, faceting, and sorting options will still work, but will only consider Embedded Prices, therefore using these options on Products with Standalone ProductPriceMode might yield inconsistent results.
This API does not support Product-level Attributes. The Attributes that have the same value in all variants of the Product also apply for Variant Attributes with the SameForAll constraint.
Product Projection Search does not support Product Tailoring.

Specifically, this means you cannot:

If you need to retrieve tailored product data, use the Get ProductProjection in Store endpoint or the Query ProductProjections endpoint with the storeProjection parameter instead.

Activate the Product Projection Search API

The Product Projection Search API is not active for the Project by default. If deactivated for your Project, the Product Projection Search endpoint returns a SearchDeactivated error.

To activate Product Projection Search for your Project, choose one of the following options:

{
  "action": "changeProductSearchIndexingEnabled",
  "enabled": true,
  "mode": "ProductProjectionsSearch"
}
Activation triggers the indexing of your Products, and the Product Projection Search API as well as the Search Term Suggestions API will be fully functional after indexing is complete.

Automatic deactivation

The Product Projection Search API and the Search Term Suggestions API are automatically deactivated for a Project if there have been no calls to them for the duration of 30 consecutive days. The APIs can be reactivated again as described above.

with GET

GET
https://api.{region}.commercetools.com/{projectKey}/product-projections/search
This method appends query parameters to the URL. The maximum allowed URL length is 8192 characters. Exceeding this limit will result in URL truncation, potentially leading to unexpected results. For funnel searches on Product Listing Pages, where users select multiple filters, we recommend the POST method which passes the query parameters within the request body, avoiding URL length restrictions.
OAuth 2.0 Scopes:
view_products:{projectKey}view_published_products:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
markMatchingVariants
​
Boolean
​
Set to true to mark matching variants in the search result.
Default: false​
text.<locale>
​
String
​
The text to analyze and search for, for example as supplied by a user through a search input field. The parameter must include the language in form of a Locale. The content to search in, that means the full-text search, is only performed in the localized Product content of the specified language.
The parameter can be passed multiple times.
fuzzy
​
Boolean
​
Set to true to apply fuzzy search on the text to analyze.
Default: false​
fuzzyLevel
​
Int
​
Set this parameter to overwrite the default fuzzy level. Only applicable if fuzzy is true.
  • 0 for text with 1-2 characters
  • 1 for text with 3-5 characters
  • 2 for text with more than 5 characters
If the provided value exceeds the default value, the API responds with an InvalidInput error.
Minimum: 0​
Maximum: 2​
filter.query
​
String
​
Applies a filter to the query results before facets are calculated. This parameter has an impact on facet counts. If you don't use the facet parameter in the same request, use this parameter instead of filter.
The parameter can be passed multiple times.
filter
​
String
​
Applies a filter to the query results after facets are calculated. This parameter does not have an impact on facet counts. Use this parameter in combination with the facet and filter.facets parameters for multi-select faceting.
The parameter can be passed multiple times.
facet
​
String
​
Requests calculation of facets.
The parameter can be passed multiple times.
filter.facets
​
String
​
Applies a filter to the calculated facet results, not to the Products returned with the query results. A facet's own aggregation is not filtered by its corresponding filter.facets criteria. Use this parameter in combination with the facet and filter parameters for multi-select faceting.
The parameter can be passed multiple times.
sort
​
String
​
Controls sorting of results. Use this parameter multiple times to sort by multiple fields.
  • When text is provided, but no sort parameter is given, the results are returned in descending order of relevance (equivalent to score desc).
  • When neither text nor a sort parameter is given, the sort order is nondeterministic.
The parameter can be passed multiple times.
expand
​
String
​
Enables server-side expansion of References. For details, see Reference Expansion.
The parameter can be passed multiple times.
limit
​
Int
​
The maximum number of results returned on a page.
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int
​
The starting point for retrieving paginated results.
Default: 0​
Minimum: 0​
Maximum: 10000​
staged
​
Boolean
​

Whether to search in the current or staged Product Projections.

For API Clients with the view_published_products, but not the view_products OAuth scope, true leads to a 403 Forbidden error.
Default: false​
priceCurrency
​
CurrencyCode
​
Enables Product price selection and Scoped Price Search.
Pattern: ^[A-Z]{3}$​
priceCountry
​
CountryCode
​
Enables Product price selection and Scoped Price Search. It can be used only in conjunction with the priceCurrency parameter.
Pattern: ^[A-Z]{2}$​
priceCustomerGroup
​
String
​
id of an existing CustomerGroup used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
priceCustomerGroupAssignments
​
String
​
IDs of existing CustomerGroups used for Product price selection, when using multiple Customer Groups. It can be used only in conjunction with the priceCurrency parameter.
The parameter can be passed multiple times.
priceChannel
​
String
​
id of an existing Channel used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
priceRecurrencePolicy
​
String
​
id of an existing RecurrencePolicy used for Product price selection. It can be used only in conjunction with the priceCurrency parameter.
localeProjection
​
Locale
​
Use for locale-based projection.
The parameter can be passed multiple times.
storeProjection
​
String
​
key of an existing Store. If the Store has defined languages, countries, distributionChannels, or supplyChannels, they are used for projections based on locale, price, and inventory.
If Product Selections are used, the API does not take the availability of the Product in the specified Store into account.
Product Tailoring modifies the product information returned in API responses. However, you can only specify Query Predicates for the original Product data, not for the tailored data.
Response:
200

ProductProjectionPagedSearchResponse

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/product-projections/search -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: ProductProjectionPagedSearchResponsejson
{
  "offset": 0,
  "count": 2,
  "total": 2,
  "limit": 0,
  "results": [
    {
      "id": "080feded-4f74-4d31-9309-f7ef6b7f1279",
      "version": 3,
      "productType": {
        "typeId": "product-type",
        "id": "1c095f1b-e638-4c7e-86c4-c58df873fca6"
      },
      "name": {
        "en": "Some Products"
      },
      "categories": [],
      "slug": {
        "en": "product_slug_jxeutnxwkswk"
      },
      "masterVariant": {
        "id": 1,
        "prices": [],
        "images": [],
        "attributes": [
          {
            "name": "text1",
            "value": {
              "it": "italian1",
              "de": "german1",
              "en": "englisch1"
            }
          }
        ]
      },
      "variants": [],
      "searchKeywords": {

      },
      "hasStagedChanges": false,
      "published": true,
      "createdAt": "1970-01-01T00:00:00.001Z",
      "lastModifiedAt": "2014-01-07T15:25:50.034Z",
      "attributes": []
    },
    {
      "id": "e779ec1a-0a98-4135-8344-d51bdafd4fe6",
      "version": 6,
      "productType": {
        "typeId": "product-type",
        "id": "bac5ef74-e0f9-4792-8439-ab84b270599e"
      },
      "name": {
        "en": "product with dates"
      },
      "description": {
        "en": "<p>Used to test the various date attributes<br></p>"
      },
      "categories": [],
      "slug": {
        "aa": "product-with-dates-1432797256269",
        "de": "product-with-dates-1432797256269",
        "en": "product-with-dates-1432797256269"
      },
      "masterVariant": {
        "id": 1,
        "prices": [],
        "images": [],
        "attributes": [
          {
            "name": "aboolean",
            "value": true
          }
        ]
      },
      "variants": [],
      "searchKeywords": {

      },
      "hasStagedChanges": true,
      "published": true,
      "createdAt": "2015-05-28T07:15:48.738Z",
      "lastModifiedAt": "2015-05-28T07:19:38.624Z",
      "attributes": []
    }
  ],
  "facets": {
    "red-things": {
      "type": "filter",
      "count": 0
    },
    "variants.attributes.size": {
      "type": "terms",
      "dataType": "text",
      "missing": 0,
      "total": 2,
      "other": 0,
      "terms": [
        {
          "term": "40",
          "count": 2
        },
        {
          "term": "41",
          "count": 2
        }
      ]
    },
    "variants.attributes.price": {
      "type": "range",
      "ranges": [
        {
          "from": 0,
          "fromStr": "0",
          "to": 100,
          "toStr": "100",
          "count": 2,
          "total": 2,
          "min": 0,
          "max": 100,
          "mean": 50.5
        }
      ]
    }
  }
}

with POST

POST
https://api.{region}.commercetools.com/{projectKey}/product-projections/search
For implementing funnel search on Product Listing Pages where users select multiple filters, use this POST method. To avoid URL length restrictions, this method passes the same query parameters as defined in the GET method, within the request body in URL-encoded format.
OAuth 2.0 Scopes:
view_products:{projectKey}view_published_products:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Request Body:URL-encoded key-value pairsasapplication/x-www-form-urlencoded
Response:
200

ProductProjectionPagedSearchResponse

as
application/json

Search response

The response returned to a Product Projection Search request. The object contains the query results with Product Projections where at least one ProductVariant matches the search query, as well as the facet results, if requested.
limit​
Int​
The maximum number of results returned on a page.
Default: 20​Minimum: 0​Maximum: 500​
offset​
Int​
The starting point for the retrieved paginated result.
Default: 0​Minimum: 0​Maximum: 10000​
count​
Int​

Actual number of results returned.

total​
Int​

Total number of results matching the query.

results​
Array of ProductProjection​
ProductProjections where at least one ProductVariant matches the search query, provided with the text.{language} and/or filter.query or filter query parameter. If the query parameter markMatchingVariants=true was provided with the request, the matching variants are marked as such.
facets​
FacetResults​
Facet results for each facet expression specified in the search request.
Only present if at least one facet parameter was provided with the search request.

Query results

The results array contains Product Projections where at least one ProductVariant matches the full-text search query or the provided filter expression.
The result can include Product Variants that do not match the search query. We recommend setting the query parameter markMatchingVariants=true to mark the matching variants.

Facet results

Each facet expression specified in the search request contains a corresponding facet result in the facets object of the query result. The corresponding results for term, range, and filtered facets are term facet result, range facet result, and filtered facet result respectively.
By default, facet results provide a count of ProductVariants. An additional count of Products can be requested through the counting products extension. A facet result can be accessed by its attribute path or, if provided in the facet expression, by its alias.
Example for two filtered facet expressions on attribute values, first with alias extensionbash
variants.attributes.color:red as red-things
variants.attributes.size:"m"
Facet result included in the search responsejson
{
  "offset": 0,
  "count": 0,
  "results": [],
  "facets": {
    "red-things": {
      "type": "filter",
      "count": 0
    },
    "variants.attributes.size": {
      "type": "filter",
      "count": 0
    }
  }
}

Term facet result

type​
FacetTypes​
terms
dataType​
TermFacetResultType​

Data type to which the facet is applied.

missing​
Int​
Number of ProductVariants that have no value for the specified term facet expression.
total​
Int​
Number of terms matching the term facet expression.
  • If the expression refers to Product fields like categories.id and reviewRatingStatistics.count, the value represents the number of Products.
  • If the expression is defined for fields specific to Product Variants, for example, variants.attributes.{name}, the value represents the number of Product Variants matching the expression.
other​
Int​
Number of terms not represented in this object (such as the number of terms beyond the limit).
terms​
Array of FacetTerm​
Values for the field specified in term facet expression for which at least one ProductVariant could be found.
By default, facet terms are returned in a descending order of their count.
If the term facet expression specifies to count Products through the counting products extension, then facet terms are returned in a descending order of their productCount.
MaxItems: 200​

TermFacetResultType

Data type to which the facet is applied.

text
For AttributeTextType Attributes.
date
For AttributeDateType Attributes.
time
For AttributeTimeType Attributes.
datetime
For AttributeDateTimeType Attributes.
boolean
For AttributeBooleanType Attributes.
number
For AttributeNumberType Attributes.

FacetTerm

term​
Any​
Value for the field specified in the term facet expression for which at least one ProductVariant could be found.
count​
Int​
Number of ProductVariants for which the term applies.
productCount​
Int​
Number of Products for which the term applies. Only available if the counting products extension is enabled.

Range facet result

type​
FacetTypes​
range
ranges​
Array of FacetRange​
Statistical data over values for date, time, datetime, number, and money type fields.

FacetRange

from​
Float​

The range's lower endpoint.

0 represents -∞.
fromStr​
String​

The range's lower endpoint.

An empty string represents -∞.

to​
Float​

The range's upper endpoint.

0 represents +∞.
toStr​
String​

The range's upper endpoint.

An empty string represents +∞.

count​
Int​
Number of ProductVariants for which the values in a field fall into the specified range.
productCount​
Int​
Number of Products for which the values in a field fall into the specified range.
Present only if the counting products extension is enabled.
total​
Float​

Sum of all values contained in the range.

min​
Float​

Minimum value within the range.

max​
Float​

Maximum value within the range.

mean​
Float​

Arithmetic mean of the values within the range.

Filtered facet result

type​
FacetTypes​
filter
count​
Int​
Number of ProductVariants matching the value specified in filtered facet expression.
productCount​
Int​
Number of Products matching the value specified in filtered facet expression.
Present only if the counting products extension is enabled.

Matching variants

For filters on searchable fields that refer to the Product as a whole (for example, categories, key, slug), all variants of the Product Projections returned in the search response match the filter by default.
For filters on Product Variant-specific searchable fields, (for example, variants.attributes.{name}, variants.prices.centAmount), the filter 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 Product Projection Search request.
This will cause the ProductVariants to include the isMatchingVariant field indicating which Product Variant matches the query.
  • If isMatchingVariant: true, the Product Variant matches the search query.
  • If isMatchingVariant: false, the Product Variant does not match the search query, but is returned as part of the returned Product Projection.
If markMatchingVariants is set to false in the Product Projection Search request, the Product Variants returned in the Product Projection Search response will not contain the isMatchingVariant field.

Full-text search

The text.{language} query parameter performs a full-text search on the ProductProjections data. For localized fields, the API only searches text matching the language specified in the text.{language} query parameter.
Search results are based on the first 256 characters provided with the text.{language} query parameter, and characters beyond this limit are ignored. The API will not return an error when you pass longer values for this query parameter.

Searchable fields

By default, the API indexes the following standard fields of a ProductProjection for full-text search:
  • name (weighed heavier than the other searchable fields)
  • description
  • slug
  • sku
  • searchKeywords
metaKeywords and metaTitle are not indexed for full-text search.
The Attributes on Product Variants of following AttributeTypes are indexed for search if the AttributeDefinition's isSearchable is set to true:
If no sort query parameter is given in the Product Projection Search request, the results are sorted by the relevance of the Product to the search text passed.

Fuzzy search

If you set the fuzzy query parameter in the Product Projection Search request to true, the API will return ProductProjections that contain slight differences from the search text. For example, a fuzzy search for "whisky" will also return Products that are labeled with "whiskey."

To optimize the discovery of related terms, the API dynamically adapts the level of fuzziness applied on the text based on the length of the text to analyze.

  • 0 - for text of one or two characters.
  • 1 - for text of three, four or five characters.
  • 2 - for text of more than five characters.
If you want to set the fuzzy level to a value different from these defaults, you can set it explicitly with the fuzzyLevel query parameter. However, the value must not exceed the default value, which is selected dynamically based on the length of the text value.
The fuzziness level is quantified in terms of the Damerau-Levenshtein distance, which is the number of operations needed to transform one word into another.

Filters

In addition to full-text search, Product Projection Search allows you to filter search results for exact values in specified Product fields. This section describes which filter parameters exist and how you formulate filter expressions for specific searchable fields.

Filter parameters

To support multi-select faceting, the API allows for filtering products before and after calculating facets.
  • The filter.query parameter filters Products in the query results before calculating facets.
  • The filter parameter filters Products in the query results after calculating facets.
  • The filter.facets parameter modifies the aggregated facet counts in the facet results, not the Products returned with the query results.
    A facet's own aggregation is not filtered by its corresponding filter.facets criteria.
    For example, if you're requesting two facets—one for color and another for size—and you apply filter.facets for color, the facet aggregation for size will be filtered accordingly, but the facet counts for color itself will remain unaffected.
    This allows for multi-select faceting in combination with the filter parameter, where storefront users can refine search results across multiple facet values without limiting the overall query results.
However, not all filter expressions can be used with all filter parameters. For more information about which filter expression can be used with which filter parameter, see field-specific filters.

Filter expressions

You can specify filters with filter expressions made of searchable fields, filter operators, and values to search for.

Matching value

Filters of the form field:{value} search for a specified value for the given field. The value must match exactly. If you want fuzzy search for text values, use full-text search instead.

Matching values

If you want to specify that the given field can have this or that value, you can specify them in the same filter parameter, separated by a comma (OR operator). For example, the below search request filters Products of the color "black" OR "grey":
GET /{projectKey}/product-projections/search?filter%3Dvariants.attributes.color.key%3A%22black%22%2C%22grey%22

Within range of values

If you want to specify that the values for a given field should be in a certain range, you specify a range filter with its lower- and upper-bounds. :range ({from} to {to})

You can specify multiple ranges for the same filter by separating the ranges by commas:

:range ({from} to {to}), ({from} to {to})
Use * to ignore the lower- or upper-bound values: :range (* to {to})

Check if value exists

If you want to check if a specific field has a value assigned, but you don't really care about which value, you can use the filter expression of the form {field}:exists.
Empty strings ("") are recognized as existing values and are caught by this filter.

Check if value is missing

If you want to check if a specific field has no value assigned, you can use the filter expression of the form {field}:missing.
Empty strings ("") are not recognized as missing values and are not caught by this filter.

Combine filters with logical AND

You can specify that Products you search for should match filter X AND filter Y at the same time by passing multiple filter parameters in one search request. This combines them with an AND operator. For example, the below search request filters Products of a certain Category AND of the color "black":
GET /{projectKey}/product-projections/search?filter%3Dcategories.id%3A%22{category-ID}%22%26filter%3Dvariants.attributes.color%3A%22black%22

Field-specific filters

This section describes the searchable fields on Products and Product Variants for which you can set filters.

Filter by Category

The following filters can be applied:

  • categories.id:"{id}" filters Products that belong to the specified Category.
  • categories:missing filters Products that are not assigned to any Category.
    Empty strings ("") are not recognized as a missing value and are not caught by this filter.
  • categories:exists filters Products that are assigned to at least one Category.
This filter can be used with filter, filter.query, and filter.facets parameters.

Filter by Category subtrees

The following filters can be applied:

  • categories.id: subtree("{id}") filters Products that belong to the specified Category or any of its descendant Categories.
  • categories.id: subtree("{id}"), subtree("{id2}") filters Products that belong to different branches of the Category tree.
    Other subtree functions can be added to the filter. Each subtree specifies the Category of the other branch in the Category tree.
The subtree function can also be used in combination with several regular ID filters: categories.id: subtree("{id1}"), "{id2}", "{id3}". If the Categories are children of {id1}, it is not necessary to specify {id2} and {id3}.
The subtree function can be applied in filter.facets.

Filter by Price

This filter only works with Embedded Prices.
If a Product Variant has several Embedded Prices, only the first Price is used for filtering. To use another Product Variant Price (selected based on the Price scope), use the Scoped Price filter.

The following filters can be applied:

  • variants.price.centAmount:{amount} filters Products whose Embedded Price matches the specified value.
  • variants.price.centAmount:range ({from} to {to}), ({from} to {to}), ... filters Products whose Embedded Price matches the specified range that includes the lower- and upper-bound values.
  • variants.price.centAmount:range (* to {to}) filters Products whose Embedded Price matches the specified range that includes the lower- and upper-bound values.
    Using * ignores the lower- or upper-bound values.
  • variants.prices:missing filters Products that contain a ProductVariant without any Embedded Price set.
    Empty strings ("") are not recognized as a missing value and are not caught by this filter.
  • variants.prices:exists filters Products that contain a ProductVariant with at least one Embedded Price set.
These filters can be used with filter, filter.query, and filter.facets parameters.

Filter by Scoped Price

To filter Products by Scoped Price, use Scoped Price Search. Filter by price only works with Embedded Prices.
Scoped Price is a Price contained inside a ProductVariant selected based on the Price scope like currency, country, Channel, Recurrence Policy, and Customer Group. This means that only those Product Variants with a Price matching all Price Selection Parameters contain the scopedPrice field with the ScopedPrice. You can apply filters on the scopedPrice field and its subfields like value and currentValue as described in this section.
These filters can be used with filter, filter.query, and filter.facets parameters.
This filter only works with Embedded Prices.

Filter by ScopedPrice value

This filter only works with Embedded Prices.
Filters, facets, and sorts Products by the original Product Variant Embedded Price value.
For example: variants.scopedPrice.value.centAmount:range (* to 1200).

Filter by ScopedPrice currentValue

This filter only works with Embedded Prices.
Filters, facets, and sorts Products by the original Product Variant Embedded Price value or a discounted value, if available.
For example: variants.scopedPrice.currentValue.centAmount:1000.

Filter by ScopedPrice discounted value

This filter only works with Embedded Prices.
Filters, facets, and sorts Products if an Embedded Price discounted value is available.
For example: variants.scopedPrice.discounted.value.centAmount:range (* to 1200).

Filter by scopedPriceDiscounted

This filter only works with Embedded Prices.
Filters, facets, and sorts Products by the ProductVariant scopedPriceDiscounted. The value would be true if a ProductDiscount is applied on the Embedded Price.

Filter by SKU

The following filters can be applied:

  • variants.sku:{sku} filters Products with a ProductVariant that matches the specified sku.
  • variants.sku:missing filters Products that have a ProductVariant with no sku set.
    Empty strings ("") are not recognized as a missing value and are not caught by this filter.
  • variants.sku:exists filters Products that have a ProductVariant with a sku set.
This filter can be used with the filter and filter.query parameters.

Filter by Product Key

The following filters can be applied:

  • key:{key} filters Product that matches the specified Product key.
  • key:missing filters Products with no key set.
    Empty strings ("") are not recognized as a missing value and are not caught by this filter.
  • key:exists filters Products with a key set.

Filter by ProductVariant Key

The following filters can be applied:

  • variants.key:{key} filters Products that have a ProductVariant matching the specified key.
  • variants.key:missing filters Products that have a ProductVariant with no key set.
    Empty strings ("") are not recognized as a missing value and are not caught by this filter.
  • variants.key:exists filters Products that have a ProductVariant with a key set.

Filter by ProductType

productType.id:{id} filters Products that matches the specified ProductType.
This filter can be used with the filter and filter.query parameters.

Filter by TaxCategory

The following filters can be applied:

  • taxCategory.id:{id} filters Products that match the specified TaxCategory.
  • taxCategory:missing filters Products that do not belong to any TaxCategory.
    Empty strings ("") are not recognized as a missing value and are not caught by this filter.
  • taxCategory:exists filters Products that have a TaxCategory set.
This filter can be used with the filter and filter.query parameters.

Filter by State

The following filters can be applied:

  • state.id:{id} filters Products that match the specified State.
  • state:missing filters Products that do not belong to any State.
    Empty strings ("") are not recognized as a missing value and are not caught by this filter.
  • state:exists filters Products that have a State set.
This filter can be used with the filter and filter.query parameters.

Filter by reviewRatingStatistics

The following filters can be applied:

  • reviewRatingStatistics.averageRating:{value} filters Products that have the average ReviewRatingStatistics matching the specified value.
  • reviewRatingStatistics.averageRating:range ({from} to {to}), ({from} to {to}), ... filters Products that have the average ReviewRatingStatistics matching the specified range that includes the lower- and upper-bound values. Using * ignores the lower- or upper-bound values.
  • reviewRatingStatistics.highestRating:{value} filters Products that have the highest ReviewRatingStatistics matching the specified value.
  • reviewRatingStatistics.highestRating:range ({from} to {to}), ({from} to {to}), ... filters Products that have the highest ReviewRatingStatistics matching the specified range that includes the lower- and upper-bound values. Using * ignores the lower- or upper-bound values.
  • reviewRatingStatistics.lowestRating:{value}: filters Products that have the lowest ReviewRatingStatistics matching the specified value.
  • reviewRatingStatistics.lowestRating:range ({from} to {to}), ({from} to {to}), ...: filters Products that have the lowest ReviewRatingStatistics matching the specified range that includes the lower- and upper-bound values. Using * ignores the lower- or upper-bound values.
  • reviewRatingStatistics.count:{value} filters Products that have a number of ReviewRatingStatistics matching the specified value.
  • reviewRatingStatistics.count:range ({from} to {to}), ({from} to {to}), ... filters Products that have a number of ReviewRatingStatistics matching the specified range.
This filter can be used with the filter and filter.query parameters.

Filter by Attribute values

To filter by an Attribute value, the Attribute must have the isSearchable field set to true in its AttributeDefinition.
Attributes defined at the Product level are not supported.

The following filters can be applied:

  • variants.attributes.{name}:"{value}" filters ProductVariants with the Attribute matching the specified value.
  • variants.attributes.{name}:range ({from} to {to}), ({from} to {to}), ... filters ProductVariants with the Attribute matching the specified range that includes the lower- and upper-bound values. Using * ignores the lower- or upper-bound values.
  • variants.attributes.{name}:missing filters Products that do not have a Attribute set.
    Empty strings ("") are not recognized as a missing value and are not caught by this filter.
  • variants.attributes.{name}:exists filters Products that have a Attribute set.
  • For AttributeEnumType Attributes, the filter must be applied to the key of the AttributePlainEnumValue.
    • variants.attributes.{myEnumName}.key:"{value}"
  • For AttributeMoneyType Attributes, the filter must be applied to Money centAmount or currencyCode property.
    • variants.attributes.{myMoneyAttribute}.centAmount:{value}
    • variants.attributes.{myMoneyAttribute}.centAmount:range ({from} to {to}), ({from} to {to}), ...
    • variants.attributes.{myMoneyAttribute}.currencyCode:"{value}"
  • For AttributeReferenceType Attributes, the filter must be applied to the id or the typeId of Reference.
    • variants.attributes.{myReferenceAttribute}.id:"{id}"
    • variants.attributes.{myReferenceAttribute}.typeId:"{typeId}"
  • For AttributeSetType Attributes, the filter can be specified multiple times to search for a set that contains at least those values (AND). Specifying multiple values, separated by a comma, will match if one of those values is present in the set (OR).
    For example, the below search request filters Products of the color "green" AND "black" OR "grey":
    GET /{projectKey}/product-projections/search?filter%3Dvariants.attributes.colors%3A%22green%22%26filter%3Dvariants.attributes.colors%3A%22black%22%2C%22grey%22
These filters can be used with the filter, filter.query, and filter.facets parameters.

Filter by Product Variant availability

The following filters can be applied:

  • variants.availability.isOnStock:true filters ProductVariants with the availability matching the specified value.
  • variants.availability.availableQuantity:range (1 to *) filters ProductVariants with the availability matching the specified range that includes the lower- and upper-bound values. Using * ignores the lower- or upper-bound values.
  • variants.availability.channels.<channel-id>.isOnStock:true filters ProductVariants in a specific supply Channel with the availability matching the specified value.
  • variants.availability.channels.<channel-id>.availableQuantity:range (1 to *) filters ProductVariants in a specific supply Channel with the availability matching the specified range that includes the lower- and upper-bound values. Using * ignores the lower- or upper-bound values.
  • variants.availability.isOnStockInChannels:"channel-id-1","channel-id-2","channel-id-3" filters ProductVariants where ProductVariantAvailability isOnStock is true in at least one of the specified Channels.

Filter by Product searchKeywords

searchKeywords.{language}.text:"{value}" filters Products that matches the search keywords in a specified locale.

Filter by DateTime

Filters ProductVariants created or updated within the specified DateTime range.

Filter by createdAt

createdAt:range ({from} to {to}) filters ProductVariants by the createdAt date in a specific date range. For example:
GET /{projectKey}/product-projections/search?filter.query%3DcreatedAt%3Arange%20(%222015-06-04T12%3A27%3A55.344Z%22%20to%20%222016-06-04T12%3A27%3A55.344Z%22)
The search result includes the lower- and upper-bound values. Using * ignores the lower- or upper-bound values.

Filter by lastModifiedAt

lastModifiedAt:range ({from} to {to}) filters ProductVariants by the lastModifiedAt date in a specific date range.
The search result includes the lower- and upper-bound values. Using * ignores the lower- or upper-bound values.

Facets

Facets calculate statistical counts to aid in faceted navigation. 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 filtered facet, and the second one by a range facet. If you want to know how many t-shirts are there for each of the sizes, request a term facet for the size attribute.
Facet calculation is requested by providing a facet expression through the facet query parameter in a Product Projection Search API call. Each type of facet has its specific facet expression:
Optionally, extend the facet expression with alias or counting products parameters.
Find the calculated facets in the facet results.
To facet by an Attribute value, the Attribute must have the isSearchable field set to true in its AttributeDefinition.
Facets for prices only work with Embedded Prices. If you need faceting for StandalonePrices, use Product Search instead.

Term facets

This facet provides the counts for each of the different values the query parameter has. It is useful, for example, for obtaining all possible values of an Attribute to provide filters for those values on the frontend.

Term facet expression

To retrieve facet counts for all occurring values of a ProductVariant field, the following facets can be applied.
  • categories.id counts Product Variants of all Categories.

Other built-in fields can be requested analogously.

Attributes

  • variants.attributes.{name}counts Product Variants for all occurring values of custom simple value Attributes such as text, date, time, datetime, boolean, and number.
  • variants.attributes.{name}.{lang}counts Product Variants for all occurring values of custom ltext Attributes in the given language.
  • variants.attributes.{name}.key counts Product Variants for all occurring enum or lenum Attribute keys.
  • variants.attributes.{name}.labelcounts Product Variants for all occurring enum Attribute labels.
  • variants.attributes.{name}.label.{lang} counts Product Variants for all occurring lenum Attribute labels in the given language.
  • variants.attributes.{name}.centAmount counts Product Variants for all occurring values of a custom money Attribute.
  • variants.attributes.{name}.currencyCode counts Product Variants for all occurring currency codes of a custom money Attribute.
The following example requests term facets for the Attributes color and size:
GET /{projectKey}/product-projections/search?facet%3Dvariants.attributes.colors%26facet%3Dvariants.attributes.size%3A%22m%22

Availability

  • variants.availability.availableQuantity counts Product Variants for all occurring available quantities.
  • variants.availability.channels.<channel-id>.availableQuantity counts Product Variants for all occurring available quantities for the supply Channel with ID <channel-id>.

Review ratings

  • reviewRatingStatistics.averageRating counts Product Variants for all occurring average ratings.
  • reviewRatingStatistics.highestRating counts Product Variants for all occurring highest ratings.
  • reviewRatingStatistics.lowestRating counts Product Variants for all occurring lowest ratings.
  • reviewRatingStatistics.count counts Product Variants for all occurring Review ratings counts.

Range facets

This type counts ProductVariants for which the query value is a range (with minimum and maximum value) specified in the range facet expression, for example, from a Product's Embedded Prices to filter Products by price with a range slider.

Range facet expression

To aggregate facet counts across ranges of values, the range qualifier can be applied analogous to the filters with its lower- and upper-bounds: :range ({from} to {to})

You can specify multiple ranges for the same facet by separating the ranges by commas:

:range ({from} to {to}), ({from} to {to})
Use * to ignore the lower- or upper-bound values: :range (* to {to})
The :range notation is applicable to the date, time, datetime, number, and money type fields. It is also applicable to a set of these types. If one matching element is contained in the set, all elements are used in the aggregation.

Ranges of Prices

  • variants.price.centAmount:range
    counts Product Variants whose Embedded Price falls in one of the specified ranges.
Counts Variants whose Price is below 50, between 50 and 100, and above 100.bash
variants.price.centAmount:range (* to 50), (50 to 100), (100 to *)

Ranges of Scoped Price

Can only be applied in combination with Scoped Price search.
  • variants.scopedPrice.currentValue.centAmount:range
    counts Product Variants whose ScopedPrice currentValue falls in one of the specified ranges.
Counts Product Variants whose Scoped Price is below 1000, between 1000 and 2000, and between 2000 and 3000 cents.bash
variants.scopedPrice.currentValue.centAmount:range (* to 1000), (1000 to 2000), (2000 to 3000)

Ranges of Money type Attributes

  • variants.attributes.{name}:range
    counts Product Variants whose values of the Attribute fall in one of the specified ranges.

Filtered facets

This facet provides counts for specific values of ProductVariant fields.

Filtered facet expression

To get facet counts for a specific field value, the requested value can be appended after a colon. This notation can be applied to any kind of field analogous to the filters.

Categories

  • categories.id:"{id}" counts Product Variants in the specified Category.
  • categories.id: subtree("{id}") counts Product Variants in the subtree of the specified Category.
  • categories.id: subtree("{id1}"), subtree("{id2}") counts Product Variants for each of the specified subtrees.
    Unlike filters, facets using subtree cannot be mixed with regular value facets, so categories.id: subtree("{id}"), "{id2}" will ignore {id2}.
  • categories.id: subtree("*"): The asterisk parameter is equivalent to counting the ProductVariants that have a Category assigned.

Prices

  • variants.price.centAmount:{amount} counts Product Variants that have the specified Embedded Price.

Attributes

  • variants.attributes.{name}:{value} counts Product Variants with the Attribute that match the specified value of a simple Attribute.

    String values must be set in quotation marks. Add the respective postfixes for other Attribute types analogous to when requesting facets for all values (see above).

  • variants.attributes.{name}:{value},{value2} counts Product Variants with the Attribute that match at least one of the values in the comma-separated list.
  • variants.attributes.{myEnumName}.key:"{value}" counts the occurrences of a specific enum key.

Facet expression extensions

Alias

Optionally, you can give an alias to all facets that can be used instead of the Attribute path in the result. This makes it possible to calculate multiple facets on the same Attribute in the same search request.

Examples:

Returns the facet with a meaningful name (default is the Attribute name).bash
variants.attributes.color.key:red as red_stuff
Returns the facet counts for two specific values of the same Attribute without causing a naming conflict.bash
variants.attributes.brand:"Coca-Cola" as brand_coke
variants.attributes.brand:"Pepsi" as brand_pepsi
Allows to show a marketing hint about many Products cheaper than 100 on a page that also shows the normal price filter.bash
variants.price.centAmount:range(0 to 9999) as price_below_100
variants.price.centAmount

Counting Products

In addition to ProductVariants, all facets can optionally count Products by appending counting products to a facet expression. The corresponding facet result then contains an additional field productCount that shows the number of Products.

Examples:

Sorting

By default, search results are sorted in a descending order of relevance with respect to the provided text (that is their "score"). An alternative sorting can be specified using the sort parameter with the structure {field} {direction}. Compound sorting (also known as multi-sort) is applied when specifying multiple sort parameters ordered by priority with each parameter having its own sorting direction, ascending (asc) or descending (desc).
If the sort parameters do not define an ordering, the position of some or all Products can be non-deterministic that is not predictable and repeatable across API requests. Common cases are:
  • When neither text nor sort is given, the complete order is non-deterministic.
  • When full text is provided but no sort is given, the results are returned in a descending order of relevance.
  • When Products have no value set on the fields that are the sort criteria, the position is non-deterministic among those with no value set.
  • When Products have identical vales on the fields that are the sort criteria, the position among each group with identical values is non-deterministic.
To achieve a deterministic order, always have a sort parameter at the end of the list of sort parameters that sorts by a field or attribute that has distinct values across all products. For example, createdAt or an Attribute specific for this purpose.

The following are standard fields to sort by:

  • name.{language}
    Sorts Products by their name.
    The field must include the language in the form of a Locale.
  • categoryOrderHints.{category ID}
    Sorts Products by their CategoryOrderHint in combination with a filter by category.
  • createdAt
    Sorts Products by their creation date.
  • lastModifiedAt
    Sorts Products by their last modification date.
  • id
    Sorts Products by their ID.
  • score Sorts Products by the search relevance score.
    Sorting by score can be combined with other sorting criteria. For example, sorting by score and id ensures consistent order of Products across several search requests for Products that have the same relevance score.
Example for sorting by the German name of the Product in ascending orderbash
name.de asc

Sort by Price

The sorting only works with Embedded Prices.
price sorts Products by their Embedded Price. Since Prices can vary across Variants of a Product, the highest Embedded Price is used for a descending sort direction, while the lowest Embedded Price is used for an ascending sort direction.
Only the centAmount of the first Embedded Price from the prices of every ProductVariant is used for sorting. If you have more than one Embedded Price defined per Product Variant, consider sorting by Scoped Price.

Sort by Scoped Price

To sort Products by their Variant's scopedPrice, use Scoped Price Search.
  • variants.scopedPrice.value
    Sorts Products by their ScopedPrice value.
  • variants.scopedPrice.currentValue
    Sorts Products by their ScopedPrice currentValue.
Sorting by value or currentValue might return an unexpected result if you don't specify one of their subfields. For example, to sort by the numerical value of the Price, you must specify the .centAmount subfield as follows: variants.scopedPrice.currentValue.centAmount.
Since prices can vary across Variants of a single Product, the following behavior applies: When the sort direction is descending, the highest Embedded Price of a product is used for sorting. When the sort direction is ascending, the lowest Embedded Price is used.
Product Projection Search compares only Embedded Prices matching exactly the Price Selection Parameters given with the Scoped Price Search request and is therefore the safer option when there is more than one Price on a Product Variant compared to sorting by Price.

Sort by Reviews

The following sorts can be applied based on ReviewRatingStatistics:
  • reviewRatingStatistics.averageRating
    Sorts Products by their average rating.
  • reviewRatingStatistics.highestRating
    Sorts Products by their highest rating.
  • reviewRatingStatistics.lowestRating
    Sorts Products by their lowest rating.
  • reviewRatingStatistics.count
    Sorts Products by the number of ratings.

Sort by values found on ProductVariants

If Products have several Product Variants, each Variant can have a different value on the sorted Attribute. You must specify whether the minimum or maximum value is to be used across the Variants to compare the Product with other Products.
By default, the minimum value is used when sorting in ascending order (asc.min) and the maximum value is used when sorting in descending order (desc.max). For a different sorting behavior, the parameters can be set to asc.max or desc.min respectively.
The field names to sort Products by values found on ProductVariants start with variants..

Sort by SKU

variants.sku sorts Products sorted alphabetically by their SKUs.

Sort by availability

To sort products by availability:

  • variants.availability.restockableInDays
    Sorts Products by number of days it takes to restock it (with no supply Channel).
  • variants.availability.channels.<channel-id>.restockableInDays
    Sorts Products by number of days it takes to restock it for a specific supply Channel.
  • variants.availability.availableQuantity
    Sorts Products by available quantity (with no supply Channel).
  • variants.availability.channels.<channel-id>.availableQuantity
    Sorts Products by available quantity for a specific supply Channel.
Example for sorting by minimal available quantity of Products in descending orderbash
`variants.availability.availableQuantity desc.min`

Sort by Attributes

In addition to the sorting by the standard fields listed above, Products can also be sorted by their specific custom Attributes. The search endpoint only supports those Attributes that have been declared as searchable in the ProductType.
Attributes can only be sorted if the isSearchable field is set to true in its AttributeDefinition.

The following sort can be applied:

  • variants.attributes.{name}
    Sorts Products by simple value Attributes such as text, date, time, datetime, boolean, and number.
  • variants.attributes.{name}.{lang}
    Sorts Products by ltext Attribute in the specified language.
  • variants.attributes.{name}.key
    Sorts Products by enum or lenum Attribute key.
  • variants.attributes.{name}.label
    Sorts Products by enum Attribute label.
  • variants.attributes.{name}.label.{lang}
    Sorts Products by lenum Attribute label in the specified language.
  • variants.attributes.{name}.centAmount
    Sorts Products by money Attribute amount.
  • variants.attributes.{name}.currencyCode
    Sorts Products by money Attribute currency.
Example for sorting by English labels of a 'lenum' Attribute 'color' in ascending orderbash
variants.attributes.color.label.en asc.max

Pagination

A response to the search request contains the first 20 results by default. Pagination allows you to retrieve the first 10 000 results by requesting them page by page. The total field in a query result indicates how many results match the search query in total.

Limit

With the limit parameter you can set the maximum number of results returned on a page. Any value between 0 and 100 is allowed, the default limit is 20. Set limit=0 if you want to retrieve facets only, but not the search result.

Offset

The offset parameter controls the starting point for retrieving paginated results. With the default value 0 you retrieve the first page of query results. Setting offset=1 skips the first page and returns the second page of results, and so on. Each page contains a number of results defined by the limit parameter.
The maximum allowed offset is 10 000.

Setting pagination parameters exceeding this limit will result in an error with the code "SearchExecutionFailure."