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.

Serving configurations

This page describes serving configurations. A serving configuration is a serving entity that associates a model or a set of controls that are used to generate your recommendation or search results.

Relationship with models and controls

When you create a serving configuration, you select a model (for Recommendations AI) or controls (for Retail Search) to attach. Serving configurations are invoked by your site when surfacing recommendations or search results. The Retail API references the serving configuration's associated model or controls at serving time to determine the recommendations or search results to generate.


A Recommendations AI can have a single model associated with it. However, any model can be associated with multiple serving configurations, enabling you to deploy the same model on different pages via different serving configurations.


Retail Search serving configurations have a multi to multi relationship with controls. You can add multiple controls to a serving configuration, and single control can be associated with multiple serving configurations.

You can create controls and then add or swap them into a live Retail Search serving configuration.

API resource and permissions

A serving configuration is passed into the Retail API using the placements resource:

  • Recommendations AI uses the URL projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/placements/SERVING_CONFIG_ID:predict.
  • Retail Search uses the URL projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/placements/SERVING_CONFIG_ID:search.

The permissions used on these resources are the and placements.predict permissions.

Support for placements in the Retail API

Serving configurations are available as of Recommendations AI v2 and Retail Search v2alpha.

Previously, Recommendations AI used placements to determine which model was used to return recommendations.

If you have existing placements, or create new placements, the Retail API will automatically create a serving configuration associated with each placement. (Creating a serving configurations does not create a corresponding placement, however.)

Serving configurations allow you to edit diversity and price reranking options and have them take effect in near real-time. With placements, diversity and pricing settings can only be changed from the recommendation model that the placement points to.

Placements are still supported, but using serving configurations instead is recommended.

Recommendations AI options for serving configurations

The following options allow you to change the behavior of a Recommendations AI serving configuration.

These options were previously available when creating models; they are now associated with serving configurations instead.

Price reranking

Price reranking causes recommended catalog items with a similar recommendation probability to be ordered by price, with the highest-priced items first. Price reranking is disabled by default.

Enabling price reranking helps balance conversion rates and average order values. Because relevance is also used to order the items returned, enabling price reranking is not the same as sorting by price.

This option can be edited after creating a serving configuration.


If you want to ensure that results returned from a single prediction request are from different categories of your product catalog, you can enable diversification. This option can be edited after creating a serving configuration. It is disabled by default.

Diversification reduces the likelihood that similar catalog items are shown in the recommendation panel, at the risk of removing some good recommendations. Diversification is configured by level, with higher levels of diversification causing fewer items to be displayed per category.

Diversification level Max items per category
None Unlimited
Low 3
Medium 2
High 1
Auto Depends on catalog

Retail Search options for serving configurations

Dynamic faceting

When dynamic faceting is enabled, Retail Search can automatically use attributes as dynamic facets in search results for this configuration, based on past user behavior such as facet clicks and views.

When dynamic faceting is enabled for a serving configuration, whether a given attribute can be used as a facet is by default defined by the product-level attribute configuration in the Retail API. Dynamic faceting settings in the API can be overwritten by site-wide attribute controls in the Cloud Console. See Site-wide controls.

Note that dynamic facets can be created based just on accurate product catalog data. However, for the feature to work optimally for your site, the facet models need to learn from activity on your site. For this, you need to set query, category and filter fields in your search event uploads accurately.

Next steps