ad_accounts14

ad_groups13

ads10

advanced_auction2

audience_insights2

audience_sharing7

audiences4

billing11

boards11

bulk3

business_access_assets12

business_access_invite6

business_access_relationships9

campaigns8

catalog_feeds8

catalog_items3

catalog_product_groups10

catalog_reports3

catalog_supplemental7

catalogs3

conversion_deletion_requests4

conversion_eqs1

conversion_events1

conversion_tags5

conversions4

customer_list_uploads3

customer_lists4

customer_segment3

integrations7

keywords5

labels5

lead_ads4

lead_forms5

leads_export2

media3

msot_events1

notification1

oauth3

order_lines2

pins8

product_group_promotions5

product_tags3

promotions5

resources6

schedules3

search3

targeting_template3

terms2

terms_of_service1

trends4

user_account14

ads

Update ads

Update multiple existing ads

patch/ad_accounts/{ad_account_id}/ads

Path parameters

ad_account_idstring required

Unique identifier of an ad account.

Request body

ad_group_idstring

ID of the ad group that contains the ad.

android_deep_linkstring nullable

Deep link URL for Android devices.

carousel_android_deep_linksstring[] nullable

Comma-separated deep links for the carousel pin on Android.

carousel_destination_urlsstring[] nullable

Comma-separated destination URLs for the carousel pin to promote.

carousel_ios_deep_linksstring[] nullable

Comma-separated deep links for the carousel pin on iOS.

click_tracking_urlstring nullable

Tracking url for the ad clicks.

collection_items_destination_url_templatestring nullable

Destination URL template for all items within a collections drawer.

collections_header_type'SHOP_THIS_COLLECTION' | 'EXPLORE_THIS_COLLECTION' | 'NO_HEADER' | 'null' nullable

Collections ad header type for ads

Ad creative type enum. Note: SHOP_THE_PIN has been deprecated. Please use COLLECTION instead.

Select a call to action (CTA) to display below your ad. Available only for ads with direct links enabled. CTA options for consideration and conversion campaigns are LEARN_MORE, SHOP_NOW, BOOK_NOW, SIGN_UP, VISIT_SITE, BUY_NOW, GET_OFFER, ORDER_NOW, ADD_TO_CART (for conversion campaigns with add to cart conversion events only)

destination_urlstring nullable

Destination URL.

Type of information in the page referenced by disclosure_url, provided either by the Food and Drug Administration (FDA) or the manufacturer.

disclosure_urlstring nullable

URL for a page that provides disclosures about a pharmaceutical product, such as potential side effects. Make sure the URL takes the user directly to the disclosure content and the referenced site is secure.

grid_click_type'CLOSEUP' | 'DIRECT_TO_DESTINATION' nullable

Where a user is taken after clicking on an ad in grid.

Note: This parameter is read-only and is set to DIRECT_TO_DESTINATION by default for direct links supported ads. grid_click_type values provided will be ignored.

idstring required

The ID of this ad.

ios_deep_linkstring nullable

Deep link URL for iOS devices.

is_cartingboolean

Is the ad a carting/WTB ad?

is_collage_accepted_termsboolean

Whether the advertiser has accepted the terms and conditions for collage ad.

is_collage_single_destinationboolean

Whether the collage ad has a single destination url override.

is_pin_deletedboolean

Is original pin deleted?

is_removableboolean

Is pin repinnable?

lead_form_idstring nullable

Lead form ID for lead ad generation.

namestring nullable

Name of the ad - 255 chars max.

pin_idstring

Pin ID. This field may only be updated for draft ads.

status'ACTIVE' | 'PAUSED' | 'ARCHIVED' | 'DRAFT' | 'DELETED_DRAFT'

Entity status

view_tracking_urlstring nullable

Tracking URL for ad impressions.

Example request

