This is the documentation for Recommendations AI only. To try Retail Search and the unified Retail console in the restricted GA phase, contact Cloud sales. If you are not planning to use Retail Search, remain on the Recommendations console until further notice.

If you are using the v1beta version of Recommendations AI, migrate to the Retail API version.

Migrating to the Retail API from beta

Recommendations AI now uses the Retail API. This page explains the changes introduced and migration best practices when moving from the v1beta1 version of the Recommendations Engine API (service endpoint to the generally available Retail API (service endpoint

The Recommendations Engine API and its documentation set remain available, but they will no longer be updated.

This document applies to you only if you started using Recommendations AI when it was in beta.

Best practices

  • Send validate-only traffic before fully migrating.
  • Incremental traffic migration is better than switching all at once. If possible, gradually migrate your traffic from v1beta1 to v2.
  • If you are running services in different regions, it's better to migrate regions one by one to avoid global outage.

Documentation changes

This documentation set is for the generally available Retail API.

The beta documentation set for Recommendations Engine API and its documentation set remain available, but they will no longer be updated. You can find the beta documentation below:

REST and RPC paths

Many changes have been made to the REST and RPC paths. Make sure to review the API documentation for the Retail API to ensure you are calling the Retail API correctly.

All paths now use instead of

For example:

v1beta1 Recommendations Engine API:


v2 Retail API:


Some resources and methods have been renamed, removed, or newly added. Use the table below to compare v1beta1 resources to those of v2.

Note that links to v1beta1 resources go to the API documentation for v1beta1.

v1beta1 Resource Method v2 Resource Method
catalogs list catalogs list
patch patch
N/A catalogs.branches.operations get
catalogs.catalogItems create catalogs.branches.products create
delete delete
get get
import import
list Removed
patch patch
catalogs.operations get catalogs.operations get
list list
catalogs.eventStores.operations get Removed
catalogs.eventStores.placements predict catalogs.placements predict
catalogs.eventStores.predictionApiKeyRegistrations create Removed
catalogs.eventStores.userEvents collect catalogs.userEvents collect
import import
list Removed
purge purge
rejoin rejoin
write write
N/A operations get

IAM changes

The following changes have been introduced to Recommendations AI Identity and Access Management (IAM) roles and permissions:

  • Recommendations AI uses IAM roles and permissions in the retail namespace instead of the automlrecommendations namespace that was used by Recommendations Engine v1beta1.
  • The role Admin Viewer has been removed.
  • Permissions for apiKeys have been removed because the predict method no longer requires its own API key.

Catalog and user event schemas

The schemas for catalog and user events have changed in the Retail API.