Use multi-image templates in product ads

With multi-image templates, you can swap up to 20 multiple images during live campaigns that contain different variations of product SKU images, image backgrounds, pricing, inventory details, and messaging.

The process involves six steps:

Modify your catalog feed with up to 20 image URL columns and corresponding image tag columns that make up multi-image templates.
Upload the feed that includes the multi-image templates you added.
Reference the added templates and tags in a product group promotion (PGP).
Make sure that the ad group to which you are linking this PGP has creative optimization disabled (if it is currently enabled).
Preview your shopping ads.

Before you begin

Make sure you do the following, if you have not already:

Generate an OAuth access token with the
ads_write
scope.
Create an ad group to link to the PGP.

Step 1: Define your image links and tags

Multi-Image templates are pairings of indexed asset links and tags for which you provide promotional messages. You can define the pairings using the catalog API or a catalog feed.

Use the API

POST

Operate on item batch

With this endpoint, you can make requests to create, update, upsert (create and update), or delete batches of catalog items. See Modify items in batch to learn how different batch operations work. The following example shows a batch creation request.

Parameters to keep in mind

These parameters are essential for multi-image items, regardless of the operation.

Any parameters and code examples that appear in this section support this use case, but may not represent the full endpoint specification. See the endpoint reference page for the comprehensive spec.

Batch API
Parameter	Description and requirements
`ad_image_X_link` Restricted	Link to an ad image. You can add up to 20 columns, with the first numbered `0` and the 20th numbered `19` . Example headings: `ad_image_0_link` … `ad_image_19_link` . Each link is 2000 characters or less and starts with `http://` or `https://` . Each image is at least 75 by 75 pixels. If you replace the image, you must also change the link for the update to occur.
`ad_image_X_tag` Restricted	Message tag for the corresponding image. You can add up to 20 columns, with the first numbered `0` and the 20th numbered `19` . Example headings: `ad_image_0_tag` … `ad_image_19_tag` . Maximum length is 511 characters. Must be unique per item. Tags are case-insensitive. As the following examples show, you can use the same tag for more than one image.

Example request


curl --request POST \
  --url https://api.pinterest.com/v5/catalogs/items/batch \
  --header 'authorization: Bearer pina_ABCD1234...' \
  --header 'content-type: application/json' \
  --data '{
  "catalog_type": "RETAIL",
  "catalog_id": "4672924420296",
  "country": "AD",
  "language": "af-ZA",
  "items": [
    {
      "item_id": "DS0294-M",
      "operation": "CREATE",
      "attributes": {
        "ad_image_0_link": "https://www.example.com/image/image_v2.jpg",
        "ad_image_1_link": "https://www.example.com/image/image_v2.jpg",
        "ad_image_2_link": "https://www.example.com/image/image_v2.jpg",
        "ad_image_0_tag": "black friday",
        "ad_image_1_tag": "black friday",
        "ad_image_2_tag": "black friday"
      }
    }
  ]
}'

See batch operation examples to understand how batch endpoint responses are structured.

Use a catalog feed

First, add columns to your feed

To include additional media assets in your product group, add the following columns to your catalog feed .

You can add up to 20 image/link pairings.

These assets are only promotional and are not organically distributed.

Multi-image columns
Column name	Description and requirements
`ad_image_X_link`	Link to an ad image. You can add up to 20 columns, with the first numbered `0` and the 20th numbered `19` . Example headings: `ad_image_0_link` … `ad_image_19_link` . Each link is 2000 characters or less and starts with `http://` or `https://` . Each image is at least 75 by 75 pixels. If you replace the image, you must also change the link for the update to occur.
`ad_image_X_tag`	Message tag for the corresponding image. You can add up to 20 columns, with the first numbered `0` and the 20th numbered `19` . Example headings: `ad_image_0_tag` … `ad_image_19_tag` . Maximum length is 511 characters. Must be unique per item. Tags are case-insensitive.

Make sure each image link must has a corresponding tag link. For example, the

ad_image_0_link

column must have a corresponding

ad_image_0_tag

column.

Make sure each image link must has a corresponding tag link. For example, the

ad_image_0_link

column must have a corresponding

ad_image_0_tag

column.

Feed example

Note that columns for ad image/tag pairings are side by side:

Next, upload the feed

Upload the product feed that includes the multi-image templates you added.

POST

Create feed

See Manage with a feed.

Step 2: Reference multi-image templates in PGPs

A product group promotion (PGP) links a catalog product group to an ad group, so the ads in the linked ad group can include the images in the product group.

In this step, you reference the image/tag pairings in a product group promotion.

POST

Create product group promotions

PATCH

Update product group promotions

Any parameters and code examples that appear in this section support this use case, but may not represent the full endpoint specification. See the endpoint reference page for the comprehensive spec.

Request parameters to keep in mind

These fields are optional in that they are not necessary for the request to be successful, but they are necessary for this use case.

