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
Request
Response
json
| Field | Description |
|---|---|
member | The card after the purchase (full Loyalty Member object, shortened above) |
transaction | The earn movement written to the ledger |
earned | Points, stamps or cashback earned by this purchase |
duplicate | true when the reference was already registered (see below) |
Body parameters
| Name | Type | Required | Description |
|---|---|---|---|
organization_id | Number | Yes | ID of your organization |
action | String | Yes | register_purchase |
member_id | Number | Yes | ID of the card |
amount | Number | No | Purchase amount in the program currency. 0 or empty registers a visit without amount. Cannot be negative. |
note | String | No | Description of the movement (defaults to In-store purchase or In-store visit) |
reference | String | No | Your 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 type | Earned |
|---|---|
stamps | earn_rules.stamps_per_visit per purchase |
points | floor(amount / amount_step) * points_per_step + points_per_visit, times the tier earn_multiplier |
cashback | amount * 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
| Message | Cause |
|---|---|
This card is blocked | The card status is blocked |
This program does not earn from purchases | Membership and gift card programs do not earn (use use_membership or load_balance) |
This program is not active | The program is draft, paused or archived |
Amount cannot be negative | amount is below zero |
Report an issue with this documentation
Please log in to report issues with our documentation.