How constraints work

V3 is in beta. General availability (GA) is planned for January 2027.

This page describes the V3 API (/v3/routing). For the V2 API (/v2/vrp), see the V2 version of this page.

Every request asks the solver two questions: which plans are allowed, and which allowed plan is best. Your constraints answer the first and your objective answers the second. This page explains the model behind both for POST /v3/routing/solve. For each field and the JSON to send, see Constraints. On this page a task is a job or a shipment. Where a rule applies to jobs only, the page says “job”.

Coming from V2? There are no constraint weights and no hard/medium/soft score levels here. A rule is either hard (it always holds) or it is a price in your own currency. See Migration from V2.

Hard and soft

Every rule you send is one of two kinds:

Kind	What it does	What you see when it bites
Hard	Never broken. A task that cannot be placed without breaking a hard rule is left out of the plan.	The task is listed in `unassigned[]` with a reason.
Soft	Allowed, at a price you set. The price is added to the plan’s cost, and the solver trades it against travel like any other cost.	A non-zero entry in `summary.score.components`.

A solve result never contains a broken hard rule: summary.score.violation_count is always 0 on /v3/routing/solve. To check a plan of your own, which may break hard rules, use /v3/routing/evaluate.

Hard constraints

Only the rules you send are active. A request with capacities and nothing else is checked for capacity and nothing else.

Rule	Request fields	What always holds
Capacity	`vehicles[].capacity`, `shifts[].capacity`, `jobs[].pickup_load`, `jobs[].delivery_load`, `shipments[].load`	The load never exceeds capacity on any named dimension, at any point of the route. With reloads, this holds within each trip.
Time windows	`time_windows[]`	The vehicle arrives no later than a window’s `to`, and an early arrival waits until `from`. A lateness rate makes the late side soft (see below).
Shift hours	`shifts[].from`, `shifts[].to`, `shifts[].max_overtime_s`	The route finishes by `to`, or by `to + max_overtime_s` when overtime is granted.
Skills	`required_skills` on tasks, `skills` on vehicles and shifts	The vehicle (or the shift, when it lists its own skills) provides every skill the task requires, at the required `min_level`.
Tag zones	`shifts[].serves_tags`, `tags` on tasks	A shift with `serves_tags` serves only tasks carrying at least one of those tags. Untagged tasks can go anywhere.
Vehicle eligibility	`eligible_vehicles.allowed` or `.excluded`	The task is served only by an allowed vehicle, or never by an excluded one.
Vehicle pin	`eligible_vehicles.allowed` with one id	The task is served by that vehicle, on any of its shifts.
Route limits	`vehicles[].limits.max_distance_m`, `.max_route_duration_s`, `.max_leg_travel_s`; `shifts[].limits`	One route’s distance and its whole span (travel, service and waiting) stay within the limit, and no single drive between two stops takes longer than `max_leg_travel_s`. A shift’s own `limits.max_distance_m` and `.max_route_duration_s` replace the vehicle’s for that shift, field by field; `max_leg_travel_s` is set on the vehicle only.
Stop count	`limits.max_stops`	A job counts as one stop, a shipment as two.
Period limits	`vehicles[].limits.periods[]`	A vehicle’s summed span, distance or stop count across its shifts in a day, a week or a window stays within the cap.
Quotas	`quotas[]`	A group of vehicles together serves at most `max_stops` stops of the listed tasks, optionally within a time window.
Relations	`relations[]`	Order within a route, same vehicle, same day, same route, synchronized visits and time lags between jobs and shipment legs. A shipment’s own id is rejected with HTTP 400 `not_supported`, except in `all_or_none` over a `consecutive` chain (see Relations).
Shipments	`shipments[]`	Pickup comes before delivery, on the same route.
Driver breaks	`shifts[].breaks[]`	Breaks are scheduled as specified and appear as `break` stops in the route.
Reloads	`shifts[].reloads[]`, `shifts[].max_trips`	A vehicle returns only to the depots listed, and makes at most `max_trips` trips.
Reachability	none (automatic)	No route uses a leg the road network cannot connect.

Capacity

Dimensions are named and matched by name between capacity and pickup_load.