[
  {
    "collections_header_type": "SHOP_THIS_COLLECTION",
    "customizable_cta_type": "LEARN_MORE",
    "disclosure_type": "MED_GUIDE",
    "grid_click_type": "CLOSEUP",
    "quiz_pin_data": {
      "questions": [
        {
          "question_id": 1,
          "question_text": "Where do you thrive?",
          "options": [
            {
              "text": "Hangout vibes"
            },
            {
              "text": "Time to party!"
            },
            {
              "text": "Keeping it lowkey"
            }
          ]
        },
        {
          "question_id": 2,
          "question_text": "Where would you nap?",
          "options": [
            {
              "text": "Hammock in the mountains"
            },
            {
              "text": "Beach towel in the sand"
            },
            {
              "text": "Tent under the stars"
            }
          ]
        },
        {
          "question_id": 2,
          "question_text": "Who are you taking?",
          "options": [
            {
              "text": "No one—solo trip!"
            },
            {
              "text": "My best friend"
            },
            {
              "text": "The family"
            }
          ]
        }
      ],
      "results": [
        {
          "organicPinId": "1234",
          "android_deep_link": "https://www.pinterest.com/",
          "iOS_deep_link": "https://www.pinterest.com/",
          "destination_url": "https://www.pinterest.com/",
          "result_id": 1
        },
        {
          "organicPinId": "1234",
          "android_deep_link": "https://www.pinterest.com/",
          "iOS_deep_link": "https://www.pinterest.com/",
          "destination_url": "https://www.pinterest.com/",
          "result_id": 2
        },
        {
          "organicPinId": "1234",
          "android_deep_link": "https://www.pinterest.com/",
          "iOS_deep_link": "https://www.pinterest.com/",
          "destination_url": "https://www.pinterest.com/",
          "result_id": 3
        }
      ]
    },
    "status": "ACTIVE",
    "tracking_urls": {
      "impression": [
        "URL1",
        "URL2"
      ],
      "click": [
        "URL1",
        "URL2"
      ],
      "engagement": [
        "URL1",
        "URL2"
      ],
      "buyable_button": [
        "URL1",
        "URL2"
      ],
      "audience_verification": [
        "URL1",
        "URL2"
      ]
    }
  }
]

Response

The request has succeeded.

Example response

{
  "items": [
    {
      "data": {
        "collections_header_type": "SHOP_THIS_COLLECTION",
        "customizable_cta_type": "LEARN_MORE",
        "disclosure_type": "MED_GUIDE",
        "grid_click_type": "CLOSEUP",
        "quiz_pin_data": {
          "questions": [
            {
              "question_id": 1,
              "question_text": "Where do you thrive?",
              "options": [
                {
                  "text": "Hangout vibes"
                },
                {
                  "text": "Time to party!"
                },
                {
                  "text": "Keeping it lowkey"
                }
              ]
            },
            {
              "question_id": 2,
              "question_text": "Where would you nap?",
              "options": [
                {
                  "text": "Hammock in the mountains"
                },
                {
                  "text": "Beach towel in the sand"
                },
                {
                  "text": "Tent under the stars"
                }
              ]
            },
            {
              "question_id": 2,
              "question_text": "Who are you taking?",
              "options": [
                {
                  "text": "No one—solo trip!"
                },
                {
                  "text": "My best friend"
                },
                {
                  "text": "The family"
                }
              ]
            }
          ],
          "results": [
            {
              "organicPinId": "1234",
              "android_deep_link": "https://www.pinterest.com/",
              "iOS_deep_link": "https://www.pinterest.com/",
              "destination_url": "https://www.pinterest.com/",
              "result_id": 1
            },
            {
              "organicPinId": "1234",
              "android_deep_link": "https://www.pinterest.com/",
              "iOS_deep_link": "https://www.pinterest.com/",
              "destination_url": "https://www.pinterest.com/",
              "result_id": 2
            },
            {
              "organicPinId": "1234",
              "android_deep_link": "https://www.pinterest.com/",
              "iOS_deep_link": "https://www.pinterest.com/",
              "destination_url": "https://www.pinterest.com/",
              "result_id": 3
            }
          ]
        },
        "status": "ACTIVE",
        "summary_status": "APPROVED",
        "tracking_urls": {
          "impression": [
            "URL1",
            "URL2"
          ],
          "click": [
            "URL1",
            "URL2"
          ],
          "engagement": [
            "URL1",
            "URL2"
          ],
          "buyable_button": [
            "URL1",
            "URL2"
          ],
          "audience_verification": [
            "URL1",
            "URL2"
          ]
        }
      },
      "exceptions": {
        "code": 2,
        "message": "AdAccount not found."
      }
    }
  ]
}

