Delivery on carts

API

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

  • delivery on GET /v1/whoami. true when the key can deliver now. false, or no delivery field, means delivery is paused for the application right now: build pickups, and there is nothing to request.
  • fulfillment and tip on POST /v1/carts. fulfillment is "pickup" (the default) or { "type": "delivery", "address": "...", "unit": "...", "instructions": "...", "handoff": "meet_at_door", "kind": "work" }, every field but type optional. kind is personal (the default) or work. tip is { "percent": 18 } or { "minor": 300 }; leave it out for the lowest preset, or send { "percent": 0 } for none. A tip sent with a pickup is 400 invalid_request, and so is a unit and instructions longer 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 new 409 delivery_unavailable with error.reason and error.userMessage, and the cart is left as it was. A tip sent alone to a cart that is a pickup is the new 409 not_delivery.
  • Over MCP. Build sessions and OAuth connections take deliverTo, deliveryUnit, deliveryInstructions, addressKind and tipPercent or tipMinor on order build, with the same rules as REST: tipPercent is a whole number from 0 to 100, tipMinor is 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 no deliverTo builds nothing and answers deliveryUnavailable.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.
  • fulfillment on every priced cart. type, dropoff.line (the street and unit the driver goes to), courierFeeMinor, tip with its presets, and deliveryUnavailable. fees gains courierFeeMinor and tipMinor, both 0 on a pickup.
  • When delivery cannot happen at cart creation, or at confirm when the price cannot be renewed, the cart is a pickup and deliveryUnavailable gives a reason on every read. Confirming it is refused with 409 delivery_unavailable until you send pickup, or a delivery that works, so nobody gets a pickup they did not choose.
  • confirmationCard on 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_quotes and address_lookups, in error.limit.name and on GET /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 as 429 rate_limited with error.limit.scope "account". Sending the same address again to /fulfillment while 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:

  1. Ask the person where to deliver, and send it as address, with unit apart. Send kind: "work" when they called it their work address; do not ask them just for it.
  2. Read fulfillment.type on the ready cart, and read fulfillment.dropoff.line, the fee, the tip and totalMinor back to the person.
  3. Confirm with totalMinor, exactly as the cart gives it. On 409 price_changed, pickup or delivery, read the cart: while it is ready, show the person its new totalMinor and confirm with it; when it is failed or expired, build a fresh cart. On 409 delivery_unavailable, show error.userMessage, then send pickup or another address.
  4. 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.

All changes