Handle rewards event notifications

​

Overview

If you already have a loyalty program and your customers are earning rewards, you can integrate with Imprints rewards event notification to handle rewards originating from Imprint.

As the loyalty program maintainer, you are responsible for managing the customer’s reward balance and issuing rewards when required. Imprint track rewards earned by customers from transactions and promotions and notifies you when rewards are available or should be issued.

​

How it works

1. Rewards Tracking

• Customer earns rewards from transactions and promotions.
• Imprint keeps track of accumulated rewards.

2. Rewards Issuance Event Notification

• When it is time for the reward to be available or usable, Imprint post a reward event notification to the endpoint you provided

3. Handling the Rewards Event Notification

• Upon receiving the event, you should process the request and issue the reward to the customer.
• If the reward is successfully issued, respond to the event notification with a 200 status code.
• If there is an issue with issuing the reward, respond with an appropriate error code.
• Imprint will retry sending the event with exponential backoff.

​

Reward Webhook Configuration Options

The rewards program can be configured in one of two ways:

1. Per-Event Reward

• Receive rewards for each individual event, such as transactions or offers, and their status updates.

2. Aggregrate Statement Reward

• Receive a single aggregated reward at the end of the customer’s statement cycle, representing the total rewards earned during the statement period

​

Aggregate Statement Reward

When configured for aggregate statement rewards, your program will receive a single AVAILABLE reward event at the end of the customer’s current statement cycle. This event reflects the total amount of rewards earned during the cycle.

Reward Issuance Upon Statement Closure Once a customer’s statement closes, you will receive a AVAILABLE reward event structured as follows:

{
  "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": "AVAILABLE"
  },
  "object": "REWARD"
}

​

Individual Rewards

If your program is configured up to receive rewards for each individual event (transactions or offers).

You will receive reward events when the reward is created and when the reward is available.

Transaction Reward Processing:

• When the transaction is CAPTURED or REFUNDED, a PENDING reward is created and you will receive a PENDING transactional reward event.

Example of a reward event send after a transaction identified by fbfe3146-3a72-4edf-a31b-b2773e9153d8 is CAPTURED

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

• When a promotion is satisfied, an offer reward is created and you will receive a PENDING offer reward event.

Statement Closure:

• When the customer’s statement closes, you will receive an AVAILABLE reward event for each reward created during the statement cycle.

Example of a reward event send after the customer’s statement closes

{
  "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": "AVAILABLE"
  },
  "object": "REWARD"
}

​

Examples

Promotional Reward

Customer should be issued $50.00 for satisfying the conditions of a promotion.

{
  "data": {
    "amount": 5000,
    "created_at": "2025-02-13T19:08:07.000Z",
    "customer_id": "1ebb6d73-d132-4c80-9736-dfd5b01f11a4",
    "reward_id": "c960a701-1eaf-47aa-8f54-c4ca96bba4b3",
    "transaction_id": "",
    "type": "OFFER",
    "status": "AVAILABLE"
  },
  "object": "REWARD"
}

Transactional Reward

Customer should be issued $1.00 for making a transaction identified by transaction_id

{
  "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": "OFFER",
    "status": "AVAILABLE"
  },
  "object": "REWARD"
}

One-time Reward

Customer should be issued a one-off reward

{
  "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": "",
    "type": "ONE_TIME",
    "status": "AVAILABLE"
  },
  "object": "REWARD"
}