Record a purchase
Records a sale for a customer and applies your program’s earn logic — cashback on the amount, or stamps. On partial-mode cashback programs the same write can also redeem via applyCashbackCents. This is a money write: the Idempotency-Key header is REQUIRED — mint a fresh key per logical sale and reuse it only when retrying that same sale. Success returns the transaction id plus the post-write loyalty snapshot; domain rejections (e.g. redeeming more than the customer’s balance) return 422 with the reason.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
Perkss customer id (UUID) — the id returned by customer create/list.
Headers
Required. A unique key (e.g. a UUIDv4) identifying this write. Retrying with the same key and payload within 24h replays the stored response instead of re-executing; the same key with a different payload is rejected with 409 IDEMPOTENCY.PAYLOAD_MISMATCH.
Request
Sale amount in cents (e.g. 1000 = 10.00). 0 is allowed for a redemption-only purchase.
Cashback balance (in cents) to apply against this sale. 0 is treated as omitted (no cashback applied). Rejected with 422 when it exceeds the available balance.
Banked rewards to redeem within this sale. 0 is treated as omitted (no rewards redeemed). Rejected with 422 when it exceeds the available rewards.
Free-form note stored on the transaction.
Response
Post-write loyalty snapshot; null when the derived state is not yet readable.