---
title: "Update ads"
method: PATCH
path: "/ad_accounts/{ad_account_id}/ads"
tags: ["ads"]
---

# Update ads

`PATCH /ad_accounts/{ad_account_id}/ads`

Update multiple existing ads

## Path parameters

- `ad_account_id` string, required

## Request body

- AdBatchUpdate[]
  - `ad_group_id` string — ID of the ad group that contains the ad.
  - `android_deep_link` string, nullable — Deep link URL for Android devices.
  - `carousel_android_deep_links` string[], nullable — Comma-separated deep links for the carousel pin on Android.
  - `carousel_destination_urls` string[], nullable — Comma-separated destination URLs for the carousel pin to promote.
  - `carousel_ios_deep_links` string[], nullable — Comma-separated deep links for the carousel pin on iOS.
  - `click_tracking_url` string, nullable — Tracking url for the ad clicks.
  - `collection_items_destination_url_template` string, 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
  - `creative_type` 'REGULAR' | 'VIDEO' | 'SHOPPING' | 'CAROUSEL' | 'MAX_VIDEO' | 'SHOP_THE_PIN' | 'COLLECTION' | 'IDEA' | 'SHOWCASE' | 'QUIZ' | 'COLLAGE' | 'MAX_WIDTH_REGULAR_COLLECTION' | 'MAX_WIDTH_VIDEO_COLLECTION' | 'APP' — Ad creative type enum. **Note:** SHOP_THE_PIN has been deprecated. Please use COLLECTION instead.
  - `customizable_cta_type` 'GET_OFFER' | 'LEARN_MORE' | 'ORDER_NOW' | 'SHOP_NOW' | 'SIGN_UP' | 'SUBSCRIBE' | 'BUY_NOW' | 'CONTACT_US' | 'GET_QUOTE' | 'VISIT_SITE' | 'APPLY_NOW' | 'BOOK_NOW' | 'REQUEST_DEMO' | 'REGISTER_NOW' | 'FIND_A_DEALER' | 'ADD_TO_CART' | 'WATCH_NOW' | 'READ_MORE' | 'BUY_TICKETS' | 'DONATE_NOW' | 'DOWNLOAD' | 'EXPLORE_MORE' | 'FIND_A_LOCATION' | 'FIND_RETAILERS' | 'GET_DEAL' | 'GET_RECIPE' | 'GET_SHOWTIMES' | 'ON_SALE' | 'PLAY_GAME' | 'TRY_IT' | 'TAKE_A_PEEK' | 'null', nullable — 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_url` string, nullable — Destination URL.
  - `disclosure_type` 'NO_DISCLOSURE' | 'PRESCRIBING_INFORMATION' | 'PRESCRIBING_INFORMATION_BOX_WARNING' | 'IMPORTANT_SAFETY_INFO' | 'MED_GUIDE' | 'PATIENT_INFORMATION' | 'null', nullable — Type of information in the page referenced by `disclosure_url`, provided either by the Food and Drug Administration (FDA) or the manufacturer.
  - `disclosure_url` string, 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.
  - `id` string, required — The ID of this ad.
  - `ios_deep_link` string, nullable — Deep link URL for iOS devices.
  - `is_carting` boolean — Is the ad a carting/WTB ad?
  - `is_collage_accepted_terms` boolean — Whether the advertiser has accepted the terms and conditions for collage ad.
  - `is_collage_single_destination` boolean — Whether the collage ad has a single destination url override.
  - `is_pin_deleted` boolean — Is original pin deleted?
  - `is_removable` boolean — Is pin repinnable?
  - `lead_form_id` string, nullable — Lead form ID for lead ad generation.
  - `name` string, nullable — Name of the ad - 255 chars max.
  - `pin_id` string — Pin ID. This field may only be updated for draft ads.
  - `quiz_pin_data` QuizPinData, nullable — This field includes all quiz data including questions, options, and results.
    - `questions` QuizPinQuestion[]
      - `options` QuizPinOption[]
        - `id` number
        - `text` string
      - `question_id` number
      - `question_text` string
    - `results` QuizPinResult[]
      - `android_deep_link` string
      - `destination_url` string
      - `ios_deep_link` string
      - `organic_pin_id` string
      - `result_id` number
    - `tie_breaker_custom_result` QuizPinResult, nullable — The result, and link out, based on the user’s choice.
      - `android_deep_link` string
      - `destination_url` string
      - `ios_deep_link` string
      - `organic_pin_id` string
      - `result_id` number
    - `tie_breaker_type` 'RANDOM' | 'CUSTOM' — Quiz ad tie breaker type, default is RANDOM
  - `status` 'ACTIVE' | 'PAUSED' | 'ARCHIVED' | 'DRAFT' | 'DELETED_DRAFT' — Entity status
  - `tracking_urls` TrackingUrls, nullable — Third-party tracking URLs. Up to three tracking URLs - with a max length of 2,000 - are supported for each event type. Tracking URLs set at the ad group or ad level can override those set at the campaign level. For more information, see [Third-party and dynamic tracking](https://help.pinterest.com/en/business/article/third-party-and-dynamic-tracking).
    - `audience_verification` string[]
    - `buyable_button` string[]
    - `click` string[]
    - `engagement` string[]
    - `impression` string[]
  - `view_tracking_url` string, nullable — Tracking URL for ad impressions.

## Response `200`

The request has succeeded.

- AdBatchWriteResponseModel
  - `items` AdBatchItem[], required
    - `data` Ad
      - `ad_account_id` string, required — The ID of the advertiser that this ad belongs to.
      - `ad_group_id` string, required — ID of the ad group that contains the ad.
      - `android_deep_link` string, nullable — Deep link URL for Android devices.
      - `campaign_id` string, required — ID of the ad campaign that contains this ad.
      - `carousel_android_deep_links` string[], nullable — Comma-separated deep links for the carousel pin on Android.
      - `carousel_destination_urls` string[], nullable — Comma-separated destination URLs for the carousel pin to promote.
      - `carousel_ios_deep_links` string[], nullable — Comma-separated deep links for the carousel pin on iOS.
      - `carting_platform_type` integer — The vendor platform type of the carting ad. 1 for MIKMAK, 2 for PEAR.
      - `carting_products` CartingProduct[] — Array of carting/WTB products for the ad.
        - `carting_product_id` string, required — the internal Pinterest carting product id (different from industry product id)
        - `display_preferred_retailers_only` boolean — Whether to display only the preferred retailers for the carting product
        - `display_product_price` boolean — Whether to display the price for the carting product
        - `preferred_retailers` CartingRetailer[] — A sorted array of preferred retailers for the carting product
          - `retailer_id` string, required — Unique identifier for the retailer
          - `retailer_name` string, required — Name of the retailer
        - `randomize_preferred_retailers` boolean — Whether to randomize preferred retailers for the carting product
      - `click_tracking_url` string, nullable — Tracking url for the ad clicks.
      - `collection_items_destination_url_template` string, 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
      - `created_time` integer — Pin creation time. Unix timestamp in seconds.
      - `creative_type` 'REGULAR' | 'VIDEO' | 'SHOPPING' | 'CAROUSEL' | 'MAX_VIDEO' | 'SHOP_THE_PIN' | 'COLLECTION' | 'IDEA' | 'SHOWCASE' | 'QUIZ' | 'COLLAGE' | 'MAX_WIDTH_REGULAR_COLLECTION' | 'MAX_WIDTH_VIDEO_COLLECTION' | 'APP', required — Ad creative type enum. **Note:** SHOP_THE_PIN has been deprecated. Please use COLLECTION instead.
      - `customizable_cta_type` 'GET_OFFER' | 'LEARN_MORE' | 'ORDER_NOW' | 'SHOP_NOW' | 'SIGN_UP' | 'SUBSCRIBE' | 'BUY_NOW' | 'CONTACT_US' | 'GET_QUOTE' | 'VISIT_SITE' | 'APPLY_NOW' | 'BOOK_NOW' | 'REQUEST_DEMO' | 'REGISTER_NOW' | 'FIND_A_DEALER' | 'ADD_TO_CART' | 'WATCH_NOW' | 'READ_MORE' | 'BUY_TICKETS' | 'DONATE_NOW' | 'DOWNLOAD' | 'EXPLORE_MORE' | 'FIND_A_LOCATION' | 'FIND_RETAILERS' | 'GET_DEAL' | 'GET_RECIPE' | 'GET_SHOWTIMES' | 'ON_SALE' | 'PLAY_GAME' | 'TRY_IT' | 'TAKE_A_PEEK' | 'null', nullable — 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_url` string, nullable — Destination URL.
      - `disclosure_type` 'NO_DISCLOSURE' | 'PRESCRIBING_INFORMATION' | 'PRESCRIBING_INFORMATION_BOX_WARNING' | 'IMPORTANT_SAFETY_INFO' | 'MED_GUIDE' | 'PATIENT_INFORMATION' | 'null', nullable — Type of information in the page referenced by `disclosure_url`, provided either by the Food and Drug Administration (FDA) or the manufacturer.
      - `disclosure_url` string, 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.
      - `id` string, required — The ID of this ad.
      - `ios_deep_link` string, nullable — Deep link URL for iOS devices.
      - `is_carting` boolean — Is the ad a carting/WTB ad?
      - `is_collage_accepted_terms` boolean — Whether the advertiser has accepted the terms and conditions for collage ad.
      - `is_collage_single_destination` boolean — Whether the collage ad has a single destination url override.
      - `is_pin_deleted` boolean — Is original pin deleted?
      - `is_removable` boolean — Is pin repinnable?
      - `lead_form_id` string, nullable — Lead form ID for lead ad generation.
      - `name` string, nullable — Name of the ad - 255 chars max.
      - `pin_id` string, required — Pin ID. This field may only be updated for draft ads.
      - `quiz_pin_data` QuizPinData, nullable — This field includes all quiz data including questions, options, and results.
        - `questions` QuizPinQuestion[]
          - `options` QuizPinOption[]
            - `id` number
            - `text` string
          - `question_id` number
          - `question_text` string
        - `results` QuizPinResult[]
          - `android_deep_link` string
          - `destination_url` string
          - `ios_deep_link` string
          - `organic_pin_id` string
          - `result_id` number
        - `tie_breaker_custom_result` QuizPinResult, nullable — The result, and link out, based on the user’s choice.
          - `android_deep_link` string
          - `destination_url` string
          - `ios_deep_link` string
          - `organic_pin_id` string
          - `result_id` number
        - `tie_breaker_type` 'RANDOM' | 'CUSTOM' — Quiz ad tie breaker type, default is RANDOM
      - `rejected_reasons` AdDisapprovalReasons[], required — Enum reason why the pin was rejected. Returned if `review_status` is "REJECTED".
      - `rejection_labels` string[], required — Text reason why the pin was rejected. Returned if `review_status` is "REJECTED".
      - `review_status` 'OTHER' | 'PENDING' | 'REJECTED' | 'APPROVED', required — Ad review status
      - `status` 'ACTIVE' | 'PAUSED' | 'ARCHIVED' | 'DRAFT' | 'DELETED_DRAFT' — Entity status
      - `summary_status` 'APPROVED' | 'PAUSED' | 'PENDING' | 'REJECTED' | 'ADVERTISER_DISABLED' | 'ARCHIVED' | 'DRAFT' | 'DELETED_DRAFT', required — Summary status for pin promotions
      - `tracking_urls` TrackingUrls, nullable — Third-party tracking URLs. Up to three tracking URLs - with a max length of 2,000 - are supported for each event type. Tracking URLs set at the ad group or ad level can override those set at the campaign level. For more information, see [Third-party and dynamic tracking](https://help.pinterest.com/en/business/article/third-party-and-dynamic-tracking).
        - `audience_verification` string[]
        - `buyable_button` string[]
        - `click` string[]
        - `engagement` string[]
        - `impression` string[]
      - `type` string, required — Always "ad".
      - `updated_time` integer — Last update time. Unix timestamp in seconds.
      - `view_tracking_url` string, nullable — Tracking URL for ad impressions.
    - `exceptions` PinterestLibError — Default error response
      - `code` integer, required
      - `message` string, required

## Other responses

- `400` — The request could not be understood by the server due to unexpected data.
- `401` — Authentication is required and has either failed or not been provided.
- `403` — The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
- `404` — The requested resource could not be found on this server.
- `429` — The user has sent too many requests in a given amount of time and is being rate limited.
- `default` — An unexpected error response.

---

[API](https://skmtc.net/pinterest/apis/pinterest-rest-api.md) · [All operations](https://skmtc.net/pinterest/apis/pinterest-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pinterest/pinterest-rest-api/revisions/b698c180678a/schema)