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.

Identity and Access Management (IAM)

This page describes how you can control Retail access and permissions using Identity and Access Management (IAM).


Google Cloud offers Identity and Access Management (IAM), which lets you give more granular access to specific Google Cloud resources and prevents unwanted access to other resources. This page describes the Retail IAM roles and permissions. For a detailed description of Google Cloud IAM, see the IAM documentation.

Retail provides a set of predefined roles designed to help you easily control access to your Retail resources. You can also create your own custom roles, if the predefined roles do not provide the sets of permissions you need. In addition, the older basic roles (Editor, Viewer, and Owner) are also still available to you, although they do not provide the same fine-grained control as the Retail roles. In particular, the basic roles provide access to resources across Google Cloud rather than just for Retail. See the basic roles documentation for more information.

Predefined roles

The Retail API provides some predefined roles you can use to provide finer-grained permissions to principals. The role you grant to a principal controls what actions the principal can take. Principals can be individuals, groups, or service accounts.

You can grant multiple roles to the same principal, and you can change the roles granted to a principal at any time, provided you have the permissions to do so.

The broader roles include the more narrowly defined roles. For example, the Retail Editor role includes all of the permissions of the Retail Viewer role, along with the addition permissions of the Retail Editor role. Likewise, the Retail Admin role includes all of the permissions of the Retail Editor role, along with its additional permissions.

The basic roles (Owner, Editor, Viewer) provide permissions across Google Cloud. The roles specific to Retail provide only Retail permissions, except for the following Google Cloud (Google Cloud) permissions, which are needed for general Google Cloud usage:

  • resourcemanager.projects.get
  • resourcemanager.projects.list

The following table lists the predefined roles available for Retail, along with their Retail permissions:

Name Retail permissions
Project > Owner All retail permissions Full access and control for all Google Cloud resources; manage user access and set up billing for a project.
Project > Editor All retail permissions Read-write access to all Google Cloud and Retail resources (except userEvents.purge, userEvents.rejoin and the ability to modify permissions and billing).
Project > Viewer *.get
Read-only access to all Google Cloud resources, including Retail resources.
Retail Admin All retail permissions Full control for all Retail resources.
Retail Editor catalogs.import
Can read all Retail resources and write products, events, except:
Retail Viewer catalogs.completeQuery
Read-only access to all Retail resources

Migrating permissions from the Recommendations AI API

If you are migrating from the previous Recommendations Engine API to the Retail API, note that the following predefined roles also include permissions for the previous API.

  • Retail Admin: Includes all the permissions of Recommendations Admin, except for apiKeys permissions.
  • Retail Editor: Includes all the permissions of Recommendations Editor, as well as catalog.update, and excluding apiKeys permissions.
  • Retail Viewer: Includes all the permissions of Recommendations Viewer.

Managing Retail IAM

You can get and set IAM policies and roles using the Google Cloud Console, the IAM methods of the API, or the Retail API. For more information, see Granting, Changing, and Revoking Access.

What's next