PGP with multi-image
Parameter name	Description and requirements
`selected_image_tag` string	Select a specific image tag from your feed. Maximum length is 511 characters. To use this parameter make sure to disable the following features: Background generation (See `is_generate_background` parameter below.) Creative optimization (See Step 4.)
`is_generate_background` string	Set to `false` . You cannot create a PGP with `selected_image_tag` with background generation enabled.
`preferred_media_type` string	Select `IMAGE` .
`ad_group_id` string	Identifier for ad group that you are linking to this PGP. Call GET List ad groups to see all your available ad groups.

Example request


POST /ad_accounts/{ad_account_id}/product_group_promotions


{
  "product_group_promotion": [
    {
      "catalog_product_group_name": "catalogProductGroupName1",
      "catalog_product_group_id": "3672924420295",
      "tracking_url": "https://www.pinterest.com",
      "creative_type": "SHOPPING",
      "status": "ACTIVE",
      "selected_image_tag": "blackFriday"
    }
  ],
  "ad_group_id": "2680059592705"
}

Response field to keep in mind

A successful request returns an

id

, which is the PGP ID that you will reference when previewing the shopping ads.

Step 3: Disable creative optimization if enabled

You cannot create a PGP with

selected_image_tag

with creative optimization enabled in the linked ad group.

Make sure that the ad group to which you are linking this PCP has creative optimization disabled by setting the ad group"s

is_creative_optimization

false

See Create campaigns and ad groups.

Step 4: Preview the shopping ads with the multiple images

Generate a URL for a Pinterest-hosted preview page, where you can make sure the ads look as you want them to with multiple images.

You can preview shopping, carousel, and collection ads for the catalog sales objective. The API generates a URL that directs users to a preview page hosted by Pinterest.

POST

Create ad preview with pin or image

Any parameters and code examples that appear in this section support this use case, but may not represent the full endpoint specification. See the endpoint reference page for the comprehensive spec.

Preview ads
Parameter name	Description and requirements
`catalog_product_group_id` string required	Catalog product group id returned when you set up the product group promotion. Example: `123-456-789`
`image_tag` string	Multi-image template tag associated with the catalog products. Example: `Christmas Sale`
`preferred_media_type` string	Select `IMAGE` .
`creative_type` string	Select a format of the shopping ad preview: `SHOPPING` `CAROUSEL` `COLLECTION`
`preferred_media_type` string	Select `IMAGE` .
`item_id` string	Item ID for product to preview standard shopping ads. Only for `SHOPPING` creative type. Example: `111111`
`customizable_cta_type` string	Apply a call-to-action to the ad: `SHOP_NOW` `BOOK_NOW` `GET_DEAL` `ON_SALE`
`hero_pin_id` string	Pin ID for the hero image. Only for `COLLECTION` ad format. Example: `987654321`
`hero_image_url` string	Hero image link. Only for `COLLECTION` ad format. Example: `https://somewebsite.com/someimage.jpg`
`hero_image_title` string	Title of the ad copy. Required for the `COLLECTION` ad format if `hero_pin_id` is not present. Example: `My Preview Image`

Example request for shopping ad format

A request to preview a standard Shopping Ad incorporates an associated template, such as

Christmas Sale

in this example:


POST https://api.pinterest.com/v5/ad_accounts/{advertiser_id}/ad_previews{"catalog_product_group_id": '123-456-789',"image_tag": 'Christmas Sale',"creative_type": SHOPPING,“item_id” :’1111111’,“customizable_cta_type”:’SHOP_NOW’}

Example request for collection ad format with a hero Pin ID


POST https://api.pinterest.com/v5/ad_accounts/{advertiser_id}/ad_previews{"catalog_product_group_id": '123-456-789',"image_tag": 'Christmas Sale',"creative_type": 'COLLECTION',“hero_pin_id”:'987654321'}

Example request for collection ad format with hero image URL and title


POST https://api.pinterest.com/v5/ad_accounts/{advertiser_id}/ad_previews{"catalog_product_group_id": '123-456-789',"image_tag": 'Christmas Sale',"creative_type": 'COLLECTION',“hero_image_url”:'https://somewebsite.com/someimage.jpg',“hero_image_title”:'My Preview Image'}

Example response

A successful request returns a URL for the ad preview page, where you can see the ad.


{
  "url": "https://ads.pinterest.com/ad-preview/68cb6cfce60580449cd44290c68db953136269eb57d8bc522f5db0cbc4682b7e/"
}

Was this page helpful?

Batch API

Parameter

Description and requirements

ad_image_X_link

Restricted

Link to an ad image.

You can add up to 20 columns, with the first numbered
0
and the 20th numbered
19
.
Example headings:
ad_image_0_link
…
ad_image_19_link
.
Each link is 2000 characters or less and starts with
http://
or
https://
.
Each image is at least 75 by 75 pixels.
If you replace the image, you must also change the link for the update to occur.

ad_image_X_tag

