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.

Managing catalog information

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.

Uploading 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"
}

Updating 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"
}

Deleting 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"

Retrieving 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"
}

Viewing 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.

Rejoining catalog events

You can rejoin catalog events by making a POST request to the userEvents:rejoin endpoint.

You must have the Retail AI Admin IAM role.

curl

Set userEventRejoinScope according to the types of events you're rejoining:

  • USER_EVENT_REJOIN_SCOPE_UNSPECIFIED: Default. Trigger rejoin for both joined and unjoined events.
  • JOINED_EVENTS: Trigger rejoin for only joined events.
  • UNJOINED_EVENTS: Trigger rejoin for only unjoined events.

The following example triggers a rejoin for only unjoined events:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
     'userEventRejoinScope': 'UNJOINED_EVENTS'
     }" \
    "https://retail.googleapis.com/v2/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/userEvents:rejoin"

You should receive a response object that looks something like this:

{
  "name": "projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/operations/OPERATION_ID"
}

You can check the status of the rejoin. Replace OPERATION_ID with the ID of the operation ID returned by the rejoin method:

curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://retail.googleapis.com/v2/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/operations/OPERATION_ID"

When the operation completes, the operation status returns as done:

{
  "name": "projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/operations/OPERATION_ID",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.retail.v2.RejoinUserEventsResponse",
    "rejoinedUserEventsCount": "1"
  }
}

Changing 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][product-type] in the reference documentation.

Changing 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.

  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 Importing 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 Importing 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.