Delivery on orders

APIBreaking

Orders from a delivery cart now read as deliveries on GET /v1/orders/:id, and say where the delivery is.

What changed

  • fulfillment.type is pickup or delivery. It was always pickup before.
  • Delivery fields. On a delivery, fulfillment.status is one of finding_courier, heading_to_store, at_store, on_the_way, arriving, delivered or failed; fulfillment.eta is when it should arrive, ISO 8601; and fulfillment.courier is { first_name, vehicle } while a driver is assigned. fulfillment.address is 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" with changed_from: "delivery", and the person collects it from the store. A delivery whose driver could not finish stays a delivery, with status failed.
  • Delivery money in amounts. courier_fee_minor and tip_minor, always 0 before, are now the delivery fee and the driver's tip that were charged: 0 for pickup, for a failed delivery, and for one that became a pickup. charged_minor is 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: null until a person at Layout decides, then from nothing up to what was confirmed. No event is sent when they decide.
    See What the person pays.
  • order.updated on delivery. When the driver has the food and is on the way, when the driver is arriving at a meet_at_door handoff, 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 no order.delivered. Each has its own event_id, numbered with the pickup-detail waves. See Delivery steps.
  • Proof of delivery. fulfillment.proof_photo_url is the driver's photo of an order left at the door, once delivered, and fulfillment.failure_reason says 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 for pickup, and status, eta and courier for delivery.
  • When changed_from is "delivery", tell the person no driver could be booked and to collect the order from store_address.
  • Treat charged_minor: null on a placed delivery as not settled yet, never as nothing charged.
  • Read the order again on every order.updated, and de-duplicate on event_id, never on the order id and event type. Not every step sends one: while status is not delivered or failed, read GET /v1/orders/:id for 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.

All changes