> ## Documentation Index
> Fetch the complete documentation index at: https://developers.kardinal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cold-chain last-mile

> Cold-chain example: a reconfigurable refrigerated compartment, trusted-keychain deliveries, zone preference, and predictive traffic on one refrigerated network.

A cold-chain last-mile operation delivers ambient and frozen goods from the same truck, often with a subset of stops (secure lockers, gated buildings) that only a driver holding the right key can serve. Traffic in the delivery area is predictable enough to forecast, and drivers still tend to work their usual sector day to day.

## What makes this vertical distinctive

* **Reconfigurable cold compartment** — a truck's compartment runs in ambient or frozen mode, one at a time: it never carries both loads at once, and can switch modes once the previous load is delivered.
* **Trusted-keychain deliveries** — a set of key-gated stops is kept to a single driver for the day, not split across whoever has room.
* **Preferred zones** — drivers are softly tied to their usual sector, pulled elsewhere only once it's covered.
* **Predictive traffic** — forecast travel time is baked into the route calculation itself.

## Combined example

```json theme={null}
{
  "tz": "Europe/Paris",
  "resources": [
    {
      "id": "truck-1",
      "vehicleProfile": { "type": "truck", "withTraffic": true },
      "capacities": { "weight": 1200, "ambiant": 400, "frozen": 250 },
      "preferredStopTags": ["zone:usual-sector-7"],
      "tags": ["driver", "bi-temperature"]
    },
    {
      "id": "driver-1",
      "vehicleProfile": { "type": "truck" },
      "capacities": { "ambiant": 400, "frozen": 250 },
      "tags": ["driver", "bi-temperature"]
    }
  ],
  "orders": [
    {
      "id": "order-ambient",
      "stops": [
        { "type": "single", "id": "stop-pickup-ambient", "position": { "lon": 2.295, "lat": 48.872 }, "kind": "pickup", "operationDuration": "PT5M", "capacities": { "ambiant": 40 } },
        { "type": "single", "id": "stop-ambient", "position": { "lon": 2.31, "lat": 48.882 }, "kind": "delivery", "operationDuration": "PT6M", "capacities": { "ambiant": 40 } }
      ]
    },
    {
      "id": "order-frozen",
      "stops": [
        { "type": "single", "id": "stop-pickup-frozen", "position": { "lon": 2.295, "lat": 48.872 }, "kind": "pickup", "operationDuration": "PT5M", "capacities": { "frozen": 20 } },
        { "type": "single", "id": "stop-frozen", "position": { "lon": 2.305, "lat": 48.854 }, "kind": "delivery", "operationDuration": "PT6M", "capacities": { "frozen": 20 } }
      ]
    },
    {
      "id": "order-afternoon-delivery",
      "stops": [
        {
          "type": "single",
          "id": "stop-afternoon-delivery",
          "position": { "lon": 2.32, "lat": 48.867 },
          "kind": "delivery",
          "operationDuration": "PT8M",
          "capacities": { "ambiant": 10 },
          "tags": ["zone:usual-sector-7"]
        }
      ]
    },
    {
      "id": "order-keychain-0",
      "stops": [
        {
          "type": "single",
          "id": "stop-keychain-0",
          "position": { "lon": 2.31, "lat": 48.882 },
          "kind": "delivery",
          "operationDuration": "PT5M",
          "tags": ["keychain:trusted-set-1"],
          "authorizedTimeWindows": [{ "begin": "2026-08-03 06:30", "end": "2026-08-03 08:00" }]
        }
      ]
    },
    {
      "id": "order-keychain-1",
      "stops": [
        {
          "type": "single",
          "id": "stop-keychain-1",
          "position": { "lon": 2.275, "lat": 48.88 },
          "kind": "delivery",
          "operationDuration": "PT5M",
          "tags": ["keychain:trusted-set-1"],
          "authorizedTimeWindows": [{ "begin": "2026-08-03 06:30", "end": "2026-08-03 08:00" }]
        }
      ]
    }
  ],
  "additionalConstraints": [
    {
      "type": "atLeastOneValidCapacity",
      "capacities": { "frozen": 0, "ambiant": 0 },
      "name": "bi-temperature-single-mode-at-a-time",
      "resourceTags": ["bi-temperature"]
    }
  ],
  "globalConstraints": [
    {
      "type": "maxCumulatedCost",
      "maximum": 1,
      "costsByResourceTag": {
        "driver": {
          "costsByStopTag": { "keychain:trusted-set-1": { "costFloor": 0, "costCoeff": 1, "overcostFloor": 1, "overcostCoeff": 0 } }
        }
      },
      "name": "one-driver-per-key-set"
    }
  ]
}
```

