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

> Issue bonus points to users in a points experience

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

This endpoint initiates an asynchronous bonus points issuance job. The
specified number of points is added to each user's points balance for the
merchant's points experience. 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.

Points issued through this endpoint are bonus points: they are added to the
user's balance directly and do not require the user to activate a reward. See
the [Points guide](/consumer/guides/points) for how points are earned and
redeemed.

### Best Practices for Event-Driven Workflows

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

Always send an idempotency key when issuing points. Retrying a request
without one can credit users more than once.

### Parameters

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

<ParamField body="points" type="integer" required>
  Number of bonus points to issue to each user. Must be a positive integer.
</ParamField>

<ParamField body="identifiers" type="array" required>
  Array of user identifiers to issue points 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 body="reason" type="string">
  Optional note describing why the points were issued. Stored with the points
  transaction for auditing.
</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="points" type="integer">
  Number of points issued to each user
</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 users successfully issued points
</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 Points theme={null}
  curl https://api.thanxsandbox.com/partner/points_experience/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 '{
      "merchant_id": "k2lye10h32l5wzo",
      "points": 250,
      "reason": "Service recovery",
      "identifiers": [
        {
          "type": "email",
          "value": "jane.smith@example.com"
        },
        {
          "type": "phone",
          "value": "+14155551234"
        }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={null}
  {
    "issuance_job": {
      "id": "job_xyz789",
      "points": 250,
      "state": "pending",
      "total_count": 2,
      "processed_count": 0,
      "success_count": 0,
      "failure_count": 0,
      "progress_percent": 0,
      "created_at": "2026-10-16T10:30:00Z",
      "started_at": null,
      "completed_at": null
    }
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.