Create and execute a tour action. Supported types include the standard CreateTourActionRequest, rebuild operations ('rebuild-rearrange', 'rebuild-route-shipments', 'rebuild-unroute-shipments', 'rebuild-reorder-stops'), and 'optimize'. Rebuild actions accept 'fragmentGroups', route/unroute shipments atomically, update stop indices, and handle document link propagation/unpropagation for affected shipments on the tour. The 'rebuild-reorder-stops' action allows carriers to reorder incomplete stops within a tour by specifying a stop index and target position ('after-next' or 'end').

manual-complete

Declares a tour executed by a carrier that does not report through Orbit (no driver app, no carrier integration). Moves the tour from Assigned or Running straight to WaitingForReview in one call, marks every load without a failure verdict as Unloaded and delivers the tour's legs; shipments and the order follow to WaitingForReview. Stop arrival/departure times are not stamped, delivery proofs are not checked, and no stop-completed events are produced — only tour-waiting-for-review fires. Completed still requires the review action. Rejected with 400 from any other status. See the Tour, Shipment & Order Status page.

fail-shipment

The operator's verdict on one shipment carried by the tour, taken without waiting for a driver report. Records the given failureReason (and optional failureComment) on that shipment's loads as NotLoaded where the cargo was never picked up and NotUnloaded where it is already on board, fails the shipment's leg on this tour, leaves the shipment Failed, and removes it from the tour; a tour left without shipments is deleted. The tour's own status is untouched. Its substatus — the driver's arrived/departed progress marker — can be recomputed against the rebuilt stop list when removing the shipment changes the stop the driver is at or has just left; the remaining shipments keep their stops. Allowed while the tour is Unassigned, Assigned or Running. Rejected with 400 once the tour is WaitingForReview, Completed or Cancelled, when the named shipment is not on the tour, or when one of its loads was already unloaded here. Re-sending the same fail-shipment while the shipment is still on the tour is safe: the recorded verdict is left untouched and only the removal runs again; once the shipment has left the tour the request is rejected with 400.

optimize

Recomputes the tour's visiting order. Optimizing never adds or removes shipments — only the stop order changes. Options: ignoreTimeWindows (default false: windows are respected wherever possible; when they are jointly impossible, the fewest possible shipments are scheduled outside their windows), preventShipmentCombination (default false: true forces strictly one shipment at a time), and dryRun (default false: true returns the proposed tour without persisting anything). The 200 response is the tour, plus two additive fields when applicable: windowViolations (an array of {shipmentId, stopType, lateBySeconds} naming every stop scheduled outside its time window — lateness is reported, never silent) and dryRun: true on previews.

Idempotency

Send a clientActionId beside the action (a UUID works well) to make a retry safe: an id already applied in this tenant is not applied again, and the response carries clientAction.status: "duplicate" with the original action's deviceTime and receivedAt, next to the tour as it is now. Without an id every request is applied. rebuild-* and optimize requests ignore the id.

Event time

An advance or reverse may carry timestamp (epoch seconds) for when the step happened; stop times, startedAt and finishedAt then use it. A timestamp in the future is capped at the time the request arrives.