Guides
Accounting and invoices
Read paid and refunded orders and the store's tax details, and know exactly what an order does not hold.
What your app needs
| You want to | Scope | Where |
|---|---|---|
| Read orders, items, totals and payment status | orders:read | GET /orders, order.paid, order.refunded |
| Put the customer's name, phone and address on a document | customers:read | Inside the order |
| Read the store's legal name, VAT number and address | store:read | GET /store |
| Read sales figures for a period | analytics:read | GET /analytics/overview |
Book a sale
Book an order when order.paid arrives, and reverse it when order.refunded arrives. Once an hour, catch anything you missed:
curl "https://larm.sa/stores/$STORE_ID/v1/orders?updated_after=2026-11-01T00:00:00Z&payment_status=paid&limit=100" \
-H "Authorization: Bearer $ACCESS_TOKEN"| Field | Use it for |
|---|---|
number | The order number the merchant and the customer see |
totals.subtotal | The items before discount and shipping |
totals.discount | The discount, and coupon_code for its coupon |
totals.shipping | The delivery charge |
totals.total | What the customer paid |
items | Each item with its quantity, unit_price, total and sku |
paid_at refunded_at | The dates to book on, in UTC |
Amounts are strings with two decimals. Add them as decimals, never as floating point numbers.
What an order does not hold
- No VAT line. An order does not record the VAT on it or say whether its prices include VAT. Agree with the merchant how to work out tax, using their settings and their
vat_number. - No invoice number. Larm does not number orders as tax invoices. If your app issues invoices, your app gives them their numbers and keeps them. The order
numberis not one. - No payment details.
GET /paymentsgives the outcome only: succeeded or failed. There is no amount, method, fee or card. - No settlement data. What the merchant receives from Larm, and when, is not available through the API.
Keep the books right
- A refund arrives as
payment_status: refunded,status: returnedandorder.refunded. Any refund marks the whole order as refunded, and there is no refund amount field. If you need the amount of a partial refund, ask the merchant. statuscan change after a sale without any money moving, so book onpayment_status, not onstatus.- Your app cannot refund, and it cannot mark an order as paid.
GET /analytics/overviewreturns the same figures the merchant sees in their dashboard. Use it to check your totals for a period.