Logistics API Settings

The simulation.data.logistics_api_settings object allows you to fine-tune the optimization process when running simulations using the Stateful API. These settings control various aspects of the solver, model constraints, and calculation behavior.

Field names are matched exactly, and unknown keys are dropped

The object is parsed into a fixed schema. A key that is not one of the parameters below is silently ignored — no error, no warning, and the run proceeds with the default. A typo, or a name borrowed from the Optimization (Stateless) API, therefore looks like a setting that has no effect.

Several parameters are deliberately named differently here than in the solver request they end up in: algo_optimize_quantity becomes model_parameters.optimize_quantity, vehicle_cost becomes model_parameters.vehicle_costs, and first_solution_strategies becomes solver_parameters.first_solution_strategy. Use the names in this page's tables.

Every default below is the out-of-the-box value. Most are deployment-configurable environment variables, so a specific installation may start from a different value — treat the defaults as indicative and set anything your operation depends on explicitly.

Core Optimization Objectives

These parameters define the primary goals of the optimization, such as minimizing cost, time, or distance.

Parameter	Type	Description	Default
algo_optimize_quantity	string	Optimization goal: total_time or total_distance. Reaches the solver as model_parameters.optimize_quantity; the setting read here is only the algo_ name.	total_time
trip_cost	number	Cost assigned to each trip. See Trip cost.	0
vehicle_cost	number	Fleet-wide fallback for a vehicle's own vehicle_cost: a fixed amount charged once for each vehicle the solver uses, applied to every vehicle that does not set the field itself. High values discourage using additional vehicles. Reaches the solver as model_parameters.vehicle_costs. See Vehicle cost.	1000
cluster_cost	object	Adds a penalty derived from how geographically spread a vehicle's stops are, pushing the solver towards tight clusters per vehicle. Takes coord_scale (coordinate-to-distance factor, default 0.001), factor (the global weight, used for vehicles with no cluster_cost_factor of their own), and ignore_nodes / ignore_node_types / ignore_latlons to exclude depots and other fixed points from the cluster it measures.	null
booking_penalty	number	Penalty for dropping a visit (unserved booking). Added to the objective function. Must be high enough to heavily discourage the solver from rejecting viable orders. See Booking penalty.	1000
slack_cost	number	Marks the run's nodes as slack-charging, so waiting time at them is priced into the objective. Only 0 and 1 are supported — it selects whether slack is charged, while slack_cost_factor sets the rate. This is the legacy path's mechanism: under path_constraints_mode set to logistics the solver takes slack cost from each vehicle's logistics_optimize_slack instead and ignores this field.	null
slack_cost_factor	number	Penalty applied per unit of slack time (waiting time) for all nodes. Setting this helps the solver try to minimize idle waiting times for drivers, leading to more compact schedules. Note: Requires path_constraints_mode set to logistics.	-
logistics_optimize_slack	boolean	If true, the solver will actively optimize and reduce the total slack (idle waiting time) in the resulting routes, tightening the schedule. Note: Requires path_constraints_mode set to logistics.	-
use_path_equalizer	boolean	Enables the Path Equalizer, which adds a penalty for routes that deviate from the average route length (in terms of number of stops). Helps distribute assignments more evenly across available vehicles.	-
path_equalizer_weight	integer	The weight (penalty multiplier) for the path equalizer objective. A higher value strongly forces the solver to prioritize balancing the number of stops across all vehicles over reducing pure travel time.	100
use_selective_path_equalizer	boolean	Applies the path equalizer only to the vehicles the solver actually uses, so balancing is measured across the working fleet instead of being diluted by vehicles left idle.	false
use_working_hours_equalizer	boolean	Enables the Working Hours Equalizer, which balances total trip duration (working hours) across vehicles rather than stop counts. Together with working_hours_equalizer_weight this is collapsed into the solver's single working_hours_equalizer coefficient, so the weight has no effect while this is false. See Equalizers.	false
working_hours_equalizer_weight	integer	Cost coefficient for the working hours equalizer, weighed against travel cost in the same objective. Ignored unless use_working_hours_equalizer is true, and ignored by the solver for a single-vehicle run.	100
use_node_weights_cost	boolean	Lets a node's own weight scale its contribution to the objective, so heavier or more important stops carry proportionally more cost.	true
route_cost_modification_primary	object	Advanced configuration to apply non-linear (polylinear) penalties or step-functions to travel time or distance matrices for the primary routing engine. Enables custom cost rules such as penalizing trips beyond a given distance or time threshold to encourage compact routes. Translated internally to travel_matrix_operator before the solver call.	-
route_cost_modification_secondary	object	Analogous to route_cost_modification_primary but applied to the secondary routing engine (e.g. spheroid for straight-line distance). Adding a small distance factor here promotes geographic compactness without overriding the primary time objective. See Route Compactness for usage details.	-

