> ## 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.

# Retail last-mile

> Retail example: key-holder-only access windows, blended subcontractor and in-house costs, pre-opening store drops, and trusted-keychain deliveries in one plan.

A retail last-mile network blends an in-house fleet with subcontracted vans, delivers to stores before opening hours as well as to end customers, and routes some access-restricted deliveries (lockers, secure sites) only through drivers who hold the right key.

## What makes this vertical distinctive

* **Key-holder-only access windows** — a locker or secure site opens early only to drivers who hold the key, with a narrower standard window for everyone else.
* **Blended subcontractor/in-house costs** — subcontractors are paid a flat fee covering their first few drops plus a rate per extra stop delivered, in-house drivers a straight per-kilometre rate — one cost model, two structures.
* **Pre-opening store drops** — store deliveries land in an early window before the shop opens, for chains that need it.
* **Trusted-keychain deliveries** — a set of key-gated stops is kept to a single driver for the day.

## Combined example

```json theme={null}
{
  "tz": "Europe/Paris",
  "resources": [
    {
      "id": "driver-key-holder",
      "vehicleProfile": { "type": "car" },
      "capacities": { "stopsDelivered": 12 },
      "tags": ["driver", "key-holder"],
      "cost": { "km": { "costCoeff": 1.2 } }
    },
    {
      "id": "van-subcontractor-a",
      "vehicleProfile": { "type": "car" },
      "capacities": { "stopsDelivered": 12 },
      "tags": ["driver"],
      "maxDistanceInKm": 25,
      "priority": -1,
      "cost": { "costsByCapacity": { "stopsDelivered": { "constantCost": 80, "costFloor": 3, "costCoeff": 15 } } }
    }
  ],
  "orders": [
    {
      "id": "order-locker-site",
      "stops": [
        {
          "type": "single",
          "id": "stop-locker-site",
          "position": { "lon": 2.318, "lat": 48.861 },
          "kind": "delivery",
          "operationDuration": "PT5M",
          "capacities": { "stopsDelivered": 1 },
          "authorizedTimeWindows": [
            { "begin": "2026-08-03 06:00", "end": "2026-08-03 20:00", "resourceTags": ["key-holder"] },
            { "begin": "2026-08-03 09:00", "end": "2026-08-03 17:00" }
          ]
        }
      ]
    },
    {
      "id": "order-store-1",
      "stops": [
        {
          "type": "single",
          "id": "stop-store-1",
          "position": { "lon": 2.335, "lat": 48.897 },
          "kind": "delivery",
          "operationDuration": "PT15M",
          "capacities": { "stopsDelivered": 1 },
          "authorizedTimeWindows": [{ "begin": "2026-08-03 05:00", "end": "2026-08-03 06:45" }]
        }
      ]
    },
    {
      "id": "order-keychain-0",
      "stops": [
        {
          "type": "single",
          "id": "stop-keychain-0",
          "position": { "lon": 2.345, "lat": 48.885 },
          "kind": "delivery",
          "operationDuration": "PT5M",
          "capacities": { "stopsDelivered": 1 },
          "tags": ["keychain:trusted-set-1"],
          "authorizedTimeWindows": [{ "begin": "2026-08-03 06:30", "end": "2026-08-03 08:00" }]
        }
      ]
    }
  ],
  "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"
    }
  ]
}
```

### Early access for key holders

