Orders and sequences

A stop is one visit, at one position. An order groups stops that belong together. A pickup and its delivery are an example. The engine plans all the stops of an order on one resource. A resource is a vehicle with its driver. A tour is the route of one resource, from its start to its end. In the solution, a tour is a list of waypoints, and a waypoint is one line of that list. This guide covers the links between stops. Each section describes one link between stops, with a link to the API reference where the exact behavior is written. The last section shows how to check the solution. These snippets use local times where they have times. The plan you put them in needs "tz". See Dates and time zones.

Stops of one order

The stops array of an order is a sequence. The engine plans these stops on one resource, in the order of the array. A pickup then a delivery in one order carry the same goods. The resource loads them at the first stop and unloads them at the second.

{
  "id": "order-1",
  "stops": [
    { "type": "single", "id": "pickup-1", "kind": "pickup", "position": { "lon": 2.364, "lat": 48.85 }, "operationDuration": "PT5M" },
    { "type": "single", "id": "delivery-1", "kind": "delivery", "position": { "lon": 2.487, "lat": 48.85 }, "operationDuration": "PT5M" }
  ]
}

The rules are these:

One vehicle, array order. In the sandbox, an order with a far stop and then a near stop was planned in that order. The same two stops in two separate orders were planned near first. With two vans 20 km apart, an order with one stop near each van went to a single van.
All stops or none. If one stop of an order can’t be served, the engine leaves the whole order out. The stop that fits is not planned alone. In the sandbox, an order with a second stop that opened after the working day of the van went to unaffectedStopIds with both stops, and the solution gave no violation.
A limit of 4 stops by default. An order without successiveStops can have at most 4 stops. In the sandbox, an order with 5 stops was refused with a 403 error. See Limits and quotas for the error and for how to raise the limit.

See Order for the rule, and Order, stop for the loads of a pickup and a delivery.

Optional orders

An order with optional: true is one that the engine can leave out. It leaves the maximizeMandatoryStops objective, so leaving it out costs nothing there. Without maximizeOptionalStops in the objectives, the engine has no reason to plan it, so it is unlikely to be planned. The default list of objectives contains maximizeOptionalStops.

{ "id": "order-bonus", "optional": true, "stops": [ ... ] }

If you write your own objectives list, add maximizeOptionalStops yourself. In the sandbox, a plan with one mandatory and one optional order planned both with the default list. With a list that left out maximizeOptionalStops, the optional stop went to unaffectedStopIds. See maximizeOptionalStops for the objective. An optional order is not the same as an order with a low priority. A mandatory order, however low its priority, still counts in maximizeMandatoryStops. See Order.optional for the rule.

Stops back to back

successiveStops: true keeps the stops of one order consecutive. The vehicle visits them one after the other, with no stop of another order in between. Without it, the engine can interleave the stops of two orders.

{ "id": "order-1", "successiveStops": true, "stops": [ ... ] }

In the sandbox, two orders each had a pickup near the depot and a delivery far from it. Without successiveStops, the engine planned both pickups, then both deliveries. With successiveStops on both orders, it planned the first pickup and its delivery, then the second pair. The flag applies to each order on its own. With the flag on one order only, that order stayed consecutive and the other order was planned around it. A tour that breaks the rule reports a violation of type successiveStops. The API reference calls successiveStops and maxStopSpan mutually exclusive, so use one or the other on an order. The API doesn’t refuse a plan that sets both. See Order.successiveStops for the rule.

Time from first to last stop

maxStopSpan limits the time that an order takes, without forcing its stops to be consecutive. It is a duration such as PT4H. The span runs from the end of service at the first stop of the order to the start of service at its last stop. Waiting time counts.

{ "id": "order-1", "maxStopSpan": "PT4H", "stops": [ ... ] }

