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