This is the unified documentation for Retail API. This includes Recommendations AI, Retail Search, and the unified Retail console (which is applicable to both Recommendations AI and Retail Search users). To use the new console or Retail Search while they are in the restricted GA phase, submit a form here to contact Cloud sales. If you are using the v1beta version of Recommendations AI, migrate to the GA version: Migrating to the Retail API from beta.

To see documentation for only Recommendations AI and the Recommendations AI-only console, go to the How-to guides for Recommendations AI and the API reference documentation for Recommendations AI.

Attribute configuration

Retail Search can leverage product attributes for indexing, dynamic faceting, and searchability. This page discusses setting those configurations and how they are treated by Retail Search depending on the method and configuration you use.

Available configuration settings

You can enable and disable the following types of attribute configurations:

  • Indexable: Retail Search can filter and facet using this attribute.
  • Dynamic faceting: Retail Search can automatically use this attribute as a dynamic facet based on past user behavior such as facet clicks and views. To enable dynamic faceting for an attribute, Indexable must be set to true for that attribute.
  • Searchable: This attribute is searchable by Retail Search queries, which increases recall for that attribute. This control is applicable only for text attributes.

Configuration methods

There are two ways in which to set attribute configurations:

  • The Product API method: Set custom attributes to indexable and searchable via the Product API method.
  • The Cloud Console: Set indexable, searchable, and dynamic faceting configurations for attributes globally across all products via Cloud Console. Which of these settings are available in the console depends on the configuration mode Retail Search is set to.

Configuration modes

There are two modes in Retail Search. What mode you are in determines how attribute configurations are treated and which attribute configurations you can set.

To switch from the default mode, you must contact Retail support. Retail Search does not support returning to the default mode after you have switched.

  • Product level configuration mode (default): By default, Retail Search is set to product level configuration mode. In this mode, setting an attribute configuration to true on the product level overrides a setting for that attribute on the catalog level.
  • Catalog level configuration mode (experimental): Catalog configuration mode is an experimental feature and you must contact Retail support to enable it. In this mode, setting an attribute configuration to true on the catalog level overrides the setting for that attribute on the product level.

Set attributes to indexable

If an attribute is set to indexable, Retail Search can filter and facet using the attribute.

All predefined system attributes for Product (for example brand, size, and color) are indexable.

Set indexability via Product

By default, custom attributes (attributes you define with Product.attributes[]) are not set to be indexable, but you can enable this configuration for any custom attribute.

Set indexability globally in the console

If you have catalog level configuration mode enabled, you can also globally set this configuration across all products for a custom attribute from the Retail console Controls page, on the Site-wide controls tab. In this mode, by default, custom attributes (attributes you define with Product.attributes[]) are set to be indexable, but you can disable this configuration for any custom attribute. For more details on how to set this in the console, see Set site-wide attribute controls.

Changes to attribute configuration settings for indexable take effect within 12 hours, or immediately on your next catalog ingestion. You can test changes right away on the Evaluate page.

Set attributes to dynamically facetable

If an attribute is set to dynamically facetable, Retail Search can use the attribute as a dynamic facet that it automatically adds to a search based on past user behavior such as facet clicks and views.

Indexable must be true for an attribute for it to be settable as a dynamic facet.

Attributes have the dynamically facetable configuration enabled by default. You can disable this configuration for any attribute.

Setting dynamic faceting for an attribute is global. The dynamic faceting configuration you apply to that attribute is used by products across the catalog that use that attribute.

Setting dynamic facetability is available regardless of configuration mode.

Note that, separately from this attribute configuration setting, dynamic faceting as a feature is experimental and you must contact Retail support to turn it on. If it is not yet turned on, Retail Search can't return any dynamic facets even if you have set an attribute to be dynamically facetable.

Set dynamic faceting globally in the console

You can only set this configuration for an attribute from the Retail console Controls page, on the Site-wide controls tab. For more on how to set this in the console, see Set site-wide attribute controls.

Dynamic faceting configuration changes take up to two days. You can test changes right away on the Evaluate page.

Set attributes to searchable

If an attribute is set to searchable, recall for that attribute in Retail Search queries is improved.

This configuration is applicable only for text attributes. It is not applicable to numerical attributes.

All predefined textual system attributes for Product (for example brand, size, and color) are searchable.

By default, custom attributes (attributes you define with Product.attributes[]) are not set to be searchable, but you can enable this configuration for any textual custom attribute.

Set searchability via Product

To enable searchability for a textual custom attribute, set that attribute's Product.attributes.searchable configuration to true for a product that contains that attribute.

Set searchability globally in the console

If you have catalog level configuration mode enabled, you can also globally set this configuration across all products for a custom attribute from the Retail console Controls page, on the Site-wide controls tab. For more details on how to set this in the console, see Set site-wide attribute controls.

Changes to attribute configuration settings for indexable on the catalog level take effect within 12 hours, or immediately on your next catalog ingestion. You can test changes right away on the Evaluate page.