Managing catalog information

This page describes how to manage your product information after you have imported a catalog into Recommendations AI. 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",
       "categories": "Shoes & Accessories > Shoes"
    }" \
    "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 \u003e Shoes"
  ],
  "title": "new product title",
  "availability": "IN_STOCK"
}

Deleting product information

Although Recommendations AI 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, Recommendations AI 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 prediction performance.

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 item 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 Recommendations AI Data page.

Recommendations AI Catalog Import Data

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.v2main.RejoinUserEventsResponse",
    "rejoinedUserEventsCount": "1"
  }
}

Changing product level configuration

When importing a catalog, you must specify if the catalog items 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 Recommendations AI Admin IAM role.

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

  2. If you plan to change event catalog item levels, purge all user events using the purge method.

  3. Delete all product items. See Deleting product items.

  4. Change the product level configuration.

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

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

  6. 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 Recommendations AI Models page

    For tuning cost details, see Pricing.