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

MethodPathDescription
GET/loyalty-redemptionsList loyalty redemptions
GET/loyalty-redemptions/:idGet a loyalty redemption
POST/loyalty-redemptionsRedeem a reward
PATCH/loyalty-redemptions/:idUse 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

FieldTypeDescription
idintegerRead-only. Unique ID.
organization_idintegerRead-only. Organization of the card.
program_idintegerRead-only. Program of the card.
member_idintegerRead-only. Card that spent the balance.
contact_idinteger | nullRead-only. Contact of the card.
reward_idinteger | nullRead-only. Redeemed reward. null for balance (amount) redemptions.
transaction_idinteger | nullRead-only. The transaction that spent the balance.
codestringRead-only. Reward code (8 characters).
statusstringOne of issued, used, cancelled, expired (see below). Only used and cancelled can be set.
costnumberRead-only. Balance spent.
reward_namestring | nullRead-only. Copy of the reward name at the time of the redemption.
reward_typestring | nullRead-only. Copy of the reward type. Balance redemptions use discount_fixed.
discount_valuenumber | nullRead-only. Copy of the reward discount. Balance redemptions use the amount spent.
expires_atstring (date-time) | nullRead-only. When an unused code expires (from the reward code_validity_days).
used_atstring (date-time) | nullRead-only. When the code was used.
used_by_user_idinteger | nullRead-only. User who marked it used (null for API keys).
channelstring | nullWhere it was created: staff, public_page, checkout, ai_assistant, api or automation.
order_idinteger | nullOrder where the code was used, if any. Can be set when marking it used.
metadataobject | nullRead-only. Extra data.
created_by_user_idinteger | nullRead-only. User who created the redemption (null for API keys).
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.
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 created it.

Status values

ValueDescription
issuedCode ready to be used
usedReward handed over or discount applied
cancelledCancelled; the balance was given back
expiredNot 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.