Use supplemental feeds with the Content API

We would like to introduce the beta version of the Merchant API. It is the new version of the Content API for Shopping and the future.

For information about how Merchant API can improve your integration and how you can help shape the future, see Announcing the Merchant API Beta.

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

Note: You can only use supplemental feeds to update existing products.

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.

Warning: If you do not include feedId as a query parameter in your request, the method will behave like a regular products.insert call and completely replace all product data with the content of the request body. This means that existing values for any fields not included in the request will be deleted.

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

Note: By default, if the same product attributes are modified by multiple supplemental feeds, the values from the supplemental feed that was created last (not the feed that was updated last) are used for the product’s final attributes. For example, if values for the price field are provided via three supplemental feeds, the value from the feed that was created last will take precedence. You can customize how data from multiple feeds is merged by defining feed rules in Merchant Center.

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.

Warning: If you do not include feedId as a query parameter in your request, the product will be deleted and removed from your account.

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.

Warning: Do not insert and delete supplemental feed data for a single product in one custombatch call. The order of operations in custombatch is not guaranteed so making a dual call may either cancel itself out or cause unexpected behavior.

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