The span covers the whole order, not each pair of stops. In the sandbox, an order had stops at about 08:01, 10:00 and 12:00. A span of 2 h 30 left the order out, although each gap was under 2 hours. A span of 4 h 30 planned it. Another test gave the first stop a service of 60 minutes. It showed that the span starts at the end of that service, not at its start. The engine doesn’t delay the first stop to make the order fit the span. In the sandbox and in production, an order had a pickup window from 08:00 to 12:00, a delivery at 12:00 and a span of 1 hour. The engine left the order out, although the pickup could have waited until 11:00. The solution gave no violation. In the sandbox, with a pickup window from 11:00 to 12:00 and the same span of 1 hour, the order was planned. The van waited until 11:00. So you need to narrow the window of the first stop yourself. See Order.maxStopSpan for the rule.

One site among several

An AlternativesStop is a stop with several candidates. A candidate is a single stop. The engine serves exactly one candidate when it plans the order. A waste collection with several disposal sites is an example. The engine picks the site that fits the tour.

{
  "id": "order-3",
  "stops": [
    { "type": "single", "id": "collect-3", "kind": "pickup", "position": { "lon": 2.309, "lat": 48.85 }, "operationDuration": "PT5M" },
    {
      "type": "alternatives",
      "id": "drop-site",
      "alternatives": [
        { "type": "single", "id": "drop-far", "kind": "delivery", "position": { "lon": 2.145, "lat": 48.85 }, "operationDuration": "PT5M" },
        { "type": "single", "id": "drop-near", "kind": "delivery", "position": { "lon": 2.282, "lat": 48.85 }, "operationDuration": "PT5M" }
      ]
    }
  ]
}

The rules are these:

One candidate is served. In the sandbox, an order with three candidate sites planned the nearest one. When the nearest site was closed, the engine planned another candidate. An order made only of an alternatives group was planned too.
All candidates have the same kind. A candidate without kind counts as a delivery. A group that mixes kinds is refused with a 400 error.
The tour names the candidate, never the group. A waypoint carries the id of the chosen candidate, here drop-near. The id of the group, here drop-site, appears nowhere in the solution.
The other candidates are listed apart. The candidates that were not chosen are in unaffectedAlternativeIds, not in unaffectedStopIds.
If no candidate fits, the whole order is left out. The id of one candidate appears in unaffectedStopIds, and the ids of the others appear in unaffectedAlternativeIds. The API reference doesn’t say which candidate goes in which list. Don’t write code that depends on it.

An AlternativesStop can switch the engine to a slower algorithm. See Sizing maxOptimizationDuration for a large problem. Use it for a choice between sites. If you only want a stop that the engine can leave out, use an optional order. This guide shows no “only if needed” pattern, such as a stop that the vehicle visits only if it doesn’t already carry an item. A group that mixes kinds is refused, and a candidate with no kind counts as a delivery. See AlternativesStop for the rule. The Waste collection case study uses a group of three disposal sites.

Same vehicle in any order

An order with several stops already keeps them on one vehicle, but in the order of the array. Sometimes you need the opposite: a set of stops that must share one vehicle, while the vehicle picks the best order. A set of key-gated deliveries is the usual case, or the stops of one customer that a single driver should handle. A maxCumulatedCost entry in globalConstraints does this. It counts how many vehicles serve the set, and it allows one. The plan below has two vans tagged driver, and three orders with one stop each, all tagged keyset-1. Two stops are close to van-1 and one is close to van-2, so without the cap the stops would be split between the two vans. The plan carries "tz" because it is a whole plan, and it can be sent as it is to POST /plans.

