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

> Key-holder-only access windows, blended subcontractor/in-house costs, pre-opening store drops, and trusted-keychain deliveries on one retail network.

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}
{
  "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 },
      "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-03T06:00:00Z", "end": "2026-08-03T20:00:00Z", "resourceTags": ["key-holder"] },
            { "begin": "2026-08-03T09:00:00Z", "end": "2026-08-03T17:00:00Z" }
          ]
        }
      ]
    },
    {
      "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-03T05:00:00Z", "end": "2026-08-03T07:00:00Z" }]
        }
      ]
    },
    {
      "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-03T06:30:00Z", "end": "2026-08-03T08:00:00Z" }]
        }
      ]
    }
  ],
  "globalConstraints": [
    {
      "type": "maxCumulatedCost",
      "maximum": 1,
      "costsByResourceTag": {
        "driver": { "costsByStopTag": { "keychain:trusted-set-1": { "using": 1 } } }
      },
      "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-07:00), ahead of the store's opening hours — 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.

### Trusted-keychain deliveries

`order-keychain-0` carries the tag `keychain:trusted-set-1`; a `globalConstraints` entry of type `maxCumulatedCost` caps the number of distinct `driver`-tagged resources allowed on that tag at 1 across the whole fleet, so whichever driver takes the first keychain stop is the only one who can take the rest of the set. See [Constraints catalog](/reference/data-model#constraints-catalog).

## Full payload

<Accordion title="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.

  ```json theme={null}
  {
    "tz": "Europe/Paris",
    "resources": [
      {
        "id": "driver-key-holder",
        "vehicleProfile": { "type": "car" },
        "workingTimeWindow": { "begin": "2026-08-03T07:00:00Z", "end": "2026-08-03T17:00:00Z" },
        "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-03T07:00:00Z", "end": "2026-08-03T17:00:00Z" },
        "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-03T07:00:00Z", "end": "2026-08-03T17:00:00Z" },
        "departure": { "lon": 2.335, "lat": 48.897 },
        "arrival": { "lon": 2.335, "lat": 48.897 },
        "capacities": { "stopsDelivered": 12 },
        "maxDistanceInKm": 25,
        "priority": -1,
        "cost": { "costsByCapacity": { "stopsDelivered": { "constantCost": 80, "costFloor": 3, "costCoeff": 15 } } }
      },
      {
        "id": "van-subcontractor-b",
        "vehicleProfile": { "type": "car" },
        "workingTimeWindow": { "begin": "2026-08-03T07:00:00Z", "end": "2026-08-03T17:00:00Z" },
        "departure": { "lon": 2.322, "lat": 48.849 },
        "arrival": { "lon": 2.322, "lat": 48.849 },
        "capacities": { "stopsDelivered": 12 },
        "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-03T06:30:00Z", "end": "2026-08-03T08:00:00Z" }]
          }
        ]
      },
      {
        "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-03T06:30:00Z", "end": "2026-08-03T08:00:00Z" }]
          }
        ]
      },
      {
        "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-03T06:30:00Z", "end": "2026-08-03T08:00:00Z" }]
          }
        ]
      },
      {
        "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-03T06:00:00Z", "end": "2026-08-03T20:00:00Z", "resourceTags": ["key-holder"] },
              { "begin": "2026-08-03T09:00:00Z", "end": "2026-08-03T17:00:00Z" }
            ]
          }
        ]
      },
      {
        "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-03T05:00:00Z", "end": "2026-08-03T07:00:00Z" }] }
        ]
      },
      {
        "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-03T06:00:00Z", "end": "2026-08-03T08:00:00Z" }] }
        ]
      },
      {
        "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": { "using": 1 } } } },
        "name": "one-driver-per-key-set"
      }
    ],
    "additionalOperationDurations": [
      { "resourceTag": "unfamiliar:sector-north", "stopTag": "sector:north", "additionalOperationDuration": "PT6M" }
    ]
  }
  ```
</Accordion>

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