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
| Method | Path | Description |
|---|---|---|
GET | /loyalty-programs | List loyalty programs |
GET | /loyalty-programs/:id | Get a loyalty program |
POST | /loyalty-programs | Create a loyalty program |
PATCH | /loyalty-programs/:id | Update a loyalty program |
DELETE | /loyalty-programs/:id | Delete 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
| Step | Endpoint |
|---|---|
| Find the program ID | GET /loyalty-programs |
| Enroll a customer (idempotent) | POST /loyalty-members |
| Find a card by phone, email or card code | GET /loyalty-members?lookup= |
| Scan a card or reward QR code | POST /loyalty-actions scan |
| Register a purchase or visit | POST /loyalty-actions register_purchase |
| Redeem a reward or balance | POST /loyalty-redemptions |
| Mark a reward code used or cancel it | PATCH /loyalty-redemptions/:id |
| Manual balance adjustment | POST /loyalty-transactions |
| Balance history | GET /loyalty-transactions |
| Card page and Apple / Google Wallet links | POST /loyalty-actions wallet_links |
| KPIs | GET /loyalty-reports |
The loyalty program object
json
Fields
| Field | Type | Description |
|---|---|---|
id | integer | Read-only. Unique ID. |
organization_id | integer | Organization that owns the program. Required on create; cannot be changed. |
name | string | Program name (1 to 255 characters). Required on create. |
description | string | null | Description (up to 5000 characters). |
type | string | One of stamps, points, cashback, membership, gift_card (see Program types). Required on create; cannot be changed. |
status | string | One of draft, active, paused, archived. Default draft. |
slug | string | Link name used in enrollment_url (up to 80 characters), unique per organization. Generated from name when omitted. |
currency_code | string | null | Currency (for example USD). Purchases only earn by amount in this currency. Required to activate cashback and gift_card programs. |
earn_rules | object | null | How 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_required | integer | null | Stamps programs: stamps for a full card, 2 to 30. Default 10. |
cashback_percent | number | null | Cashback programs: percentage of the purchase returned, greater than 0 and up to 100. Default 5. |
welcome_bonus | number | Balance given on enrollment (points, stamps or cashback). Default 0. |
birthday_bonus | number | Balance given on the member's birthday (metadata.birthday of the member, MM-DD). Default 0. |
referrals_enabled | boolean | Members can invite friends with their referral_code (points, stamps and cashback only). Default false. |
referrer_bonus | number | Bonus for the member who invited. Default 0. |
referred_bonus | number | Bonus for the invited member. Default 0. |
expiration_days | integer | null | Days after which earned balance expires (at least 1). null = never. |
min_redeem_amount | number | null | Cashback: minimum amount per redemption. |
membership_uses | integer | null | Membership: uses granted on enrollment (at least 1). Default 10. |
membership_validity_days | integer | null | Membership: days the card is valid after enrollment (sets the member expires_at). |
gift_card_default_amount | number | null | Gift cards: opening balance when no initial_amount is sent on enrollment. |
tiers_enabled | boolean | Members are placed in tiers (points, stamps and cashback only). Default false. |
tier_basis | string | null | What tiers measure: lifetime_points, lifetime_spend or visits. Default lifetime_points for points programs. |
card_design | object | null | Card 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. |
locations | array | null | Up to 10 store locations shown by wallet passes: name, address, latitude, longitude, relevant_text. |
enrollment_settings | object | null | Public enrollment page options: ask_birthday, require_email, require_phone (default true), consent_text, headline, success_message. |
terms | string | null | Terms and conditions (up to 10000 characters). |
public_enrollment_enabled | boolean | Customers can join on the public enrollment_url. Default true. |
apple_wallet_enabled | boolean | Offer the Apple Wallet pass. Default true. |
google_wallet_enabled | boolean | Offer the Google Wallet pass. Default true. |
google_class_id | string | null | Read-only. Google Wallet class of the program. |
google_class_synced_at | string (date-time) | null | Read-only. Last sync of the Google Wallet class. |
member_count | integer | Read-only. Number of members. |
created_by_user_id | integer | null | Read-only. User who created the program (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. Set when the program is deleted. |
enrollment_url | string | Read-only, calculated. Public page where customers join (/l/{organization_id}/{slug}). |
wallet_availability | object | Read-only, calculated. Whether Apple Wallet and Google Wallet passes are available on the platform (apple, google). |
Program types
| Value | Balance | How customers earn or use it |
|---|---|---|
stamps | Stamps | earn_rules.stamps_per_visit stamps per qualifying visit; a full card has stamps_required stamps. |
points | Points | floor(amount / earn_rules.amount_step) * earn_rules.points_per_step, plus earn_rules.points_per_visit per visit. |
cashback | Money (currency_code) | cashback_percent of the purchase amount. Spent by amount. |
membership | Uses left | Starts with membership_uses; each check-in uses one. |
gift_card | Money (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
| Value | Description |
|---|---|
draft | Being configured. |
active | Live: members earn and redeem. |
paused | Temporarily stopped. |
archived | Closed. 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 Code | Description |
|---|---|
400 Bad Request | Invalid data or a business rule was not met |
401 Unauthorized | Missing or invalid API key |
403 Forbidden | The organization_id sent is not the API key's organization |
404 Not Found | Program, member, reward or code not found (also for records of other organizations) |
429 Too Many Requests | Rate limit exceeded (see Authentication) |
500 Internal Server Error | Server 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.