Update inventory for AI Commerce Search

This page outlines the methods for managing real-time price and quantity updates for the AI Commerce Search catalog using the AI Commerce Search API.

While the Product create, read, update, and delete (CRUD) methods are used to broadly modify a Product's attributes, there is a set of Product methods that can be used for updating inventory-specific fields with varying levels of granularity.

Understand inventory

In general terms, inventory usually refers to stock levels (quantity) and price for items on an ecommerce site. For the AI Commerce Search API, inventory refers to price, availability, available quantity, fulfillment information and local pricing and additional local attributes. These fields are defined in the Product schema with the following fields:

• Product.availability
• Product.availableQuantity
• Product.priceInfo
• Product.fulfillmentInfo
• Product.localInventories

Product-level inventory

For ecommerce site merchants with an online catalog only, inventory is usually represented as the products in the catalog only. Price, availability and all other data is set on each Product entry in the catalog. The fulfillmentInfo and localInventories fields aren't used.

Local inventory

For retailers that have multiple locations, products are still represented by the Product entries in the catalog, but local inventory (price, availability and fulfillment) can be added to locations (placeId) for a product with the addLocalInventories method.

There are two separate Product fields used for local inventory: Product.fulfillmentInfo and Product.localInventories. One or both can be used, depending on the requirements. Both fulfillmentInfo and localInventories are lists of locations with associated data.

fulfillmentInfo specifies how a product is fulfilled at a particular location, whereas localInventories specifies price and other custom attributes for each location.

To mark a product as out of stock or no longer available at a specific location, the removeLocalInventories method is used to remove fulfillment and inventory from a product for a particular placeId.

Inventory update methods

Changes to a product's inventory information may occur much more frequently than changes to its catalog information. As such, a specialized set of methods are provided to handle large volumes of inventory-specific updates. These methods are asynchronous because of downstream optimizations that support hundreds of concurrent updates per product, without sacrificing performance.

Incremental updates

Follow the local inventory updates guide to issue incremental inventory updates. The newer API methods provide more fine-grained control for per-place inventory attributes.

fulfillment_info is often used to encode place-level fulfillment availability for a Product. In some cases, fulfillment availability for some specific places can change. You can decide to issue updates that describe this change, instead of using the UpdateProduct method to respecify all the product's fulfillment information.

In such cases, the AddFulfillmentPlaces and RemoveFulfillmentPlaces methods can be used to incrementally update a product's fulfillment changes based on which place IDs are added or removed for a given fulfillment type.

public static AddFulfillmentPlacesResponse addFulfillmentPlaces(
    Product productToUpdate, String fulfillmentInfoType, ImmutableList<String> placeIds)
    throws IOException, InterruptedException, ExecutionException {
  ProductServiceClient productClient = getProductServiceClient();

  AddFulfillmentPlacesRequest request = AddFulfillmentPlacesRequest.newBuilder()
      .setProduct(productToUpdate.getName())
      .setType(fulfillmentInfoType)
      .addAllPlaceIds(placeIds)
      .setAddTime(Timestamps.fromMillis(System.currentTimeMillis()))
      .build();

  AddFulfillmentPlacesResponse response = productClient
      .addFulfillmentPlacesAsync(request).get();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;
}

  {
    product: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
    type: "pickup-in-store"
    place_ids: "store0"
    place_ids: "store1"
    add_time: {
      seconds: 100
      nanos: 100
    }
    allow_missing: true
  }
  

This sample AddFulfillmentPlacesRequest adds fulfillment type "pickup-in-store" to place IDs "store0" and "store1" for the specified product. Because AddFulfillmentPlacesRequest.allow_missing is set to true, even if the product does not already exist, the updated inventory information will be stored for when the product is eventually created. The update is time stamped with AddFulfillmentPlacesRequest.add_time to prevent stale updates from overriding the fulfillment status of these place IDs. These features are discussed in greater detail in the following sections.

The behavior is identical for RemoveFulfillmentPlacesRequest and the schema is very similar.

When fulfillment_types is updated by AddLocalInventories and RemoveLocalInventories, it reflects a mapping from each place ID to a list of fulfillment types it supports. When fulfillment_info is updated by AddFulfillmentPlaces and RemoveFulfillmentPlaces, it reflects a mapping from each specific fulfillment type to a list of place IDs that supports each type. Both API types are modifying the same underlying fulfillment information, and the effect of both types of APIs is reflected by Product.fulfillment_info.

Non-incremental updates

The price_info, availability, and available_quantity methods can't be incrementally updated, because they represent product-level inventory, not place-level information. It can also be good to issue non-incremental updates to fulfillment_info. Instead of only incremental changes, SetInventory is recommended.

The setInventory method is the preferred way to update price, availability, and quantity at the product level when many, frequent updates required. The setInventory method is asynchronous, so the updates might not happen immediately. The default quota (300,000 requests per minute) supports much more requests than UpdateProduct.

Additionally, the setInventory method is used for local fulfillment updates when fulfillmentInfo is included in the request, but it can't update the localInventories fields. For those attributes, use the addLocalInventories and removeLocalInventories methods.

Local inventory is saved at the store-level, independent of the catalog. For customers with online and offline inventory, the main product catalog can be used for online or a specific placeId (-1 or online for example) could be used to represent online inventory. However, use the main catalog for online inventory because the product inventory fields should be populated with valid priceInfo and availability values. If a separate inventory placeId is used for online, then the main catalog price and availability information should also be kept up to date. For more on local inventory updates, see Update local inventory.

public static SetInventoryResponse setInventoryWithMask(Product productToUpdate,
    FieldMask updateMask)
    throws IOException, ExecutionException, InterruptedException {
  ProductServiceClient productClient = getProductServiceClient();

  SetInventoryRequest request = SetInventoryRequest.newBuilder()
      .setInventory(productToUpdate)
      .setSetMask(updateMask)
      .setSetTime(Timestamps.fromMillis(System.currentTimeMillis()))
      .setAllowMissing(true)
      .build();

  SetInventoryResponse response = productClient.setInventoryAsync(request).get();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;
}

  {
    product: {
      name: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
      availability: IN_STOCK
      fulfillment_info: {
        type: "pickup-in-store"
        place_ids: "store0"
        place_ids: "store1"
        place_ids: "store2"
        place_ids: "store3"
      }
      fulfillment_info: {
        type: "same-day-delivery"
      }
    }
    set_time: {
      seconds: 100
      nanos: 100
    }
    set_mask: {