Delivery on carts
Carts are still pickup by default. Delivery is on for every application, sandbox and production, and a cart can now be a delivery instead: the same order, collected from the store by a driver Layout books and brought to the person. The whole path is on Delivery.
What changed
deliveryonGET /v1/whoami.truewhen the key can deliver now.false, or nodeliveryfield, means delivery is paused for the application right now: build pickups, and there is nothing to request.fulfillmentandtiponPOST /v1/carts.fulfillmentis"pickup"(the default) or{ "type": "delivery", "address": "...", "unit": "...", "instructions": "...", "handoff": "meet_at_door", "kind": "work" }, every field buttypeoptional.kindispersonal(the default) orwork.tipis{ "percent": 18 }or{ "minor": 300 }; leave it out for the lowest preset, or send{ "percent": 0 }for none. A tip sent with a pickup is400 invalid_request, and so is aunitandinstructionslonger than 280 characters together, counting 3 for the separator.POST /v1/carts/:id/fulfillment. Changes a ready cart to pickup or delivery, its address, unit or notes, or the tip. It is all or nothing: a change that cannot happen is the new409 delivery_unavailablewitherror.reasonanderror.userMessage, and the cart is left as it was. A tip sent alone to a cart that is a pickup is the new409 not_delivery.- Over MCP. Build sessions and OAuth connections take
deliverTo,deliveryUnit,deliveryInstructions,addressKindandtipPercentortipMinoronorderbuild, with the same rules as REST:tipPercentis a whole number from 0 to 100,tipMinoris up to 5000, never both, and the unit and driver notes together fit in 280 characters. A build session chooses delivery when it builds, and builds again to change it; a delivery with nodeliverTobuilds nothing and answersdeliveryUnavailable.reason: "no_address". On an OAuth connection,action: "fulfillment"also changes a carted build. - The address. You send it with each cart; Layout never shares a person's saved addresses with an application. Once the order is placed, Layout saves it to the person's Layout account, filed under
kind, unless they already have it there or 6 of their 8 saved addresses are used. It never becomes their default over one they have. Driver notes stay with the order. fulfillmenton every priced cart.type,dropoff.line(the street and unit the driver goes to),courierFeeMinor,tipwith itspresets, anddeliveryUnavailable.feesgainscourierFeeMinorandtipMinor, both0on a pickup.- When delivery cannot happen at cart creation, or at confirm when the price cannot be renewed, the cart is a pickup and
deliveryUnavailablegives areasonon every read. Confirming it is refused with409 delivery_unavailableuntil you send pickup, or a delivery that works, so nobody gets a pickup they did not choose. confirmationCardon a delivery cart. On a person's token it states the address, the service fee, the delivery fee, the tip, the total and the card that will be billed.- Two new limit names.
delivery_quotesandaddress_lookups, inerror.limit.nameand onGET /v1/usage. Each is counted per person, per application and per developer account, across its applications: 3,000 quotes and 1,000 address lookups a day for the account, refused as429 rate_limitedwitherror.limit.scope"account". Sending the same address again to/fulfillmentwhile the cart's quote has more than two minutes left reuses it and is not counted, and sandbox counts toward neither. See the numbers.
Why it matters
Your product can offer delivery from the same restaurants with the same flow: one cart, one total, one confirm. The person sees the delivery fee and the tip before they say yes, and when Layout texts them a code, it names the street and city the order goes to.
What to do
Nothing, if you only offer pickup. To offer delivery:
- Ask the person where to deliver, and send it as
address, withunitapart. Sendkind: "work"when they called it their work address; do not ask them just for it. - Read
fulfillment.typeon the ready cart, and readfulfillment.dropoff.line, the fee, the tip andtotalMinorback to the person. - Confirm with
totalMinor, exactly as the cart gives it. On409 price_changed, pickup or delivery, read the cart: while it isready, show the person its newtotalMinorand confirm with it; when it isfailedorexpired, build a fresh cart. On409 delivery_unavailable, showerror.userMessage, then send pickup or another address. - Say in your privacy notice that a delivery address is kept in the person's Layout account.
To try every ending in sandbox, send simulate inside the delivery fulfillment, or, from CLI 0.5.4, run layout test-order --deliver-to "500 Howard St" --courier <ending>. See Test every ending.
Breaking changes
None for a client that ignores fields it does not know. Every cart now carries fulfillment, and fees carries courierFeeMinor and tipMinor, both 0 for pickup. A person can also switch your cart to delivery in Layout, and then totalMinor includes the fee and tip, so keep confirming with totalMinor rather than adding up fees.