Generate dynamic product titles

Open beta

You can improve catalog campaign performance with AI-generated product titles that change automatically based on rules, feed attributes, or campaign context. With this capability, the promoted item can show a more relevant headline at any given time.

A dynamic title can pull in product data such as color, size, brand, discount, season, or custom labels and adapt across many products instead of requiring manual title edits for each item.

How it works

You enable this feature when creating or updating a product group promotion. Pinterest generates a .csv file listing all possible dynamically generated titles. You have the option to review the list, approving or rejecting each title, or you can allow publication of the AI-generated titles without a review.

If you choose to review the titles, you go through a series of steps to download, review, and upload the file.

Before you start

Make sure you have the following prerequisites in place:

Dynamic title prerequisites
What you need	Why you need it	How to get it
OAuth token with `ads:read` and `ads:write` scopes	These ads scopes are required for the Pinterest API endpoints you will call.	Set up your OAuth token and learn about scopes.
Access to the dynamic titles feature	For this feature, you need explicit access.	Contact your Pinterest representative if you have not already been granted access.
Catalog shopping campaign with at least one ad group	If creating a new product group promotion, you will need to reference a parent ad group in a catalog shopping campaign.	Create campaigns and ad groups.
Pinterest advertiser account	For you to interact with any tools/endpoints related to campaigns, ad groups, and ads, your OAuth token must be related to a Pinterest advertiser ID.	Learn how to create an advertiser account.

Step 1: Enable dynamic titles

Enable generation of dynamic titles in a new or existing product group promotion. This action produces a .csv file listing all possible dynamic titles.

Endpoints

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

Parameters for enabling dynamic titles
Parameter	Description
`ad_account_id` string Required	Identify the account that owns the product group promotion.
`product_group_promotion.` `is_dynamic_titles` boolean Optional but necessary for this use case	Set to `true` to enable generation of dynamic titles.
`product_group_promotion.` `dynamic_titles_approval_type` string Optional but necessary for this use case	Set to `MANUAL` to require manual review of generated titles before they can be published. Select this option if you want more control over title content. Set to `AUTOMATIC` to publish and run AI-generated titles without manual review. If you select this option, you do not need to take any more steps to apply dynamic titles to product group promotions. However, you can still view the .csv list of dynamic titles for reference.
`product_group_promotion.` `ad_group_id` string Required	Identify the parent ad group for the product group promotion.

Example request


curl --request POST \
  --url https://api.pinterest.com/v5/ad_accounts/123456789012/product_group_promotions \
  --header 'authorization: Bearer pina_ABCD1234...' \
  --header 'content-type: application/json' \
  --data '{
  "ad_group_id": "2680090195657",
  "product_group_promotion": [
    {
      "catalog_product_group_id": "4672956004260",
      "catalog_product_group_name": "Most Popular",
      "creative_type": "SHOPPING",
      "grid_click_type": "DIRECT_TO_DESTINATION",
      "status": "ACTIVE",
      "is_image_auto_resizing": false,
      "is_generate_background": false,
      "is_dynamic_titles": true,
      "dynamic_titles_approval_type": "MANUAL"
    }
  ]
}'

Example response


{
  "items": [
    {
      "data": {
        "id": "4260609797873",
        "ad_group_id": "2680090493150",
        "creative_type": "SHOPPING",
        "status": "ACTIVE",
        "collections_header_type": null,
        "collections_hero_destination_url": null,
        "collections_hero_pin_id": null,
        "slideshow_collections_description": null,
        "slideshow_collections_title": null,
        "is_generate_background": false,
        "selected_image_tag": null,
        "selected_video_tag": null,
        "preferred_media_type": null,
        "is_image_auto_resizing": false,
        "bid_in_micro_currency": 0,
        "catalog_product_group_id": "4672956004260",
        "catalog_id": "4854522508133",
        "catalog_type": "RETAIL",
        "catalog_product_group_name": "Most Popular",
        "customizable_cta_type": "SHOP_NOW",
        "definition": "*/",
        "grid_click_type": "DIRECT_TO_DESTINATION",
        "is_mdl": false,
        "parent_id": "2680090493150",
        "relative_definition": "*/",
        "hide_installment_price": true,
        "is_dynamic_titles": true,
        "dynamic_titles_approval_type": "MANUAL"
      }
    }
  ]
}

Wait up to 48 hours for Pinterest to generate the titles before taking the next step.

If you selected the

MANUAL

option for

dynamic_titles_approval_type

