/tours/{tourId}/actions

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.

select-purchasing-product

Selects a purchasing product for this tour. The tour must have an assigned carrier; the product must be among the transport shape's purchasing products (or the current product when the tour has no shape reference), and its price is calculated with that carrier. This action is operator-only.

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.

detach-carrier-price

Ends the price takeover for one tour whose price comes from its integrated carrier (priceSource: "integrated"). The tour's priceSource becomes manual and its line items stay as they are; they can be edited again afterwards, and later price changes the carrier makes to its order are no longer taken over for this tour. The carrier is not told about edits made afterwards, so settle the price with the carrier directly. The action carries no fields besides type. Rejected with 400 when the tour's price source is not integrated, which is also the answer to a second request that arrives after the price was already detached; two concurrent requests detach the tour once, and the other one is answered with 400 or 409.

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.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

More details for the "review" action can be found in our documentation

Path Params
string
required
Body Params

request to create tour action

string
enum
required
Allowed:
stops
array of objects
required
length ≥ 2

The tour's stops in execution order; at least two are required (a pickup and a dropoff).

stops*
string
required

Internal VehicleClass id (UUID) for the tour.

string
required
length ≥ 1

The operational region, given as the region's identifier (a slug such as "berlin"), not its UUID id.

extras
array
extras
string
string

Public comment on the tour (visible to the carrier).

string

Internal comment on the tour (operator-only).

carrierInfo
object

Optional carrier assignment at creation; providing a carrierId makes the tour start Assigned rather than Unassigned.

string
enum

When set to preserve, rebuilds keep the created stops even when they carry no freight, until a rebuild with the purge override sweeps them or a rearrange omits them. When omitted or purge, rebuilds derive stops from freight alone (the default behavior).

Allowed:
properties
object

Custom property values for the new tour, keyed by the id of a property definition defined for tours; each value is validated against its definition. An unknown property id or a value of the wrong type is rejected with a 400 error and no tour is created. When omitted, or when every value is null, the tour has no properties. The value of a document-type property is the id of an uploaded document: the tour is created with a link from that document to the new tour, and the property stores the id of that link. A request that creates no tour creates no link.

string
length between 1 and 128

Idempotency id of this action, unique per tenant (a UUID is a good choice). Sending the same id again returns the original result with status duplicate instead of applying the action twice. Generated by the platform when omitted.

Responses

400

action rejected for the tour's current status — e.g. manual-complete outside Assigned/Running, review outside WaitingForReview. Nothing was changed. A rebuild-rearrange with persistStopRetentionStrategy but no stopRetentionStrategy is rejected with 400. A rebuild whose productAlignment recalculate is infeasible with onInfeasible fail, combines tour recalculate with explicit lineItems, or recalculates the order of a tour whose shipments span several orders, include a shipment without an order, or belong to no order, is rejected with 400. recalculate-price on a tour carrying shipments of several orders answers 400 with the violation code tour-shared.

401

unauthorized

Language
Credentials
Header
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json