Loyalty redemptions
A redemption spends part of a card balance and issues a reward code. Points and stamps programs redeem a catalog reward; cashback and gift cards redeem an amount of money, which becomes a fixed discount. The code is handed over at the counter (mark it used) or applied as a discount code at the catalog checkout.
Reward codes are bearer codes: whoever has the code can use it.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /loyalty-redemptions | List loyalty redemptions |
GET | /loyalty-redemptions/:id | Get a loyalty redemption |
POST | /loyalty-redemptions | Redeem a reward |
PATCH | /loyalty-redemptions/:id | Use or cancel a redemption |
There is no delete: cancel a code instead. The API key is scoped to one organization: reads are filtered to it automatically, and organization_id is required in the body of a redemption.
The loyalty redemption object
json
Fields
| Field | Type | Description |
|---|---|---|
id | integer | Read-only. Unique ID. |
organization_id | integer | Read-only. Organization of the card. |
program_id | integer | Read-only. Program of the card. |
member_id | integer | Read-only. Card that spent the balance. |
contact_id | integer | null | Read-only. Contact of the card. |
reward_id | integer | null | Read-only. Redeemed reward. null for balance (amount) redemptions. |
transaction_id | integer | null | Read-only. The transaction that spent the balance. |
code | string | Read-only. Reward code (8 characters). |
status | string | One of issued, used, cancelled, expired (see below). Only used and cancelled can be set. |
cost | number | Read-only. Balance spent. |
reward_name | string | null | Read-only. Copy of the reward name at the time of the redemption. |
reward_type | string | null | Read-only. Copy of the reward type. Balance redemptions use discount_fixed. |
discount_value | number | null | Read-only. Copy of the reward discount. Balance redemptions use the amount spent. |
expires_at | string (date-time) | null | Read-only. When an unused code expires (from the reward code_validity_days). |
used_at | string (date-time) | null | Read-only. When the code was used. |
used_by_user_id | integer | null | Read-only. User who marked it used (null for API keys). |
channel | string | null | Where it was created: staff, public_page, checkout, ai_assistant, api or automation. |
order_id | integer | null | Order where the code was used, if any. Can be set when marking it used. |
metadata | object | null | Read-only. Extra data. |
created_by_user_id | integer | null | Read-only. User who created the redemption (null for API keys). |
created_at | string (date-time) | Read-only. Creation time. |
updated_at | string (date-time) | Read-only. Last update time. |
deleted_at | string (date-time) | null | Read-only. Always null. |
contact | object | null | Read-only, added to every response: id, first_name, last_name, email, phone. |
created_by_user | object | null | Read-only, added: id, first_name, last_name of the user who created it. |
Status values
| Value | Description |
|---|---|
issued | Code ready to be used |
used | Reward handed over or discount applied |
cancelled | Cancelled; the balance was given back |
expired | Not used before expires_at; the balance was given back |
When a redemption is created, the Loyalty reward redeemed automation trigger runs.
Report an issue with this documentation
Please log in to report issues with our documentation.