in the preceding step, you need to take all of the following steps to download, review, and upload a .csv file containing the dynamic titles. If you selected the

AUTOMATIC

option, you can download and review the .csv file for your own reference, but do not upload it afterward.

If you selected the

MANUAL

option for

dynamic_titles_approval_type

in the preceding step, you need to take all of the following steps to download, review, and upload a .csv file containing the dynamic titles. If you selected the

AUTOMATIC

option, you can download and review the .csv file for your own reference, but do not upload it afterward.

Step 2: Check if the titles are available

Find out if the .csv list of dynamic titles is available for you to download and view.

Endpoint

GET

Get dynamic titles status

Example request

Pass your ad account and relevant ad group ID in the request URL:


GET /v5/ad_accounts/123456789012/ad_groups/1099511703602/dynamic_titles/status

Response fields

Response fields for checking csv
Field	Description
`is_ready` boolean	Whether the .csv list of titles is available for download and review.
`generated_count` integer	Total number of generated titles. Note that some products may have multiple title variants.
`reviewed_count` integer	Total number of validated approvals and rejections of dynamic titles. This field shows `0` at this stage and should show more than `0` at Step 9.

Example response


{ "is_ready": true, "generated_count": 987, "reviewed_count": 456 }

Step 3: Get the download URL for the list of titles

Endpoint

GET

Get dynamic titles CSV download URL

Example request

Pass your ad account and relevant ad group IDs in the request URL:


GET /v5/ad_accounts/123456789012/ad_groups/1099511703602/dynamic_titles/csv

Response field

Response fields for download URL
Field	Description
`download_url` string	Presigned AWS S3 URL for the review CSV; valid for one hour.

Example response


{
  "download_url": "https://s3.amazonaws.com/bucket/dynamic_titles/review.csv?AWSAccessKeyId=..."
}

Step 4: Download the list of titles

Submit a

GET

request to the presigned AWS S3 URL returned to you in the preceding step.

Example request


GET https://s3.amazonaws.com/bucket/dynamic_titles/review.csv?AWSAccessKeyId=...

The response is the .csv file.

Step 5: Review the list of titles

If you opted for manual approval in Step 1, you approve and reject titles for publication in this step. Otherwise, you can simply view the titles for reference.

Open the .csv file in a spreadsheet app, review the dynamic title(s) for each item, and mark whether you approve or reject each title (if you opted for manual approval). The file contains the following columns:

item id: Merchant item ID from the advertiser's catalog.
image url: URL for the displayed image of the item.
title: Advertiser's manually provided title for the item.
description: Advertiser's provided description of the item.
dynamic title: Title generated for the product, with the image, original title, and description are used as input. Do not manually change any titles in this column, or uploading the reviewed file will fail.
variant number: For any item with multiple generated titles, or variants, the identifier for one of the variants.
approval status: Whether you approve of the dynamic title for the item in a given row (mark y for "yes") or reject it and do not want it published (mark n for "no").
- Only enter y or n, uploading the reviewed file will fail. If you re-review the .csv and enter a blank approval status for a previously approved or rejected row, Pinterest will not change that status.
- If you reject a title, Pinterest does not replace it.
rejection reason: A brief note explaining why you rejected the title. This is purely informational for Pinterest and does not affect how the .csv file is processed.

See this example of a reviewed file, which shows two variants of a product dynamic title:

Step 6: Get an upload URL

Only take this step if you selected the

manual

option for

dynamic_titles_approval_type

in Step 1.

Only take this step if you selected the

manual

option for

dynamic_titles_approval_type

in Step 1.

After reviewing the list of titles you upload it for processing. In this step, get a URL for uploading the reviewed .csv file.

Endpoint

GET

Get dynamic titles upload URL

Example request

Pass your ad account and relevant ad group ID in the request URL:


GET /v5/ad_accounts/123456789012/ad_groups/1099511703602/dynamic_titles/uploads

Response fields

Response fields for upload URL
Field	Description
`upload_url` string	Presigned AWS S3 URL for uploading the reviewed .csv file The URL is valid for one hour.
`request_id` string	Upload session's unique identifier that must be passed to the endpoint for processing the reviewed .csv file.
`existing_file_name` string	Indicates whether a previously reviewed CSV exists for the affected ad group.

Example response


{
  "upload_url": "https://s3.amazonaws.com/bucket/dynamic_titles/candidate.csv?AWSAccessKeyId=...",
  "request_id": "549755814107-1099511703602-1714300000-abc123",
  "existing_filename": null
}

