Delivery on orders
Orders from a delivery cart now read as deliveries on GET /v1/orders/:id, and say where the delivery is.
What changed
fulfillment.typeispickupordelivery. It was alwayspickupbefore.- Delivery fields. On a delivery,
fulfillment.statusis one offinding_courier,heading_to_store,at_store,on_the_way,arriving,deliveredorfailed;fulfillment.etais when it should arrive, ISO 8601; andfulfillment.courieris{ first_name, vehicle }while a driver is assigned.fulfillment.addressis the street line and unit it is going to. A pickup order has none of these delivery keys. See Delivery orders. - A delivery can become a pickup. When no driver could be booked, the order reads
type: "pickup"withchanged_from: "delivery", and the person collects it from the store. A delivery whose driver could not finish stays a delivery, withstatusfailed. - Delivery money in
amounts.courier_fee_minorandtip_minor, always0before, are now the delivery fee and the driver's tip that were charged:0for pickup, for a failed delivery, and for one that became a pickup.charged_minoris 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:
nulluntil a person at Layout decides, then from nothing up to what was confirmed. No event is sent when they decide.
order.updatedon delivery. When the driver has the food and is on the way, when the driver is arriving at ameet_at_doorhandoff, when it is delivered, when the driver could not finish, and when no driver could be booked. Finding a driver, heading to the store and at the store send nothing. No new event type, and noorder.delivered. Each has its ownevent_id, numbered with the pickup-detail waves. See Delivery steps.- Proof of delivery.
fulfillment.proof_photo_urlis the driver's photo of an order left at the door, once delivered, andfulfillment.failure_reasonsays why a failed delivery did not complete, in words to show the person.
"fulfillment": {
"type": "delivery",
"name": "Sam",
"address": "500 Howard St, Floor 3",
"ready_text": "Ready by 10:15 AM",
"merchant_order_number": "A47",
"instructions": "Pick up at the mobile order counter",
"status": "on_the_way",
"eta": "2026-10-15T17:42:00.000Z",
"courier": { "first_name": "Alex", "vehicle": "Silver Toyota Prius" },
"proof_photo_url": null,
"failure_reason": null
}
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 forpickup, andstatus,etaandcourierfordelivery. - When
changed_fromis"delivery", tell the person no driver could be booked and to collect the order fromstore_address. - Treat
charged_minor: nullon a placed delivery as not settled yet, never as nothing charged. - Read the order again on every
order.updated, and de-duplicate onevent_id, never on the order id and event type. Not every step sends one: whilestatusis notdeliveredorfailed, readGET /v1/orders/:idfor the live status.
const order = await getOrder(payload.order.id);
if (order.fulfillment.type === "delivery") {
showDelivery(order.fulfillment.status, order.fulfillment.eta, order.fulfillment.courier);
} else {
showPickup(order.ready_eta, order.fulfillment, order.fulfillment.changed_from === "delivery");
}
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, 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.