Loyalty members
A loyalty member is one customer's card in one program. A contact can have one card per program. Each card has a member_code (the code printed in its QR and scanned at the counter), a balance (points, stamps, money or uses depending on the program type) and a private card_url the customer can open on their phone or add to Apple Wallet / Google Wallet.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /loyalty-members | List or look up loyalty members |
GET | /loyalty-members/:id | Get a loyalty member |
POST | /loyalty-members | Enroll a loyalty member |
PATCH | /loyalty-members/:id | Update a loyalty member |
DELETE | /loyalty-members/:id | Delete a loyalty member |
The API key is scoped to one organization: reads are filtered to it automatically, and organization_id is required in the body on enroll.
The loyalty member object
json
Fields
| Field | Type | Description |
|---|---|---|
id | integer | Read-only. Unique ID. |
organization_id | integer | Organization of the card. Required on enroll; cannot be changed. |
program_id | integer | Loyalty program of the card. Required on enroll; cannot be changed. |
contact_id | integer | Contact who owns the card. A contact has one card per program. Cannot be changed. |
status | string | One of active, blocked. A blocked card cannot earn, redeem or check in. |
marketing_consent | boolean | The customer accepts marketing messages. |
expires_at | string (date-time) | null | Card expiry (memberships with membership_validity_days). null = no expiry. |
metadata | object | null | Extra data stored on the card. metadata.birthday (MM-DD) is used for the program birthday_bonus. |
member_code | string | Read-only. Card code shown in the card QR. Use it with lookup or the scan action. |
balance | number | Read-only. Current balance: points, stamps, money (cashback / gift card) or uses left (membership). Changed only through actions, redemptions and adjustments. |
lifetime_earned | number | Read-only. Total earned since enrollment. |
lifetime_redeemed | number | Read-only. Total redeemed since enrollment. |
lifetime_spend | number | Read-only. Total purchase amount registered on the card. |
visits_count | integer | Read-only. Qualifying purchases or visits. |
rewards_unlocked_count | integer | Read-only. Number of times the balance went up to (or past) the cost of an active reward. |
tier_id | integer | null | Read-only. Current tier, when the program has tiers. |
uses_remaining | integer | null | Read-only. Uses left on a membership. |
enrolled_at | string (date-time) | Read-only. Enrollment time. |
enrollment_source | string | How the card was created: public_page, manual, checkout, automation, api, import, ai_assistant, referral or purchase. Cards created with an API key get api unless you send another value. |
referral_code | string | null | Read-only. The member's own code to invite friends (programs with referrals). |
referred_by_member_id | integer | null | Read-only. Member who invited this customer. |
consent_at | string (date-time) | null | Read-only. When marketing consent was given. |
last_activity_at | string (date-time) | null | Read-only. Last balance movement. |
last_visit_at | string (date-time) | null | Read-only. Last qualifying purchase or visit. |
wallet_serial | string | Read-only. Public identifier of the card used in card_url and the wallet pass links. |
google_object_id | string | null | Read-only. Google Wallet object of the card. |
google_object_synced_at | string (date-time) | null | Read-only. Last sync with Google Wallet. |
apple_pass_updated_at | string (date-time) | null | Read-only. Last update of the Apple Wallet pass. |
apple_pass_installed_at | string (date-time) | null | Read-only. When the card was added to Apple Wallet. |
google_pass_saved_at | string (date-time) | null | Read-only. When the card was saved to Google Wallet. |
created_by_user_id | integer | null | Read-only. User who enrolled the card (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 card is deleted. |
contact | object | null | Read-only, added to every response: id, first_name, last_name, email, phone, phone_country_code, avatar_url. |
tier | object | null | Read-only, added: id, name, color, earn_multiplier. |
program | object | null | Read-only, added: id, name, type, currency_code, stamps_required, status. |
card_url | string | null | Read-only, added. Private card page. Anyone with this link can see the card, so only share it with the card owner. |
The card's wallet authentication token is never returned.
Related
To register purchases, check-ins and gift card top-ups on a card, see Loyalty Actions. For the balance history, see Loyalty Transactions.
Report an issue with this documentation
Please log in to report issues with our documentation.