Skip to main content
POST
/
partner
/
promotions
curl https://api.thanxsandbox.com/partner/promotions \
  -X POST \
  -H 'X-ClientId: {client_id}' \
  -H 'Accept-Version: v4.0' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -d '{
    "merchant_id": "k2lye10h32l5wzo",
    "name": "Summer 20% Off",
    "discount_type": "percent",
    "discount_value": 20,
    "minimum_spend": 25,
    "fine_print": "Limit one per customer",
    "redemption_venue": "online",
    "starts_at": "2026-06-01T00:00:00Z",
    "ends_at": "2026-08-31T23:59:59Z",
    "code_count": 10000
  }'

curl https://api.thanxsandbox.com/partner/promotions \
  -X POST \
  -H 'X-ClientId: {client_id}' \
  -H 'Accept-Version: v4.0' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -d '{
    "merchant_id": "k2lye10h32l5wzo",
    "name": "Launch Week",
    "discount_type": "amount",
    "discount_value": 5,
    "redemption_venue": "all",
    "static_code": "LAUNCH5"
  }'

{
  "promotion": {
    "id": "promo_abc123",
    "name": "Summer 20% Off",
    "state": "active",
    "discount_type": "percent",
    "discount_value": "20.0",
    "minimum_spend": "25.0",
    "maximum_discount": null,
    "fine_print": "Limit one per customer",
    "redemption_venue": "online",
    "starts_at": "2026-06-01T00:00:00Z",
    "ends_at": "2026-08-31T23:59:59Z",
    "generation_type": "single_use",
    "redemption_count": 0,
    "total_codes": 0,
    "code_generation_status": "in_progress"
  }
}

{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "static_code and code_count are mutually exclusive"
  }
}
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

​
merchant_id
string
required
Merchant ID
​
name
string
required
Promotion name
​
discount_type
string
required
Type of discount: amount, percent, or item
​
discount_value
number
required
Discount amount. Interpreted according to discount_type (for example, a percentage for percent or a currency amount for amount).
​
minimum_spend
number
Minimum spend required to redeem
​
maximum_discount
number
Maximum discount that can be applied (where supported by the discount type)
​
fine_print
string
Terms and conditions
​
instructions
string
Redemption instructions shown to the customer
​
redemption_venue
string
Where the promotion can be redeemed: all, instore, or online. Defaults to instore.
​
starts_at
datetime
When the promotion becomes active (ISO8601)
​
ends_at
datetime
When the promotion ends (ISO8601). Must be after starts_at.
​
static_code
string
A single shared code to create as a multi_use pool. Mutually exclusive with code_count.
​
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.
​
state
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.
​
redemption_restrictions
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.
​
id
string
Promotion ID
​
name
string
Promotion name
​
state
string
Promotion state (active or draft)
​
discount_type
string
Type of discount the promotion applies: percent, item, or amount
​
discount_value
string
Discount amount, as a string. Null if not set.
​
minimum_spend
string
Minimum spend required to redeem, as a string. Null if not set.
​
maximum_discount
string
Maximum discount that can be applied, as a string. Null if not set.
​
fine_print
string
Terms and conditions
​
redemption_venue
string
Where the promotion can be redeemed
​
starts_at
datetime
Promotion start timestamp (ISO8601). Null if not set.
​
ends_at
datetime
Promotion end timestamp (ISO8601). Null if not set.
​
generation_type
string
How the pool’s codes are generated: multi_use or single_use. Null if no pool was created.
​
redemption_count
integer
Number of times codes in the active pool have been redeemed
​
total_codes
integer
Total number of codes in the active pool
​
code_generation_status
string
Status of asynchronous code generation for the active pool: none (no codes requested), in_progress, complete, or failed
curl https://api.thanxsandbox.com/partner/promotions \
  -X POST \
  -H 'X-ClientId: {client_id}' \
  -H 'Accept-Version: v4.0' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -d '{
    "merchant_id": "k2lye10h32l5wzo",
    "name": "Summer 20% Off",
    "discount_type": "percent",
    "discount_value": 20,
    "minimum_spend": 25,
    "fine_print": "Limit one per customer",
    "redemption_venue": "online",
    "starts_at": "2026-06-01T00:00:00Z",
    "ends_at": "2026-08-31T23:59:59Z",
    "code_count": 10000
  }'

curl https://api.thanxsandbox.com/partner/promotions \
  -X POST \
  -H 'X-ClientId: {client_id}' \
  -H 'Accept-Version: v4.0' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -d '{
    "merchant_id": "k2lye10h32l5wzo",
    "name": "Launch Week",
    "discount_type": "amount",
    "discount_value": 5,
    "redemption_venue": "all",
    "static_code": "LAUNCH5"
  }'

{
  "promotion": {
    "id": "promo_abc123",
    "name": "Summer 20% Off",
    "state": "active",
    "discount_type": "percent",
    "discount_value": "20.0",
    "minimum_spend": "25.0",
    "maximum_discount": null,
    "fine_print": "Limit one per customer",
    "redemption_venue": "online",
    "starts_at": "2026-06-01T00:00:00Z",
    "ends_at": "2026-08-31T23:59:59Z",
    "generation_type": "single_use",
    "redemption_count": 0,
    "total_codes": 0,
    "code_generation_status": "in_progress"
  }
}

{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "static_code and code_count are mutually exclusive"
  }
}