{
  "problem": {
    "vehicles": [
      {
        "id": "van-1",
        "capacity": { "weight": 1000 },
        "shifts": [
          { "id": "mon", "from": "2026-07-01T08:00:00+02:00", "to": "2026-07-01T17:00:00+02:00" }
        ]
      }
    ],
    "jobs": [
      { "id": "job-1", "location": [3.7250, 51.0500], "pickup_load": { "weight": 20 } }
    ]
  }
}

Time windows

A window is hard unless you price lateness. This job must be reached between 09:00 and 12:00:

{
  "id": "job-1",
  "location": [3.7250, 51.0500],
  "time_windows": [
    { "from": "2026-07-01T09:00:00+02:00", "to": "2026-07-01T12:00:00+02:00" }
  ]
}

Several windows on one task mean “any of these”. Arriving early always waits for from; only the late side can be made soft.

Relations

relations[] ties jobs and shipment legs to each other. It has ten types, and all of them are hard.

[
  { "type": "sequence", "stops": ["job-1", "job-2"] },
  { "type": "same_vehicle", "tag": "customer-42" },
  { "type": "same_day", "stops": ["job-3", "job-4"] },
  { "type": "same_route", "stops": ["job-9", "job-10"] },
  { "type": "synchronized", "stops": ["job-5", "job-6"], "max_spread_s": 300 },
  { "type": "time_lag", "from": { "stop": "job-7", "on": "departure" }, "to": { "stop": "job-8" }, "min_s": 3600 },
  { "type": "compatible_vehicles", "stops": ["job-5", "job-6"] },
  { "type": "all_or_none", "stops": ["job-5", "job-6"] }
]

Type	Members	Rule
`sequence`	`stops`	members that share a route appear on it in this order; other stops may come in between. It does not by itself put the members on the same route. A single id makes that job the first stop of its route.
`consecutive`	`stops` (at least 2)	Like `sequence`, and no other stop may sit between two neighbouring members served on the same route. An unassigned member is skipped. Members on different routes are unconstrained; add `same_route` to keep them together.
`tag_order`	`tags` (two or more tag labels)	On every route, every job tagged `tags[0]` comes before every job tagged `tags[1]`, and so on.
`same_vehicle`	`stops` or one `tag`	The members are served by the same vehicle.
`same_day`	`stops` or one `tag`	The members are served on shifts whose `from` falls on the same calendar date, read in the offset each `from` is written with. The day belongs to the shift, not to the visit time.
`same_route`	`stops` or one `tag`	The members are served on one route: one shift of one vehicle (V2 `SAME_TRIP`). Reloads within the shift do not split it.
`synchronized`	`stops`	The members start (or, with `"on": "departure"`, finish) within `max_spread_s` seconds of each other, across vehicles. `max_spread_s` is required; `0` means exactly together.
`time_lag`	`from` and `to`, two different jobs	`to` starts or ends between `min_s` and `max_s` seconds after `from` starts or ends, across vehicles. `min_s` defaults to `0`; without `max_s` there is no upper bound.
`compatible_vehicles`	`stops` only: 2 to 16 jobs, each also named by a `synchronized` or `time_lag` relation	Every two different vehicles that serve the members must be compatible. Compatibility comes from `vehicles[].compatible_with`: a vehicle without the field pairs with any vehicle, and a list is a veto, so two vehicles pair only if neither list excludes the other. A vehicle always pairs with itself.
`all_or_none`	`stops`: 2 or more jobs or shipments (a shipment stands for both legs). Each job is also named by a `synchronized` or `time_lag` relation, or the group is exactly one `consecutive` chain	Either every member is served or none is. It sets no timing.

An unknown relation type is rejected with HTTP 400.

A relation reaches a shipment through its legs: sequence, same_vehicle, same_day and same_route accept a leg’s stop id (by default "{shipment}:pickup" or "{shipment}:delivery") and bind that leg like a job. A leg coupled to other tasks by synchronized or time_lag is rejected with HTTP 400. A shipment’s own id in the stops of a relation, and a shipment that carries the tag of a same_vehicle or same_day relation, is rejected with HTTP 400 not_supported; tag_order rejects a tag that selects a shipment. The one exception is all_or_none, which takes a shipment’s own id (both legs) in a group that is exactly one consecutive chain. No member is silently dropped. See Shipments in relations.

