# Delivery

Deliver a cart instead of a pickup, over REST, MCP or the CLI. It is the same cart, confirm and order as a pickup, with an address, a delivery fee and a tip. The fields are in Carts; this page is the path through them.

## Can this key deliver

[GET /v1/whoami](https://docs.layout.link/api#get-v1-whoami) with your secret answers in `delivery`. Delivery is on for every application, in sandbox and production, with nothing to apply for or turn on.

- **`true`:** this key can deliver now. Build with `fulfillment`, as below.
- **`false`, or no `delivery` field:** delivery is paused for this application right now. Build pickups; there is nothing to request. A delivery cart over REST is then built as a pickup whose reason is `not_enabled`, and an MCP build asking for delivery builds nothing.

A key that can deliver can still meet an address it cannot deliver to, so check every cart, as in step 2.

## The five steps

1. **Build with `fulfillment`.** `POST /v1/carts` with `"fulfillment": { "type": "delivery", "address": "...", "unit": "...", "instructions": "..." }`, and `tip` when the person chose one. Ask the person where to deliver: Layout never shares their saved addresses. See [Asking for delivery](https://docs.layout.link/carts#asking-for-delivery).
2. **Check it did not fall back.** On the ready cart, `fulfillment.type` must be `delivery`. When it is `pickup` with `fulfillment.deliveryUnavailable`, show its `message`, then send pickup, or a delivery that works, to [POST /v1/carts/:id/fulfillment](https://docs.layout.link/carts#post-v1-carts-id-fulfillment). Until you do, a confirm is refused with `409 delivery_unavailable`. See [When delivery cannot happen](https://docs.layout.link/carts#delivery-unavailable).
3. **Show the confirm with the amounts.** The address from `fulfillment.dropoff.line`, the items, the delivery fee (`fees.courierFeeMinor`), the tip (`fees.tipMinor`, which the person can change to one of `fulfillment.tip.presets`), Layout's service fee (`fees.serviceFeeMinor`), the one total, `totalMinor`, and the `card`. On a connected person's token, show `confirmationCard` as written; it says all of it.
4. **Confirm with `expectedTotalMinor`.** Send the cart's `totalMinor` unchanged. A `409 price_changed` means nothing was confirmed or charged. Read the cart with `GET /v1/carts/:id`. While it is `ready`, it holds the new total: check `fulfillment` as in step 2, show the person the new `totalMinor`, and confirm with it and a new `idempotencyKey`. When it is `failed` or `expired`, build a fresh cart. When it is `closed`, read its `order` before anything else: it may have been confirmed elsewhere.
5. **Track it.** The order is `placed` and stays `placed` to the door: `fulfillment.status` is where the delivery is. `order.updated` comes at the main [delivery steps](https://docs.layout.link/events#delivery-steps). On each one, read [GET /v1/orders/:id](https://docs.layout.link/api#delivery-orders) for the live `status`, `eta` and driver. Keep reading only while `fulfillment.type` is `delivery` and `fulfillment.status` is neither `delivered` nor `failed`. Every other read ends the loop, including a `type` of `pickup`, which has no `status`. When `changed_from` is `"delivery"`, no driver came: tell the person to collect the order from `store_address`.

## In one script

A whole sandbox delivery with a build grant, at the test restaurant `test_place_placed`. It needs `curl` and `jq`.

```
API=https://api.layout.link/v1
KEY=dlv-$(date +%s)
CART=$(curl -s $API/carts \
  -H "Authorization: Bearer $LAYOUT_GRANT" \
  -H "Content-Type: application/json" \
  -d '{
    "placeId": "test_place_placed",
    "request": "a latte",
    "fulfillment": { "type": "delivery", "address": "500 Howard St, San Francisco, CA", "unit": "Floor 3", "instructions": "Front desk" },
    "idempotencyKey": "'"$KEY"'-cart"
  }' | jq -r '.cart.id')

while :; do
  curl -s $API/carts/$CART -H "Authorization: Bearer $LAYOUT_GRANT" > cart.json
  [ "$(jq -r '.cart.status' cart.json)" != building ] && break
  sleep 3
done
jq '.cart | { status, type: .fulfillment.type, deliveryUnavailable: .fulfillment.deliveryUnavailable,
  to: .fulfillment.dropoff.line, fees, totalMinor }' cart.json

[ "$(jq -r '.cart.fulfillment.type' cart.json)" = delivery ] || { echo "fell back to pickup"; exit 1; }
ORDER=$(curl -s $API/carts/$CART/confirm \
  -H "Authorization: Bearer $LAYOUT_GRANT" \
  -H "Content-Type: application/json" \
  -d '{ "expectedTotalMinor": '"$(jq '.cart.totalMinor' cart.json)"', "idempotencyKey": "'"$KEY"'-confirm" }' | jq -r '.order.id')

curl -s $API/orders/$ORDER -H "Authorization: Bearer $LAYOUT_SECRET_KEY" | jq '{ state, fulfillment, amounts }'
```

Read the order again, by the stop rule in step 5: until `fulfillment.type` is `pickup`, or `fulfillment.status` is `delivered` or `failed`. In production the same calls deliver real food, with a person's yes before the confirm.

## Over MCP and the CLI

- **MCP.** A build session (`lgb_`) and an OAuth connection deliver by the same rule as REST. `order` with `action: "build"` takes `deliverTo` (the address), `deliveryUnit`, `deliveryInstructions`, `addressKind`, and a tip as `tipPercent` (`0` for no tip) or `tipMinor` (cents); leave both out for the lowest preset. The carted build's `fulfillment` carries `type`, `dropoff.line`, `courierFeeMinor` and `tip`: check `type` as in step 2, then confirm with the build's `totalMinor` as `expectedTotalMinor`. A build session chooses delivery when it builds and has no `fulfillment` action: to change the type, address or tip, cancel the cart and build again with a new `idempotencyKey`. A build session's cart that fell back to a pickup cannot be confirmed as a pickup: its confirm answers `delivery_unavailable` and orders nothing. Cancel it and build again, as a pickup or with an address that works. On an OAuth connection, `action: "fulfillment"` with the `orderId` changes the type, address, notes or tip. See [Ordering over MCP](https://docs.layout.link/mcp#delivery-on-mcp).
- **CLI.** `layout test-order --deliver-to "500 Howard St" --courier lost --json` runs a whole sandbox delivery and checks it ends as `--courier` says. `layout test-order --help` lists every delivery flag. See [Run a test order](https://docs.layout.link/cli#run-a-test-order).

## Test every ending

In sandbox, `simulate` inside a delivery `fulfillment` sets how the simulated driver's run ends, `delivered` when it is left out. The CLI's `--courier` is the same. It works at test restaurants too: they ignore the cart's own `simulate` and `latency`, never the delivery's. Send `"latency": "instant"` on a cart at a real restaurant, from a sandbox places search, and any ending runs end to end in under about 15 seconds. Over MCP a sandbox delivery ends `delivered`: test the other endings over REST or the CLI.

```
"fulfillment": { "type": "delivery", "address": "500 Howard St", "simulate": "no_courier" },
"latency": "instant"
```

The order's `state` is `placed` at every ending. The last column is what a real order charges. In sandbox nothing is charged and `amounts.charged_minor` is `null`, while `courier_fee_minor` and `tip_minor` read as the column says.

| `simulate` | What happens | `fulfillment` at the end | `order.updated` steps | What the person pays |
| --- | --- | --- | --- | --- |
| `delivered` | The driver collects the order and hands it over, or leaves it at the door, as `handoff` says. | `status: "delivered"`, with `proof_photo_url` when left at the door | `on_the_way`, `delivered`, and `arriving` between them with `meet_at_door` | Everything confirmed |
| `left_at_door` | The driver cannot reach the person and leaves it at the door, with a photo. | `status: "delivered"`, with `proof_photo_url` | `on_the_way`, `delivered` | Everything confirmed |
| `running_late` | Once the driver has the food, `eta` moves 10 minutes later. | `status: "delivered"` | `on_the_way`, `delivered` | Everything confirmed |
| `courier_canceled` | The first driver cancels before collecting the food. Layout books a second, who delivers. | `finding_courier` again, with no event, then `status: "delivered"` | `on_the_way`, `delivered` | Everything confirmed |
| `no_courier` | No driver can be booked, so the order becomes a pickup. | `type: "pickup"`, `changed_from: "delivery"` | One, when it becomes a pickup | The food and the service fee. No delivery fee or tip |
| `lost` | The driver collects the food and it never arrives. | `status: "failed"`, with `failure_reason` | `on_the_way`, `failed` | Nothing |
| `returned` | The driver collects the food and takes it back to the store. | `status: "failed"`, with `failure_reason` | `on_the_way`, `failed` | What a person at Layout decides. `charged_minor` is `null` until then |

- A sandbox address with a digit in it resolves near the test restaurants with no lookup. One without is `address_not_found`.
- `test_place_delivery_far` is too far to deliver to: it answers `out_of_range` with `test_place_placed` as the `alternative`.
- The simulated delivery fee is $4.99. Sandbox quotes and lookups never count toward the [delivery limits](https://docs.layout.link/limits#delivery-quotes-and-address-lookups), and nothing is saved to the test person's account.

## What the person pays

A delivery that arrives charges what the person confirmed: the food, Layout's service fee, the delivery fee and the tip. The delivery fee charged is never more than the one they confirmed. A delivery that does not arrive never charges the delivery fee or the tip, as the table above says.

When no driver can be booked, Layout's service fee is still charged as confirmed, including its 4% on the delivery fee.

When a driver takes the food back to the store (`returned`), a person at Layout decides what is charged, from nothing up to what was confirmed. Until then `amounts.charged_minor` is `null`. No event is sent when they decide: read `GET /v1/orders/:id` again later for the figure. In sandbox `charged_minor` stays `null` at every ending, because nothing is charged.

`amounts.charged_minor` on the order is what the card was charged, whatever the ending. See [Delivery orders](https://docs.layout.link/api#delivery-orders).