Operational Constraints

These settings define the hard limits and constraints for routes, such as time windows, slack, and compliance rules.

Parameter	Type	Description	Default
max_pickup_slack	integer	Maximum allowed waiting time (slack) before a pickup node (in seconds). Limits how early a vehicle can arrive and wait idly before a pickup starts.	-
max_dropoff_slack	integer	Maximum allowed waiting time (slack) before a dropoff node (in seconds). Limits how early a vehicle can arrive and wait idly before a dropoff.	-
allow_vehicle_late	boolean	Relaxes time constraints to allow late or early arrivals for better route efficiency or to fit more orders, instead of rejecting them.	false
vehicle_late_penalty_coefficient	integer	Penalty weight for lateness when allow_vehicle_late is true. Higher values discourage late arrivals, preserving strict SLAs unless absolutely necessary.	-
max_possible_lateness	integer	Absolute maximum allowed lateness in seconds. Even if allow_vehicle_late is enabled, the solver will not violate this extreme upper limit.	null
truckban_enabled	boolean	Enables or disables truck ban constraints, which restrict certain areas for vehicles during specific time windows.	-
truckban_strategy	object	Defines the strategy for handling truck bans (e.g., waiting outside the zone, avoiding the zone entirely, etc.).	-
truckban_buffer_time_windows	integer	Buffer time (in seconds) added when adjusting time windows for truck bans, providing a safety margin for the vehicle to leave the restricted zone before the ban starts.	-
logistics_break_info_handling_enabled	boolean	Master switch for driver break handling, across both the optimization pipeline and the Manual Edit API. While it is off, no vehicle's dynamic-break parameters are sent to the solver — so an optimization run plans no driver breaks at all — calculate_break_start_times is disabled, so no break_start_ts is returned, and manual edits neither recalculate nor preserve breaks, clearing break_info from the nodes they touch. Must be on for driver breaks to be planned and to survive an edit. Omitting it, or sending null, falls back to the deployment-level default rather than to a fixed false; send true or false explicitly to be sure which behaviour you get. See Driver Breaks and Driver Breaks and Manual Edits.	deployment default (off unless enabled)
enable_time_windows_adjustment	boolean	Enables time window adjustment for nodes generated from operations_locations. This allows modifying the node's time windows using open_ts_offset and close_ts_offset values from the location settings.	false
time_windows_adjustment_strategy	string	Defines the strategy for time window adjustment. Currently, the only supported value is DROPOFF_FIXED_CLOSE_TS_OFFSET. Under this strategy, the close_ts_offset (seconds) is subtracted from the node's original close time, ensuring it does not precede the open time: new_close_time = max(original_open_time, original_close_time - close_ts_offset). The open_ts_offset is currently unused by this strategy. Modification of open_ts is not supported at the moment.	DROPOFF_FIXED_CLOSE_TS_OFFSET
use_walking_time_to_reduce_time_windows	boolean	Uses walking time to adjust time windows.	false
cumulative_limitations	array	Defines physical or operational limitations on the number of vehicles that can be serviced simultaneously at a specific location or depot.	-
clear_cumulative_limitations	boolean	If true, clears and ignores any previously set cumulative vehicle limitations at locations.	-
max_departures_per_hour	number	Caps how many vehicles may leave the operations locations per hour, as one simulation-wide setting instead of a cumulative_limitation on each operations location. The value N is resolved into a single cumulative limitation covering every pickup and vehicle_position node, with max_cumulative_vehicles of 1 and depot_service_time of 3600 / N — one vehicle serviced at a time, so one departure every 3600 / N seconds. Unset or 0 applies no limitation. It cannot be combined with a per-location cumulative_limitation; a run that configures both is rejected. Applies to optimization runs only — manual edit re-solves never carry cumulative limitations. See Limiting capacity of the warehouse.	null
cumulative_limitations_mode	string	Whether depot slot assignment is solved together with the routes (local_search) or in a separate pass after them (postprocessing). The default is set per deployment and is currently postprocessing, which differs from the Optimization (Stateless) API's own default of local_search. Has no effect unless a cumulative limitation applies. See Controlling when depot slots are assigned.	postprocessing
compound_zones	array	Definitions for specialized zones (e.g. specific areas or depots) that apply an artificial time penalty strictly upon entry or exit.	-

Grouping & Sequence Rules

These parameters control how orders are grouped onto vehicles and the sequence in which they are serviced.

