Enroll a loyalty member

Enroll a customer in a loyalty program and get their card. Use an existing contact (contact_id) or send the customer's details (contact) and AchieveApex finds the contact by email or phone, or creates it.

Endpoint

POST
/loyalty-members

Request

With customer details

With an existing contact

Response

json

The response is the Loyalty Member object plus already_enrolled. Send card_url to the customer (or use the send_card action) so they can open the card and add it to their wallet.

Body parameters

NameTypeRequiredDescription
organization_idNumberYesID of your organization
program_idNumberYesID of the loyalty program
contact_idNumberOne of contact_id / contactID of an existing contact of your organization
contactObjectOne of contact_id / contactCustomer details: first_name, last_name, email, phone, phone_country_code, phone_country_iso. An email or a phone is required.
marketing_consentBooleanNoThe customer accepted marketing messages (stores consent_at)
referral_codeStringNoReferral code of the member who invited this customer (programs with referrals)
initial_amountNumberNoGift cards: opening balance. Defaults to the program gift_card_default_amount
metadataObjectNoExtra data stored on the card
enrollment_sourceStringNoDefaults to api for API key requests

Behavior

  • Idempotent: a contact has one card per program. Enrolling the same contact again returns the existing card unchanged with already_enrolled: true, so it is safe to retry.
  • Contact matching: with contact, the contact is found by email first, then by phone (with or without the country code). Empty fields of an existing contact (name, email, phone) are filled with the values you send; existing values are never overwritten. If no contact matches, a new one is created.
  • Opening movements on a new card: the program welcome_bonus (points, stamps and cashback), the membership uses (membership_uses) or the gift card balance, and the referral bonus when a valid referral_code is sent.
  • Enrolling a new card fires the Member enrolled automation trigger.
  • Errors: "contact_id or contact is required", "Email or phone is required", "Invalid email", "This program is archived" (400) and "Loyalty program not found" (404).

Report an issue with this documentation

Please log in to report issues with our documentation.