This is the documentation for Recommendations AI, Retail Search, and the new Retail console.

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.