Step 7: Upload your reviewed .csv file

Only take this step if you selected the

manual

option for

dynamic_titles_approval_type

in Step 1.

Only take this step if you selected the

manual

option for

dynamic_titles_approval_type

in Step 1.

Submit a

PUT

request to the presigned AWS S3 URL returned to you in the preceding step. Reference the reviewed .csv file residing on your local drive.

Example request

In this example, the name of the file is

reviewed.csv


curl -X PUT "https://pinterest-waterloo.s3.amazonaws.com/..." \
  -H "Content-Type: text/csv" \
  --upload-file /path/to/reviewed.csv

Response

A successful upload returns an empty response body with an

ETag

header from S3.

Step 8: Submit the reviewed .csv file for processing

Only take this step if you selected the

manual

option for

dynamic_titles_approval_type

in Step 1.

Only take this step if you selected the

manual

option for

dynamic_titles_approval_type

in Step 1.

Endpoint

POST

Process dynamic titles CSV

Example request

In the request URL, pass your ad account ID, relevant ad group ID, and the request ID returned in Step 6.


POST /v5/ad_accounts/123456789012/ad_groups/1099511703602/dynamic_titles
{ "request_id": "549755814107-1099511703602-1714300000-abc123" }

Response fields

Response fields for submitting csv
Field	Description
`status` string	Validation status of `SUCCESS` that only appears when the request succeeds.
`errors` array of objects	Container for any reviewed titles that failed validation.
`errors.row_number` integer	The row in the .csv file containing a title review that failed validation.
`errors.error_type` string	Description of the validation failure.

Example response for a successful request.

When the request succeeds, the endpoint returns a validation status of

SUCCESS

and an empty

errors

array:


{
  "status": "SUCCESS",
  "errors": []
}

Example response for a request with errors

For a request with errors, the endpoint returns an

errors

array containing row numbers and descriptions for any errors in the .csv file:


{
  "errors": [
    {
      "row_number": 15,
      "error_type": "ROW_VALIDATION_FAILED"
    }
  ]
}

How reviews and validation work

Pinterest only serves a dynamic title if you explicitly approve it.

If your first submitted review fails for a title, Pinterest serves the title you manually provided for the item. However if, for example, your first submission successfully approves a row, and the second submission rejects that same row but fails validation, then Pinterest displays the title in that row.

Pinterest updates the serving of dynamic titles once a day. So, in the preceding case, you could see the second review (with the rejection) succeed but the rejected title could continue to serve for 24 hours.

Step 9: Verify completion of review validation

Only take this step if you selected the

manual

option for

dynamic_titles_approval_type

in Step 1.

Only take this step if you selected the

manual

option for

dynamic_titles_approval_type

in Step 1.

Endpoint

GET

Get dynamic titles status

Example request

Pass your ad account and relevant ad group ID in the request URL:


GET /v5/ad_accounts/123456789012/ad_groups/1099511703602/dynamic_titles/status

Response fields

Response fields for verifying completion
Field	Description
`is_ready` boolean	Whether the .csv list of titles is available for download and review.
`errors` array of objects	Container for any reviewed titles that failed validation.
`generated_count` integer	Total number of generated titles. Note that some products may have multiple title variants.
`reviewed_count` integer	Total number of validated approvals and rejections of dynamic titles. Approved titles are published within 24 hours.

Was this page helpful?

Dynamic title prerequisites
What you need	Why you need it	How to get it
OAuth token with `ads:read` and `ads:write` scopes	These ads scopes are required for the Pinterest API endpoints you will call.	Set up your OAuth token and learn about scopes.
Access to the dynamic titles feature	For this feature, you need explicit access.	Contact your Pinterest representative if you have not already been granted access.
Catalog shopping campaign with at least one ad group	If creating a new product group promotion, you will need to reference a parent ad group in a catalog shopping campaign.	Create campaigns and ad groups.
Pinterest advertiser account	For you to interact with any tools/endpoints related to campaigns, ad groups, and ads, your OAuth token must be related to a Pinterest advertiser ID.	Learn how to create an advertiser account.

Dynamic title prerequisites

What you need

Why you need it

How to get it

OAuth token with

ads:read

and

ads:write

scopes

These ads scopes are required for the Pinterest API endpoints you will call.

Set up your OAuth token and learn about scopes.

Access to the dynamic titles feature

For this feature, you need explicit access.

Contact your Pinterest representative if you have not already been granted access.

Catalog shopping campaign with at least one ad group