Restricted

Message tag for the corresponding image.

You can add up to 20 columns, with the first numbered
0
and the 20th numbered
19
.
Example headings:
ad_image_0_tag
…
ad_image_19_tag
.
Maximum length is 511 characters. Must be unique per item. Tags are case-insensitive.
As the following examples show, you can use the same tag for more than one image.

curl --request POST \
  --url https://api.pinterest.com/v5/catalogs/items/batch \
  --header 'authorization: Bearer pina_ABCD1234...' \
  --header 'content-type: application/json' \
  --data '{
  "catalog_type": "RETAIL",
  "catalog_id": "4672924420296",
  "country": "AD",
  "language": "af-ZA",
  "items": [
    {
      "item_id": "DS0294-M",
      "operation": "CREATE",
      "attributes": {
        "ad_image_0_link": "https://www.example.com/image/image_v2.jpg",
        "ad_image_1_link": "https://www.example.com/image/image_v2.jpg",
        "ad_image_2_link": "https://www.example.com/image/image_v2.jpg",
        "ad_image_0_tag": "black friday",
        "ad_image_1_tag": "black friday",
        "ad_image_2_tag": "black friday"
      }
    }
  ]
}'

Multi-image columns

Column name

Description and requirements

ad_image_X_link

Link to an ad image.

You can add up to 20 columns, with the first numbered
0
and the 20th numbered
19
.
Example headings:
ad_image_0_link
…
ad_image_19_link
.
Each link is 2000 characters or less and starts with
http://
or
https://
.
Each image is at least 75 by 75 pixels.
If you replace the image, you must also change the link for the update to occur.

ad_image_X_tag

Message tag for the corresponding image.

You can add up to 20 columns, with the first numbered
0
and the 20th numbered
19
.
Example headings:
ad_image_0_tag
…
ad_image_19_tag
.
Maximum length is 511 characters. Must be unique per item. Tags are case-insensitive.

PGP with multi-image

Parameter name

Description and requirements

selected_image_tag

string

Select a specific image tag from your feed.

Maximum length is 511 characters.

To use this parameter make sure to disable the following features:

Background generation (See
is_generate_background
parameter below.)
Creative optimization (See Step 4.)

is_generate_background

string

Set to

false

You cannot create a PGP with

selected_image_tag

with background generation enabled.

preferred_media_type

string

Select

IMAGE

ad_group_id

string

Identifier for ad group that you are linking to this PGP.

Call

GET

List ad groups

to see all your available ad groups.

{
  "product_group_promotion": [
    {
      "catalog_product_group_name": "catalogProductGroupName1",
      "catalog_product_group_id": "3672924420295",
      "tracking_url": "https://www.pinterest.com",
      "creative_type": "SHOPPING",
      "status": "ACTIVE",
      "selected_image_tag": "blackFriday"
    }
  ],
  "ad_group_id": "2680059592705"
}

Preview ads

Parameter name

Description and requirements

catalog_product_group_id

string

required

Catalog product group id returned when you set up the product group promotion.

Example:

123-456-789

image_tag

string

Multi-image template tag associated with the catalog products.

Example:

Christmas Sale

preferred_media_type

string

Select

IMAGE

creative_type

string

Select a format of the shopping ad preview:

SHOPPING
CAROUSEL
COLLECTION

preferred_media_type

string

Select

IMAGE

item_id

string

Item ID for product to preview standard shopping ads.

Only for

SHOPPING

creative type.

Example:

111111

customizable_cta_type

string

Apply a call-to-action to the ad:

SHOP_NOW
BOOK_NOW
GET_DEAL
ON_SALE

hero_pin_id

string

Pin ID for the hero image.

Only for

COLLECTION

ad format.

Example:

987654321

hero_image_url

string

Hero image link. Only for

COLLECTION

ad format.

Example:

https://somewebsite.com/someimage.jpg

hero_image_title

string

Title of the ad copy.

Required for the

COLLECTION

ad format if

hero_pin_id

is not present.

Example:

My Preview Image

POST https://api.pinterest.com/v5/ad_accounts/{advertiser_id}/ad_previews{"catalog_product_group_id": '123-456-789',"image_tag": 'Christmas Sale',"creative_type": SHOPPING,“item_id” :’1111111’,“customizable_cta_type”:’SHOP_NOW’}

POST https://api.pinterest.com/v5/ad_accounts/{advertiser_id}/ad_previews{"catalog_product_group_id": '123-456-789',"image_tag": 'Christmas Sale',"creative_type": 'COLLECTION',“hero_pin_id”:'987654321'}

POST https://api.pinterest.com/v5/ad_accounts/{advertiser_id}/ad_previews{"catalog_product_group_id": '123-456-789',"image_tag": 'Christmas Sale',"creative_type": 'COLLECTION',“hero_image_url”:'https://somewebsite.com/someimage.jpg',“hero_image_title”:'My Preview Image'}