/tours/{tourId}/actions

post

https://api.dev.orbit.do/v5/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.

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.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

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

Path Params

tourId

string

required

Body Params

request to create tour action

type

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*

vehicleClassId

string

required

Internal VehicleClass id (UUID) for the tour.

region

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

displayName

string

comment

string

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

internalComment

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.

stopRetentionStrategy

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:

Responses

400

action rejected for the tour's current status — e.g. manual-complete outside Assigned/Running, review outside WaitingForReview. Nothing was changed.

401

unauthorized

403

the stopRetentionStrategy override was sent by a carrier actor; only operator users and API keys may send it

Language

Credentials

Header

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200updated tour