Docs › Orders

The order object & statuses

Fields, lifecycle and dispatchedTo values.

Responses from POST /v1/orders and GET /v1/orders/{externalId} return an order:

Field	Type	Description
`orderId`	string	Dragonfly's id for the order.
`externalId`	string	Your id: the one you sent.
`status`	enum	See the lifecycle below.
`dispatchedTo`	string or null	Create only. Where the order went; see below.
`dropoffs`	integer	Create only. Number of delivery stops.
`trackingUrl`	string or null	Live tracking page for the recipient, once available.
`promisedDeliveryAt`	timestamp or null	The delivery promise, when one is set.
`deliveredAt`	timestamp or null	When the delivery was completed.
`onTime`	boolean or null	Whether it was delivered inside its window.
`createdAt`	timestamp	When Dragonfly received the order.
`idempotentReplay`	boolean	Create only. `true` when this `externalId` already existed.

Status lifecycle

text

PENDING ──► ASSIGNED ──► PICKED_UP ──► DELIVERED
   │            │
   └────────────┴──► CANCELLED        (any) ──► FAILED

Status	Meaning
`PENDING`	Received. Waiting for a driver, or for Dragonfly to build routes.
`ASSIGNED`	A driver (or a route with a driver) has it.
`PICKED_UP`	The driver collected it and is delivering.
`DELIVERED`	Delivered, with proof of delivery captured.
`FAILED`	The delivery couldn't be completed (for example, a bad address or no access). Webhooks carry the reason.
`CANCELLED`	Cancelled before pickup.

Value	Meaning
`cartwheel`	Single drop, sent to a catering/on-demand driver network.
`onfleet`	Multi-stop route, dispatched as one route.
`internal`	Dispatched by Dragonfly's own dispatch board and driver app.
`dragonfly_routing`	Held for Dragonfly to build the day's routes. See routing modes.
`sandbox`	Sandbox key: simulated.
`null`	An idempotent replay (the order already existed), or an order recorded for dispatch later.

Something unclear or missing? Tell us.