Sign in

v29

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

Get promotion by id

Get a promotion by its Pinterest-specific id. It must be associated with the provided ad account id.

get/ad_accounts/{ad_account_id}/promotions/{promotion_id}

Path parameters

promotion_idstring required

Promotion ID

ad_account_idstring required

Unique identifier of an ad account.

Response

The request has succeeded.

ad_account_idstring required

The Ad Account ID that this promotion belongs to.

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 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.

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

Entity status

Example response

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