List 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.
Authorizations
A secret API key. Publishable keys cannot reach this API. A key may carry an expiry, and an expired key is refused exactly like an unknown one, with a 401 that names no reason; check the key's expires_at in the dashboard rather than inferring it from a response. When a merchant rolls a key's secret they choose a grace window of up to 3 days, and for its duration BOTH the new secret and the one it replaced authenticate, so an integration moves over on its own deploy schedule instead of at the instant the button is pressed. Move before the window closes: after it, the old secret is refused. Nothing else about this contract moves with a roll. The key keeps its id and its scopes, so the only thing an integration updates is the credential itself.
Query Parameters
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.
actual, partial, backfilled, missing 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.
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.
1 <= x <= 100The 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.