# List order margins

`GET /api/v1/order-margins`

What each order actually MADE, newest first: revenue, the real cost of the goods, the modeled processor fee, the modeled carrier cost, the tax, and anything refunded since. THESE FIGURES ARE FROZEN AT PLACEMENT and never recomputed. The cost of goods is each line's variant cost price AT THE INSTANT THE ORDER WAS PLACED, so editing a cost price today does not restate last month. That is the whole design, and it is why this family has no write half: nothing may rewrite a frozen row, including you. EVERY ROW CARRIES ITS OWN currency_code AND YOU MUST GROUP BY IT. Amounts are minor units of the currency the shopper paid in, so a store selling into several regions returns several currencies in one page and adding them produces a number that is wrong with nothing reporting it. READ cogs_source BEFORE YOU READ cogs. actual means every line had a cost price. partial means some did, so cogs is a FLOOR and net_profit a CEILING, and missing_cost_variants says how many products are unpriced. backfilled means the figures were written after the fact by a backfill rather than at placement. missing means none of the lines had a cost, and cogs, net_profit and margin_bps are then NULL rather than zero, because a zero cost would make an unpriced catalogue read as a perfect margin. Use ?cogs_source=missing to get exactly the orders you still need to price. payment_fee AND shipping_cost ARE MODELED, not invoiced. They are computed from the merchant's cost model at placement, which is what fee_source and shipping_source say on every row, and they are not the fee a processor later settled or the amount a carrier later billed. refunded IS THE ONE FIGURE THAT MOVES. It sums SUCCEEDED refunds at read time, so it can grow on a row you already hold and net_profit falls with it. Refunds still pending are not counted, because one that later fails must not lower a profit you already reported. ORDERS PLACED BEFORE MARGIN TRACKING BEGAN ARE ABSENT, with no placeholder row. The cost prices in force at that instant are gone, so there is nothing honest to synthesise, and you will find fewer margins than orders. That gap is the coverage window rather than an error. PAGED BY computed_at, which the freeze never rewrites, so "everything since my last sync" is a walk that stops when it crosses your watermark. A refund on an old order does not move computed_at, so such a walk finds new orders rather than new refunds. THERE IS NO PERIOD REPORT ON THIS API and there will not be one. A total over a window is not a resource: its shape would be a chart's shape, and the merchant-facing one covers a single currency and silently omits every order in every other. Total these rows yourself and you get complete data you can group correctly, plus a per-order flag telling you which numbers not to trust.

## Query parameters

- `cogs_source` (actual | partial | backfilled | missing) — Narrow the page by how trustworthy the cost figure is. ?cogs_source=missing is the one to integrate against: those are exactly the orders whose products had no cost price at placement, so their cogs, net_profit and margin_bps are null and their profit is unknowable until you price the catalogue. partial means the cost understates and missing_cost_variants says by how many products. A value outside the enum is a 400 rather than an unfiltered page, because a silently ignored filter would hand you every order you have ever taken when you asked which ones are still unpriced, and you would read your whole catalogue as unpriced.
- `currency_code` (string) — Narrow the page to one currency, which is what totalling these rows requires: every amount is minor units of the order's OWN currency, so a multi-region store returns several currencies in one page. CASE IS FOLDED on both sides, so "USD" and "usd" match the same rows. A currency the store has never sold in is an empty page rather than a 404, which is what stops this being a probe for which markets a merchant trades in.
- `limit` (integer) — Rows per page. Out of range is a 400 rather than a silent clamp, so a client asking for more than 100 learns it did not get it.
- `after` (string) — The next_cursor from the previous page. Opaque: decode nothing from it and construct nothing by hand, since its encoding is not part of this contract. Omit it to read the first page.

## Responses

- `200` — Success
- `400` — The request was refused before any state changed. `code` is one of:

`invalid_body`, a write body this route will not take. `reason` partitions it
and `field` names the key when one key is at fault.
`invalid_query`, a query parameter, including limit and after.
`invalid_text`, a NUL byte or bytes that are not valid UTF-8 anywhere in the
path, the query or the body. Strip control characters before sending.
`idempotency_key_required`, a write sent without the Idempotency-Key header.
`invalid_request`, an Idempotency-Key longer than 255 bytes.

Routes add their own codes for rules only they know. Switch with a default arm.
- `401` — No credential, or one this API does not accept. `code` is always
`unauthorized`.

THE BODY IS DELIBERATELY UNINFORMATIVE. An expired key, a revoked key, a
publishable key, a key belonging to another merchant and a key that never
existed are all refused with the same bytes, so this response cannot be used to
probe which keys exist. Check the key's state in the dashboard rather than
inferring it here.

Send the key as `Authorization: Bearer <key>` or as `X-API-Key: <key>`. It is
never accepted in a query string.
- `403` — The key lacks the read_margin scope. `code` is `insufficient_scope` and the message names the scope to ask the merchant for.
- `429` — Too many requests. `code` is `rate_limited`.

Two limits apply independently: one on the credential and the route family,
one on the client address. The headers describe whichever has less left, so
honouring Retry-After always clears the window that bound.
- `default` — Any status this operation does not list, in the same envelope.

A 5xx means the request may or may not have applied. Retry it with the SAME
Idempotency-Key: that is the only way to find out without risking a duplicate,
and it is what the key is for.

A few 4xx conditions arrive here rather than as a listed status because they
depend on the merchant's plan or on a module being wired: 402 when a quota or a
plan limit is reached, and 503 when a capability the route needs is not
configured on this deployment. Both carry a `code` naming which.

## Example

```bash
curl --request GET \
  --url 'https://api.mercemur.com/api/v1/order-margins' \
  --header 'Authorization: Bearer <token>'
```