This Recommendations AI documentation references the Recommendations console. We recommend switching to the Retail console and using the Retail documentation, which documents Recommendations AI, the Retail console, and Retail Search.

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

Method: projects.locations.catalogs.setDefaultBranch

Set a specified branch id as default branch. API methods such as SearchService.Search, ProductService.GetProduct, ProductService.ListProducts will treat requests using "default_branch" to the actual branch id set as default.

For example, if projects/*/locations/*/catalogs/*/branches/1 is set as default, setting SearchRequest.branch to projects/*/locations/*/catalogs/*/branches/default_branch is equivalent to setting SearchRequest.branch to projects/*/locations/*/catalogs/*/branches/1.

Using multiple branches can be useful when developers would like to have a staging branch to test and verify for future usage. When it becomes ready, developers switch on the staging branch using this API while keeping using projects/*/locations/*/catalogs/*/branches/default_branch as SearchRequest.branch to route the traffic to this staging branch.

CAUTION: If you have live predict/search traffic, switching the default branch could potentially cause outages if the ID space of the new branch is very different from the old one.

More specifically:

  • PredictionService will only return product IDs from branch {newBranch}.
  • SearchService will only return product IDs from branch {newBranch} (if branch is not explicitly set).
  • UserEventService will only join events with products from branch {newBranch}.

HTTP request


The URL uses gRPC Transcoding syntax.

Path parameters



Full resource name of the catalog, such as projects/*/locations/global/catalogs/default_catalog.

Request body

The request body contains data with the following structure:

JSON representation
  "branchId": string,
  "note": string,
  "force": boolean


The final component of the resource name of a branch.

This field must be one of "0", "1" or "2". Otherwise, an INVALID_ARGUMENT error is returned.

If there are no sufficient active products in the targeted branch and force is not set, a FAILED_PRECONDITION error is returned.



Some note on this request, this can be retrieved by CatalogService.GetDefaultBranch before next valid default branch set occurs.

This field must be a UTF-8 encoded string with a length limit of 1,000 characters. Otherwise, an INVALID_ARGUMENT error is returned.



If set to true, it permits switching to a branch with branchId even if it has no sufficient active products.

Response body

If successful, the response body is empty.

Authorization Scopes

Requires the following OAuth scope:


For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the catalog resource:

  • retail.catalogs.update

For more information, see the IAM documentation.