We will sunset v2 of the Content API on March 29th, 2021. To avoid disruptions with your integration, please migrate to v2.1 as soon as possible. For more information, see Migrating to v2.1.

Product Collections

Product collections let you define groups of products to use with rich formats, such as Shoppable Images. Each collection can include up to 100 products. You can create a collection with either the Google Merchant Center or the Content API.

This guide shows how to use product collections through the Content API, including examples for how to create a collection for Shoppable Images and how to check the status of a collection.

Using product collections

The Content API includes two services to manage product collections:

  • Collections: Lets you get, list, insert, and delete product collections.

  • CollectionStatuses: Lets you get and list the status of collections to discover whether a collection has any issues that may cause the collection to be invalid for a destination, such as Shopping Ads.

Example: Create a collection for Shoppable Images

Shoppable Images are high- quality images which show one or more annotated products, and are configured using collections. To use Shoppable Images, you must specify values for the imageLink and featuredProduct fields, in addition to the fields required for all collections. For more information about required fields, see the Content API reference documentation.

To use Shoppable Images, you must create a collection of products and use the imageLink field to specify an image that contains up to ten products. We recommend using square images (with a 1:1 aspect ratio).

You must also specify the products displayed in the image using the featuredProduct field, including the coordinates of the products in the image using the x and y fields. These fields are only required for collections used with Shoppable Images. The x and y values must be between 0 and 1, inclusive.

Each collection can include a maximum of 100 products. However, for Shoppable Images, we recommend that you specify coordinates for no more than 10 products per image to ensure that there is enough space on the image to show the product callouts. The offerId field that is part of the featuredProduct object must match the offerId value on the products resource, which is different from the id value on the products resource.

In addition to the imageLink and featuredProduct fields, which are required for Shoppable Images, you can also specify a collection headline using the optional headline field. We recommend including a headline to provide customers with additional details about the collection.

To create a new collection for Shoppable Images, make a POST request to the Collections.insert endpoint using the following URL and request body:

https://shoppingcontent.googleapis.com/content/v2.1/merchantId/collections
{
  "id": "exampleCollection"
  "language": "en",
  "productCountry": "UK",
  "imageLink": ["www.imageLink.example"],
  "featuredProduct": [
{
  "offerId": '432',
  "x": 0.11,
  "y": 0.99
},
{ "offerId": '433',
  "x": 0.53,
  "y": 0.89
}
],
  "link": "www.link.example",
  "mobileLink": "www.mobileLink.example",
  "headline": "www.link.example",
  "customLabel0": "Organize",
  "customLabel1": "Your",
  "customLabel2": "Bidding/Reporting",
  "customLabel3": "With",
  "customLabel4": "Me"
}

Example: Check the status of a collection

To discover whether the collection you created above has issues that would invalidate the collection from serving ads, make a GET request to the CollectionsStatuses.get endpoint using the following URL, and include the id of the collection whose status you want to retrieve. You do not have to provide a request body.

https://shoppingcontent.googleapis.com/content/v2.1/merchantID/collectionstatuses/collection ID

Example collection status response

{
  "id": "exampleCollection",
  "creationDate": "2020-09-22T00:26:51Z",
  "lastUpdateDate": "2020-09-22T00:26:51Z",
  "collectionLevelIssues": [
    {
      "code": "invalid_url",
      "servability": "unaffected",
      "resolution": "merchant_action",
      "attributeName": "link",
      "description": "Invalid URL [link]",
      "detail": "Use a complete URL that starts with http:// or https:// and
          links to a valid destination such as an image or a landing page",
      "documentation": "https://support.google.com/merchants/answer/7052112"
    },
    {
      "code": "invalid_url",
      "servability": "unaffected",
      "resolution": "merchant_action",
      "attributeName": "imageLink",
      "description": "Invalid URL [imageLink]",
      "detail": "Use a complete URL that starts with http:// or https:// and
          links to a valid destination such as an image or a landing page",
      "documentation": "https://support.google.com/merchants/answer/7052112"
    }
  ]
}