API Reference
Log In
API Reference

/shipments-planner-jobs/recalculate

post
https://api.dev.orbit.do/v5/shipments-planner-jobs/recalculate

Synchronously re-optimize the changed tours of an existing planner solution and return the updated solution. Unlike registering a job, this call does not create tours and does not need polling.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
shipmentIds
array of strings
required
length ≥ 1

Internal Shipment ids (6-character uppercase codes) to plan. Must cover every shipment carried by the start solution's changed tours; omitting one is rejected. Supplied ids that do not exist or reference shipments outside a routable status (Unrouted or Failed) are silently dropped from the optimization rather than rejected.

shipmentIds*
vehicles
array
required
length ≥ 1

Vehicles available for the recalculation. Must include the vehicles the start-solution tours reference by vehicleId.

vehicles*
string
required

Internal Vehicle id (auto-generated UUID), opaque — humans identify a vehicle by its numberPlate, not by this id.

string
required

Internal id of the tenant that owns this vehicle.

string
required

Internal Carrier id (UUID) of the carrier that owns this vehicle.

string
enum
required

Directory status controlling whether the vehicle is available for assignment.

Allowed:
string

The manufacturer of the vehicle.

string

The model of the vehicle.

string
string
length between 3 and 3
^[A-Z]{3}$

The country code of the number plate (ISO Alpha-3)

string

Vehicle Identification Number

string
required
length ≥ 1

Reference to a VehicleClass by its id — a caller-chosen readable slug like "RIGID_75", not a UUID. Sets the capacity/dimension template this vehicle belongs to.

extras
array of strings
required

Vehicle capability flags this vehicle provides (e.g. Liftgate, Refrigerated), matched against a shipment's required extras to gate feasibility.

extras*
number
≥ 0

Internal cargo-container width in CENTIMETERS (not the outer vehicle width, which is in meters). Used by 3D load planning to place loads across the container.

number
≥ 0

Internal cargo-container length in CENTIMETERS. Drives loading-metre (LDM) utilization and load placement in the primary loading direction.

number
≥ 0

Internal cargo-container height in CENTIMETERS. Constrains load stacking height in 3D load planning.

≥ 0

Outer vehicle width in METERS (note: metres, unlike the centimetre container dimensions). Used for routing/access constraints.

≥ 0

Outer vehicle length in meters (see outerWidth).

≥ 0

Outer vehicle height in meters (see outerWidth).

number
required
≥ 0

Maximum cargo weight the container can carry, in kilograms. Enforced by 3D load planning against the combined load weight.

number
required
≥ 0

Maximum gross vehicle weight in kilograms (cargo plus the vehicle itself).

string

Operator-only free-text note about the vehicle.

number
required

Creation timestamp in epoch SECONDS (Europe/Berlin).

number

Last-update timestamp in epoch MILLISECONDS (milliseconds, unlike createdAt which is seconds).

properties
object | null

Key-value pairs in the dictionary have property IDs as keys. Property keys and their values appear only when the property value is explicitly set. All property values are validated against their definitions - requests with unknown property IDs or invalid value types will be rejected with a 400 error.

accessDirection
array of strings

Sides from which the cargo container can be loaded and unloaded.

accessDirection
Allowed:
string
enum

The type of fuel used by the vehicle.

string
enum

The emission standard of the vehicle.

Allowed:
string
enum

The emission class of the vehicle.

Allowed:
1 to 9007199254740991

The number of axles on the vehicle.

start
object

Address the vehicle starts its tour from. Defaults to the depot/data when omitted.

end
object

Address the vehicle must return to at the end of its tour. Defaults to the start when omitted.

number
≥ 0

Maximum total driving distance for one tour on this vehicle, in METERS (e.g. 300000 for 300 km).

number
≥ 0

Maximum total tour duration for this vehicle, in MINUTES (e.g. 480 for an 8-hour shift), covering driving, service, and waiting.

number
≥ 0

Maximum number of load units this vehicle may carry per tour.

number
≥ 0

Maximum number of stops (pickups plus dropoffs) on one tour for this vehicle.

schedule
object

Weekly availability windows during which this vehicle can be routed.

number
≥ 0

Relative cost weight applied each time this vehicle is used (not a currency amount); raise to make the planner prefer fewer vehicles.

number
≥ 0

Multiplier on estimated driving speed for this vehicle: below 1.0 assumes slower travel (e.g. 0.8 = 20% slower), above 1.0 faster.

options
object
string
boolean

When true, shipment pickup and delivery time windows are ignored during this recalculation, so stops may be scheduled at any time of day. Vehicle availability windows still apply.

startSolution
object
required

The proposed-tour set to recalculate. Tour ids in solutionTours must be unique, and each changedTours id must appear once and match a solutionTours id.

Responses

400

Invalid request body

401

Unauthorized

404

Profile not found

409

the submitted plan pins a shipment that now has several legs without naming one, so its kept stops cannot be matched to a leg — re-plan those shipments and recalculate the rebuilt plan

500

The solution could not be recalculated

Updated 27 days ago

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

Updated 27 days ago

Did this page help you?