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.branches.products.addLocalInventories

Updates local inventory information for a Product at a list of places, while respecting the last update timestamps of each inventory field.

This process is asynchronous and does not require the Product to exist before updating inventory information. If the request is valid, the update will be enqueued and processed downstream. As a consequence, when a response is returned, updates are not immediately manifested in the Product queried by ProductService.GetProduct or ProductService.ListProducts.

Local inventory information can only be modified using this method. ProductService.CreateProduct and ProductService.UpdateProduct has no effect on local inventories.

This feature is only available for users who have Retail placements.search enabled. Please enable Retail placements.search on Cloud Console before using this feature.

HTTP request

POST https://retail.googleapis.com/v2/{product=projects/*/locations/*/catalogs/*/branches/*/products/**}:addLocalInventories

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
product

string

Required. Full resource name of Product, such as projects/*/locations/global/catalogs/default_catalog/branches/default_branch/products/some_product_id.

If the caller does not have permission to access the Product, regardless of whether or not it exists, a PERMISSION_DENIED error is returned.

Request body

The request body contains data with the following structure:

JSON representation
{
  "localInventories": [
    {
      object (LocalInventory)
    }
  ],
  "addMask": string,
  "addTime": string,
  "allowMissing": boolean
}
Fields
localInventories[]

object (LocalInventory)

Required. A list of inventory information at difference places. Each place is identified by its place ID. At most 3000 inventories are allowed per request.

addMask

string (FieldMask format)

Indicates which inventory fields in the provided list of LocalInventory to update. The field is updated to the provided value.

If a field is set while the place does not have a previous local inventory, the local inventory at that store is created.

If a field is set while the value of that field is not provided, the original field value, if it exists, is deleted.

If the mask is not set or set with empty paths, all inventory fields will be updated.

If an unsupported or unknown field is provided, an INVALID_ARGUMENT error is returned and the entire update will be ignored.

This is a comma-separated list of fully qualified names of fields. Example: "user.displayName,photo".

addTime

string (Timestamp format)

The time when the inventory updates are issued. Used to prevent out-of-order updates on local inventory fields. If not provided, the internal system time will be used.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

allowMissing

boolean

If set to true, and the Product is not found, the local inventory will still be processed and retained for at most 1 day and processed once the Product is created. If set to false, a NOT_FOUND error is returned if the Product is not found.

Response body

If successful, the response body contains an instance of Operation.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the product resource:

  • retail.products.update

For more information, see the IAM documentation.

LocalInventory

The inventory information at a place (e.g. a store) identified by a place ID.

JSON representation
{
  "placeId": string,
  "priceInfo": {
    object (PriceInfo)
  },
  "attributes": {
    string: {
      "text": [
        string
      ],
      "numbers": [
        number
      ],
      "searchable": boolean,
      "indexable": boolean
    },
    ...
  },
  "fulfillmentTypes": [
    string
  ]
}
Fields
placeId

string

The place ID for the current set of inventory information.

priceInfo

object (PriceInfo)

Product price and cost information.

Google Merchant Center property price.

attributes[]

map (key: string, value: object)

Additional local inventory attributes, for example, store name, promotion tags, etc.

This field needs to pass all below criteria, otherwise an INVALID_ARGUMENT error is returned:

  • At most 30 attributes are allowed.
  • The key must be a UTF-8 encoded string with a length limit of 32 characters.
  • The key must match the pattern: [a-zA-Z0-9][a-zA-Z0-9_]*. For example, key0LikeThis or KEY_1_LIKE_THIS.
  • The attribute values must be of the same type (text or number).
  • Only 1 value is allowed for each attribute.
  • For text values, the length limit is 256 UTF-8 characters.
  • The attribute does not support search. The searchable field should be unset or set to false.
  • The max summed total bytes of custom attribute keys and values per product is 5MiB.
attributes[].text[]

string

The textual values of this custom attribute. For example, ["yellow", "green"] when the key is "color".

Empty string is not allowed. Otherwise, an INVALID_ARGUMENT error is returned.

Exactly one of text or numbers should be set. Otherwise, an INVALID_ARGUMENT error is returned.

attributes[].numbers[]

number

The numerical values of this custom attribute. For example, [2.3, 15.4] when the key is "lengths_cm".

Exactly one of text or numbers should be set. Otherwise, an INVALID_ARGUMENT error is returned.

attributes[].searchable
(deprecated)

boolean

This field is normally ignored unless [AttributesConfig.attribute_config_level][] of the Catalog is set to the deprecated 'PRODUCT_LEVEL_ATTRIBUTE_CONFIG' mode. For information about product-level attribute configuration, see Configuration modes. If true, custom attribute values are searchable by text queries in SearchService.Search.

This field is ignored in a UserEvent.

Only set if type text is set. Otherwise, a INVALID_ARGUMENT error is returned.

attributes[].indexable
(deprecated)

boolean

This field is normally ignored unless [AttributesConfig.attribute_config_level][] of the Catalog is set to the deprecated 'PRODUCT_LEVEL_ATTRIBUTE_CONFIG' mode. For information about product-level attribute configuration, see Configuration modes. If true, custom attribute values are indexed, so that they can be filtered, faceted or boosted in SearchService.Search.

This field is ignored in a UserEvent.

See SearchRequest.filter, SearchRequest.facet_specs and SearchRequest.boost_spec for more details.

fulfillmentTypes[]

string

Input only. Supported fulfillment types. Valid fulfillment type values include commonly used types (such as pickup in store and same day delivery), and custom types. Customers have to map custom types to their display names before rendering UI.

Supported values:

  • "pickup-in-store"
  • "ship-to-store"
  • "same-day-delivery"
  • "next-day-delivery"
  • "custom-type-1"
  • "custom-type-2"
  • "custom-type-3"
  • "custom-type-4"
  • "custom-type-5"

If this field is set to an invalid value other than these, an INVALID_ARGUMENT error is returned.

All the elements must be distinct. Otherwise, an INVALID_ARGUMENT error is returned.