Skip to main content
POST
/
partner
/
promotions
/
:id
/
codes
curl https://api.thanxsandbox.com/partner/promotions/promo_abc123/codes \
  -X POST \
  -H 'X-ClientId: {client_id}' \
  -H 'Accept-Version: v4.0' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  -d '{
    "merchant_id": "k2lye10h32l5wzo",
    "count": 10000
  }'

{
  "code_generation": {
    "promotion_id": "promo_abc123",
    "pool_id": "pool_def456",
    "requested_count": 10000,
    "status": "in_progress"
  }
}

{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "count must be an integer between 1 and 100000"
  }
}
Scope required: promos.write
This endpoint adds a batch of unique single-use codes to an existing promotion — use it to top up (replenish) a promotion whose supply of unredeemed codes is running low. The promotion can be created via Create Promotion or in the Thanx dashboard. Codes are added to the promotion’s active single_use pool (one is created if the promotion does not have an active pool yet), so newly generated codes are retrievable through List Promotion Codes alongside the existing ones. By default, codes are 8-character, uppercase, alphanumeric values (the letters I, L, and O are excluded to avoid ambiguity). Use prefix and code_length to customize their format. Generation runs asynchronously. The endpoint returns immediately with a 202 Accepted response describing the generation request. Poll Get Promotion until code_generation_status is complete, then fetch the new codes with List Promotion Codes.

​
Per-Request Cap

A single request may generate up to 100,000 codes. Requests above this cap return a 422 Unprocessable Entity error. To add more than 100,000 codes, submit multiple requests. (For a larger initial pool, code_count on Create Promotion accepts up to 4,000,000 in a single call.)

​
Idempotency

This endpoint supports idempotent requests via the X-Idempotency-Key header. When provided, duplicate requests with the same key return the cached response from the original request rather than generating codes again. If the request body differs from the original, a 422 Unprocessable Entity error is returned. We strongly recommend sending an idempotency key so that a retried request does not silently double-generate codes.

​
Parameters

​
id
string
required
Promotion ID
​
merchant_id
string
required
Merchant ID
​
count
integer
required
Number of codes to generate (1–100,000)
​
prefix
string
Optional prefix prepended to each generated code (e.g., FIVEGUYS).
​
code_length
integer
Length of the random portion of each code (4–20). Defaults to 8.
​
X-Idempotency-Key
string
Optional idempotency key to prevent duplicate code generation.

​
Response

Returns 202 Accepted describing the accepted generation request.
​
promotion_id
string
Promotion ID the codes are generated for
​
pool_id
string
ID of the pool the codes are added to
​
requested_count
integer
Number of codes requested
​
status
string
Generation status: in_progress, complete, or failed. This is the same value exposed as code_generation_status on Get Promotion, which you poll until it reaches complete.
curl https://api.thanxsandbox.com/partner/promotions/promo_abc123/codes \
  -X POST \
  -H 'X-ClientId: {client_id}' \
  -H 'Accept-Version: v4.0' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  -d '{
    "merchant_id": "k2lye10h32l5wzo",
    "count": 10000
  }'

{
  "code_generation": {
    "promotion_id": "promo_abc123",
    "pool_id": "pool_def456",
    "requested_count": 10000,
    "status": "in_progress"
  }
}

{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "count must be an integer between 1 and 100000"
  }
}