Follow an Order Lifecycle

An order raises several events over its life. This page shows which ones, roughly when, and what each is worth doing something about. It assumes you already have a working receiver — if not, start with Handle an order placed event.

A normal order

orders.order.placed                the order is confirmed in our order system
orders.order.delivery.estimated    expected delivery dates are set
orders.order.delivery.created      a delivery is created for some or all lines
orders.order.delivery.picked       picking starts on that delivery in the warehouse
orders.order.delivery.sent         that delivery leaves the warehouse
orders.order.invoiced              an invoice is issued for what was sent
orders.order.completed             every line is now invoiced or cancelled

orders.order.delivery.estimated normally follows orders.order.placed within a minute. The rest are paced by the warehouse and by billing, so hours or days can pass between them.

An order that ships in parts repeats the middle four — one orders.order.delivery.created, one orders.order.delivery.picked, one orders.order.delivery.sent and one orders.order.invoiced per shipment — before a single orders.order.completed at the end.

Changes along the way

At any point before the order finishes, orders.order.lines.changed tells you that a line was added, removed, substituted, repriced, quantity-changed or cancelled. There is no separate event per kind of change: re-read orderLines[] and compare it against what you hold.

orders.order.delivery.estimated also arrives again whenever expected delivery dates are revised.

The two endings

An order finishes in one of two ways.

orders.order.completed — every line has been invoiced or cancelled. It arrives at most once, and normally alongside the final orders.order.invoiced.

orders.order.cancelled — the whole order was cancelled. It arrives at most once, and alongside an orders.order.lines.changed for the cancelled lines.

After either, one more event can still arrive. orders.order.credited is raised when a credit note is issued, and a return processed weeks later raises it against an order that completed long ago. Do not treat orders.order.completed or orders.order.cancelled as permission to stop listening.

One change, several events

Both endings above raise two events for one underlying change, and they arrive as separate deliveries with different eventIds. Deduplicating on eventId will not collapse them, and neither event is a duplicate of the other.

Their order is not fixed. A cancellation can deliver orders.order.cancelled before its orders.order.lines.changed or after it, sometimes within the same second. Never wait for one having seen the other, and never treat the second one as unexpected.

The reliable way to handle this is to let every event mean the same thing: re-fetch the order. The fetch returns current state, so it does not matter which event prompted it, how many arrived, or in what order.

Three things that surprise people

quantity.fulfilled moves on orders.order.invoiced, not on orders.order.delivery.sent. It is calculated from billings, not from shipments, so a line that has physically left the warehouse still reads fulfilled: 0 until the invoice is issued. Read deliveries[] if you need to know what has shipped. Credit notes are excluded from the calculation, so a return does not decrement it.

A cancellation request stops succeeding at the first orders.order.delivery.picked, not at orders.order.delivery.sent. Picking closes the request path for the whole order, not just for the lines in the delivery that started picking — lines waiting in a delivery that has not even been created yet are already past it too. This is about requests, not about the event itself: orders.order.cancelled can still be raised afterward for reasons other than a request you made.

There is no status field on an order. GET /orders/v1/{orderId} does not return one — only the list endpoints do. Read the events map for Placed, Completed and Cancelled, and orderLines[].quantity for how much has been fulfilled or cancelled. See Orders overview → the events map.