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

# Delivery windows

> A delivery window is a bookable time slot, tied to a store location and bounded by capacity, that an order can be scheduled into.

A **delivery window** is a bookable time slot for scheduled deliveries. Each window is associated with a [store location](/reference/store-locations), spans a start and end time, and holds a limited amount of capacity. Customers (or your system on their behalf) reserve a window for an order; when the window's cutoff passes, the confirmed orders in it are dispatched together.

## What a delivery window is

Create a window with [Create a single delivery window](/api-reference/delivery-windows/create-a-single-delivery-window) (`POST /v1/delivery-window`) and read one back with [Get a delivery window](/api-reference/delivery-windows/get-a-delivery-window) (`GET /v1/delivery-window/{id}`). A window can define:

* A **start** and **end** time (`startTime` / `endTime`, with `*Local` and `timezoneId` variants) — the slot the customer sees
* A **cutoff time** (`cutoffTime`) — the moment after which the window stops accepting orders and its bookings are dispatched
* A **maximum capacity** (`maximumCapacity`) — how many orders, or how much requested capacity, the window can hold
* A **store location** (`storeLocationId`) and, optionally, a **zone** (`zoneId` / `zoneExternalId`)
* A **recurrence rule** (`rrule`) with `exceptionDates`, so a window can repeat (for example, every weekday) without creating each occurrence by hand
* A **lead time** (`leadTimeMinutes`), **price** (`priceCents`), and **minimum order value** (`minimumOrderValueCents`)
* **Allowed tags** (`allowedTags`) and free-form `windowMetadata`

<Info>
  To find the windows an order is eligible for — based on its store location and requirements — use [Get eligible delivery windows for order](/api-reference/delivery-windows/get-eligible-delivery-windows-for-order) (`GET /v1/eligible_delivery_windows`). It requires an order ID (or external order ID) and a `startTime`/`endTime` range, and optionally a `requestedCapacity`.
</Info>

## Booking, confirming & revoking

Reserving a window for an order is a two-phase flow keyed off your **external order identifier**. This lets a customer hold a slot while they finish checkout, then commit it only when the order is placed.

<Steps>
  <Step title="Book">
    [Book a delivery window for order](/api-reference/delivery-windows/book-a-delivery-window-for-order) (`POST /v1/order/external-identifier/{externalId}/delivery-window/book`) reserves a window. The booking **holds** capacity in the window until it is confirmed or revoked. Pass the `deliveryWindowId`; you may also pass a `requestedCapacity` and an `expiresAt` after which an unconfirmed booking lapses.
  </Step>

  <Step title="Confirm">
    [Confirm a delivery window for order](/api-reference/delivery-windows/confirm-a-delivery-window-for-order) (`POST /v1/order/external-identifier/{externalId}/delivery-window/confirm`) finalizes a previously booked window and **commits** the capacity reservation.
  </Step>

  <Step title="Revoke">
    [Revoke a delivery window for order](/api-reference/delivery-windows/revoke-a-delivery-window-for-order) (`POST /v1/order/external-identifier/{externalId}/delivery-window/revoke`) releases the capacity reservation and disassociates the window from the order.
  </Step>
</Steps>

<Note>
  You can also create an order and attach a delivery window in one call with [Upsert order by external identifier with delivery window](/api-reference/order/upsert-order-by-external-identifier-with-delivery-window) (`POST /v1/order/external-identifier/{externalId}/delivery-window`).
</Note>

## Capacity & shifts

Each window has a finite `maximumCapacity`. Booking an order holds capacity; confirming commits it; revoking returns it to the pool. A window that has reached its capacity is no longer eligible for new bookings, which is why an eligibility check accepts a `requestedCapacity` — so you only see windows that can still accommodate the order.

Windows are grouped into **shifts** for dispatch. Orders are batched by organization, store location, pick shift name, and cutoff date, and the whole shift is dispatched together once its cutoff has passed — rather than each order being dispatched individually at order time.

## The `shift.dispatched` event

When a shift's cutoff passes, Nash dispatches the confirmed orders in that shift as a batch and fires the [`shift.dispatched`](/reference/shift-dispatched-event) webhook. Before dispatch, each order is validated: its delivery window must be `confirmed`, its cutoff must have passed, and the order must not already be `dispatched` or `archived`.

The webhook payload reports both the jobs that were created (`created_job_ids`) and any orders or jobs that failed, with per-entity error messages (`errors`). This lets you reconcile a whole shift in one event: successful orders are now live deliveries, and failed ones can be corrected and re-dispatched. For the full payload structure, validation rules, and worked scenarios, see the [`shift.dispatched` event](/reference/shift-dispatched-event) page.

## Next steps

<CardGroup cols={2}>
  <Card title="Create a delivery window" icon="calendar-plus" href="/api-reference/delivery-windows/create-a-single-delivery-window">
    Define a bookable time slot with capacity and cutoff.
  </Card>

  <Card title="Book a window for an order" icon="calendar-check" href="/api-reference/delivery-windows/book-a-delivery-window-for-order">
    Reserve capacity for an order by external ID.
  </Card>

  <Card title="Eligible windows for order" icon="list-check" href="/api-reference/delivery-windows/get-eligible-delivery-windows-for-order">
    Find the windows an order can be scheduled into.
  </Card>

  <Card title="shift.dispatched event" icon="bolt" href="/reference/shift-dispatched-event">
    The webhook fired when a shift is dispatched.
  </Card>
</CardGroup>