Use supplemental feeds with the Content API

  • The Merchant API is the new version of the Content API for Shopping and allows for partial product data updates using supplemental feeds.

  • Supplemental feeds enable adding or updating product data by using the feedId parameter with products.insert, products.delete, products.custombatch.insert, and products.custombatch.delete methods.

  • Using supplemental feeds to update product data only affects the specified fields, leaving other product data unchanged unless previously included in a request for the same feed.

  • When using the products.delete method with a supplemental feed, it removes only the supplemental data, reverting the product to its original state before the supplemental feed update.

  • The products.custombatch method enables making changes to multiple products in a single API call to reduce individual requests, but avoid combining insert and delete operations for the same product within a single batch call.

You can use supplemental feeds to make partial updates to product data by adding the feedId as a query parameter when making calls to the products.insert, products.delete, products.custombatch.insert, and products.custombatch.delete methods.

For example, you can make a products.insert supplemental feed method call to the following URL:

POST https://shoppingcontent.googleapis.com/content/v2.1/merchantId/products?feedId=feedId

products.insert

The supplemental feed products.insert method adds the product fields you send in the request body, overwriting those fields if they exist. When using a supplemental feed, this method leaves all other product fields unchanged, unless the fields had been included in a previous request for the same feed. While data added via other feeds is not affected, each request overwrites the previous requests for the same feed. This means that if you add or update a field via a supplemental feed request, and then do not include the field in a subsequent request, the data for the omitted field is removed from the feed. This behavior differs from calling products.insert without a supplemental feed, which deletes all existing product data and replaces it with the fields you send in the request body.

Use the following URL to make a request to the supplemental feed Product.insert service:

POST https://shoppingcontent.googleapis.com/content/v2.1/merchantId/products?feedId=feedId

You must include the offerId, feedLabel, channel, and contentLanguage fields in the request body. All other fields are optional.

Example

To change the availability of a product from “in stock” to “out of stock”, you could use the following request body to make a supplemental feeds Product.insert method call:

{
 "offerId": "1111111111",
 "contentLanguage": "en",
 "feedLabel": "US",
 "channel": "online",
 "availability": "out of stock",
}

products.delete

The products.delete method removes all of the supplemental data that was previously added by products.insert calls using the specified supplemental feed. Calling this method for a supplemental feed does not affect the original product data added before the supplemental feed Product.insert call(s) were made. You can think of this like removing a layer of data for a specific feed; the data added via other feeds is unaffected, and the product effectively reverts to its previous state before the supplemental feed layer was added. This differs from calling products.delete without a supplemental feed, which deletes the entire product and all of its data.

Use the following URL to make a request the supplemental feed products.delete service, where the productId is the REST ID of the product, represented as: channel:contentLanguage:feedLabel:offerId:

DELETE https://shoppingcontent.googleapis.com/content/v2.1/merchantId/products/productId?feedId=feedId

No request body is needed for supplemental feeds products.delete method calls.

products.custombatch

The custombatch methods allow you to insert or delete supplemental feed data for multiple products using a single API call to minimize the number of API calls made.

Use the following request URL to make a custombatch call:

https://shoppingcontent.googleapis.com/content/v2.1/products/batch

For all supplemental feed custombatch calls, you must include the batchId, merchantID, method, and feedId parameters in the request body.

products.custombatch:insert

When making supplemental feed calls to the products.custombatch:insert method, you must include the offerId, feedLabel, channel, and contentLanguage in the request body, in addition to the required batchId, merchantID, and method parameters. All other product fields are optional.

Example

To update the price value for two existing products, you could use the following request to make a products.custombatch:insert method call:.

{
  "entries": [
    {
      "batchId": 1111,
      "merchantId": 1234567,
      "method": "insert",
      "feedId": "7654321",
      "product": {
         "offerId": "1111111111",
         "contentLanguage": "en",
         "targetCountry": "US",
         "feedLabel": "US",
         "channel": "online",
         "price": {
          "value": "30.99",
          "currency": "USD"
         }
      }
    },
    {
      "batchId": 1112,
      "merchantId": 1234567,
      "method": "insert",
      "feedId": "7654321",
      "product": {
         "offerId": "2222222222",
         "contentLanguage": "en",
         "targetCountry": "US",
         "feedLabel": "US",
         "channel": "online",
         "price": {
          "value": "33.99",
          "currency": "USD"
         },
      },
    }
}

products.custombatch:delete

To remove all updates made to two products via a specified supplemental feed, you could use the following request to make a products.custombatch:delete method call:

{
  "entries": [
    {
      "batchId": 1115,
      "merchantId": 1234567,
      "method": "delete",
      "feedId": "7654321",
      "productId": "online:en:US:1111111111"
    },
    {
      "batchId": 1116,
      "merchantId": 1234567,
      "method": "delete",
      "feedId": "7654321",
      "productId": "online:en:US:2222222222"
    }
  ]
}
Previous
Create supplemental feeds
Next
Use feed rules