Parameter	Type	Description	Default
node_grouping_enabled	boolean	Merges orders at the exact same coordinates with chainable time windows into one stop before solving. See Order Grouping.	false
node_grouping_capacity_strategy	string	Capacity threshold a group's combined demand must not exceed: min, max, median or mean of the eligible vehicles' capacities, or ignore.	min
assigned_node_grouping_enabled	boolean	Extends node_grouping_enabled to nodes that are already assigned to a vehicle, so each vehicle's own assigned stops are grouped with one another (capacity check skipped). It does not merge a new order into an assigned stop. Has no effect unless node_grouping_enabled is also true, and applies to PDP runs only — the CVRPTW path never groups assigned nodes. When false, grouping considers unassigned nodes only.	false
mutually_exclusive_groups	array	List of group pairs that are designated as mutually exclusive. This prevents bookings from these specified groups from being simultaneously mixed on the same vehicle.	-
strictly_exclusive_groups	array	List of groups that cannot be mixed under any generic circumstances on the same vehicle. By default, all groups are treated as strictly-exclusive unless overridden.	-
group_crossing_penalty	number	Penalty added to the cost function when non-strictly exclusive groups are mixed, discouraging crossed deliveries while still preserving mathematical feasibility.	-
booking_order_prioritization	object	Configuration rule to prioritize critical bookings over standard jobs, influencing the solver to guarantee specific SLAs on high-priority orders.	-
use_lifo_order_check	boolean	Enables strict Last-In-First-Out (LIFO) order constraints, frequently used in standard PDP cases to match stackable loading logic.	false
lifo_order_check_on_all_vehicles	boolean	Ensures the LIFO execution check is systematically applied across all vehicles rather than selectively.	true

Manual Editing & Re-Planning Support

These settings specifically affect how the system behaves when manual edits (insertions, moves) are performed or when re-planning live routes.

Driver break handling during edits is governed by logistics_break_info_handling_enabled, listed under Operational Constraints because it gates the optimization pipeline as well.

Parameter	Type	Description	Default
manual_edit_api_minimize_slack	boolean	Tries to actively minimize idle waiting times (slack) when a planner performs manual edit actions (e.g., drag and drop bookings).	-
manual_edit_allow_vehicle_late	boolean	Dictates whether vehicles are allowed to be late specifically during manual edits, giving the planner more flexibility to force an assignment.	true
manual_edit_lateness_penalty_coefficient	integer	The penalty coefficient applied for lateness when the planner forces an edit that causes a delay.	10
manual_edit_api_vehicle_logistics_optimize_slack	boolean	Determines if vehicle-specific slack optimization is enforced during manual operations. If not provided, relies on the broader logistics_optimize_slack flag.	-
manual_edit_api_use_vehicle_start_time	boolean	Ensures that manual edit calculations explicitly respect and adapt to the vehicle's predefined daily start time and ongoing sequence timeline.	-
manual_edit_api_solver_kind	string	Defines the specific solver algorithm used specifically to handle manual edits (default: LOCAL). Useful for tuning responsiveness vs robustness during interaction.	LOCAL
manual_edit_finalization_type_pickups	string	Defines the specific time finalization constraint strategy (min for earliest possible time, or max for latest) used iteratively for pickups during edits.	-
manual_edit_finalization_type_dropoffs	string	Defines the specific time finalization strategy (min or max) assigned to dropoff nodes explicitly upon performing a manual edit.	-
manual_edit_max_possible_lateness	integer	The discrete maximum upper limit in lateness allowable during manual interventions (seconds) before raising an outright failure.	-
manual_edit_optimize_quantity	string	Defines the localized operational goal specifically invoked during edits: normally overriding to total_time or total_distance temporarily.	-
manual_edit_slack_cost_factor	number	Modifiable cost penalty applied per incremental unit of slack explicitly when validating a user's manual re-arrangement or forced fit.	-
manual_edit_allow_cvrptw_conversion	boolean	Enables CVRPTW mode and order grouping during manual edits in the simulation. When active, manual planning actions trigger an optimization check for CVRPTW feasibility (same pickup locations and time windows). If feasible, multiple orders are converted into a single node. Similarly, drop-offs at the same location with overlapping time windows are consolidated into a single action (ignoring capacity constraints).This streamlines manual planning by ensuring trips have a single pickup and consolidated drop-offs, visiting each location only once per trip.	false
manual_edit_try_strict_time_windows_request	boolean	Tries to strictly enforce time windows perfectly during manual edits initially; only gently loosens timewindow constraints sequentially if unfeasible. Should be used with manual_edit_allow_vehicle_late=true.	false
manual_edit_keep_assigned_nodes_relative_order	boolean	If true, the solver strictly preserves the relative sequence of already assigned nodes during manual edits. Useful for a planner inserting new orders without unexpectedly reshaping or reshuffling the ongoing route context.	-
manual_edit_td_postprocessing_no_offer_if_time_window	boolean	The Manual Edit API's counterpart to postprocessing_no_offer_if_time_window, governing that API's own time-dependent re-timing pass. When true, an edit whose refined arrival times push a booking past its close_time_ts unassigns that booking rather than leaving it on the route in violation: its nodes go back to NEW with scheduled_ts and break_info cleared, and the booking is reported under details.rejected_bookings in the response. Takes effect on vehicle_assign_booking_list and shift_nodes_time_windows only; other actions re-time their routes without acting on a violation. Requires tdroute_postprocessing_enabled. See Pruning bookings that miss their window.	false

