Status Reference¶

Last updated October 20, 2026

Two vocabularies, never mixed within a single field. Orders and shipments speak the Omnishelf vocabulary. Parcels speak the carrier vocabulary. Both are lowercase snake_case strings.

Order and shipment status¶

Value	Meaning	What causes it
`awaiting_shipment`	The order exists but no label has been produced yet. Still yours to prepare.	The starting state for retailers whose labels are bought on their own carrier account. Included in the default `status` filter. An order waiting for a label Omnishelf has to upload by hand is not shown on the API at all until the label arrives.
`processing`	Actionable. Omnishelf is generating the label, a label exists, or tracking has been submitted, but no carrier scan has arrived.	The starting state for every order whose label Omnishelf generates, and the state after you submit tracking. Also covers an order marked shipped upstream without tracking. No event is emitted for this transition.
`shipped`	At least one parcel has a genuine carrier scan and the order is in the carrier network, or part of it is delivered.	A carrier scan other than `pending` or `info_received` lands on a parcel.
`exception`	A parcel has a delivery problem that needs attention.	Any parcel reports `failed_attempt` or `exception`. Takes precedence over every other rollup.
`delivered`	Complete. Every parcel has been delivered.	All parcels report `delivered`.
`on_hold`	Paused. Do not ship.	Held in the fulfilment system. Lifts, and the order returns to its rollup, as soon as that hold is released. Fires `fulfilment_order.on_hold`.
`cancelled`	Terminated. Do not ship, and destroy or return any label already printed.	Cancelled by Omnishelf or upstream. Final. Fires `fulfilment_order.cancelled`.

Shipment status uses the same vocabulary but is scoped to one shipment's parcels, and is computed at read time rather than stored. Only awaiting_shipment, processing, on_hold, and cancelled are accepted by the status filter on the list endpoint.

on_hold and cancelled are set on the order and override its rollup. A cancelled order reports every one of its shipments as cancelled too. An on-hold order doesn't: its shipments keep the status their parcels roll up to, so a shipment can read shipped or delivered while the order is on_hold.

Parcel tracking status¶

Carrier vocabulary, normalised to the values in the table below. Casing and separators are normalised (In Transit and in-transit both become in_transit), and provider-specific values are mapped to the documented value closest in meaning. For example, pre_transit is returned as pending. A parcel with no tracking data yet has tracking_status: null.

Value	Meaning	Counts as a scan?
`pending`	Tracking number issued; the carrier has no data for it yet.	No
`info_received`	The carrier has label data on file but has not physically taken the parcel.	No
`in_transit`	Moving through the carrier network.	Yes
`out_for_delivery`	On a vehicle for delivery today.	Yes
`failed_attempt`	Delivery was attempted and failed. Rolls the whole order up to `exception`.	Yes — problem state
`to_pick_up`	Awaiting collection at a carrier access point or locker.	Yes
`delivered`	Delivered. Terminal state.	Yes
`exception`	Damage, loss, customs hold or another carrier-reported problem. Rolls the whole order up to `exception`.	Yes — problem state
`return_to_sender`	The carrier is returning the parcel to the sender.	No
`cancelled`	The label or tracking was cancelled; the parcel is not moving.	No

tracking_status only returns values from this table. Still, treat an unrecognised value as "in transit, unknown detail" rather than failing, because new values may be added within v1.

How statuses roll up¶

Parcels roll up into a shipment status, and shipments into an order status. Both are evaluated top to bottom and the first rule that matches wins. A shipment's status:

#	Condition	Result
1	Any parcel is `failed_attempt` or `exception`	`exception`
2	Every parcel that has a status is `delivered`	`delivered`
3	Any parcel is `in_transit`, `out_for_delivery` or `to_pick_up`	`shipped`
4	Any parcel is `pending` or `info_received`, the shipment has a tracking number but no status yet, or a parcel has a label	`processing`
5	Otherwise	`awaiting_shipment`

A shipment of a cancelled order reads cancelled. The order's own status starts from its shipments:

#	Condition	Order status
1	The order is cancelled	`cancelled`
2	The order is held in the fulfilment system	`on_hold`
3	Any shipment is `exception`	`exception`
4	Every shipment is `delivered`	`delivered`
5	Any shipment is `shipped` or `delivered`	`shipped`
6	Any shipment is `processing`	`processing`
7	The order is marked shipped upstream but has no tracking yet	`processing`
8	The retailer buys its labels on its own carrier account	`awaiting_shipment`
9	Otherwise — Omnishelf generates the label	`processing`

Every order has at least one parcel¶

Omnishelf creates a shipment with a single placeholder parcel the moment an order is created, so shipments and parcels are never empty arrays. The placeholder is promoted in place — same parcel_id — as soon as a real label or tracking number arrives, so it is safe to key your own records off it.

`pending` and `info_received` are not carrier scans¶

A shipment whose parcels are all pending is processing, not shipped — the label exists but the carrier has not taken the box. The same applies to info_received. If you treat "has a tracking number" as "shipped", your status will diverge from Omnishelf's on every order that has a label printed but not yet collected.

Shipment rule 1 also means one exceptional parcel makes the whole order exception, even if every other parcel is already delivered. A partly delivered order, by contrast, reads shipped until every shipment is delivered.