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

> [!NOTE]
>
> Scope required: `points.issue`

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](https://docs.thanx.com/partner/issuance-jobs/get-issuance-job.md) 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](https://docs.thanx.com/consumer/guides/points.md) 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](https://docs.thanx.com/partner/overview.md#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

**merchant\_id** `string` *required*

Merchant ID

**points** `integer` *required*

Number of bonus points to issue to each user. Must be a positive integer.

**identifiers** `array` *required*

Array of user identifiers to issue points to (max 10,000)

**identifier**

**type** `string` *required*

Identifier type: `email` or `phone`

**value** `string` *required*

Identifier value. Phone numbers must be in E.164 format (e.g.,
`+12025551234`).

**reason** `string`

Optional note describing why the points were issued. Stored with the points
transaction for auditing.

**X-Idempotency-Key** `string`

Optional idempotency key to prevent duplicate issuance jobs.

### Response

Returns `202 Accepted` with the issuance job object.

**id** `string`

Issuance job ID

**points** `integer`

Number of points issued to each user

**state** `string`

Job state: `pending`, `processing`, `completed`, or `failed`

**total\_count** `integer`

Total number of identifiers submitted

**processed\_count** `integer`

Number of identifiers processed so far

**success\_count** `integer`

Number of users successfully issued points

**failure\_count** `integer`

Number of failed issuances

**progress\_percent** `integer`

Completion percentage (0-100)

**created\_at** `datetime`

Job creation timestamp (ISO8601)

**started\_at** `datetime`

Processing start timestamp (ISO8601), null if not started

**completed\_at** `datetime`

Processing completion timestamp (ISO8601), null if not completed

```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"
      }
    ]
  }'
```

```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
  }
}
```


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