Amazon
Amazon SP-API orders: what you get and what you do not
The Selling Partner API is well documented and still surprises people, because the shape of the data does not match the shape of the mental model. Sellers think in orders. SP-API thinks in orders, order items, buyer info and financial events, and those are four different calls returning four different things.
If you design around the orders endpoint alone, you will get a long way and then discover you cannot answer basic questions like what did this actually cost me.
What the orders call gives you
Order-level facts: the Amazon order id, purchase date, order status, the marketplace it came from, the fulfilment channel, and the shipping service level. This is enough to know that an order exists, when it arrived, and how urgently it needs to move.
It also gives you the latest ship date, which is the field that should drive your working day. Like TikTok, Amazon hands you an absolute deadline rather than making you derive it from a handling time. Sort by it and work down.
What it does not give you
It does not give you the items. That is a separate call per order, and it is the one that turns a cheap integration into an expensive one, because you are now making one call per order rather than one call per page of orders.
It does not give you the buyer address in full on every marketplace - address availability varies by region and by how long ago the order was placed, and personally identifiable information is restricted behind additional access.
And it does not give you money. Not real money. There is an order total, and the order total is not what you will be paid.
The per-order item call is the design decision
Because items require a call per order, your throughput is bounded by how many of those you can make. A naive integration fetches items for every order on every sweep, including orders that were delivered two months ago and have not changed since.
The fix is to fetch items once, store them, and never ask again. Order items do not change after dispatch. Treat them as immutable and the call count collapses to roughly one per new order, which is entirely manageable.
Money lives in financial events
The finances API is where fees, refunds, promotions and adjustments actually appear, and it does not line up neatly with orders. One order can generate several financial events across several days, and some events belong to no order at all.
This is the part sellers underestimate. Reconciling finances to orders is a real piece of work, and skipping it means your margin numbers are estimates dressed as facts.
- Order total is gross and provisional
- Referral fees appear as separate events
- FBA fees, if applicable, arrive separately again
- Refunds generate their own events, sometimes weeks later
- Reserves and adjustments may never map to a single order
Pull by update time, not by date range
The single most useful habit with SP-API is to query by last-updated rather than by purchase date, and to keep a marker of where you got to. Purchase-date queries re-fetch the same historical rows forever. Update-time queries return the handful of things that actually changed.
It also handles the case that catches everyone out: an order placed last week that was cancelled today. A purchase-date sweep of this week will never see it. An update-time sweep sees it immediately.
A design that holds up
- Sweep orders by last-updated, keeping a cursor
- For any order id you have not seen, fetch its items once and store them
- Never re-fetch items for an order in a terminal state
- Pull financial events on their own schedule and match on order id
- Treat anything you cannot match as a question to answer, not a rounding error
Build it that way and the integration stays cheap as volume grows. Build it around per-order polling and it gets more expensive every month you succeed.