Transactions

Record a purchase

View as Markdown
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

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

customerIdstringRequired

Perkss customer id (UUID) — the id returned by customer create/list.

Headers

Idempotency-KeystringRequired

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

This endpoint expects an object.
amountCentsdoubleRequired

Sale amount in cents (e.g. 1000 = 10.00). 0 is allowed for a redemption-only purchase.

applyCashbackCentsdoubleOptional

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.

redeemRewardCountdoubleOptional

Banked rewards to redeem within this sale. 0 is treated as omitted (no rewards redeemed). Rejected with 422 when it exceeds the available rewards.

reasonstringOptional

Free-form note stored on the transaction.

Response

The write was recorded.
transactionIdstring
Id of the transaction this write recorded.
loyaltyobject or null

Post-write loyalty snapshot; null when the derived state is not yet readable.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
503
Service Unavailable Error