Product collections

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.

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.

Note: Shoppable Images is currently the only ad format that supports collections. However, additional formats may be added so that you can re-use your collections across different ad formats.

Use 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).

Key Point: The imageLink field for collections accepts an array of image link values. However, only the first value in the array is used for the Shoppable Images format.

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.

Key Point: The headline field for collections accepts an array of headline values. However, only the first value in the array is used for the Shoppable Images format.

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

Warning: If a collection exists with the same id, making a request to collections.insert replaces the resource entirely.

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