Tour, Shipment & Order Status

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.
–	Failed	failed	Every shipment of the order has ended and a failed one has no cargo left to move, because its goods were written off (see perishedLoadCount). failed is its own terminal: the customer neither received the goods nor called the order off, which cancelled would mean. It is derived, so undoing a write-off returns the order to confirmed. Orbit's own apps label it "Undeliverable" (German: "Nicht zustellbar"); the API value stays failed.

Automatic Review

A tenant can enable review settings so that a tour reaching WaitingForReview is completed by the platform instead of waiting for an operator to open it. The tour is only completed when nothing about it needs a human, and the tenant chooses which findings count as an exception:

• Undelivered loads — any load reported NotLoaded or NotUnloaded, whatever the failure reason.
• Damaged loads — any load that failed with the LoadDamaged reason.
• Missing stop times — any stop without a logged arrival or departure time, which is how a tour closed by manual-complete reads.
• Missing proofs — a stop that requires a proof type no captured document covers.

Each exception can be turned off independently; every one that stays on keeps a tour with that finding parked exactly as before. When an exception applies, the tour simply stays in WaitingForReview and the review action remains an operator's to make.

For webhook consumers this means tour-waiting-for-review is normally followed by tour-completed within seconds, with a tour-action-created event for the review action in between. On a tenant with automatic review enabled, do not treat WaitingForReview as a state a tour will dwell in. When the missing-proofs exception is enabled, the platform waits for proof documents still being uploaded or rendered before it decides, so the completion can arrive as late as the tenant's configured proof wait (two hours unless the tenant changed it, at most six hours; a tenant can also choose not to wait at all). Proofs still pending or not renderable when the wait ends count as missing, and the tour stays in WaitingForReview for a human.

Multi-Leg Shipments

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 load can also end without arriving, in two ways that a consumer must not confuse. Returned means this shipment's obligation for the load moved to a return shipment: the goods are intact and travel on under that shipment, and this shipment un-fails, closing as Cancelled once every load has exited that way. Perished means the goods no longer exist as deliverable cargo, declared by an operator with a reason (Lost or Damaged); no shipment, stop or transport is created for it, the shipment closes as Failed, and the order closes as failed once its every shipment has ended. Damaged goods remain in the operator's location stock as dead stock until their disposal is recorded on the leg load (disposedAt); lost goods leave it immediately. perishedLoadCount counts the written-off loads and is the only field that still says so once the shipment has left every recovery list. Both values appear on a load's aggregateStatus; neither appears on the five-value per-tour load status, where a perished load keeps whatever it last reported.

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.

Integrated Carriers

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).

Cancellation & Deletion

Tour Cancellation

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.

Tour Reset

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.

Tour Manual Completion

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.

Tour Deletion

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.

Shipment Cancellation

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.

Order Cancellation

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.

Order Manual Completion (Shipment-less Orders)

Trigger	Order Status	Description
complete action on order (shipment-less only)	completed	Order is declared executed in one call. Only valid for an order created with no shipment request (box rental, box sale, recycling brokerage): an order with any shipment request keeps the fully-derived status the rest of this page describes.

This applies only to an order created with no shipment requests. Such an order has no shipment to derive a status from, so it is the one exception to "statuses are updated in lockstep" at the top of this page.

The action is POST /orders/{orderId}/actions with { "type": "complete" }. It moves the order from confirmed to completed and is refused with 409 from any other status, including requested, cancelled, or an order already completed.

uncomplete stays a no-op signal for every order regardless of shipment count, completion is final.

Multi-Entity Cases

Multiple Shipments on One Tour

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.

Multiple Shipments on One Order

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.