/shipments/{shipmentId}/legs

put

https://api.dev.orbit.do/v5/shipments/{shipmentId}/legs

Replace a shipment's leg plan. A declarative, idempotent full-replace of the complete set of legs the shipment should have. Send the entire desired plan; the server reconciles it against the current legs, preserving execution facts (statuses, logged times) that a plan cannot express. Optimistic concurrency is enforced via expectedShipmentUpdatedAtMs (the shipment's millisecond-resolution updatedAtMilliseconds): if the shipment changed since you read it, the request is rejected with 409.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

shipmentId

string

required

The ID of the shipment whose leg plan to replace.

Body Params

The complete desired leg plan plus the optimistic-lock token.

expectedShipmentUpdatedAtMs

number

required

The shipment's last-known updatedAtMilliseconds timestamp, used for optimistic concurrency. Millisecond resolution is required: the leg-plan write is version-locked at the millisecond, so the seconds-only updatedAt cannot distinguish two writes landing in the same second. A mismatch means the shipment changed since you read it and the request is rejected with 409. A positive value below 10^12 is rejected with 400 as a probable epoch-seconds value.

plan

array of objects

required

length ≤ 10

The complete desired set of legs for the shipment (full replace). Each entry declares one leg's structure: its stops, the loads it carries, and the tour it is routed on. Capped at 10 legs; a stop address may omit its coordinate pair, and on a NEW leg (an entry without id) a stop carrying a shipperAddressId or globalAddressId may omit the address entirely.

plan*

acceptCapacityWarnings

boolean

Accept capacity warnings (a tour would be overloaded). Default false: a plan carrying a capacity warning is rejected with 422 unless this is true. Preflight the plan via POST /shipments/:id/legs/preflight to see the warnings first.

acceptTimeWindowWarnings

boolean

Accept time-window warnings (a leg's window does not overlap its tour). Default false: a plan carrying a time-window warning is rejected with 422 unless this is true.

acceptDownstreamTimeWindowWarnings

boolean

Accept downstream-time-window warnings (the simulated post-change schedule of an affected tour arrives at a stop after its requested window closes). Default false: a plan carrying one is rejected with 422 unless this is true.

acceptChainDeadlineWarnings

boolean

Accept chain-deadline warnings (a leg's projected dropoff leaves the shipment's remaining legs no chance to make the final delivery). Default false: a plan carrying one is rejected with 422 unless this is true.

Responses

400

Bad request - the plan violates a structural integrity rule (e.g. broken adjacency, an uncovered load, or an unknown shipment load reference).

401

Unauthorized - invalid or missing API key.

403

Forbidden - the API key may not modify this shipment's legs.

404

Shipment not found.

409

Conflict - the shipment changed since it was read (optimistic-lock mismatch on expectedShipmentUpdatedAtMs).

503

Service unavailable - applying the plan required re-routing a tour and the routing engine was momentarily unavailable. The request was not applied; retry.

Language

Credentials

Header

URL

Loading…

Response

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

application/json

200The full current set of legs for the shipment after the plan was applied — same envelope AND same shape as GET /shipments/{shipmentId}/legs: transport-path order with each reachable leg's derived position (omitted for a leg the path cannot reach, e.g. a plan still being assembled).