A shipment already has one built-in rule of its own: the pickup comes before the delivery, on the same route. See Relations for every field and every rejected combination.

Soft constraints

Use these levers to allow something at a price. Each one reports what it cost in summary.score.components.

Lever	Request fields	What is priced	Score component
Per-window lateness	`time_windows[].per_late_hour`	Arriving after `to` on that one window, per hour late	`lateness`
Fleet-wide lateness	`objective.per_late_hour`	Arriving after `to` on every window that has no rate of its own, per hour late	`lateness`
Alternative-window cost	`time_windows[].choice_cost`	Being served in this window instead of a cheaper one on the same task (flat amount)	`window_choice`
Target	`target.at`, `target.on`, `target.per_late_hour`	Reaching the task’s arrival or departure after `at`, per hour late	`target`
Overtime	`shifts[].max_overtime_s` with `costs.per_overtime_hour` (fleet, vehicle or shift)	Finishing past the shift’s `to`, per hour	`overtime`
Preferred tags	`vehicles[].preferred_tags[]`	A vehicle serving a task that does not carry the preferred tag (flat `violation_cost`)	`tag_preference`
Vehicle preferences	`preferences[]` on a task	The task being served by a vehicle other than the preferred one (flat `violation_cost`)	`preferences`

How they combine:

Lateness, per window or fleet-wide. Use time_windows[].per_late_hour when only some tasks may run late: it softens that one window and leaves every other window hard. It must be greater than 0 and is allowed only on a task with exactly one window. Use objective.per_late_hour to soften all windows at once; a window with its own rate keeps that rate. Omit the fleet rate to keep windows hard: an explicit 0.0 is rejected with HTTP 400.
Alternative-window cost does not soften anything. Every window stays hard; choice_cost only grades which of a task’s two or more windows is preferred. A non-zero choice_cost anywhere in the request cannot be combined with objective.per_late_hour (HTTP 400).
A target is a point, not a window. It never makes a task unassignable and never forces a vehicle to wait. On a shipment it is measured on the delivery leg. The stop reports target_lateness_s.
Overtime is bounded. max_overtime_s grants the extension; anything beyond to + max_overtime_s is still forbidden. Without per_overtime_hour overtime carries no extra charge beyond the normal hourly route rate.
Preference entries are independent. A task listing several preferred vehicles pays for every listed vehicle that does not serve it, including when one of the others does. A vehicle with several preferred_tags charges each tag the task lacks.

A job with a soft window, a target, and a preferred vehicle:

{
  "id": "job-1",
  "location": [3.7250, 51.0500],
  "time_windows": [
    { "from": "2026-07-01T09:00:00+02:00", "to": "2026-07-01T12:00:00+02:00", "per_late_hour": 60.0 }
  ],
  "target": { "at": "2026-07-01T10:00:00+02:00", "on": "arrival", "per_late_hour": 20.0 },
  "preferences": [{ "vehicle": "van-1", "violation_cost": 50.0 }]
}

Three more priced fields shape a plan without softening a rule: drop_cost makes a task optional at a price, assignment_costs prices serving a task on a given vehicle, and objective.grouping keeps nearby tasks together. Skills, capacity, eligibility, relations, limits and quotas have no soft form.

From constraints to the objective

Among the plans that respect every hard rule, the solver compares in a fixed order: least unassigned_priority first, then least cost. Serving required tasks always comes before saving money; every soft lever above is part of cost. Objective function covers the comparison, priority, and the cost model in full. You set cost rates at three levels: fleet-wide under objective.costs, per vehicle under vehicles[].costs, and per shift under shifts[].costs. A lower level replaces a rate field by field.

{
  "problem": {
    "vehicles": [
      {
        "id": "van-1",
        "costs": { "per_route": 150.0 },
        "shifts": [
          {
            "id": "mon",
            "from": "2026-07-01T08:00:00+02:00",
            "to": "2026-07-01T17:00:00+02:00",
            "start": { "location": [4.35, 50.85] },
            "end": { "location": [4.35, 50.85] }
          }
        ]
      }
    ],
    "jobs": [
      { "id": "job-1", "location": [4.36, 50.86] }
    ],
    "objective": {
      "currency": "EUR", "costs": { "per_travel_km": 0.20, "per_route_hour": 25.0 }
    }
  }
}

