> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thanx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate Promotion Codes

> Add a batch of single-use codes to an existing promotion

<Info>
  Scope required: `promos.write`
</Info>

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](/partner/promotions/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](/partner/promotions/list-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](/partner/promotions/get-promotion) until
`code_generation_status` is `complete`, then fetch the new codes with
[List Promotion Codes](/partner/promotions/list-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](/partner/promotions/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

<ParamField path="id" type="string" required>
  Promotion ID
</ParamField>

<ParamField body="merchant_id" type="string" required>
  Merchant ID
</ParamField>

<ParamField body="count" type="integer" required>
  Number of codes to generate (1–100,000)
</ParamField>

<ParamField body="prefix" type="string">
  Optional prefix prepended to each generated code (e.g., `FIVEGUYS`).
</ParamField>

<ParamField body="code_length" type="integer">
  Length of the random portion of each code (4–20). Defaults to `8`.
</ParamField>

<ParamField header="X-Idempotency-Key" type="string">
  Optional idempotency key to prevent duplicate code generation.
</ParamField>

### Response

Returns `202 Accepted` describing the accepted generation request.

<ResponseField name="promotion_id" type="string">
  Promotion ID the codes are generated for
</ResponseField>

<ResponseField name="pool_id" type="string">
  ID of the pool the codes are added to
</ResponseField>

<ResponseField name="requested_count" type="integer">
  Number of codes requested
</ResponseField>

<ResponseField name="status" type="string">
  Generation status: `in_progress`, `complete`, or `failed`. This is the same
  value exposed as `code_generation_status` on
  [Get Promotion](/partner/promotions/get-promotion), which you poll until it
  reaches `complete`.
</ResponseField>

<RequestExample>
  ```bash Generate Promotion Codes theme={null}
  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
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={null}
  {
    "code_generation": {
      "promotion_id": "promo_abc123",
      "pool_id": "pool_def456",
      "requested_count": 10000,
      "status": "in_progress"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "UNPROCESSABLE_ENTITY",
      "message": "count must be an integer between 1 and 100000"
    }
  }
  ```
</ResponseExample>