Skip to main content
POST
Scope required: promos.write
This endpoint creates a new promotion for the specified merchant. It mirrors the functionality available in the Thanx dashboard: it creates the promotion’s underlying program and redeem configuration, and — depending on how codes are requested — its initial code pool. For the full lifecycle — creating a promotion, generating codes, dispensing them to customers, and replenishing — see the Promotions Overview.

​
Code Pools

How you supply codes at creation determines the pool that is created:
  • static_code — creates a multi_use pool containing a single shared code that can be redeemed multiple times (a “universal” code). The pool is marked complete immediately.
  • code_count — creates a single_use pool and enqueues asynchronous generation of that many unique one-time codes. Poll Get Promotion until code_generation_status is complete, then fetch the codes with List Promotion Codes. Additional single-use codes can later be generated with Generate Promotion Codes.
  • Neither — the promotion is created without any codes.
static_code and code_count are mutually exclusive.

​
Parameters

​
string
required
Merchant ID
​
string
required
Promotion name
​
string
required
Type of discount: amount, percent, or item
​
number
required
Discount amount. Interpreted according to discount_type (for example, a percentage for percent or a currency amount for amount).
​
number
Minimum spend required to redeem
​
number
Maximum discount that can be applied (where supported by the discount type)
​
string
Terms and conditions
​
string
Redemption instructions shown to the customer
​
string
Where the promotion can be redeemed: all, instore, or online. Defaults to instore.
​
datetime
When the promotion becomes active (ISO8601)
​
datetime
When the promotion ends (ISO8601). Must be after starts_at.
​
string
A single shared code to create as a multi_use pool. Mutually exclusive with code_count.
​
integer
Number of unique one-time codes to generate as a single_use pool (1–4,000,000). Generation runs asynchronously. Mutually exclusive with static_code.
​
string
Initial state: active or draft. Defaults to active. Draft promotions are managed in the Thanx dashboard — the read endpoints (List Promotions, Get Promotion) return only active promotions.
​
hash
Optional day-of-week and time-of-day restrictions on when the promotion can be redeemed. Write-only: these are applied at creation and viewed or edited in the Thanx dashboard; they are not returned by the read endpoints.

​
Response

Returns 201 Created with the newly created promotion. The response uses the same shape as Get Promotion.
​
string
Promotion ID
​
string
Promotion name
​
string
Promotion state (active or draft)
​
string
Type of discount the promotion applies: percent, item, or amount
​
string
Discount amount, as a string. Null if not set.
​
string
Minimum spend required to redeem, as a string. Null if not set.
​
string
Maximum discount that can be applied, as a string. Null if not set.
​
string
Terms and conditions
​
string
Where the promotion can be redeemed
​
datetime
Promotion start timestamp (ISO8601). Null if not set.
​
datetime
Promotion end timestamp (ISO8601). Null if not set.
​
string
How the pool’s codes are generated: multi_use or single_use. Null if no pool was created.
​
integer
Number of times codes in the active pool have been redeemed
​
integer
Total number of codes in the active pool
​
string
Status of asynchronous code generation for the active pool: none (no codes requested), in_progress, complete, or failed