Changes

Changed in 14 of the 29 revisions of this API.1128119

Jun 4, 2026v5b698c180678a1175See the full diff
- ▲
  added the new required request property /
  new-required-request-property
- ●
  removed subschema #2: AdUpdateRequest from the request property allOf list
  request-property-all-of-removed
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the non-success response with the status
  response-non-success-status-added
- ○
  added the non-success response with the status
  response-non-success-status-added
- ○
  added the non-success response with the status
  response-non-success-status-added
- ○
  added the non-success response with the status
  response-non-success-status-added
- ○
  added the non-success response with the status
  response-non-success-status-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  removed subschema #3 from the // response property allOf list for the response status
  response-property-all-of-removed
- ○
  the response property became required for the status
  response-property-became-required
- ○
  the response property /// became required for the status
  response-property-became-required
- ○
  the response property /// became required for the status
  response-property-became-required
- ○
  added the required property /// to the response with the status
  response-required-property-added
- ○
  added the required property /// to the response with the status
  response-required-property-added
- ○
  added the required property /// to the response with the status
  response-required-property-added
- ○
  added the required property /// to the response with the status
  response-required-property-added
- ○
  added the required property /// to the response with the status
  response-required-property-added
- ○
  added the required property /// to the response with the status
  response-required-property-added
- ○
  added the required property /// to the response with the status
  response-required-property-added
- ○
  added the required property /// to the response with the status
  response-required-property-added
- ○
  added the required property /// to the response with the status
  response-required-property-added
- ○
  added the required property /// to the response with the status
  response-required-property-added
- ○
  added the required property /// to the response with the status
  response-required-property-added
This revision also has 182 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Dec 11, 2025v5537bde5a50b14See the full diff
- ○
  added the new optional request property /////
  new-optional-request-property
- ○
  added the new optional request property /////
  new-optional-request-property
- ○
  added the optional property /////// to the response with the status
  response-optional-property-added
- ○
  added the optional property /////// to the response with the status
  response-optional-property-added
This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Oct 16, 2025v514c297539b6433See the full diff
- ●
  added the new COLLAGE enum value to the /////// response property for the response status
  response-property-enum-value-added
- ●
  added the new MAX_WIDTH_REGULAR_COLLECTION enum value to the /////// response property for the response status
  response-property-enum-value-added
- ●
  added the new MAX_WIDTH_VIDEO_COLLECTION enum value to the /////// response property for the response status
  response-property-enum-value-added
- ○
  added the new COLLAGE enum value to the request property /////
  request-property-enum-value-added
- ○
  added the new MAX_WIDTH_REGULAR_COLLECTION enum value to the request property /////
  request-property-enum-value-added
- ○
  added the new MAX_WIDTH_VIDEO_COLLECTION enum value to the request property /////
  request-property-enum-value-added
This revision also has 7 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Apr 4, 2025v510f9eba4ad971111See the full diff
- ●
  added the new BUY_TICKETS enum value to the /////// response property for the response status
  response-property-enum-value-added
- ●
  added the new DONATE_NOW enum value to the /////// response property for the response status
  response-property-enum-value-added
- ●
  added the new DOWNLOAD enum value to the /////// response property for the response status
  response-property-enum-value-added
- ●
  added the new EXPLORE_MORE enum value to the /////// response property for the response status
  response-property-enum-value-added
- ●
  added the new FIND_A_LOCATION enum value to the /////// response property for the response status
  response-property-enum-value-added
- ●
  added the new GET_DEAL enum value to the /////// response property for the response status
  response-property-enum-value-added
- ●
  added the new GET_RECIPE enum value to the /////// response property for the response status
  response-property-enum-value-added
- ●
  added the new GET_SHOWTIMES enum value to the /////// response property for the response status
  response-property-enum-value-added
- ●
  added the new ON_SALE enum value to the /////// response property for the response status
  response-property-enum-value-added
- ●
  added the new PLAY_GAME enum value to the /////// response property for the response status
  response-property-enum-value-added
