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

# Rewards Program

> Guide on reward types, statuses, earning configurations, and processing reward webhooks

### Overview

If you have a loyalty program, you can integrate with Imprint's reward webhooks to handle rewards earned by your customers. As the loyalty program maintainer, you are responsible for issuing and deducting rewards when notified by Imprint.

This guide covers reward types, statuses, earning configurations, webhook delivery timing, and how to process individual and aggregated reward events.

### How it works

1. **Customer earns rewards** — Customers earn rewards from transactions, promotions, referrals, and other qualifying events. Imprint tracks all rewards earned.

2. **Imprint sends a reward webhook** — When a reward is ready to be issued or deducted, Imprint sends a reward event to your configured endpoint.

3. **You process the reward** — Upon receiving the event, issue or deduct the reward for the customer. Respond with a `200` status code to acknowledge receipt. If there is an issue, respond with an appropriate error code and Imprint will retry with exponential backoff.

4. **You confirm issuance** — Depending on your webhook configuration:
   * **`AVAILABLE`/`DEDUCTED` webhooks** — Your `200` acknowledgement confirms that the reward has been issued or deducted. No further action is required.
   * **`PENDING`/`PENDING_DEDUCTION` webhooks** — After processing the reward, use the [Update a reward](/api-reference/update-a-reward) API to update the status to `AVAILABLE` or `DEDUCTED` to confirm issuance.

### Reward Types

Imprint supports the following reward types:

| Type            | Description                                                                                                                                       |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TRANSACTIONAL` | Earned from qualifying purchases. The reward amount is determined by the earning rate configured for the program.                                 |
| `OFFER`         | Earned when a customer satisfies the conditions of a promotion or offer.                                                                          |
| `ONE_TIME`      | A one-off reward issued to a customer, typically for goodwill or manual adjustments.                                                              |
| `STATEMENT`     | An aggregated reward representing the total rewards earned during a statement cycle. Only used with the aggregate statement reward configuration. |
| `REFERRAL`      | Earned when a customer successfully refers a new cardholder.                                                                                      |
| `DELAYED`       | An aggregated reward representing the total rewards earned, issued after a configured number of days have elapsed since the rewards were created. |

### Reward Status

Rewards follow a lifecycle with two paths:

**Issuance: `PENDING` → `AVAILABLE`**

* `PENDING` — The reward has been created and is ready to be issued by you. After issuing the reward, use the [Update a reward](/api-reference/update-a-reward) API to update the status to `AVAILABLE`.
* `AVAILABLE` — The reward has been issued to the customer.

**Deduction: `PENDING_DEDUCTION` → `DEDUCTED`**

* `PENDING_DEDUCTION` — A deduction has been initiated (e.g., due to a returned transaction) and is ready to be processed by you. After debiting the reward, use the [Update a reward](/api-reference/update-a-reward) API to update the status to `DEDUCTED`.
* `DEDUCTED` — The reward has been deducted from the customer's balance.

Your webhook can be configured to deliver events with either status:

* **`PENDING` / `PENDING_DEDUCTION`** — You receive the event, process the reward, then confirm via the API.
* **`AVAILABLE` / `DEDUCTED`** — You receive the event, process the reward, and your `200` acknowledgement confirms issuance. No API call is required.

### Choosing a Webhook Status Configuration

Choose which webhook status to receive based on how you issue rewards:

* **`AVAILABLE` / `DEDUCTED`** — Use this if you will always issue or deduct the full reward amount as provided in the webhook. When you acknowledge the event with a `200` response, Imprint considers the reward issued. No further action is needed.

* **`PENDING` / `PENDING_DEDUCTION`** — Use this if you need to modify the reward amount before issuing. For example, if your program issues rewards in $5 increments and the webhook contains a $7 reward, you may choose to issue only \$5. After processing the reward, use the [Update a reward](/api-reference/update-a-reward) API to update the status to `AVAILABLE` or `DEDUCTED` and set the amount to the actual amount issued.

#### Example: `AVAILABLE` webhook flow

1. Imprint sends a webhook with status `AVAILABLE` and amount `1000` (\$10.00):

```json theme={null}
{
  "data": {
    "amount": 1000,
    "customer_id": "1ebb6d73-d132-4c80-9736-dfd5b01f11a4",
    "reward_id": "c960a701-1eaf-47aa-8f54-c4ca96bba4b3",
    "type": "TRANSACTIONAL",
    "status": "AVAILABLE"
  },
  "object": "REWARD"
}
```

2. You issue the full \$10.00 reward and respond with `200`.

3. The reward is now `AVAILABLE`. Calling [Get a reward](/api-reference/get-a-reward) returns:

```json theme={null}
{
  "reward_id": "c960a701-1eaf-47aa-8f54-c4ca96bba4b3",
  "amount": 1000,
  "status": "AVAILABLE"
}
```

#### Example: `PENDING` webhook flow

1. Imprint sends a webhook with status `PENDING` and amount `1200` (\$12.00):

```json theme={null}
{
  "data": {
    "amount": 1200,
    "customer_id": "1ebb6d73-d132-4c80-9736-dfd5b01f11a4",
    "reward_id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a",
    "type": "TRANSACTIONAL",
    "status": "PENDING"
  },
  "object": "REWARD"
}
```

2. You respond with `200` to acknowledge receipt.

3. The reward remains `PENDING`. Calling [Get a reward](/api-reference/get-a-reward) returns:

```json theme={null}
{
  "reward_id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a",
  "amount": 1200,
  "status": "PENDING"
}
```

4. You issue $10.00 (your program issues in $5 increments) and call [Update a reward](/api-reference/update-a-reward) with status `AVAILABLE` and amount `1000`.

5. Calling [Get a reward](/api-reference/get-a-reward) now returns:

```json theme={null}
{
  "reward_id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a",
  "amount": 1000,
  "status": "AVAILABLE"
}
```

### Reward Earning

You receive reward webhooks when rewards are ready to be issued. The timing depends on your program's earning configuration:

| Earning Timing   | Description                                                                                                                                                                                                                                                              |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Immediate        | A webhook is sent for each individual reward as it is created. For `TRANSACTIONAL` rewards, this is when the transaction settles. For `OFFER`, `ONE_TIME`, and `REFERRAL` rewards, this is when the reward event occurs (e.g., promotion satisfied, referral completed). |
| Statement        | A single aggregated webhook is sent at the end of the customer's statement cycle, representing the total rewards earned during that period.                                                                                                                              |
| Delayed (X days) | A single aggregated webhook is sent after a configured number of days have elapsed since the rewards were created.                                                                                                                                                       |

### Aggregated Rewards

For programs configured with statement or delayed issuance, all rewards earned during the period are aggregated into a single reward event.
Instead of receiving individual webhooks for each transaction or offer, you receive one webhook representing the total rewards earned.

* **Statement issuance** — The aggregated reward is sent when the customer’s statement closes.
* **Delayed issuance** — The aggregated reward is sent after the configured number of days have elapsed.

Example of an aggregated reward event:

```json theme={null}
{
  "data": {
    "amount": 1000,
    "created_at": "2025-02-13T19:08:07.000Z",
    "customer_id": "1ebb6d73-d132-4c80-9736-dfd5b01f11a4",
    "reward_id": "c960a701-1eaf-47aa-8f54-c4ca96bba4b3",
    "type": "STATEMENT",
    "status": "PENDING"
  },
  "object": "REWARD"
}
```

### Individual Rewards

For programs configured with immediate issuance, you receive a webhook for each individual reward event.

#### Transaction Rewards

When a transaction settles, you receive a reward webhook for a `TRANSACTIONAL` type reward.

Example of a reward event sent when a transaction settles:

```json theme={null}
{
  "data": {
    "amount": 100,
    "created_at": "2025-02-13T19:08:07.000Z",
    "customer_id": "1ebb6d73-d132-4c80-9736-dfd5b01f11a4",
    "reward_id": "c960a701-1eaf-47aa-8f54-c4ca96bba4b3",
    "transaction_id": "fbfe3146-3a72-4edf-a31b-b2773e9153d8",
    "type": "TRANSACTIONAL",
    "status": "PENDING"
  },
  "object": "REWARD"
}
```

#### Offer Rewards

When a promotion is satisfied, you receive a reward webhook for an `OFFER` type reward.

Example of a reward event sent when an offer is satisfied:

```json theme={null}
{
  "data": {
    "amount": 5000,
    "created_at": "2025-02-13T19:08:07.000Z",
    "customer_id": "1ebb6d73-d132-4c80-9736-dfd5b01f11a4",
    "reward_id": "a3b2c1d0-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "type": "OFFER",
    "status": "PENDING"
  },
  "object": "REWARD"
}
```

#### Referral Rewards

When a referral is completed, you receive a reward webhook for a `REFERRAL` type reward.

Example of a reward event sent when a referral is completed:

```json theme={null}
{
  "data": {
    "amount": 10000,
    "created_at": "2025-02-13T19:08:07.000Z",
    "customer_id": "1ebb6d73-d132-4c80-9736-dfd5b01f11a4",
    "reward_id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a",
    "type": "REFERRAL",
    "status": "PENDING"
  },
  "object": "REWARD"
}
```

#### One-Time Rewards

When a one-off reward is issued, you receive a reward webhook for a `ONE_TIME` type reward.

Example of a one-time reward event:

```json theme={null}
{
  "data": {
    "amount": 100,
    "created_at": "2025-02-13T19:08:07.000Z",
    "customer_id": "1ebb6d73-d132-4c80-9736-dfd5b01f11a4",
    "reward_id": "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b",
    "type": "ONE_TIME",
    "status": "PENDING"
  },
  "object": "REWARD"
}
```