Put a shift’s start and end on the shift itself, as start and end, each naming a location or a depot.

Why a task is left unassigned

When the solver leaves a task out of the plan, the solve response says why. Each task left out has an entry in unassigned[]; you do not need an extra request or flag.

{
  "task": "job-9",
  "category": "blocked",
  "reasons": [
    { "constraint": "capacity",
      "message": "Capacity refused this task on at least one vehicle"
    }
  ],
  "relaxations": [
    {
      "pointer": "/problem/jobs/8/pickup_load",
      "op": "reduce_load",
      "amount": 5,
      "unit": "load",
      "message": "Reduce this task's load (its `pickup_load` or `delivery_load`) by 5, or add 5 capacity to an eligible vehicle."
    }
  ]
}

Read the entry in this order:

category tells you what kind of fix can work. impossible and blocked mean a hard rule is in the way: change the request, or add capacity or working time. priced_out means the task has a drop_cost and paying it was cheaper than serving the task. time_limit means a worthwhile place exists and the time budget ran out first.
reasons[] has one entry per rule that blocked the task, once each, named in constraint. For priced_out and time_limit there is one reason without a constraint.
relaxations[] gives the smallest change that would have let the task fit, when one number can express it: reduce_load (in load units) for capacity, extend_time_window (in seconds) for time windows. It is empty for rules such as skills, where the fix is structural. pointer is a JSON Pointer to the field to change in your request body, such as /problem/jobs/8/pickup_load.

Errors lists every category and reason code with what to check for each. Tasks that were routed carry no explanation. See Explainable AI for worked examples.

Performance impact

The solver checks only the rules your request uses, so a plain capacity problem is the fastest kind to search. Each additional kind of rule (time windows, skills, relations, shipments, breaks) adds work to every candidate move, which means fewer moves explored in the same options.time_limit_s. Send the rules your operation needs and leave out the ones it does not. See the Performance guide for the other levers.

Best practices

Use a hard rule for anything that must always hold. Capacity, skills, eligibility and limits belong in their own fields, not in a large cost.
Pick the narrowest lateness lever. Soften one task’s single window with time_windows[].per_late_hour, soften all windows with objective.per_late_hour, and use target for a deadline that must never make a task unassignable.
Make a task optional with drop_cost. Tasks are required by default.
Rank required tasks with priority. When not every required task fits, the solver keeps the higher-priority ones. See Objective function.
Read unassigned[] before tuning costs. Cost rates do not rescue a task that a hard rule blocks; category, reasons and relaxations tell you what does.
Relate a shipment through its legs. A shipment’s own id in a relation is rejected with HTTP 400 not_supported (all_or_none over a consecutive chain is the exception); name {shipment}:pickup or {shipment}:delivery instead. To tie a shipment to a vehicle, set eligible_vehicles on the shipment.

Fields are validated strictly: an unknown or misspelled field, and contradictory combinations such as priority together with drop_cost on one task, are rejected with HTTP 400 and a message describing the problem. See Errors.

Constraints

Every constraint field, with the JSON to send

Objective function

How plans are compared, priority, and the cost model

Explainable AI

Worked examples of the unassigned[] diagnosis

Performance guide

How problem size and constraint choice affect solve time

Platform

Routing API

Hard and soft

Hard constraints

Capacity

Time windows

Relations

Soft constraints

From constraints to the objective

Why a task is left unassigned

Performance impact

Best practices

Constraints

Objective function

Explainable AI

Performance guide

​Hard and soft

​Hard constraints

​Capacity

​Time windows

​Relations

​Soft constraints

​From constraints to the objective

​Why a task is left unassigned

​Performance impact

​Best practices

​Related topics

Constraints

Objective function

Explainable AI

Performance guide

Hard and soft

Hard constraints

Capacity

Time windows

Relations

Soft constraints

From constraints to the objective

Why a task is left unassigned

Performance impact

Best practices

Related topics