# Delivery on orders

November 8, 2026 · API · Breaking

Orders from a delivery cart now read as deliveries on `GET /v1/orders/:id`, and say where the delivery is.

## What changed

- **`fulfillment.type` is `pickup` or `delivery`.** It was always `pickup` before.
- **Delivery fields.** On a delivery, `fulfillment.status` is one of `finding_courier`, `heading_to_store`, `at_store`, `on_the_way`, `arriving`, `delivered` or `failed`; `fulfillment.eta` is when it should arrive, ISO 8601; and `fulfillment.courier` is `{ first_name, vehicle }` while a driver is assigned. `fulfillment.address` is the street line and unit it is going to. A pickup order has none of these delivery keys. See [Delivery orders](https://docs.layout.link/api#delivery-orders).
- **A delivery can become a pickup.** When no driver could be booked, the order reads `type: "pickup"` with `changed_from: "delivery"`, and the person collects it from the store. A delivery whose driver could not finish stays a delivery, with `status` `failed`.
- **Delivery money in `amounts`.** `courier_fee_minor` and `tip_minor`, always `0` before, are now the delivery fee and the driver's tip that were charged: `0` for pickup, for a failed delivery, and for one that became a pickup. `charged_minor` is what the card was charged at each ending:  Delivered, or left at the door: everything confirmed, with the delivery fee and the tip.
- No driver could be booked, so it became a pickup: the food and Layout's service fee. Never the delivery fee or the tip.
- The driver lost the food: `0`.
- Any other delivery that failed, such as the driver taking the food back to the store: `null` until a person at Layout decides, then from nothing up to what was confirmed. No event is sent when they decide.

## Why it matters

Your product can show the person where their delivery is, and tell them plainly when it turned into a pickup so they know to go to the store. The order's `state` stays `placed` throughout: `fulfillment.status` is the delivery.

## What to do

- Handle both values of `fulfillment.type`. Show the store's pickup details for `pickup`, and `status`, `eta` and `courier` for `delivery`.
- When `changed_from` is `"delivery"`, tell the person no driver could be booked and to collect the order from `store_address`.
- Treat `charged_minor: null` on a placed delivery as not settled yet, never as nothing charged.
- Read the order again on every `order.updated`, and de-duplicate on `event_id`, never on the order id and event type. Not every step sends one: while `status` is not `delivered` or `failed`, read `GET /v1/orders/:id` for the live status.

## Breaking changes

Yes, for code that assumed every order is a pickup. `fulfillment.type` can now be `delivery`, and a strict client generated from the old OpenAPI spec, where `type` was the constant `pickup`, can reject it. Regenerate from the current [openapi.json](https://docs.layout.link/openapi.json), and do not tell the person to collect a delivery order from the store unless `changed_from` is `"delivery"`. Clients that require exactly the old `fulfillment` keys also need the delivery keys.
