[Product collections](https://support.google.com/merchants/answer/9699507) let you
define groups of products to use with rich formats, such as
[Shoppable Images](https://support.google.com/merchants/answer/9700018). 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]
> **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](https://support.google.com/merchants/answer/9455869).

### Example: Create a collection for Shoppable Images

[Shoppable Images](https://support.google.com/merchants/answer/9700018) 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](https://developers.google.com/shopping-content/reference/rest/v2.1).

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

> [!IMPORTANT]
> **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`](https://developers.google.com/shopping-content/reference/rest/v2.1/products#Product.FIELDS.offer_id)
field that is part of the `featuredProduct` object must match the `offerId`
value on the `products` resource, which is different from the
[`id`](https://developers.google.com/shopping-content/reference/rest/v2.1/products#Product.FIELDS.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.

> [!IMPORTANT]
> **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]
> **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"
        }
      ]
    }