Simulation Execution & Logic

These parameters control the flow of the simulation and how it interacts with the current state of execution.

Parameter	Type	Description	Default
only_pdp	boolean	Strives to forcefully mandate classic Pickup and Delivery Problem (PDP) mathematical model processing rather than gracefully failing back to CVRPTW.	false
pipeline_type	string	Internal logic layout configuration: e.g., simple_one_stage executes exactly one holistic stateless solver pass; whereas two_stages performs a structural estimation run followed closely by precision scaling adjustments.	simple_one_stage
allow_upload_after_simulation_start_time	boolean	If true, enables live operational changes by explicitly allowing order/booking injections or manifest modifications even sequentially after the core shift start time has passed.	false
booking_data_pipeline_filters	array	List of filter rules applied to incoming bookings before they are processed by the pipeline. Each rule targets a field in booking.data and supports operations such as equals, not_equals, contains, not_contains, in, not_in, is_null, and is_not_null. The value field supports Django template syntax (e.g. {{ simulation.start_time|date:'Y-m-d' }}), allowing dynamic filtering based on simulation properties. All rules are applied sequentially; only bookings matching all rules are passed to the solver.	[]
should_lock_next_stop_if_vehicle_live	boolean	Operationally locks the immediate upcoming physical stop assignment for active vehicles, structurally preventing real-time re-optimizations from abruptly modifying a driver's target destination while en route.	true
should_optimize_fail_to_board_bookings	boolean	Attempts actively to re-examine or securely salvage trips that were temporarily tagged or rejected as failed-to-board within the continuing sequential solve logic.	true
enable_pickup_reassignment	boolean	Allows the optimizer to move an already-assigned pickup node to a different vehicle, instead of treating existing pickup assignments as fixed.	false
enable_inventory_tracking	boolean	Tracks stock levels at inventory locations across the run, so the plan respects what is actually available to load rather than assuming every pickup can be served.	false
exclude_unroutable_bookings	boolean	Drops bookings the routing engine cannot reach from the calculation instead of letting one unreachable coordinate degrade or fail the run. The excluded bookings come back as rejected.	false
geofence_definition_strategy	object	Operational strategy pattern assigning logic for localized map geofence creation rules.	-
geofence_vehicle_allocation_strategy	object	Allocation stringency rule map (STRICT vs. FLEXIBLE) defining precisely how robustly a vehicle is structurally held within its parent designated geofence operational cluster bounds.	-
should_set_max_slack_start_location_zero	boolean	Explicitly resets maximum allowed waiting time on the vehicle's initial start node perfectly to zero, essentially preventing artificial dispatch delays systematically.	-
path_constraints_mode	string	Underpinning path architectural restrictions engine methodology (legacy vs logistics).	-
finalization_type_pickups	string	Method defining the physical time allocation assignment internally for generic pickups, choosing either min (dispatch as earliest logically scheduled) or deliberately assigning to max.	min
finalization_type_dropoffs	string	Method defining the physical time allocation assignment explicitly for generic dropoff completions (min or equivalently max).	min
tdroute_postprocessing_enabled	boolean	Runs a second pass after the solver that re-times the route against time-dependent travel times, refining scheduled_ts, estimated_earliest_arrival_ts and slack. Applies both to the optimization pipeline and to every manual edit that re-times a route. Supported on the OSRME routing engine only — routes on any other engine are left untouched — and fails open, so a routing-engine error is logged and the solver's original timings stand. Note: this pass also rewrites break_info on every node it re-times, planning driver rests on its own cumulative clock. A vehicle that does not have both dynamic_break_duration and dynamic_break_avg_time_between_breaks set has its recorded break plan cleared. See Driver Breaks.	false
postprocessing_no_offer_if_time_window	boolean	Decides what the tdroute_postprocessing_enabled pass does when its refined timings turn out to break a time window — waiting time behind a truck ban that the solver never priced in, for example, can push an arrival past the node's close_time_ts. When false the booking stays on the route in violation. When true the whole booking is pruned instead — both its pickup and its dropoff — the leg the removal opens up is re-measured, and the pass runs again over what remains, cascading if that turns up a further violation. Pruned bookings join the run's rejected bookings with the reason tdroute_postprocessing_time_window_violation, so they go through the normal no-offer handling. Has no effect unless tdroute_postprocessing_enabled is on. Governs the optimization pipeline; the Manual Edit API has its own manual_edit_td_postprocessing_no_offer_if_time_window.	false

