> ## 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.

# Issue Rewards

> Issue rewards to users for a campaign variant

<Info>
  Scope required: `rewards.issue`
</Info>

This endpoint initiates an asynchronous reward issuance job. Rewards are
issued to the specified users for a given campaign variant. The endpoint
returns immediately with a `202 Accepted` response containing the issuance
job details. Use the
[Get Issuance Job](/partner/issuance-jobs/get-issuance-job) endpoint to poll
for completion status.

### Best Practices for Event-Driven Workflows

While there is nothing preventing you from issuing rewards one user at a
time, we strongly recommend batching identifiers into a single request
whenever possible. Sending individual requests per user is significantly
less efficient and may result in rate limiting under the
[global rate limits](/partner/overview#global-rate-limits). Collect
identifiers and submit them in batches of up to 10,000 per request for
optimal throughput.

### 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. If the request body differs
from the original, a `422 Unprocessable Entity` error is returned.

### Parameters

<ParamField body="campaign_id" type="string" required>
  Campaign ID
</ParamField>

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

<ParamField body="variant_id" type="string" required>
  Variant ID. Must belong to the specified campaign.
</ParamField>

<ParamField body="identifiers" type="array" required>
  Array of user identifiers to issue rewards to (max 10,000)

  <Expandable title="identifier">
    <ParamField body="type" type="string" required>
      Identifier type: `email` or `phone`
    </ParamField>

    <ParamField body="value" type="string" required>
      Identifier value. Phone numbers must be in E.164 format (e.g.,
      `+12025551234`).
    </ParamField>
  </Expandable>
</ParamField>

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

### Response

Returns `202 Accepted` with the issuance job object.

<ResponseField name="id" type="string">
  Issuance job ID
</ResponseField>

<ResponseField name="campaign_id" type="string">
  Campaign ID
</ResponseField>

<ResponseField name="variant_id" type="string">
  Variant ID
</ResponseField>

<ResponseField name="state" type="string">
  Job state: `pending`, `processing`, `completed`, or `failed`
</ResponseField>

<ResponseField name="total_count" type="integer">
  Total number of identifiers submitted
</ResponseField>

<ResponseField name="processed_count" type="integer">
  Number of identifiers processed so far
</ResponseField>

<ResponseField name="success_count" type="integer">
  Number of rewards successfully issued
</ResponseField>

<ResponseField name="failure_count" type="integer">
  Number of failed issuances
</ResponseField>

<ResponseField name="progress_percent" type="integer">
  Completion percentage (0-100)
</ResponseField>

<ResponseField name="created_at" type="datetime">
  Job creation timestamp (ISO8601)
</ResponseField>

<ResponseField name="started_at" type="datetime">
  Processing start timestamp (ISO8601), null if not started
</ResponseField>

<ResponseField name="completed_at" type="datetime">
  Processing completion timestamp (ISO8601), null if not completed
</ResponseField>

<RequestExample>
  ```bash Issue Rewards theme={null}
  curl https://api.thanxsandbox.com/partner/campaigns/issue \
    -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 '{
      "campaign_id": "camp_abc123",
      "merchant_id": "k2lye10h32l5wzo",
      "variant_id": "var_treat1",
      "identifiers": [
        {
          "type": "email",
          "value": "jane.smith@example.com"
        },
        {
          "type": "phone",
          "value": "+14155551234"
        }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={null}
  {
    "issuance_job": {
      "id": "job_xyz789",
      "campaign_id": "camp_abc123",
      "variant_id": "var_treat1",
      "state": "pending",
      "total_count": 2,
      "processed_count": 0,
      "success_count": 0,
      "failure_count": 0,
      "progress_percent": 0,
      "created_at": "2025-06-15T10:30:00Z",
      "started_at": null,
      "completed_at": null
    }
  }
  ```
</ResponseExample>