Orbit supplies a current status for tours, shipments and orders. Statuses are updated in lockstep:
| Tour Status | Shipment Status | Order Status | Description |
|---|
| – | – | requested | Order is requested, no shipment and no tour created yet. |
| – | Unrouted | confirmed | Order is confirmed, shipment is created but not routed on a tour yet. |
| Unassigned | Routed | confirmed | Tour is created from shipment, not assigned to a carrier yet. |
| Assigned | Routed | confirmed | Tour is assigned to a carrier. |
| Running | EnroutePickup | confirmed | Tour is started. More detailed tour status can be obtained from "substatus" property. Shipment status is updated. |
| Running | EnrouteDropoff | confirmed | Shipment pickup stop is reached on tour, shipment status is updated. |
| WaitingForReview | WaitingForReview | WaitingForReview | Tour is finished and waiting for review. Shipment and Order status are updated to “WaitingForReview”. |
| Completed | Delivered | completed | Tour is reviewed. No effects on shipment and order status. |
| Running | Failed | unchanged | Delivery of the shipment failed (e.g. a stop could not be completed). The shipment is taken off the tour and can be re-planned on a new tour or closed after review. The order keeps its current status. |
A shipment whose transport is split into several legs (see GET /shipments/{shipmentId}/legs) derives its status from the whole leg set. Two additional statuses exist only for such shipments:
| Shipment Status | Order Status | Description |
|---|
| PartiallyRouted | confirmed | At least one leg is booked on a tour while at least one leg is still unrouted, and no cargo has been handed to a hub yet. Routing exists but is incomplete — read the shipment's legs (and unroutedLegCount) for per-leg placement. Never occurs for single-leg shipments. |
| AtHub | confirmed | The cargo is parked between legs: a leg that stops short of the shipment's final dropoff has completed, and the onward carriage has not started — whether the onward leg is booked or still unrouted (unroutedLegCount tells the two apart). Nothing is moving. Never occurs for single-leg shipments. |
While any leg is actively executing, the shipment reports the position of its least-advanced moving leg (EnroutePickup / EnrouteDropoff), exactly as in the table above; per-load progress is carried by each load's aggregateStatus and statusLog (each entry names both the tourId and the legId that recorded it).
Because status reports the least-advanced leg, a failure on a leg that is not the last one is not visible in status while a later leg is still on track — the shipment keeps reading Routed or PartiallyRouted. Read failedLegCount for that: any value above zero means at least one leg needs recovery (retry or return on the leg), whatever status says. It is the exception-side counterpart of unroutedLegCount, and like it, is present only on shipments that carry an explicit leg set.
A multi-leg shipment's status is not monotonic, because the journey genuinely repeats: a two-leg shipment runs Routed → EnroutePickup → EnrouteDropoff → AtHub → EnroutePickup → EnrouteDropoff → Delivered. AtHub marks each pause between legs, so a consumer polling status never sees the shipment fall back to a value it already left behind (before this status existed, the pause reported Routed — indistinguishable from "nothing has happened yet"). Cargo position always wins over booking state: cancelling or un-booking an onward leg while cargo waits at a hub keeps the shipment AtHub (with unroutedLegCount > 0), it never demotes it to PartiallyRouted. Note that a partial delivery on a parallel split reports Routed or PartiallyRouted, not AtHub: there the completed leg reached the final dropoff and no cargo is waiting anywhere.
For tours assigned to an integrated carrier (a carrier connected through an external transport API instead of Orbit's driver apps), the lifecycle above is driven by status events reported by the carrier — via webhook pushes or periodic polling — rather than by driver actions. The same statuses apply, with these characteristics:
- The tour advances forward only (
Assigned → Running → WaitingForReview) and never past WaitingForReview; reviewing/completing and cancelling remain operator actions.
- A tour may skip
Running and move directly to WaitingForReview when the carrier's delivery confirmation is the first event received. Consumers of tour webhooks should not rely on observing every intermediate status.
- The
carrierBooking block on tour reads carries the integration lifecycle: integrationStatus (booked, inTransit, exception, failed, cancelled) and statusLog (every carrier event, verbatim). A carrier-reported cancellation is surfaced as integrationStatus: "cancelled" only — the tour's own status is never changed automatically.
- Shipment statuses are updated in lockstep, as in the table above. Because integrated carriers do not report per-stop progress, shipments show
EnroutePickup while the tour is Running (no EnrouteDropoff step).
| Trigger | Tour Status | Shipment Status | Order Status | Description |
|---|
| Tour cancelled | Cancelled | Unrouted | confirmed | Tour is cancelled. Shipment is unrouted and can be re-planned on a new tour. Order remains confirmed. |
| Trigger | Tour Status | Shipment Status | Order Status | Description |
|---|
| Tour reset | Assigned | Routed | confirmed | Tour is reset to “Assigned” status. Shipment remains “Routed” on the tour. Logged times and substatus are cleared. |
| Trigger | Tour Status | Shipment Status | Order Status | Description |
|---|
| Tour deleted | (deleted) | Unrouted | confirmed | Tour is deleted. All shipments on the tour are unrouted and can be re-planned. Order remains confirmed. |
| Trigger | Shipment Status | Tour Status | Order Status | Description |
|---|
| Shipment cancelled | Cancelled | (unchanged) | confirmed | Shipment is cancelled. If shipment is on a tour, it is removed from the tour and the tour is rebuilt without it. Order remains confirmed. |
| Trigger | Order Status | Shipment Status | Tour Status | Description |
|---|
| Order cancelled | cancelled | Cancelled | (rebuilt or deleted) | Order is cancelled. All shipments are cancelled. Shipments are removed from their tours. Tours are rebuilt without cancelled shipments or deleted if no shipments remain. |
Scenario 1: Tour Cancellation
| Trigger | Tour Status | All Shipments Status | Order Status | Description |
|---|
| Tour cancelled | Cancelled | Unrouted | confirmed | All shipments on the tour are unrouted and can be re-planned. Orders remain confirmed. |
Scenario 2: One Shipment Cancelled
| Trigger | Tour Status | Cancelled Shipment | Other Shipments | Description |
|---|
| 1 Shipment cancelled | (rebuilt) | Cancelled (removed from tour) | Routed (remain on tour) | Tour is rebuilt without the cancelled shipment. Other shipments remain on the tour. |
Scenario: Order Cancellation
| Trigger | Order Status | All Shipments Status | Tours Status | Description |
|---|
| Order cancelled | cancelled | Cancelled (removed from tours) | (rebuilt or deleted) | All shipments are cancelled and removed from their tours. Tours are rebuilt or deleted. |
