Sign in

v29

latestOpenAPI 3.0.3MITraw.githubusercontent.com2026-06-042661,1122.5 MB
promotions

Create promotions

Create multiple new promotions.

post/ad_accounts/{ad_account_id}/promotions

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.

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 required

Internal name for the promotion.

promotion_type'VARIABLE' | 'SITEWIDE' | 'CHECKOUT' | 'SAVE_X_ON_Y' | 'BUY_X_GET_Y' | 'SPEND_X_SAVE_Y' | 'FREE_SHIPPING' | 'FREE_SHIPPING_MINIMUM' | 'FREE_SHIPPING_WITH_DISCOUNT' | 'SITEWIDE_IN_STORES' | 'EXTRA_PERCENT_OFF' | 'GIFT_WITH_PURCHASE' | 'GIFT_WITH_PURCHASE_MINIMUM' | 'FIXED' | 'PERCENT_OFF_CLEARANCE' | 'X_OFF_Y' | 'GIFT_WITH_FIRST_PURCHASE' | 'BUY_X_GET_ONE_FREE' | 'CASH_BACK' | 'POINTS_ON_ALL_PURCHASES' | 'BONUS' | 'POINTS_WITH_PURCHASE' | 'CUSTOM' required

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."
      }
    }
  ]
}