# Delivery on carts

November 8, 2026 · API

Carts are still pickup by default. Delivery is on for every application, sandbox and production, and a cart can now be a delivery instead: the same order, collected from the store by a driver Layout books and brought to the person. The whole path is on [Delivery](https://docs.layout.link/delivery).

## What changed

- **`delivery` on `GET /v1/whoami`.** `true` when the key can deliver now. `false`, or no `delivery` field, means delivery is paused for the application right now: build pickups, and there is nothing to request.
- **`fulfillment` and `tip` on `POST /v1/carts`.** `fulfillment` is `"pickup"` (the default) or `{ "type": "delivery", "address": "...", "unit": "...", "instructions": "...", "handoff": "meet_at_door", "kind": "work" }`, every field but `type` optional. `kind` is `personal` (the default) or `work`. `tip` is `{ "percent": 18 }` or `{ "minor": 300 }`; leave it out for the lowest preset, or send `{ "percent": 0 }` for none. A tip sent with a pickup is `400 invalid_request`, and so is a `unit` and `instructions` longer than 280 characters together, counting 3 for the separator.
- **`POST /v1/carts/:id/fulfillment`.** Changes a ready cart to pickup or delivery, its address, unit or notes, or the tip. It is all or nothing: a change that cannot happen is the new `409 delivery_unavailable` with `error.reason` and `error.userMessage`, and the cart is left as it was. A tip sent alone to a cart that is a pickup is the new `409 not_delivery`.
- **Over MCP.** Build sessions and OAuth connections take `deliverTo`, `deliveryUnit`, `deliveryInstructions`, `addressKind` and `tipPercent` or `tipMinor` on `order` `build`, with the same rules as REST: `tipPercent` is a whole number from 0 to 100, `tipMinor` is up to 5000, never both, and the unit and driver notes together fit in 280 characters. A build session chooses delivery when it builds, and builds again to change it; a delivery with no `deliverTo` builds nothing and answers `deliveryUnavailable.reason: "no_address"`. On an OAuth connection, `action: "fulfillment"` also changes a carted build.
- **The address.** You send it with each cart; Layout never shares a person's saved addresses with an application. Once the order is placed, Layout saves it to the person's Layout account, filed under `kind`, unless they already have it there or 6 of their 8 saved addresses are used. It never becomes their default over one they have. Driver notes stay with the order.
- **`fulfillment` on every priced cart.** `type`, `dropoff.line` (the street and unit the driver goes to), `courierFeeMinor`, `tip` with its `presets`, and `deliveryUnavailable`. `fees` gains `courierFeeMinor` and `tipMinor`, both `0` on a pickup.
- **When delivery cannot happen** at cart creation, or at confirm when the price cannot be renewed, the cart is a pickup and `deliveryUnavailable` gives a `reason` on every read. Confirming it is refused with `409 delivery_unavailable` until you send pickup, or a delivery that works, so nobody gets a pickup they did not choose.
- **`confirmationCard` on a delivery cart.** On a person's token it states the address, the service fee, the delivery fee, the tip, the total and the card that will be billed.
- **Two new limit names.** `delivery_quotes` and `address_lookups`, in `error.limit.name` and on `GET /v1/usage`. Each is counted per person, per application and per developer account, across its applications: 3,000 quotes and 1,000 address lookups a day for the account, refused as `429 rate_limited` with `error.limit.scope` `"account"`. Sending the same address again to `/fulfillment` while the cart's quote has more than two minutes left reuses it and is not counted, and sandbox counts toward neither. See [the numbers](https://docs.layout.link/limits#delivery-quotes-and-address-lookups).

## Why it matters

Your product can offer delivery from the same restaurants with the same flow: one cart, one total, one confirm. The person sees the delivery fee and the tip before they say yes, and when Layout texts them a code, it names the street and city the order goes to.

## What to do

Nothing, if you only offer pickup. To offer delivery:

1. Ask the person where to deliver, and send it as `address`, with `unit` apart. Send `kind: "work"` when they called it their work address; do not ask them just for it.
2. Read `fulfillment.type` on the ready cart, and read `fulfillment.dropoff.line`, the fee, the tip and `totalMinor` back to the person.
3. Confirm with `totalMinor`, exactly as the cart gives it. On `409 price_changed`, pickup or delivery, read the cart: while it is `ready`, show the person its new `totalMinor` and confirm with it; when it is `failed` or `expired`, build a fresh cart. On `409 delivery_unavailable`, show `error.userMessage`, then send pickup or another address.
4. Say in your privacy notice that a delivery address is kept in the person's Layout account.

To try every ending in sandbox, send `simulate` inside the delivery `fulfillment`, or, from CLI 0.5.4, run `layout test-order --deliver-to "500 Howard St" --courier <ending>`. See [Test every ending](https://docs.layout.link/delivery#test-every-ending).

## Breaking changes

None for a client that ignores fields it does not know. Every cart now carries `fulfillment`, and `fees` carries `courierFeeMinor` and `tipMinor`, both `0` for pickup. A person can also switch your cart to delivery in Layout, and then `totalMinor` includes the fee and tip, so keep confirming with `totalMinor` rather than adding up `fees`.
