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 withfulfillment, as below.false, or nodeliveryfield: 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 isnot_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
- Build with
fulfillment.POST /v1/cartswith"fulfillment": { "type": "delivery", "address": "...", "unit": "...", "instructions": "..." }, andtipwhen the person chose one. Ask the person where to deliver: Layout never shares their saved addresses. See Asking for delivery. - Check it did not fall back. On the ready cart,
fulfillment.typemust bedelivery. When it ispickupwithfulfillment.deliveryUnavailable, show itsmessage, then send pickup, or a delivery that works, to POST /v1/carts/:id/fulfillment. Until you do, a confirm is refused with409 delivery_unavailable. See When delivery cannot happen. - 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 offulfillment.tip.presets), Layout's service fee (fees.serviceFeeMinor), the one total,totalMinor, and thecard. On a connected person's token, showconfirmationCardas written; it says all of it. - Confirm with
expectedTotalMinor. Send the cart'stotalMinorunchanged. A409 price_changedmeans nothing was confirmed or charged. Read the cart withGET /v1/carts/:id. While it isready, it holds the new total: checkfulfillmentas in step 2, show the person the newtotalMinor, and confirm with it and a newidempotencyKey. When it isfailedorexpired, build a fresh cart. When it isclosed, read itsorderbefore anything else: it may have been confirmed elsewhere. - Track it. The order is
placedand staysplacedto the door:fulfillment.statusis where the delivery is.order.updatedcomes at the main delivery steps. On each one, read GET /v1/orders/:id for the livestatus,etaand driver. Keep reading only whilefulfillment.typeisdeliveryandfulfillment.statusis neitherdeliverednorfailed. Every other read ends the loop, including atypeofpickup, which has nostatus. Whenchanged_fromis"delivery", no driver came: tell the person to collect the order fromstore_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.orderwithaction: "build"takesdeliverTo(the address),deliveryUnit,deliveryInstructions,addressKind, and a tip astipPercent(0for no tip) ortipMinor(cents); leave both out for the lowest preset. The carted build'sfulfillmentcarriestype,dropoff.line,courierFeeMinorandtip: checktypeas in step 2, then confirm with the build'stotalMinorasexpectedTotalMinor. A build session chooses delivery when it builds and has nofulfillmentaction: to change the type, address or tip, cancel the cart and build again with a newidempotencyKey. A build session's cart that fell back to a pickup cannot be confirmed as a pickup: its confirm answersdelivery_unavailableand orders nothing. Cancel it and build again, as a pickup or with an address that works. On an OAuth connection,action: "fulfillment"with theorderIdchanges the type, address, notes or tip. See Ordering over MCP. - CLI.
layout test-order --deliver-to "500 Howard St" --courier lost --jsonruns a whole sandbox delivery and checks it ends as--couriersays.layout test-order --helplists 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.
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_faris too far to deliver to: it answersout_of_rangewithtest_place_placedas thealternative.- 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.