Purchase and receipt data integration

The most central data in ReceiptRoller is the receipt. One payment corresponds to one receipt, which holds multiple line items (item). Receipts are issued from a POS or your own payment system, and can be accessed with both store-scope and User-scope.

Main fields

Related scopes

• receipt.read — read a store's receipts
• receipt.write — newly issue / void a receipt
• user.receipts.read — a general consumer's own receipts (review required)
• user.receipts.write — add memos/tags to one's own receipts (review required)

Retrieval patterns

Retrieve as a store owner

GET /v1/receipts?store_id=str_abc123&issued_after=2026-04-01
Authorization: Bearer {store token}

Retrieve as the consumer themselves

GET /v1/me/receipts?limit=20
Authorization: Bearer {user token}

Issuing a receipt QR (claim-token)

Hand over a just-received receipt on the spot as a QR code. After displaying the receipt in a native app (Android / iOS), issue a claim-token (a one-time claim token) from the target transaction's id, encode the returned URL into a QR, and display it on screen. When the customer scans it, they can claim that single receipt (it is the same mechanism as the QR shown by the web POS screen).

1. Issue a claim-token

POST /api/v1/transactions/{id}/claim-token?organizationId={organizationId}
Authorization: Bearer {access_token}
Content-Type: application/json

{ "ttlMinutes": 1440 }

{id} is the composite ID returned by the transaction list / detail (pos:{terminalId}:{transactionId}). Only POS transactions are supported (an OMS order returns 400). The scope is store.orders.read or sales.read. ttlMinutes is optional (default 1440 = 24 hours).

Response

{
  "id": "pos:9edfb4b8-...:6a8c44a6-...",
  "claimToken": "a7K3xQ9mZp2v",
  "claimUrl": "https://receiptroller.io/rx/a7K3xQ9mZp2v",
  "expiresAt": "2026-06-22T06:40:00Z"
}

2. Generate the QR — encode claimUrl as-is with a QR library (ZXing on Android, etc.) and display it. The QR contains no receipt data itself, only the URL. Because the image is generated on the app side, no image request to the server is needed.

• The token is single-use and expires in 24 hours by default (changeable with ttlMinutes). If it is not scanned, issue it again.
• When the customer scans it, they land on https://receiptroller.io/rx/{claimToken}, and the native app (universal link / app link) or the web preview displays that transaction's receipt.
• If you need a fixed QR posted at the store terminal (showing the latest transaction per register), encode https://receiptroller.io/r/{publicTerminalId} from the terminal's publicTerminalId.

Webhook events

• receipt.issued — issued
• receipt.voided — voided
• receipt.refunded — refunded
• receipt.updated — content updated (e.g. added supplementary info)

Common use cases

• Accounting integration: retrieve receipts daily and register them in accounting software
• Consumer receipt management app: sync one's own receipts to a household-budget app
• Receipt QR handover: display a QR in the app after checkout so the customer receives a digital receipt
• BI aggregation: sales analysis by time of day and by product (also leveraging per-line tax and discounts)
• Fraud detection: detect anomalies in the refund rate

Notes

• Receipts with line items have a large payload, so list retrieval does not include line items (include them only when explicitly requested with ?expand=items)
• When voided or refunded, the original receipt remains and its status changes. Always reference status when aggregating
• Amounts are provided both tax-inclusive and tax-exclusive, as total_amount / subtotal
• Per-line tax and discount amounts, the tender breakdown (split payment), the refund breakdown, and card brand / last 4 digits are retained when the source POS sends them (raw payloads are also kept on the server to prevent data loss)
• The payload of a receipt QR (claim-token) is a URL only. Because receipt data is fetched after landing on /rx/{token}, the QR itself contains no personal information

Related guides

• PosTransactionDto reference — the internal model spec of transactions imported from a POS
• Guide for wallet apps: retrieving receipts via OAuth
• Guide for stores: issuing receipts and Webhook notifications
• OAuth scopes reference
• Back to the developer help index