Loyalty programs

A loyalty program is a card your customers carry: a stamp card, a points program, cashback, a membership (a pack of uses) or a gift card. Each customer gets one member card per program. Programs are usually configured in the Loyalty app; through the API you read them to know their ID, type, currency and enrollment link, and you can also create and configure them.

Endpoints

MethodPathDescription
GET/loyalty-programsList loyalty programs
GET/loyalty-programs/:idGet a loyalty program
POST/loyalty-programsCreate a loyalty program
PATCH/loyalty-programs/:idUpdate a loyalty program
DELETE/loyalty-programs/:idDelete a loyalty program

All requests use your API key in the x-api-key header (see Authentication). An API key is scoped to one organization: reads are filtered to it automatically, and organization_id is required in the body when you create records. Records of other organizations are never returned (lists come back empty and direct access returns 404).

Loyalty API at a glance

StepEndpoint
Find the program IDGET /loyalty-programs
Enroll a customer (idempotent)POST /loyalty-members
Find a card by phone, email or card codeGET /loyalty-members?lookup=
Scan a card or reward QR codePOST /loyalty-actions scan
Register a purchase or visitPOST /loyalty-actions register_purchase
Redeem a reward or balancePOST /loyalty-redemptions
Mark a reward code used or cancel itPATCH /loyalty-redemptions/:id
Manual balance adjustmentPOST /loyalty-transactions
Balance historyGET /loyalty-transactions
Card page and Apple / Google Wallet linksPOST /loyalty-actions wallet_links
KPIsGET /loyalty-reports

The loyalty program object

json

Fields

FieldTypeDescription
idintegerRead-only. Unique ID.
organization_idintegerOrganization that owns the program. Required on create; cannot be changed.
namestringProgram name (1 to 255 characters). Required on create.
descriptionstring | nullDescription (up to 5000 characters).
typestringOne of stamps, points, cashback, membership, gift_card (see Program types). Required on create; cannot be changed.
statusstringOne of draft, active, paused, archived. Default draft.
slugstringLink name used in enrollment_url (up to 80 characters), unique per organization. Generated from name when omitted.
currency_codestring | nullCurrency (for example USD). Purchases only earn by amount in this currency. Required to activate cashback and gift_card programs.
earn_rulesobject | nullHow purchases and visits earn: sources (orders, invoices, reservations, events booleans), amount_step, points_per_step, stamps_per_visit, min_amount, points_per_visit (non-negative numbers; amount_step greater than 0) and auto_enroll (enroll the buyer on the first qualifying purchase). Sent keys are merged with the current rules.
stamps_requiredinteger | nullStamps programs: stamps for a full card, 2 to 30. Default 10.
cashback_percentnumber | nullCashback programs: percentage of the purchase returned, greater than 0 and up to 100. Default 5.
welcome_bonusnumberBalance given on enrollment (points, stamps or cashback). Default 0.
birthday_bonusnumberBalance given on the member's birthday (metadata.birthday of the member, MM-DD). Default 0.
referrals_enabledbooleanMembers can invite friends with their referral_code (points, stamps and cashback only). Default false.
referrer_bonusnumberBonus for the member who invited. Default 0.
referred_bonusnumberBonus for the invited member. Default 0.
expiration_daysinteger | nullDays after which earned balance expires (at least 1). null = never.
min_redeem_amountnumber | nullCashback: minimum amount per redemption.
membership_usesinteger | nullMembership: uses granted on enrollment (at least 1). Default 10.
membership_validity_daysinteger | nullMembership: days the card is valid after enrollment (sets the member expires_at).
gift_card_default_amountnumber | nullGift cards: opening balance when no initial_amount is sent on enrollment.
tiers_enabledbooleanMembers are placed in tiers (points, stamps and cashback only). Default false.
tier_basisstring | nullWhat tiers measure: lifetime_points, lifetime_spend or visits. Default lifetime_points for points programs.
card_designobject | nullCard colors (background_color, foreground_color, label_color, accent_color as #RRGGBB), images (logo_url, icon_url, strip_image_url) and stamp_icon. Sent keys are merged with the current design.
locationsarray | nullUp to 10 store locations shown by wallet passes: name, address, latitude, longitude, relevant_text.
enrollment_settingsobject | nullPublic enrollment page options: ask_birthday, require_email, require_phone (default true), consent_text, headline, success_message.
termsstring | nullTerms and conditions (up to 10000 characters).
public_enrollment_enabledbooleanCustomers can join on the public enrollment_url. Default true.
apple_wallet_enabledbooleanOffer the Apple Wallet pass. Default true.
google_wallet_enabledbooleanOffer the Google Wallet pass. Default true.
google_class_idstring | nullRead-only. Google Wallet class of the program.
google_class_synced_atstring (date-time) | nullRead-only. Last sync of the Google Wallet class.
member_countintegerRead-only. Number of members.
created_by_user_idinteger | nullRead-only. User who created the program (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. Set when the program is deleted.
enrollment_urlstringRead-only, calculated. Public page where customers join (/l/{organization_id}/{slug}).
wallet_availabilityobjectRead-only, calculated. Whether Apple Wallet and Google Wallet passes are available on the platform (apple, google).

Program types

ValueBalanceHow customers earn or use it
stampsStampsearn_rules.stamps_per_visit stamps per qualifying visit; a full card has stamps_required stamps.
pointsPointsfloor(amount / earn_rules.amount_step) * earn_rules.points_per_step, plus earn_rules.points_per_visit per visit.
cashbackMoney (currency_code)cashback_percent of the purchase amount. Spent by amount.
membershipUses leftStarts with membership_uses; each check-in uses one.
gift_cardMoney (currency_code)Loaded on enrollment (gift_card_default_amount) or with a top-up. Spent by amount.

Purchases only earn by amount when they are in the program currency_code. earn_rules.min_amount sets a minimum purchase. When tiers are enabled, points and cashback earned are multiplied by the member tier earn_multiplier (stamps are not multiplied).

Status values

ValueDescription
draftBeing configured.
activeLive: members earn and redeem.
pausedTemporarily stopped.
archivedClosed. New members cannot be enrolled.

Events in your systems

Loyalty events can be sent to your own systems with Automations: create an automation with a Loyalty Events trigger and add an HTTP node that calls your endpoint. Available triggers: member enrolled, loyalty balance changed, reward unlocked, reward redeemed, tier changed, card requested, member inactive and balance expiring. The trigger data includes the contact, the program, the member (code, balance, tier) and the card URL, which you can map into the HTTP request.

Error Handling

The Loyalty API returns standard HTTP status codes. Business rules return 400 Bad Request with a readable message, for example "Not enough balance for this reward", "This reward requires the Gold tier", "This card is blocked" or "This program is not active".

json
Status CodeDescription
400 Bad RequestInvalid data or a business rule was not met
401 UnauthorizedMissing or invalid API key
403 ForbiddenThe organization_id sent is not the API key's organization
404 Not FoundProgram, member, reward or code not found (also for records of other organizations)
429 Too Many RequestsRate limit exceeded (see Authentication)
500 Internal Server ErrorServer error

Related

Loyalty Members, Loyalty Actions, Loyalty Transactions, Loyalty Redemptions, Loyalty Rewards, Loyalty Tiers and Loyalty Reports.

Report an issue with this documentation

Please log in to report issues with our documentation.