Advanced Solver Configuration

These parameters provide low-level control over the VRP solver algorithm. They are typically used by experts to tune performance and search behavior.

Parameter	Type	Description	Default
algorithm	string	Solver algorithm: static (default) or dynamic (for real-time/on-demand).	static
first_solution_strategies	array	A list of first solution strategies (integers) to be used concurrently to execute the optimization run. The first entry becomes the solver's own solver_parameters.first_solution_strategy.	[0]
first_solution_strategies_second_stage	array	First solution strategies for the second stage of a two-stage run, used only when pipeline_type is two_stages. Unset reuses the first stage's strategies.	null
solution_limit	number	Maximum number of solutions to generate during the search.	100000000
time_limit_ms	number	Maximum time allowed for the search (in milliseconds). Note this is a 30-second budget out of the box, not an effectively unlimited one — raise it deliberately for large runs, or let auto_calculate_time_limit_enabled size it from the problem.	30000
time_limit_ms_second_stage	number	Search time limit for the second stage of a two-stage run (pipeline_type set to two_stages). Has no effect on a single-stage pipeline.	30000
auto_calculate_time_limit_enabled	boolean	Enable or disable auto calculation of solver time limit.	null
auto_calculate_time_limit_params	object	Parameters for auto calculation of solver time limit. See Auto Calculation Solver Time for details.	null
use_local_search_metaheuristic	boolean	Enables local search metaheuristics.	false
guided_local_search_lambda_coefficient	number	Parameter for the guided local search procedure.	0.1
use_tsp_opt	boolean	Enables Traveling Salesperson Problem (TSP) optimization.	false
log_search	boolean	Enables search logging.	false
lns_time_limit_ms	number	Time limit for Large Neighborhood Search (LNS) completion search.	1000
savings_neighbors_ratio	number	Ratio for savings neighbors.	1.0
waypoints_optimization_second_phase	boolean	Enables a second phase of waypoint optimization for prebook mode.	false
waypoints_solution_limit	number	Maximum number of solutions the waypoint optimization phase may generate, bounding its share of the search budget.	1000
optimization_step	number	Minimum improvement step for local search.	1
use_all_local_search_operators	boolean	Uses all available local search operators.	false
use_local_search_operators	array	Names of the individual local search operators to enable, for tuning the search rather than taking all or none. Each entry must be one of the solver's known operator names; an unrecognised name fails validation. An empty list leaves the choice to the solver.	[]
use_depth_first_search	boolean	Uses depth-first search instead of local search.	false
cvb_fleetmin_time_limit	integer	Time limit for CVB fleet minimization.	600
cvb_fleetmin_solutions_limit	integer	Solution limit for CVB fleet minimization.	-
cvb_fleetmin_iterations_limit	integer	Iteration limit for CVB fleet minimization.	-
use_cvb_local_search_operator	boolean	Uses CVB local search operator.	-
cvb_local_search_iterations_limit	integer	Iteration limit for CVB local search.	-
average_travel_duration_to_node	integer	Estimated average travel duration to a node (in seconds).	1200
total_to_furthest_distance_ratio	number	Hard cap on the ratio between a vehicle's total travel distance and its distance to the furthest node it serves, rejecting routes that wander far off the radial line. See Distance ratio constraint.	null
partition_nodes	boolean	Splits nodes into partitions before the search so the solver works through smaller sub-problems. Supported on the VRP toolbox solver only.	false
use_mixed_time_matrix	boolean	Lets the run combine travel times from more than one source matrix, for fleets whose vehicles do not all share a routing profile.	false

Infrastructure & Connectivity

Settings for connecting to external calculation services.

Parameter	Type	Description	Default
stateless_api_server	string	URL of a custom stateless API server to use for the simulation.	-
stateless_api_login	string	Login for custom stateless API server.	-
stateless_api_password	string	Password for custom stateless API server.	-