# 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`](/api/orders-list), [`order.paid`](/events/order-paid), [`order.refunded`](/events/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`](/api/store-get) |
| Read sales figures for a period | `analytics:read` | [`GET /analytics/overview`](/api/analytics-overview) |

## Book a sale

Book an order when [`order.paid`](/events/order-paid) arrives, and reverse it when [`order.refunded`](/events/order-refunded) arrives. Once an hour, catch anything you missed:

```bash
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 `number` is not one.
- **No payment details.** [`GET /payments`](/api/payments-list) gives 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: returned` and [`order.refunded`](/events/order-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.
- `status` can change after a sale without any money moving, so book on `payment_status`, not on `status`.
- Your app cannot refund, and it cannot mark an order as paid.
- [`GET /analytics/overview`](/api/analytics-overview) returns the same figures the merchant sees in their dashboard. Use it to check your totals for a period.