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

Manage catalog information

Stay organized with collections Save and categorize content based on your preferences.

This page describes how to manage your product information after you have imported a catalog into the Retail API. You can read, write, and delete products in your catalog.

To keep your catalog up to date as product information changes, import your catalog the same way as the very first time. For help with importing your catalog, see Importing catalog information.

Create/Get/Update/Delete product tutorial

This tutorial shows you how to use the Retail API Product Service methods, which perform the following actions:

  • Create a product
  • Get a product
  • Update a product
  • Delete a product

For step-by-step guidance for this task directly in the Cloud Shell Editor, click Guide me:

Guide me


The following sections take you through the same steps as clicking Guide me.

Create product tutorial

This tutorial shows you how to create a single product.


For step-by-step guidance for this task directly in the Cloud Shell Editor, click Guide me:

Guide me


The following sections take you through the same steps as clicking Guide me.

Get product tutorial

This tutorial shows you how to retrieve a product item.


For step-by-step guidance for this task directly in the Cloud Shell Editor, click Guide me:

Guide me


The following sections take you through the same steps as clicking Guide me.

Update product tutorial

This tutorial shows you how to update a product in a catalog.


For step-by-step guidance for this task directly in the Cloud Shell Editor, click Guide me:

Guide me


The following sections take you through the same steps as clicking Guide me.

Delete product tutorial

This tutorial shows you how to delete a product from a catalog.


For step-by-step guidance for this task directly in the Cloud Shell Editor, click Guide me:

Guide me


The following sections take you through the same steps as clicking Guide me.

Upload a product

curl

Create a single product item by using the products.create REST method.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
      "title": "PRODUCT_TITLE",
      "categories": "Shoes & Accessories > Shoes"
    }' \
    "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products?productId=PRODUCT_ID"

If the request is successful, the product object is returned, such as in the following example.

{
  "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID",
  "id": "PRODUCT_ID",
  "primaryProductId": "PRODUCT_ID",
  "type": "PRIMARY",
  "categories": [
    "Shoes & Accessories \u003e Shoes"
  ],
  "title": "product title",
  "availability": "IN_STOCK"
}

Java

public static Product createProduct(Product productToCreate, String productId)
    throws IOException {
  return getProductServiceClient().createProduct(
      DEFAULT_BRANCH_NAME, productToCreate, productId
  );
}

Update product information

As your product catalog changes, you can refresh your catalog by uploading changes in products such as new products, prices, and stock status in real time. You can upload only products that have been added or changed; you do not need to reload your entire catalog.

curl

Update product information by using the products.patch method.

The following example updates the title for a specific product:

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
       "title": "new-title-value"
    }" \
    "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID?updateMask=title"

If the request is successful, the product object is returned, such as in the following example.

{
  "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID",
  "id": "PRODUCT_ID",
  "primaryProductId": "PRODUCT_ID",
  "type": "PRIMARY",
  "categories": [
    "Shoes & Accessories > Shoes"
  ],
  "title": "new product title",
  "availability": "IN_STOCK"
}

Java

public static Product updateProduct(Product productToUpdate) throws IOException {
  return getProductServiceClient().updateProduct(productToUpdate, FieldMask.getDefaultInstance());
}

Delete product information

Although the Retail API provides a way to delete products from your catalog, keep in mind that if you record a user event that relates to a product item that has been deleted, the Retail API cannot process the user event properly and it might be deleted. In addition, including historical catalog data improves the quality of your model and is critical for good recommendations and search results.

You should set the availability of obsolete products to OUT_OF_STOCK rather than deleting them.

curl

Delete a product by using the delete method, replacing PRODUCT_ID with the ID of the product you want to delete.

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID"

Java

public static void deleteProduct(String productName) throws IOException {
  getProductServiceClient().deleteProduct(productName);
}

Retrieve a product item

curl

You retrieve a product item by making a GET request to the products endpoint, replacing PRODUCT_ID with the ID of the product you want to retrieve:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"  \
    "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID"

You should see output similar to the following:

{
    "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID"
    "id": "PRODUCT_ID",
    "primaryProductId": "PRODUCT_ID",
    "type": "PRIMARY",
    "categories": [
      "Shoes & Accessories \u003e Shoes"
    ],
    "title": "product title",
    "availability": "IN_STOCK"
}

Java

public static Product getProduct(String productName) throws IOException {
  return getProductServiceClient().getProduct(productName);
}

View aggregated information about your catalog

You can view aggregated information about your catalog and preview uploaded product items in the in the Catalog tab on the Retail Data page.

Change product types

When importing a product, you can specify if the product's type is primary, variant, or a collection. If a product's type changes or was specified incorrectly, you must delete the product and create it it with the updated type specified.

A product's type can be set to TYPE_UNSPECIFIED, PRIMARY, VARIANT, or COLLECTION. For more details, see product.Type in the reference documentation.

Change product level configuration

When importing a catalog with Merchant Center, you must specify if the products are primaries or variants. If these product levels change or were specified incorrectly, use the procedure below to correct their configuration. You must have the Retail Admin IAM role to complete this procedure.

  1. Make sure no imports are occurring while you reconfigure the product levels. This ensures data does not get uploaded at the wrong level.

  2. Delete all product items. See products.delete. The catalog must be completely empty before proceeding to the next step.

  3. Re-import your data to change the product level configuration.

    This procedure depends on how you import. Follow the appropriate procedure in Import Catalog Information to set the product levels to their new configuration.

  4. Finish importing the new catalog with the modified level configuration, using your chosen procedure in Import Catalog Information.

  5. Tune all existing models.

    To tune a model, go to the Models page, click the model name to view its details page, then click Manual Tune in the button bar.

    Go to the Retail Models page

    For tuning cost details, see Pricing.