Register a purchase

Register an in-store purchase or visit on a card. The program's earning rules decide what the customer earns: points, stamps or cashback, including the tier multiplier.

Endpoint

POST
/loyalty-actions with "action": "register_purchase"

Request

Response

json
FieldDescription
memberThe card after the purchase (full Loyalty Member object, shortened above)
transactionThe earn movement written to the ledger
earnedPoints, stamps or cashback earned by this purchase
duplicatetrue when the reference was already registered (see below)

Body parameters

NameTypeRequiredDescription
organization_idNumberYesID of your organization
actionStringYesregister_purchase
member_idNumberYesID of the card
amountNumberNoPurchase amount in the program currency. 0 or empty registers a visit without amount. Cannot be negative.
noteStringNoDescription of the movement (defaults to In-store purchase or In-store visit)
referenceStringNoYour ticket, receipt or order number (up to 60 characters). Makes the request idempotent.

Idempotency

Send your own ticket or receipt number in reference. A purchase is registered once per program and reference: if you send the same reference again (for example after a timeout), nothing is added and the response returns the original transaction with duplicate: true. Without reference, every request registers a new purchase.

How much is earned

Program typeEarned
stampsearn_rules.stamps_per_visit per purchase
pointsfloor(amount / amount_step) * points_per_step + points_per_visit, times the tier earn_multiplier
cashbackamount * cashback_percent / 100, times the tier earn_multiplier

Nothing is earned when the purchase is below earn_rules.min_amount. Points and stamps balances are whole numbers (rounded down); cashback keeps two decimals. transaction.amount is the value actually credited. When tiers are enabled and a multiplier applies, transaction.metadata.tier_multiplier shows it.

Every registered purchase counts as a visit (visits_count) and adds amount to lifetime_spend. If the customer was referred, their first purchase also pays the referrer bonus.

Errors

MessageCause
This card is blockedThe card status is blocked
This program does not earn from purchasesMembership and gift card programs do not earn (use use_membership or load_balance)
This program is not activeThe program is draft, paused or archived
Amount cannot be negativeamount is below zero

Report an issue with this documentation

Please log in to report issues with our documentation.