- ●
  added the new TRY_IT enum value to the /////// response property for the response status
  response-property-enum-value-added
- ○
  added the new BUY_TICKETS enum value to the request property /////
  request-property-enum-value-added
- ○
  added the new DONATE_NOW enum value to the request property /////
  request-property-enum-value-added
- ○
  added the new DOWNLOAD enum value to the request property /////
  request-property-enum-value-added
- ○
  added the new EXPLORE_MORE enum value to the request property /////
  request-property-enum-value-added
- ○
  added the new FIND_A_LOCATION enum value to the request property /////
  request-property-enum-value-added
- ○
  added the new GET_DEAL enum value to the request property /////
  request-property-enum-value-added
- ○
  added the new GET_RECIPE enum value to the request property /////
  request-property-enum-value-added
- ○
  added the new GET_SHOWTIMES enum value to the request property /////
  request-property-enum-value-added
- ○
  added the new ON_SALE enum value to the request property /////
  request-property-enum-value-added
- ○
  added the new PLAY_GAME enum value to the request property /////
  request-property-enum-value-added
- ○
  added the new TRY_IT enum value to the request property /////
  request-property-enum-value-added
This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 14, 2024v589c27ed39cfd116See the full diff
- ▲
  removed the enum value VISIT_WEBSITE of the request property /////
  request-property-enum-value-removed
- ●
  added the new VISIT_SITE enum value to the /////// response property for the response status
  response-property-enum-value-added
- ○
  added the new optional request property //////////
  new-optional-request-property
- ○
  added the new optional request property //////////
  new-optional-request-property
- ○
  added the new VISIT_SITE enum value to the request property /////
  request-property-enum-value-added
- ○
  added the optional property //////////// to the response with the status
  response-optional-property-added
- ○
  added the optional property //////////// to the response with the status
  response-optional-property-added
- ○
  removed the VISIT_WEBSITE enum value from the /////// response property for the response status
  response-property-enum-value-removed
This revision also has 4 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Apr 23, 2024v5f9321315766f1See the full diff
- ▲
  the request property type changed from no type to object
  request-property-type-changed
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Feb 8, 2024v57529b464d5cb49See the full diff
- ●
  added the new DELETED_DRAFT enum value to the /////// response property for the response status
  response-property-enum-value-added
- ●
  added the new DELETED_DRAFT enum value to the //////// response property for the response status
  response-property-enum-value-added
- ●
  added the new DRAFT enum value to the /////// response property for the response status
  response-property-enum-value-added
- ●
  added the new DRAFT enum value to the //////// response property for the response status
  response-property-enum-value-added
- ○
  added the new optional request property /////
  new-optional-request-property
- ○
  added the new optional request property /////
  new-optional-request-property
- ○
  added the new optional request property /////
  new-optional-request-property
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added the new DELETED_DRAFT enum value to the request property /////
  request-property-enum-value-added
- ○
  added the new DRAFT enum value to the request property /////
  request-property-enum-value-added
- ○
  added the optional property /////// to the response with the status
  response-optional-property-added
- ○
  added the optional property /////// to the response with the status
  response-optional-property-added
- ○
  added the optional property /////// to the response with the status
  response-optional-property-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 17, 2023v50ff12596bafd2See the full diff
- ○
  added the new optional request property /////
  new-optional-request-property
- ○
  added the optional property /////// to the response with the status
  response-optional-property-added
Jul 14, 2023v552586a27477122See the full diff
- ●
  added the new COLLECTION enum value to the /////// response property for the response status
  response-property-enum-value-added
- ●
  added the new SHOWCASE enum value to the /////// response property for the response status
  response-property-enum-value-added
- ○
  added the new COLLECTION enum value to the request property /////
  request-property-enum-value-added
- ○
  added the new SHOWCASE enum value to the request property /////
  request-property-enum-value-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
May 12, 2023v5689b4b26763911See the full diff
- ●
  added the new QUIZ enum value to the /////// response property for the response status
  response-property-enum-value-added
- ○
  added the new QUIZ enum value to the request property /////
  request-property-enum-value-added
This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history (14 revisions)