If creating a new product group promotion, you will need to reference a parent ad group in a catalog shopping campaign.

Create campaigns and ad groups.

Pinterest advertiser account

For you to interact with any tools/endpoints related to campaigns, ad groups, and ads, your OAuth token must be related to a Pinterest advertiser ID.

Learn how to create an advertiser account.

Parameters for enabling dynamic titles

Parameter

Description

ad_account_id

string
Required

Identify the account that owns the product group promotion.

product_group_promotion.

is_dynamic_titles

boolean
Optional but necessary for this use case

Set to

true

to enable generation of dynamic titles.

product_group_promotion.

dynamic_titles_approval_type

string
Optional but necessary for this use case

Set to

MANUAL

to require manual review of generated titles before they can be published. Select this option if you want more control over title content.

Set to

AUTOMATIC

to publish and run AI-generated titles without manual review. If you select this option, you do not need to take any more steps to apply dynamic titles to product group promotions. However, you can still view the .csv list of dynamic titles for reference.

product_group_promotion.

ad_group_id

string
Required

Identify the parent ad group for the product group promotion.

curl --request POST \
  --url https://api.pinterest.com/v5/ad_accounts/123456789012/product_group_promotions \
  --header 'authorization: Bearer pina_ABCD1234...' \
  --header 'content-type: application/json' \
  --data '{
  "ad_group_id": "2680090195657",
  "product_group_promotion": [
    {
      "catalog_product_group_id": "4672956004260",
      "catalog_product_group_name": "Most Popular",
      "creative_type": "SHOPPING",
      "grid_click_type": "DIRECT_TO_DESTINATION",
      "status": "ACTIVE",
      "is_image_auto_resizing": false,
      "is_generate_background": false,
      "is_dynamic_titles": true,
      "dynamic_titles_approval_type": "MANUAL"
    }
  ]
}'

{
  "items": [
    {
      "data": {
        "id": "4260609797873",
        "ad_group_id": "2680090493150",
        "creative_type": "SHOPPING",
        "status": "ACTIVE",
        "collections_header_type": null,
        "collections_hero_destination_url": null,
        "collections_hero_pin_id": null,
        "slideshow_collections_description": null,
        "slideshow_collections_title": null,
        "is_generate_background": false,
        "selected_image_tag": null,
        "selected_video_tag": null,
        "preferred_media_type": null,
        "is_image_auto_resizing": false,
        "bid_in_micro_currency": 0,
        "catalog_product_group_id": "4672956004260",
        "catalog_id": "4854522508133",
        "catalog_type": "RETAIL",
        "catalog_product_group_name": "Most Popular",
        "customizable_cta_type": "SHOP_NOW",
        "definition": "*/",
        "grid_click_type": "DIRECT_TO_DESTINATION",
        "is_mdl": false,
        "parent_id": "2680090493150",
        "relative_definition": "*/",
        "hide_installment_price": true,
        "is_dynamic_titles": true,
        "dynamic_titles_approval_type": "MANUAL"
      }
    }
  ]
}

Response fields for checking csv

Field

Description

is_ready

boolean

Whether the .csv list of titles is available for download and review.

generated_count

integer

Total number of generated titles. Note that some products may have multiple title variants.

reviewed_count

integer

Total number of validated approvals and rejections of dynamic titles.

This field shows

0

at this stage and should show more than

0

at Step 9.

Response fields for download URL

Field

Description

download_url

string

Presigned AWS S3 URL for the review CSV; valid for one hour.

Response fields for upload URL

Field

Description

upload_url

string

Presigned AWS S3 URL for uploading the reviewed .csv file The URL is valid for one hour.

request_id

string

Upload session's unique identifier that must be passed to the endpoint for processing the reviewed .csv file.

existing_file_name

string

Indicates whether a previously reviewed CSV exists for the affected ad group.

Response fields for submitting csv

Field

Description

status

string

Validation status of

SUCCESS

that only appears when the request succeeds.

errors

array of objects

Container for any reviewed titles that failed validation.

errors.row_number

integer

The row in the .csv file containing a title review that failed validation.

errors.error_type

string

Description of the validation failure.

Response fields for verifying completion

Field

Description

is_ready

boolean

Whether the .csv list of titles is available for download and review.

errors

array of objects

Container for any reviewed titles that failed validation.

generated_count

integer

Total number of generated titles. Note that some products may have multiple title variants.

reviewed_count

integer

Total number of validated approvals and rejections of dynamic titles.

Approved titles are published within 24 hours.