`order-locker-site` carries two `authorizedTimeWindows`: an early one (06:00-20:00) tagged `resourceTags: ["key-holder"]`, and a narrower standard one (09:00-17:00) with no tag. Only `driver-key-holder` can use the early window; every other resource is restricted to the untagged one. See [Restricting a window to specific resources](/guides/advanced-constraints#restricting-a-window-to-specific-resources).

### Blended subcontractor/in-house costs

`driver-key-holder.cost.km.costCoeff: 1.2` charges a straight per-kilometre rate. `van-subcontractor-a.cost` is instead priced per stop delivered, through `costsByCapacity` on a `stopsDelivered` capacity that every stop increments by 1: a flat `constantCost: 80` that covers the first 3 stops (`costFloor: 3`), then `costCoeff: 15` for each stop delivered beyond that. The two resources are priced on different structures, but both roll up into the same `minimizeCosts` objective for a single, comparable plan. See [The `cost` object](/guides/cost-modeling#the-cost-object) and [Piecewise-linear cost functions](/guides/cost-modeling#piecewise-linear-cost-functions).

### Pre-opening store drops

`order-store-1.authorizedTimeWindows` is a single hard window (05:00-06:45), ahead of the store's opening hours at 07:00 — an ordinary `authorizedTimeWindows` use, no different in kind from [Multiple time windows per stop](/guides/advanced-constraints#multiple-time-windows-per-stop), just with one window instead of several. In the full payload below, `van-subcontractor-a` starts its day at 04:30, because a vehicle whose day starts when the window closes can only deliver at the last minute. The window ends at 06:45, not at the 07:00 opening, because a time window limits when the vehicle arrives, not when the unloading ends: its end is the opening time minus the 15-minute unloading.

### Trusted-keychain deliveries

`order-keychain-0` carries 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. The constraint only counts resources that carry the tag it targets, and a wildcard isn't accepted, so the subcontractor vans carry `driver` too: without it, they could take keychain stops freely. 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).

## 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": "driver-key-holder",
>       "vehicleProfile": { "type": "car" },
>       "workingTimeWindow": { "begin": "2026-08-03 07:00", "end": "2026-08-03 17:00" },
>       "departure": { "lon": 2.33, "lat": 48.875 },
>       "arrival": { "lon": 2.33, "lat": 48.875 },
>       "capacities": { "stopsDelivered": 12 },
>       "tags": ["driver", "key-holder", "sector:north"],
>       "cost": { "km": { "costCoeff": 1.2 } }
>     },
>     {
>       "id": "driver-standard",
>       "vehicleProfile": { "type": "car" },
>       "workingTimeWindow": { "begin": "2026-08-03 07:00", "end": "2026-08-03 17:00" },
>       "departure": { "lon": 2.33, "lat": 48.875 },
>       "arrival": { "lon": 2.33, "lat": 48.875 },
>       "capacities": { "stopsDelivered": 12 },
>       "tags": ["driver", "unfamiliar:sector-north"],
>       "cost": { "km": { "costCoeff": 1.2 } }
>     },
>     {
>       "id": "van-subcontractor-a",
>       "vehicleProfile": { "type": "car" },
>       "workingTimeWindow": { "begin": "2026-08-03 04:30", "end": "2026-08-03 14:30" },
>       "departure": { "lon": 2.335, "lat": 48.897 },
>       "arrival": { "lon": 2.335, "lat": 48.897 },
>       "capacities": { "stopsDelivered": 12 },
>       "tags": ["driver"],
>       "maxDistanceInKm": 25,
>       "priority": -1,
>       "cost": { "costsByCapacity": { "stopsDelivered": { "constantCost": 80, "costFloor": 3, "costCoeff": 15 } } }
>     },
>     {
>       "id": "van-subcontractor-b",
>       "vehicleProfile": { "type": "car" },
>       "workingTimeWindow": { "begin": "2026-08-03 07:00", "end": "2026-08-03 17:00" },
>       "departure": { "lon": 2.322, "lat": 48.849 },
>       "arrival": { "lon": 2.322, "lat": 48.849 },
>       "capacities": { "stopsDelivered": 12 },
>       "tags": ["driver"],
>       "maxDistanceInKm": 25,
>       "priority": -2,
>       "cost": { "costsByCapacity": { "stopsDelivered": { "constantCost": 80, "costFloor": 3, "costCoeff": 15 } } }
>     }
>   ],
>   "orders": [
>     {
>       "id": "order-keychain-0",
>       "stops": [
>         {
>           "type": "single",
>           "id": "stop-keychain-0",
>           "position": { "lon": 2.345, "lat": 48.885 },
>           "kind": "delivery",
>           "operationDuration": "PT5M",
>           "capacities": { "stopsDelivered": 1 },
>           "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.31, "lat": 48.883 },
>           "kind": "delivery",
>           "operationDuration": "PT5M",
>           "capacities": { "stopsDelivered": 1 },
>           "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.34, "lat": 48.857 },
>           "kind": "delivery",
>           "operationDuration": "PT5M",
>           "capacities": { "stopsDelivered": 1 },
>           "tags": ["keychain:trusted-set-1"],
>           "authorizedTimeWindows": [{ "begin": "2026-08-03 06:30", "end": "2026-08-03 08:00" }]
>         }
>       ]
>     },
>     {
>       "id": "order-locker-site",
>       "stops": [
>         {
>           "type": "single",
>           "id": "stop-locker-site",
>           "position": { "lon": 2.318, "lat": 48.861 },
>           "kind": "delivery",
>           "operationDuration": "PT5M",
>           "capacities": { "stopsDelivered": 1 },
>           "authorizedTimeWindows": [
>             { "begin": "2026-08-03 06:00", "end": "2026-08-03 20:00", "resourceTags": ["key-holder"] },
>             { "begin": "2026-08-03 09:00", "end": "2026-08-03 17:00" }
>           ]
>         }
>       ]
>     },
>     {
>       "id": "order-job-0",
>       "stops": [{ "type": "single", "id": "stop-job-0", "position": { "lon": 2.355, "lat": 48.87 }, "kind": "delivery", "operationDuration": "PT10M", "capacities": { "stopsDelivered": 1 }, "tags": ["sector:north"] }]
>     },
>     {
>       "id": "order-job-1",
>       "stops": [{ "type": "single", "id": "stop-job-1", "position": { "lon": 2.3, "lat": 48.89 }, "kind": "delivery", "operationDuration": "PT10M", "capacities": { "stopsDelivered": 1 }, "tags": ["sector:north"] }]
>     },
>     {
>       "id": "order-store-1",
>       "stops": [
>         { "type": "single", "id": "stop-store-1", "position": { "lon": 2.335, "lat": 48.897 }, "kind": "delivery", "operationDuration": "PT15M", "capacities": { "stopsDelivered": 1 }, "authorizedTimeWindows": [{ "begin": "2026-08-03 05:00", "end": "2026-08-03 06:45" }] }
>       ]
>     },
>     {
>       "id": "order-store-2",
>       "stops": [
>         { "type": "single", "id": "stop-store-2", "position": { "lon": 2.322, "lat": 48.849 }, "kind": "delivery", "operationDuration": "PT15M", "capacities": { "stopsDelivered": 1 }, "authorizedTimeWindows": [{ "begin": "2026-08-03 06:00", "end": "2026-08-03 08:00" }] }
>       ]
>     },
>     {
>       "id": "order-overflow-0",
>       "stops": [{ "type": "single", "id": "stop-overflow-0", "position": { "lon": 2.345, "lat": 48.885 }, "kind": "delivery", "operationDuration": "PT1H", "capacities": { "stopsDelivered": 1 } }]
>     },
>     {
>       "id": "order-overflow-1",
>       "stops": [{ "type": "single", "id": "stop-overflow-1", "position": { "lon": 2.31, "lat": 48.883 }, "kind": "delivery", "operationDuration": "PT1H", "capacities": { "stopsDelivered": 1 } }]
>     },
>     {
>       "id": "order-overflow-2",
>       "stops": [{ "type": "single", "id": "stop-overflow-2", "position": { "lon": 2.34, "lat": 48.857 }, "kind": "delivery", "operationDuration": "PT1H", "capacities": { "stopsDelivered": 1 } }]
>     },
>     {
>       "id": "order-overflow-3",
>       "stops": [{ "type": "single", "id": "stop-overflow-3", "position": { "lon": 2.318, "lat": 48.861 }, "kind": "delivery", "operationDuration": "PT1H", "capacities": { "stopsDelivered": 1 } }]
>     }
>   ],
>   "objectives": ["maximizeMandatoryStops", "minimizeResources", "minimizeLargestTourDuration", "minimizeCosts", "minimizeDistance", "minimizeWorkingDuration"],
>   "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"
>     }
>   ],
>   "additionalOperationDurations": [
>     { "resourceTag": "unfamiliar:sector-north", "stopTag": "sector:north", "additionalOperationDuration": "PT6M" }
>   ]
> }
> ```

## See also

* [Modeling advanced constraints](/guides/advanced-constraints#restricting-a-window-to-specific-resources) — `resourceTags` on a time window.
* [Cost modeling](/guides/cost-modeling#the-cost-object) — the full `Cost` object, including `km` and `costsByCapacity`.
* [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.