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 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.
  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. Until you do, a confirm is refused with 409 delivery_unavailable. See When delivery cannot happen.
  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. On each one, read GET /v1/orders/:id 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.
  • 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.

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.

simulateWhat happensfulfillment at the endorder.updated stepsWhat the person pays
deliveredThe 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 dooron_the_way, delivered, and arriving between them with meet_at_doorEverything confirmed
left_at_doorThe driver cannot reach the person and leaves it at the door, with a photo.status: "delivered", with proof_photo_urlon_the_way, deliveredEverything confirmed
running_lateOnce the driver has the food, eta moves 10 minutes later.status: "delivered"on_the_way, deliveredEverything confirmed
courier_canceledThe 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, deliveredEverything confirmed
no_courierNo driver can be booked, so the order becomes a pickup.type: "pickup", changed_from: "delivery"One, when it becomes a pickupThe food and the service fee. No delivery fee or tip
lostThe driver collects the food and it never arrives.status: "failed", with failure_reasonon_the_way, failedNothing
returnedThe driver collects the food and takes it back to the store.status: "failed", with failure_reasonon_the_way, failedWhat 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, 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.