{
  "tz": "Europe/Paris",
  "resources": [
    {
      "id": "van-1",
      "vehicleProfile": {
        "type": "car"
      },
      "workingTimeWindow": {
        "begin": "2026-10-22 06:00",
        "end": "2026-10-22 20:00"
      },
      "departure": {
        "lon": 2.35,
        "lat": 48.85
      },
      "arrival": {
        "lon": 2.35,
        "lat": 48.85
      },
      "tags": [
        "driver"
      ]
    },
    {
      "id": "van-2",
      "vehicleProfile": {
        "type": "car"
      },
      "workingTimeWindow": {
        "begin": "2026-10-22 06:00",
        "end": "2026-10-22 20:00"
      },
      "departure": {
        "lon": 2.55,
        "lat": 48.95
      },
      "arrival": {
        "lon": 2.55,
        "lat": 48.95
      },
      "tags": [
        "driver"
      ]
    }
  ],
  "orders": [
    {
      "id": "order-1",
      "stops": [
        {
          "type": "single",
          "id": "stop-1",
          "position": {
            "lon": 2.36,
            "lat": 48.86
          },
          "kind": "delivery",
          "operationDuration": "PT10M",
          "tags": [
            "keyset-1"
          ]
        }
      ]
    },
    {
      "id": "order-2",
      "stops": [
        {
          "type": "single",
          "id": "stop-2",
          "position": {
            "lon": 2.364,
            "lat": 48.862
          },
          "kind": "delivery",
          "operationDuration": "PT10M",
          "tags": [
            "keyset-1"
          ]
        }
      ]
    },
    {
      "id": "order-3",
      "stops": [
        {
          "type": "single",
          "id": "stop-3",
          "position": {
            "lon": 2.55,
            "lat": 48.96
          },
          "kind": "delivery",
          "operationDuration": "PT10M",
          "tags": [
            "keyset-1"
          ]
        }
      ]
    }
  ],
  "globalConstraints": [
    {
      "type": "maxCumulatedCost",
      "name": "one-vehicle-per-keyset-1",
      "maximum": 1,
      "costsByResourceTag": {
        "driver": {
          "costsByStopTag": {
            "keyset-1": {
              "costFloor": 0,
              "costCoeff": 1,
              "overcostFloor": 1,
              "overcostCoeff": 0
            }
          }
        }
      }
    }
  ],
  "objectives": [
    "maximizeMandatoryStops",
    "minimizeDistance"
  ]
}

Here is how to read the maxCumulatedCost entry. costCoeff: 1 counts one for each stop of the set that a vehicle visits. overcostFloor: 1 with overcostCoeff: 0 stops the count at 1, so a vehicle that takes one stop of the set costs 1, and a vehicle that takes all three also costs 1. Each vehicle that takes at least one stop of the set therefore costs 1, and maximum: 1 across the fleet leaves room for one vehicle only. On the sandbox, this plan puts all three stops on one van and leaves unaffectedStopIds empty. The same plan without the globalConstraints entry splits the set across both vans. A few traps are worth knowing before you use this pattern:

Every resource that may serve the set must carry the tag in costsByResourceTag, here driver. The cap only counts resources that carry the tag, and the wildcard "*" is refused. A resource without the tag could take stops of the set freely.
Write one entry per set, and give each set its own stop tag. Two sets that share a tag would be counted as one set.
If no single vehicle can serve the whole set, for example because of time windows or capacity, the extra stops are not given to a second vehicle. They stay in unaffectedStopIds, and globalViolations stays empty. See Capping a fleet-wide cost with maxCumulatedCost and Handling infeasibility.
A vehicle that does several trips can serve the set across its trips. See Multi-trip tours.

In the sandbox, a plan with twenty sets of three stops, each set with its own entry, planned every stop. No set was split. The same plan without the entries split all twenty sets across the two vans. For this pattern in a full plan, see the “Trusted-keychain deliveries” sections of Retail last-mile and Cold-chain last-mile.

Preferred order between orders

Between two different orders, the engine has no hard precedence. The stops of two orders can come in any order, and on different vehicles. If you want a preference, tag the stops and add the maximizePrecedences objective with pairs of tags.

"objectives": [
  "maximizeMandatoryStops",
  { "type": "maximizePrecedences", "precedences": [{ "previous": "first", "next": "then" }] },
  "minimizeDistance"
]

