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

MethodPathDescription
GET/loyalty-transactionsList loyalty transactions
GET/loyalty-transactions/:idGet a loyalty transaction
POST/loyalty-transactionsAdjust 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

FieldTypeDescription
idintegerRead-only. Unique ID.
organization_idintegerRead-only. Organization of the card.
program_idintegerRead-only. Program of the card.
member_idintegerRead-only. Card whose balance moved.
contact_idinteger | nullRead-only. Contact of the card.
typestringRead-only. Kind of movement (see Transaction types).
amountnumberRead-only. Signed amount: positive adds balance, negative removes it.
balance_afternumberRead-only. Card balance right after this movement.
remaining_amountnumber | nullRead-only. For credits that can expire: the part not spent yet. Spending uses the credits that expire first.
expires_atstring (date-time) | nullRead-only. When the remaining part of this credit expires.
expired_atstring (date-time) | nullRead-only. When the remaining part of this credit expired.
source_typestring | nullRead-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_idstring | nullRead-only. ID of the origin (your reference, an order ID, a reward ID...).
source_amountnumber | nullRead-only. Purchase amount that produced an earn movement.
descriptionstring | nullText shown in the history (up to 500 characters).
metadataobject | nullRead-only. Extra data of the movement.
idempotency_keystring | nullWrite-only. Your unique key for an adjustment. Never returned.
created_by_user_idinteger | nullRead-only. User who made the movement (null for API key movements).
created_atstring (date-time)Read-only. Creation time.
updated_atstring (date-time)Read-only. Last update time.
deleted_atstring (date-time) | nullRead-only. Always null: transactions are never deleted.
contactobject | nullRead-only, added to every response: id, first_name, last_name, email, phone.
created_by_userobject | nullRead-only, added: id, first_name, last_name of the user who made the movement.

Transaction types

ValueDescription
earnEarned from a purchase or visit
bonusWelcome or birthday bonus
referralReferral bonus
redeemSpent on a reward or cashback
useMembership check-in or gift card spend
loadGift card or membership uses loaded
adjustManual adjustment
expireExpired balance
reversalReturned balance (cancelled purchase or cancelled reward code)

Report an issue with this documentation

Please log in to report issues with our documentation.