How constraints work

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

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.violations 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`, `jobs[].pickup`, `jobs[].delivery`, `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	`skills` on tasks, 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	`locked_vehicle`	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_time_s`	One route’s distance and its whole span (travel, service and waiting) stay within the limit, and no single travel leg takes longer than `max_leg_travel_time_s`.
Stop count	`limits.max_tasks`	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_tasks` stops of the listed jobs.
Relations	`relations[]`	Order within a route, same vehicle, same day, same route, synchronized visits and time lags between jobs. Relations do not constrain shipments (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.

{
  "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": { "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 to each other. It has nine 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_wait_s": 300 },
  { "type": "time_lag", "from": { "stop": "job-7", "on": "end" }, "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.
`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": "end"`, finish) within `max_wait_s` seconds of each other, across vehicles. `max_wait_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` only: at least 2 jobs, each also named by a `synchronized` or `time_lag` relation	Either every member is served or none is. It sets no timing.

An unknown relation type is rejected with HTTP 400.

Relations act on jobs, not on shipments. A shipment id in the stops of a sequence, same_vehicle, same_day or synchronized relation is accepted but not constrained: the request is not rejected, and the relation has no effect on that shipment. The same holds for a shipment that carries the tag of a same_vehicle or same_day relation. Five cases are rejected with HTTP 400: a shipment id in a time_lag, a shipment id in a compatible_vehicles relation, a shipment id in an all_or_none relation, a tag in a tag_order relation that selects a shipment, and a shipment named in or selected by a same_route relation.

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[].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 `objective.costs.per_overtime_hour`	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`)	`other`

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; cost only grades which of a task’s two or more windows is preferred. A non-zero window 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_fee makes a task optional at a price, preferred_date with objective.non_preferred_date_cost steers a task to a day, 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 unserved_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 in two places: fleet-wide rates under objective.costs, and per-vehicle terms under vehicles[].costs.

{
  "problem": {
    "vehicles": [
      {
        "id": "van-1",
        "costs": { "fixed": 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.

{
  "job_id": "job-9",
  "category": "blocked",
  "reasons": [
    {
      "code": "CAPACITY_EXCEEDED",
      "message": "No vehicle has enough remaining capacity to serve this job"
    }
  ],
  "relaxations": [
    {
      "field": "/jobs/job-9/pickup",
      "op": "reduce_demand",
      "amount": 5,
      "unit": "load",
      "suggestion": "Reduce this task's load (its `pickup` or `delivery`) 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_fee and paying it was cheaper than serving the task. search_limit means a worthwhile place exists and the time budget ran out first.
reasons[].code names the rule that blocked the task. One code is reported per task.
relaxations[] gives the smallest change that would have let the task fit, when one number can express it: reduce_demand (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. field names the task by its id, under /jobs/ or /shipments/; it is a label, not a path into your request body.

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_fee. 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.
Do not rely on a relation to constrain a shipment. Relations act on jobs. To tie a shipment to a vehicle, set locked_vehicle or eligible_vehicles on the shipment.

Fields are validated strictly: an unknown or misspelled field, and contradictory combinations such as drop_fee and priority 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