POS transaction integration

For integrations that read what happens at the till (accounting exports, loyalty, analytics).

Reading sales

GET /api/v1/businesses/{id}/sales?from=…&to=…&status=COMPLETED&channel=POS (orders:read). Without reports:read a token sees only sales its own application created; with it, all sales.

Each sale has subtotal, discountTotal, taxTotal, total, amountPaid, refundedTotal, costTotal, lines[] (per-line netAmount, taxAmount, grossAmount, taxClass, taxRate) and payments[].

Statuses: OPEN (unpaid online order), PARKED, QUOTE, PARTIALLY_PAID (balance on a customer account), COMPLETED, VOIDED. A completed sale is immutable — the database refuses edits. Refunds are separate Refund records and payments with direction: "OUT".

Events

• sale.completed — a sale or paid order completed.
• refund.created — { id, number, saleId, total, reason, restock }.

Payments

Payment.status is PENDING, AUTHORISED, CAPTURED, FAILED or CANCELLED. Only CAPTURED counts as money received. Card payments today come from standalone terminals: the cashier confirms approval and may record the last four digits. POS never receives or stores card numbers, CVVs or PINs, and the API rejects a card summary containing more than four digits.

Receipts

GET …/sales/{id}/receipt returns a structured document (?format=text for 42-column plain text). Wording follows the VAT Act: a VAT-registered business issues a "Tax Invoice"; over R5,000 a full tax invoice needs the buyer's details (the document lists anything missing).

Ringing up sales through the API

POST …/sales is available to signed-in staff (the register uses it). Integrations submit orders instead.