In the sandbox, a stop tagged first was 8 km from the depot, and a stop tagged then was 2 km away. Without the objective, the engine planned the near stop first. With the objective, it planned the stop tagged first first. This is a preference, not a rule: the engine can break a pair. See maximizePrecedences for the objective and its limits. For a rule that the engine always keeps, put the stops in one order. To fix a sequence yourself, see fixed assignments.

Checking the solution

The engine plans the stops that fit, and it lists the others. A stop that the engine can’t serve is not an error. These fields of the solution help:

tours holds the waypoints. A stop that the engine planned appears there with its own id.
unaffectedStopIds lists the stops that the engine left out.
unaffectedAlternativeIds lists the candidates of an AlternativesStop that were not chosen.
The violations of a tour name the hard rules that the tour breaks. A stop that the engine dropped doesn’t appear there.

So a stop id that you sent can be in a tour, in unaffectedStopIds, or in unaffectedAlternativeIds. The id of an alternatives group is in none of them. Check each of the three lists. A candidate in unaffectedAlternativeIds is not a lost stop.

Example plan

This plan has one van and three orders. The first two orders are a pickup then a delivery, with successiveStops: true. The third order is a collection, then an AlternativesStop with two drop sites. All the candidates are deliveries. Every stop is open all day, so the order of the stops doesn’t depend on road times.

{
  "tz": "Europe/Paris",
  "maxOptimizationDuration": "PT5S",
  "resources": [
    {
      "id": "van-1",
      "vehicleProfile": { "type": "car" },
      "workingTimeWindow": { "begin": "2026-11-03 08:00", "end": "2026-11-03 18:00" },
      "departure": { "lon": 2.35, "lat": 48.85 },
      "arrival": { "lon": 2.35, "lat": 48.85 }
    }
  ],
  "orders": [
    {
      "id": "order-1",
      "successiveStops": true,
      "stops": [
        { "type": "single", "id": "pickup-1", "kind": "pickup", "position": { "lon": 2.364, "lat": 48.85 }, "operationDuration": "PT5M" },
        { "type": "single", "id": "delivery-1", "kind": "delivery", "position": { "lon": 2.487, "lat": 48.85 }, "operationDuration": "PT5M" }
      ]
    },
    {
      "id": "order-2",
      "successiveStops": true,
      "stops": [
        { "type": "single", "id": "pickup-2", "kind": "pickup", "position": { "lon": 2.378, "lat": 48.85 }, "operationDuration": "PT5M" },
        { "type": "single", "id": "delivery-2", "kind": "delivery", "position": { "lon": 2.501, "lat": 48.85 }, "operationDuration": "PT5M" }
      ]
    },
    {
      "id": "order-3",
      "stops": [
        { "type": "single", "id": "collect-3", "kind": "pickup", "position": { "lon": 2.309, "lat": 48.85 }, "operationDuration": "PT5M" },
        {
          "type": "alternatives",
          "id": "drop-site",
          "alternatives": [
            { "type": "single", "id": "drop-far", "kind": "delivery", "position": { "lon": 2.145, "lat": 48.85 }, "operationDuration": "PT5M" },
            { "type": "single", "id": "drop-near", "kind": "delivery", "position": { "lon": 2.282, "lat": 48.85 }, "operationDuration": "PT5M" }
          ]
        }
      ]
    }
  ]
}

The same plan with the SDKs:

from kardinal.routing import models
from kardinal.routing.plans import Order, PlanCreate

depot = models.Position(lon=2.35, lat=48.85)


def stop(stop_id, kind, lon):
    return models.SingleStop(
        type="single",
        id=stop_id,
        kind=kind,
        position=models.Position(lon=lon, lat=48.85),
        operationDuration="PT5M",
    )


van = models.Resource(
    id="van-1",
    vehicleProfile=models.VehicleProfileCar(type="car"),
    workingTimeWindow=models.TimeWindow(begin="2026-11-03 08:00", end="2026-11-03 18:00"),
    departure=depot,
    arrival=depot,
)

drop_site = models.AlternativesStop(
    type="alternatives",
    id="drop-site",
    alternatives=[stop("drop-far", "delivery", 2.145), stop("drop-near", "delivery", 2.282)],
)

