Skip to main content
POST
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

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

​
Response

Returns 202 Accepted describing the accepted generation request.
​
string
Promotion ID the codes are generated for
​
string
ID of the pool the codes are added to
​
integer
Number of codes requested
​
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.