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

MethodPathDescription
GET/loyalty-membersList or look up loyalty members
GET/loyalty-members/:idGet a loyalty member
POST/loyalty-membersEnroll a loyalty member
PATCH/loyalty-members/:idUpdate a loyalty member
DELETE/loyalty-members/:idDelete 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

FieldTypeDescription
idintegerRead-only. Unique ID.
organization_idintegerOrganization of the card. Required on enroll; cannot be changed.
program_idintegerLoyalty program of the card. Required on enroll; cannot be changed.
contact_idintegerContact who owns the card. A contact has one card per program. Cannot be changed.
statusstringOne of active, blocked. A blocked card cannot earn, redeem or check in.
marketing_consentbooleanThe customer accepts marketing messages.
expires_atstring (date-time) | nullCard expiry (memberships with membership_validity_days). null = no expiry.
metadataobject | nullExtra data stored on the card. metadata.birthday (MM-DD) is used for the program birthday_bonus.
member_codestringRead-only. Card code shown in the card QR. Use it with lookup or the scan action.
balancenumberRead-only. Current balance: points, stamps, money (cashback / gift card) or uses left (membership). Changed only through actions, redemptions and adjustments.
lifetime_earnednumberRead-only. Total earned since enrollment.
lifetime_redeemednumberRead-only. Total redeemed since enrollment.
lifetime_spendnumberRead-only. Total purchase amount registered on the card.
visits_countintegerRead-only. Qualifying purchases or visits.
rewards_unlocked_countintegerRead-only. Number of times the balance went up to (or past) the cost of an active reward.
tier_idinteger | nullRead-only. Current tier, when the program has tiers.
uses_remaininginteger | nullRead-only. Uses left on a membership.
enrolled_atstring (date-time)Read-only. Enrollment time.
enrollment_sourcestringHow 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_codestring | nullRead-only. The member's own code to invite friends (programs with referrals).
referred_by_member_idinteger | nullRead-only. Member who invited this customer.
consent_atstring (date-time) | nullRead-only. When marketing consent was given.
last_activity_atstring (date-time) | nullRead-only. Last balance movement.
last_visit_atstring (date-time) | nullRead-only. Last qualifying purchase or visit.
wallet_serialstringRead-only. Public identifier of the card used in card_url and the wallet pass links.
google_object_idstring | nullRead-only. Google Wallet object of the card.
google_object_synced_atstring (date-time) | nullRead-only. Last sync with Google Wallet.
apple_pass_updated_atstring (date-time) | nullRead-only. Last update of the Apple Wallet pass.
apple_pass_installed_atstring (date-time) | nullRead-only. When the card was added to Apple Wallet.
google_pass_saved_atstring (date-time) | nullRead-only. When the card was saved to Google Wallet.
created_by_user_idinteger | nullRead-only. User who enrolled the card (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 card is deleted.
contactobject | nullRead-only, added to every response: id, first_name, last_name, email, phone, phone_country_code, avatar_url.
tierobject | nullRead-only, added: id, name, color, earn_multiplier.
programobject | nullRead-only, added: id, name, type, currency_code, stamps_required, status.
card_urlstring | nullRead-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.