plan = PlanCreate(
    tz="Europe/Paris",
    maxOptimizationDuration="PT5S",
    resources=[van],
    orders=[
        Order(
            id="order-1",
            successiveStops=True,
            stops=[stop("pickup-1", "pickup", 2.364), stop("delivery-1", "delivery", 2.487)],
        ),
        Order(
            id="order-2",
            successiveStops=True,
            stops=[stop("pickup-2", "pickup", 2.378), stop("delivery-2", "delivery", 2.501)],
        ),
        Order(id="order-3", stops=[stop("collect-3", "pickup", 2.309), drop_site]),
    ],
)

import type { PlanCreateInput } from "@kardinal-ai/sdk";

const depot = { lon: 2.35, lat: 48.85 };

function stop(id: string, kind: "pickup" | "delivery", lon: number) {
  return {
    type: "single" as const,
    id,
    kind,
    position: { lon, lat: 48.85 },
    operationDuration: "PT5M",
  };
}

const plan: PlanCreateInput = {
  tz: "Europe/Paris",
  maxOptimizationDuration: "PT5S",
  resources: [
    {
      id: "van-1",
      priority: 0,
      vehicleProfile: { type: "car" },
      workingTimeWindow: { begin: "2026-11-03 08:00", end: "2026-11-03 18:00" },
      departure: depot,
      arrival: depot,
    },
  ],
  orders: [
    {
      id: "order-1",
      priority: 0,
      successiveStops: true,
      stops: [stop("pickup-1", "pickup", 2.364), stop("delivery-1", "delivery", 2.487)],
    },
    {
      id: "order-2",
      priority: 0,
      successiveStops: true,
      stops: [stop("pickup-2", "pickup", 2.378), stop("delivery-2", "delivery", 2.501)],
    },
    {
      id: "order-3",
      priority: 0,
      stops: [
        stop("collect-3", "pickup", 2.309),
        {
          type: "alternatives",
          id: "drop-site",
          alternatives: [stop("drop-far", "delivery", 2.145), stop("drop-near", "delivery", 2.282)],
        },
      ],
    },
  ],
};

What the solution shows

The sandbox returns this for the plan, with the offset of Europe/Paris and with seconds. Only the fields that matter here are kept. The times come from the sandbox and depend on its routing. The order of the stops is the same in production.

{
  "unaffectedStopIds": [],
  "unaffectedAlternativeIds": ["drop-far"],
  "tours": [
    {
      "resourceId": "van-1",
      "isValid": true,
      "wayPoints": [
        { "type": "begin", "departureTime": "2026-11-03T08:00:00+01:00" },
        { "type": "stop", "stopId": "collect-3", "arrivalTime": "2026-11-03T08:03:36+01:00", "departureTime": "2026-11-03T08:08:36+01:00" },
        { "type": "stop", "stopId": "drop-near", "arrivalTime": "2026-11-03T08:10:58+01:00", "departureTime": "2026-11-03T08:15:58+01:00" },
        { "type": "stop", "stopId": "pickup-1", "arrivalTime": "2026-11-03T08:23:10+01:00", "departureTime": "2026-11-03T08:28:10+01:00" },
        { "type": "stop", "stopId": "delivery-1", "arrivalTime": "2026-11-03T08:38:58+01:00", "departureTime": "2026-11-03T08:43:58+01:00" },
        { "type": "stop", "stopId": "pickup-2", "arrivalTime": "2026-11-03T08:53:32+01:00", "departureTime": "2026-11-03T08:58:32+01:00" },
        { "type": "stop", "stopId": "delivery-2", "arrivalTime": "2026-11-03T09:09:20+01:00", "departureTime": "2026-11-03T09:14:20+01:00" },
        { "type": "end", "arrivalTime": "2026-11-03T09:27:36+01:00" }
      ]
    }
  ]
}