### Reconfigurable cold compartment

`truck-1.capacities` and `driver-1.capacities` both carry `ambiant` and `frozen` as two independent dimensions. An `atLeastOneValidCapacity` constraint scoped to `bi-temperature`-tagged resources requires at least one of the two to stay at zero at every stop: at any point of its tour, each truck carries only ambient or only frozen goods, never a mix, and it can switch from one to the other once the previous load is delivered. The tag decides which resources the rule covers: a resource without the `bi-temperature` tag is outside the rule and can carry both at once. The declared capacities only set how much of each kind a truck can carry, and a resource that doesn't declare a capacity has no limit on it, which is why every truck in this example declares both. This is a related but distinct pattern from [Multi-compartment vehicles](/guides/advanced-constraints#multi-compartment-vehicles): that guide's `atLeastOneConstraint` picks one whole setup for the entire tour, while this gate is checked stop by stop through an ordinary `capacities` mutual-exclusion.

### Trusted-keychain deliveries

`order-keychain-0`/`-1` share the tag `keychain:trusted-set-1`. A `globalConstraints` entry of type `maxCumulatedCost` gives every `driver`-tagged resource a cost on the stops of that set: `costCoeff: 1` counts each keychain stop the resource visits, and `overcostFloor: 1` with `overcostCoeff: 0` stops the count after the first one. Each driver therefore costs 1 as soon as it takes a keychain stop, and `maximum: 1` across the whole fleet leaves room for a single driver on the set. Every resource in this example carries `driver`, because the constraint only counts resources with the tag it targets and a wildcard isn't accepted. If no single driver can reach every stop of the set in time, the extra stops stay unplanned, in `unaffectedStopIds`, rather than going to a second driver (see [Handling infeasibility](/guides/handling-infeasibility)). See [Constraints catalog](/reference/data-model#constraints-catalog).

### Preferred zones

