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

promotions

Update promotions

Changed on Jun 4, 2026

Update multiple promotions.

patch/ad_accounts/{ad_account_id}/promotions

Request

Base URL
https://api.pinterest.com/v5
Auth
OAuth 2
Authorization codehttps://www.pinterest.com/oauth/
Token URLhttps://api.pinterest.com/v5/oauth/token
Scopesads:write
TypeScript
https://skmtc.dev/pinterest/apis/pinterest-rest-api/docs/ad_accounts/:ad_account_id/promotions/patch.ts
A function with typed inputs. Its response is checked against the schema.

Path parameters

ad_account_idstring required

Unique identifier of an ad account.

Request body

discount_status'OTHER' | 'ACTIVE' | 'PAUSED' | 'SCHEDULED' | 'EXPIRED'

Discount status based on the current time and start and end time of discount

end_timeinteger

Promotion end time. Unix timestamp in seconds. Independent of campaign end time.

external_idstring

Platform-specific ID for this promotion. Will be null for promotions first created within Pinterest.

idstring required

Promotion ID

platform_typestring

The source integration platform used when creating the promotion. Currently supported values are 'DEFAULT' and 'SHOPIFY'.

promotion_codestring

Code that can be used to redeem a promotion.

promotion_custom_idstring

An optional field for user defined promotion ID for this promotion. Will copy from Pinterest system generated ID if user did not provide one.

promotion_titlestring

Internal name for the promotion.

Determines the displayed promotion text along with what parameters (if any) are needed to complete the template.

start_timeinteger

Promotion start time. Unix timestamp in seconds. Independent of campaign start time.

Example request

[
  {
    "promotion_type": "VARIABLE",
    "template_values": [
      {
        "amount": 100,
        "custom_text": "My promotion",
        "percent": 10
      }
    ]
  }
]

Response

The request has succeeded.

Example response

{
  "promotions": [
    {
      "data": {
        "promotion_type": "VARIABLE",
        "status": "ACTIVE",
        "template_values": [
          {
            "amount": 100,
            "custom_text": "My promotion",
            "percent": 10
          }
        ]
      },
      "exception": {
        "code": 2,
        "message": "Advertiser not found."
      }
    }
  ]
}

Changes

Jun 4, 2026v5b698c180678a Revision changes
- breaking
  added the new required request property /
- warning
  removed subschema #2 from the request property allOf list
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  removed subschema #2 from the // response property allOf list for the response status
- info
  the response property /// became required for the status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status
Aug 12, 2025v58fb7ab040159 Revision changes
- warning
  added the new CUSTOM enum value to the //// response property for the response status
- info
  added the new optional request property ////
- info
  added the new CUSTOM enum value to the request property //
- info
  added the optional property ////// to the response with the status

Operation history (4 revisions)