Each order with successiveStops is visited as a pair: pickup-1 and delivery-1, then pickup-2 and delivery-2.
The same plan without successiveStops gave another sequence in the sandbox: pickup-1, pickup-2, delivery-2, delivery-1. So the flag changed the plan.
The tour names drop-near, the chosen candidate. The group id drop-site appears nowhere.
drop-far is in unaffectedAlternativeIds. It is not a lost stop. unaffectedStopIds is empty, because the engine planned every order.

A check in code

This check compares the solution with the plan that you sent. It maps each candidate id to its group, so it can tell a lost order from a candidate that was not chosen. It reports a single stop that is left out, and a group that has no candidate in a tour. It doesn’t report a candidate that is in unaffectedAlternativeIds.

def check_orders(plan, solution):
    """Return one message for each order that the engine did not fully serve."""
    served = {
        waypoint.root.stopId.root
        for tour in solution.tours
        for waypoint in tour.wayPoints
        if waypoint.root.type == "stop"
    }
    left_out = {stop_id.root for stop_id in solution.unaffectedStopIds or []}

    # Map each candidate id to the id of its group.
    group_of = {
        candidate.id.root: stop.id.root
        for order in plan.orders
        for stop in order.stops
        if stop.type == "alternatives"
        for candidate in stop.alternatives
    }
    served_groups = {group_of[stop_id] for stop_id in served if stop_id in group_of}

    problems = []
    for order in plan.orders:
        for stop in order.stops:
            if stop.type == "single" and stop.id.root in left_out:
                problems.append(f"{order.id.root}: {stop.id.root} is left out")
            if stop.type == "alternatives" and stop.id.root not in served_groups:
                problems.append(f"{order.id.root}: no candidate of {stop.id.root} is in a tour")
    return problems

import type { PlanCreateInput, WaitedSolution } from "@kardinal-ai/sdk";

export function checkOrders(plan: PlanCreateInput, solution: WaitedSolution): string[] {
  const served = new Set(
    (solution.tours ?? []).flatMap((tour) =>
      (tour.wayPoints ?? []).filter((w) => w.type === "stop").map((w) => w.stopId),
    ),
  );
  const leftOut = new Set(solution.unaffectedStopIds ?? []);

  // Map each candidate id to the id of its group.
  const groupOf = new Map<string, string>();
  for (const order of plan.orders ?? []) {
    for (const stop of order.stops) {
      if (stop.type !== "alternatives") continue;
      for (const candidate of stop.alternatives) groupOf.set(candidate.id, stop.id);
    }
  }
  const servedGroups = new Set([...served].map((id) => groupOf.get(id ?? "")));

  const problems: string[] = [];
  for (const order of plan.orders ?? []) {
    for (const stop of order.stops) {
      if (stop.type === "single" && leftOut.has(stop.id)) {
        problems.push(`${order.id}: ${stop.id} is left out`);
      }
      if (stop.type === "alternatives" && !servedGroups.has(stop.id)) {
        problems.push(`${order.id}: no candidate of ${stop.id} is in a tour`);
      }
    }
  }
  return problems;
}

On the example plan, the check returns no problem, although drop-far is in unaffectedAlternativeIds. Then look at the violations of each tour. The API reference names the violation types for the order rules: successiveStops, order and maxStopSpan.

Vocabulary mapping

Before modeling

Modeling business rules

Integration

Advanced modeling

Operations

Stops of one order

Optional orders

Stops back to back

Time from first to last stop

One site among several

Same vehicle in any order

Preferred order between orders

Checking the solution

Example plan

What the solution shows

A check in code

​Stops of one order

​Optional orders

​Stops back to back

​Time from first to last stop

​One site among several

​Same vehicle in any order

​Preferred order between orders

​Checking the solution

​Example plan

​What the solution shows

​A check in code

Stops of one order

Optional orders

Stops back to back

Time from first to last stop

One site among several

Same vehicle in any order

Preferred order between orders

Checking the solution

Example plan

What the solution shows

A check in code