`truck-1.preferredStopTags: ["zone:usual-sector-7"]` is matched against the same tag on `stop-afternoon-delivery` — a soft pull toward the truck's usual sector, scored through `maximizePreferredStops` rather than enforced as a hard rule. It's the same `preferredStopTags` mechanism [Driver skills and qualifications](/guides/advanced-constraints#driver-skills-and-qualifications) documents for a skill preference, applied here to a zone instead.

### Predictive traffic

`truck-1.vehicleProfile.withTraffic: true` makes the engine use forecast travel times for this truck's legs rather than free-flow distances.

## Full payload

> **Full payload — ready to submit as POST /plans**
>
> The preceding example isolates the four mechanisms this vertical needs; this expands it to the scale of a real working day — a full fleet schedule (`workingTimeWindow`, `departure`, `arrival`), the complete `objectives` list, and enough orders to look like an actual route rather than a minimal illustration. Submit it as-is via [`POST /plans`](/api-reference/plan/create-a-plan) — the service assigns the plan's `id`, so don't include one of your own. Its datetimes are local times, read in the plan's `tz` (`Europe/Paris`); see [Dates and time zones](/reference/data-model#dates-and-time-zones).
>
> ```json theme={null}
> {
>   "tz": "Europe/Paris",
>   "resources": [
>     {
>       "id": "truck-1",
>       "vehicleProfile": { "type": "truck", "withTraffic": true },
>       "workingTimeWindow": { "begin": "2026-08-03 05:00", "end": "2026-08-03 20:00" },
>       "departure": { "lon": 2.295, "lat": 48.872 },
>       "arrival": { "lon": 2.295, "lat": 48.872 },
>       "capacities": { "weight": 1200, "pallets": 12, "ambiant": 400, "frozen": 250 },
>       "preferredStopTags": ["zone:usual-sector-7"],
>       "tags": ["driver", "bi-temperature"],
>       "breaks": [{ "type": "workingDurationSlidingBreak", "minBreakDuration": "PT30M", "maxInterBreakDuration": "PT6H" }],
>       "maxWorkingDuration": "PT9H",
>       "cost": { "workedHours": { "costFloor": 8, "costCoeff": 1, "overcostFloor": 10, "overcostCoeff": 1.25 } }
>     },
>     {
>       "id": "driver-1",
>       "vehicleProfile": { "type": "truck" },
>       "workingTimeWindow": { "begin": "2026-08-03 07:00", "end": "2026-08-03 17:00" },
>       "departure": { "lon": 2.295, "lat": 48.872 },
>       "arrival": { "lon": 2.295, "lat": 48.872 },
>       "capacities": { "ambiant": 400, "frozen": 250 },
>       "tags": ["driver", "bi-temperature"]
>     },
>     {
>       "id": "driver-2",
>       "vehicleProfile": { "type": "truck" },
>       "workingTimeWindow": { "begin": "2026-08-03 07:00", "end": "2026-08-03 17:00" },
>       "departure": { "lon": 2.295, "lat": 48.872 },
>       "arrival": { "lon": 2.295, "lat": 48.872 },
>       "capacities": { "ambiant": 400, "frozen": 250 },
>       "tags": ["driver", "bi-temperature"]
>     }
>   ],
>   "orders": [
>     {
>       "id": "order-ambient",
>       "stops": [
>         { "type": "single", "id": "stop-pickup-ambient", "position": { "lon": 2.295, "lat": 48.872 }, "kind": "pickup", "operationDuration": "PT5M", "capacities": { "ambiant": 40 } },
>         { "type": "single", "id": "stop-ambient", "position": { "lon": 2.31, "lat": 48.882 }, "kind": "delivery", "operationDuration": "PT6M", "capacities": { "ambiant": 40 } }
>       ]
>     },
>     {
>       "id": "order-chilled",
>       "stops": [
>         { "type": "single", "id": "stop-pickup-chilled", "position": { "lon": 2.295, "lat": 48.872 }, "kind": "pickup", "operationDuration": "PT5M", "capacities": { "frozen": 30 } },
>         { "type": "single", "id": "stop-chilled", "position": { "lon": 2.275, "lat": 48.88 }, "kind": "delivery", "operationDuration": "PT6M", "capacities": { "frozen": 30 } }
>       ]
>     },
>     {
>       "id": "order-frozen",
>       "stops": [
>         { "type": "single", "id": "stop-pickup-frozen", "position": { "lon": 2.295, "lat": 48.872 }, "kind": "pickup", "operationDuration": "PT5M", "capacities": { "frozen": 20 } },
>         { "type": "single", "id": "stop-frozen", "position": { "lon": 2.305, "lat": 48.854 }, "kind": "delivery", "operationDuration": "PT6M", "capacities": { "frozen": 20 } }
>       ]
>     },
>     {
>       "id": "order-afternoon-0",
>       "stops": [
>         { "type": "single", "id": "stop-pickup-afternoon-0", "position": { "lon": 2.295, "lat": 48.872 }, "kind": "pickup", "operationDuration": "PT5M", "capacities": { "pallets": 1 } },
>         {
>           "type": "single",
>           "id": "stop-afternoon-0",
>           "position": { "lon": 2.32, "lat": 48.867 },
>           "kind": "delivery",
>           "operationDuration": "PT8M",
>           "capacities": { "pallets": 1 },
>           "tags": ["zone:usual-sector-7"],
>           "authorizedTimeWindows": [{ "begin": "2026-08-03 08:00", "end": "2026-08-03 18:00" }],
>           "preferredTimeWindows": [{ "begin": "2026-08-03 14:00", "end": "2026-08-03 16:00" }]
>         }
>       ]
>     },
>     {
>       "id": "order-afternoon-1",
>       "stops": [
>         { "type": "single", "id": "stop-pickup-afternoon-1", "position": { "lon": 2.295, "lat": 48.872 }, "kind": "pickup", "operationDuration": "PT5M", "capacities": { "pallets": 1 } },
>         { "type": "single", "id": "stop-afternoon-1", "position": { "lon": 2.265, "lat": 48.887 }, "kind": "delivery", "operationDuration": "PT8M", "capacities": { "pallets": 1 }, "tags": ["zone:usual-sector-7"] }
>       ]
>     },
>     {
>       "id": "order-afternoon-2",
>       "stops": [
>         { "type": "single", "id": "stop-pickup-afternoon-2", "position": { "lon": 2.295, "lat": 48.872 }, "kind": "pickup", "operationDuration": "PT5M", "capacities": { "pallets": 1 } },
>         { "type": "single", "id": "stop-afternoon-2", "position": { "lon": 2.3, "lat": 48.894 }, "kind": "delivery", "operationDuration": "PT8M", "capacities": { "pallets": 1 }, "tags": ["zone:overflow"] }
>       ]
>     },
>     {
>       "id": "order-keychain-0",
>       "stops": [
>         {
>           "type": "single",
>           "id": "stop-keychain-0",
>           "position": { "lon": 2.31, "lat": 48.882 },
>           "kind": "delivery",
>           "operationDuration": "PT5M",
>           "tags": ["keychain:trusted-set-1"],
>           "authorizedTimeWindows": [{ "begin": "2026-08-03 06:30", "end": "2026-08-03 08:00" }]
>         }
>       ]
>     },
>     {
>       "id": "order-keychain-1",
>       "stops": [
>         {
>           "type": "single",
>           "id": "stop-keychain-1",
>           "position": { "lon": 2.275, "lat": 48.88 },
>           "kind": "delivery",
>           "operationDuration": "PT5M",
>           "tags": ["keychain:trusted-set-1"],
>           "authorizedTimeWindows": [{ "begin": "2026-08-03 06:30", "end": "2026-08-03 08:00" }]
>         }
>       ]
>     },
>     {
>       "id": "order-keychain-2",
>       "stops": [
>         {
>           "type": "single",
>           "id": "stop-keychain-2",
>           "position": { "lon": 2.305, "lat": 48.854 },
>           "kind": "delivery",
>           "operationDuration": "PT5M",
>           "tags": ["keychain:trusted-set-1"],
>           "authorizedTimeWindows": [{ "begin": "2026-08-03 06:30", "end": "2026-08-03 08:00" }]
>         }
>       ]
>     }
>   ],
>   "objectives": ["maximizeMandatoryStops", "minimizeResources", "minimizeLargestTourDuration", "minimizeCosts", "maximizePreferredStops", "minimizeDelay", "minimizeWorkingDuration", "minimizeDistance"],
>   "additionalConstraints": [
>     { "type": "atLeastOneValidCapacity", "capacities": { "frozen": 0, "ambiant": 0 }, "name": "bi-temperature-single-mode-at-a-time", "resourceTags": ["bi-temperature"] }
>   ],
>   "globalConstraints": [
>     {
>       "type": "maxCumulatedCost",
>       "maximum": 1,
>       "costsByResourceTag": { "driver": { "costsByStopTag": { "keychain:trusted-set-1": { "costFloor": 0, "costCoeff": 1, "overcostFloor": 1, "overcostCoeff": 0 } } } },
>       "name": "one-driver-per-key-set"
>     }
>   ]
> }
> ```

## See also

* [Modeling advanced constraints](/guides/advanced-constraints#multi-compartment-vehicles) — the related whole-tour compartment-setup pattern.
* [Modeling advanced constraints](/guides/advanced-constraints#driver-skills-and-qualifications) — `preferredStopTags`, the soft mechanism behind zone preference.
* [Data model](/reference/data-model#constraints-catalog) — the full `additionalConstraints` and `globalConstraints` catalog.

Ready to model an operation like this one? [Send your first API call](/getting-started/first-api-call) with your own data, or contact [customer.success@kardinal.ai](mailto:customer.success@kardinal.ai) to walk through your specific constraints.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.