Rewards Program - Imprint Docs

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

Customer earns rewards — Customers earn rewards from transactions, promotions, referrals, and other qualifying events. Imprint tracks all rewards earned.
Imprint sends a reward webhook — When a reward is ready to be issued or deducted, Imprint sends a reward event to your configured endpoint.
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.
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 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 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 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 to update the status to AVAILABLE or DEDUCTED and set the amount to the actual amount issued.

Example: `AVAILABLE` webhook flow

Imprint sends a webhook with status AVAILABLE and amount 1000 ($10.00):

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

You issue the full $10.00 reward and respond with 200.
The reward is now AVAILABLE. Calling Get a reward returns:

{
  "reward_id": "c960a701-1eaf-47aa-8f54-c4ca96bba4b3",
  "amount": 1000,
  "status": "AVAILABLE"
}

Example: `PENDING` webhook flow

Imprint sends a webhook with status PENDING and amount 1200 ($12.00):

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

You respond with 200 to acknowledge receipt.
The reward remains PENDING. Calling Get a reward returns:

{
  "reward_id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a",
  "amount": 1200,
  "status": "PENDING"
}

You issue $10.00 (your program issues in$ 5 increments) and call Update a reward with status AVAILABLE and amount 1000.
Calling Get a reward now returns:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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"
}

​Overview

​How it works

​Reward Types

​Reward Status

​Choosing a Webhook Status Configuration

​Example: AVAILABLE webhook flow

​Example: PENDING webhook flow

​Reward Earning

​Aggregated Rewards

​Individual Rewards

​Transaction Rewards

​Offer Rewards

​Referral Rewards

​One-Time Rewards