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”. Also reached directly from Assigned/Running by the manual-complete action (see "Tour Manual Completion"). |
| 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 |
|---|
manual-complete action on tour | WaitingForReview | WaitingForReview | WaitingForReview | Tour is declared executed in one call, from Assigned or Running. Loads without a failure verdict are marked Unloaded and their legs Delivered; Shipment and Order status follow to “WaitingForReview”. A shipment whose loads all carry failure verdicts reads Failed instead. |
The manual-complete action (POST /tours/{tourId}/actions with { "type": "manual-complete" }) is meant for tours driven by a carrier that neither uses Orbit's driver apps nor is connected as an integrated carrier, so no stop-by-stop report will ever arrive. It replaces walking the tour through every stop with advance:
- The tour moves from
Assigned or Running straight to WaitingForReview; startedAt (if not already set) and finishedAt are stamped with the time of the call. From any other status the action is rejected with 400.
- Every load that carries no failure verdict becomes
Unloaded. A NotLoaded / NotUnloaded verdict recorded by an earlier advance is kept, so a shipment whose loads all failed reads Failed, exactly as after a driven tour.
- Stop
loggedArrivalTime / loggedDepartureTime are not stamped — nobody observed the stops. They stay empty unless the reviewer asserts timings through the review action.
- Delivery proofs are not checked, even for stops that would otherwise require one. Proofs can still be attached afterwards via
add-proof.
- Legs with at least one load that carries no failure verdict become
Delivered; their shipments and the order follow to WaitingForReview in the same transaction (a leg whose loads all carry a verdict becomes Failed and its shipment reads Failed, as stated above). For a multi-leg shipment, complete the tours of the earlier legs first — the action does not check leg order, and the shipment would already read WaitingForReview while an earlier leg is still Routed.
- Webhooks: only
tour-waiting-for-review (and tour-action-created) fire; there is no preceding tour-started, tour-arrived-at-stop or tour-departed-from-stop. Automations and task templates listening on tour-action-created run as for any action; stop-based triggers (stop arrived / stop completed) do not.
Completed still requires the review action; the Hub already shows an order in WaitingForReview as completed.- The action is not gated on a carrier integration: on a tour booked with an integrated carrier it pre-empts the carrier's own delivery report. Later carrier events still land as facts (
carrierBooking.statusLog, stop times) but never move the tour backwards.
- A mistaken call is undone with
reset: the tour returns to Assigned, loads to Routed, and legs, shipments and the order follow.
| 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. |
