Loyalty transactions
Every change to a card balance is a transaction: purchases, bonuses, redemptions, check-ins, top-ups, expirations and manual adjustments. The ledger is append-only: transactions cannot be edited or deleted. To undo a movement, create an opposite adjustment.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /loyalty-transactions | List loyalty transactions |
GET | /loyalty-transactions/:id | Get a loyalty transaction |
POST | /loyalty-transactions | Adjust a balance |
There is no update or delete. The API key is scoped to one organization: reads are filtered to it automatically, and organization_id is required in the body of an adjustment.
The loyalty transaction 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 whose balance moved. |
contact_id | integer | null | Read-only. Contact of the card. |
type | string | Read-only. Kind of movement (see Transaction types). |
amount | number | Read-only. Signed amount: positive adds balance, negative removes it. |
balance_after | number | Read-only. Card balance right after this movement. |
remaining_amount | number | null | Read-only. For credits that can expire: the part not spent yet. Spending uses the credits that expire first. |
expires_at | string (date-time) | null | Read-only. When the remaining part of this credit expires. |
expired_at | string (date-time) | null | Read-only. When the remaining part of this credit expired. |
source_type | string | null | Read-only. Origin of the movement, e.g. pos (a purchase registered with a reference), order, invoice, reservation, event_registration, reward, check_in, manual, api. |
source_id | string | null | Read-only. ID of the origin (your reference, an order ID, a reward ID...). |
source_amount | number | null | Read-only. Purchase amount that produced an earn movement. |
description | string | null | Text shown in the history (up to 500 characters). |
metadata | object | null | Read-only. Extra data of the movement. |
idempotency_key | string | null | Write-only. Your unique key for an adjustment. Never returned. |
created_by_user_id | integer | null | Read-only. User who made the movement (null for API key movements). |
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: transactions are never deleted. |
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 made the movement. |
Transaction types
| Value | Description |
|---|---|
earn | Earned from a purchase or visit |
bonus | Welcome or birthday bonus |
referral | Referral bonus |
redeem | Spent on a reward or cashback |
use | Membership check-in or gift card spend |
load | Gift card or membership uses loaded |
adjust | Manual adjustment |
expire | Expired balance |
reversal | Returned balance (cancelled purchase or cancelled reward code) |
Report an issue with this documentation
Please log in to report issues with our documentation.