Repository navigation
feat: Introduce Food Checkout Capability and Fulfillment & Tip Extensions - #897
Conversation
… rendering and deep link creations due to potential naming collisions.
|
The operation names ( Two suggestions:
|
|
Thanks @karangoel16 for the feedback! This divergence is actually working as intended based on UCP's core design principles around vertical independence & schema boundaries, specifically:
Because of this, there is intentionally no formal relationship or shared normative schema binding between But with respect to your callout on conformance, it's an interesting one as we took a stab on an earlier proposal in Phase 3 of RFC #520. We wanted to have validations at individual vertical suite level instead of coupling schemas across verticals to achieve this. |
|
Thanks for bringing up this PR @jingyli . Below are some comments about it: 1. Singular Delivery Destination
Because of this mismatch, 2.
|
|
Thanks for opening this early. One gap from where we sit: pickup assumes the buyer walks up to the counter. At Autolane (Austin), a customer's AI agent places a restaurant pickup order, and we send an autonomous vehicle on the customer's behalf to collect it curbside and deliver it. No one walks in; staff load the order into the vehicle. This draft already covers most of that flow: 1. No structured pickup handoff. 2. The collector is assumed to be the buyer, in person. Arrival check-in matters more without a driver: the platform, not a person, has to say "the vehicle is in stall 3." That probably belongs with Get Order, so I've left it out here. We'd like to contribute this. Once the council picks a direction, Autolane can open a PR for either change, or both. |
|
Coordination note on Nothing needs to change here — once this lands I'm happy to send Food the same change as a follow-up. #914 also touches |
|
On the For an agent, though, it is hard to check reliably. The content is free text, and it arrives on a line item after the dish has been chosen. The same gap was raised on the charter in #518 (comment) , asking for a structured dietary-safety field on the item and cart. A small option within this PR: an optional list of allergen codes on the warning, next to the free text, with the code list named, since the lists differ by jurisdiction (14 groups in the EU's Annex II, 9 major allergens in the US). If Filtering at selection time belongs with menu discovery, which this PR leaves out of scope; the menuconform fixtures linked in #786 cover that case. |
… resolution - Update source/schemas/food/types/fulfillment_method.json allOf if/then branches, dependentRequired, and description to target singular destination instead of plural destinations. - Add optional quantity property (integer, minimum 1, default 1) to source/schemas/food/types/modification.json to match the normative Food Checkout specification. - Align REST endpoint paths in source/services/food/rest.openapi.json to /checkout-sessions* to match docs/specification/food/checkout/rest.md and shopping/rest.openapi.json. - Restore UCP $def and allOf Type-column resolution in main.py (dropped during merge from main) and guard env.conf access so scripts/test_schema_tables.py passes.
|
+1 to @frmoretto's allergen codes on the warning. We build an ordering agent for F&B brands in Southeast Asia, and three rules have mattered more to us than the code list itself:
Happy to share our mapping of these onto the current schemas if useful. |
igrigorik
left a comment
There was a problem hiding this comment.
@jingyli thanks, great progress. A few remaining flags...
Tips as an extension
I want to push on this rather than defer it. "Nearly every food checkout tips" is a US-market observation. There are many markets where tips are not common or used at all. Uber Eats' own help pages describe in-app tipping as "available in cities that have the tipping functionality" -- a per-market feature flag. Further we can't make this change later without imposing a large amount of pain, as it would imply a breaking change.
Tips, in sprit, is similar to discount and fulfillment, both of which are negotiated extensions. And the chartered services DTC will almost certainly reach for same common extension capability. Yes, it's more work, but its the right work to do now.
fulfillable_on: "now" -- re-flagging
This was a note in earlier review and didn't get the response. It's the same question the Location hours work settled in #687: the parent draft there had open_now beside open_at, and it collapsed to a single instant because a sentinel makes identical messages mean different things depending on whose clock resolves "now." The shipped rule (Location — Hours-Based Filter): "the value it sends identifies one specific instant … A Business MUST NOT round, shift, or otherwise reinterpret the supplied instant." Each degree of interpretive freedom gets one owner.
fulfillable_on: "now" is the response-side mirror: the Business knows the instant it composed the response and encodes it as a verb; the Platform receives it after latency and reasoning and re-anchors it to its own clock. And food has no "now" — pickup is ~15 minutes out, and the Business already states the instant as the first option's earliest_fulfillment_time; with scheduling present the field does even less.
Ask: remove now and simplify, adopting explicit timestamps in both directions.
Mechanical nitpicks
cart.json:cart_idoncheckout.jsonwith theanyOfis exactly the #940 shape and supports the out-of-band carts you described — that part's right. The file is now redundant as well as unreachable (a profile advertising bothfood.checkoutandfood.cartstill fails composition with multiple root capabilities), and as published it validates{}. Delete it;read: omitoncart_id. (@amithanda's thread.)- Inverted MUSTs at L470–471 and L787–788 — "MUST reject … if … is recognized" / "is supported" — say the opposite of the schema description.
|
Thanks @igrigorik for the follow-up review! Responses to the outstanding flags: Tips as an extensionI'm personally convinced with the argument that
fulfillable_on: "now" -- re-flaggingThis was a miss and should now be addressed. Mechanical nitpicksBoth points are now addressed with the exception of |
igrigorik
left a comment
There was a problem hiding this comment.
Thanks @jingyli, LGTM. 🙇🏻
A couple more nitpicks that I'd love to see fixed before this is merged:
fulfillment.mdL741: the delivery→pickup example still showsStaff Tip (10%) 500in the response totals, but the request sent onlyfulfillment— under the new rule the switch clearsselected_option_idand Unset adds nothing tototals[]. Drop the tip line (total →5438), or show the reselection in a later update. Same edit at L646: "recompute … percentage tips" → "when the Tip Extension is active."index.mdL399:ready_for_complete= "dishes, fulfillment, buyer contact, and tip are valid" — both are optional extensions now; "…and any active extension's inputs are valid."mkdocs.ymlllms description for the checkout page still says "cart and checkout operations."
|
Thanks @jingyli for addressing all the review feedback! |
|
📋 Discussed in UCP Shopping Tech Council (STC) Meeting - 2026-11-06 This pull request was referenced under the following agenda topic(s):
See the full meeting minutes for discussion notes and action items. |
|
Huge congratulations to @jingyli, @amithanda, and the Food DTC on merging #897 and launching Food Checkout on ucp.dev (#1053) right in time for the UCP Summit! The convergence on In travel & transit F&B concessions across airport terminals, motorway plazas, and rail stations, four concrete production patterns reinforce the design choices here and highlight where Phase 2 (Menu, Cart, Get Order, and structured dietary safety) hooks will have outsized impact: 1. Why @igrigorik's
|
Description
On behalf of the entire Food Domain Tech Council, this PR introduces the Checkout Capability (
dev.ucp.food.checkout), Fulfillment Extension (dev.ucp.food.fulfillment), and Tip Extension (dev.ucp.food.tip), establishing the foundational data contracts, state lifecycle, and transport bindings for prepared food and beverage orders in UCP.By standardizing single-establishment order scoping, structured dish customization, order-wide delivery/pickup fulfillment (ASAP or scheduled), and courier/staff gratuity across both REST and MCP transports, this capability enables platforms to facilitate food ordering sessions across diverse food businesses (restaurants, cafes, bakeries, food trucks, ghost kitchens, etc.) while leaving menu authority, kitchen state, pricing calculations, and Merchant of Record (MoR) responsibilities with the business.
Motivation
While retail checkout (
dev.ucp.shopping.checkout) models itemized physical/digital goods with simple quantities and per-item shipments, food commerce introduces distinct transactional dynamics:food_establishment): Prepared food is cooked to order and must leave the kitchen within minutes, so a session is bound to exactly one preparation location. Every dish MUST come from that establishment's live menu.line_item,dish,modification): A line item pairs a menudishwith buyer-selectedmodifications[](protein, spice level, extra toppings, or$0removals/substitutions) and a free-form kitchennote. Two units of the same dish with different modifications or notes are distinct line items, and notes MUST NOT alter price or structured modifications.dev.ucp.food.tip): Courier and counter-staff tips are part of checkout, not an afterthought. Businesses advertise preset options (percentage or absolute); platforms record the buyer's preset or custom choice; the business resolves it into a pricedtotals[]entry.dev.ucp.food.fulfillment): Fulfillment is order-wide (no split destination deliveries), may be ASAP or scheduled for a specific time, and requires structured multi-select handoff preferences (e.g., contactless drop-off, ring doorbell, curbside pickup) plus courier/pickup instructions.#42), a committed fulfillment window, and a live tracking link rather than a static receipt.Scope
In Scope
dev.ucp.food.checkout):incomplete,requires_escalation,ready_for_complete,complete_in_progress,completed,canceled) with deterministic handoffs viacontinue_url(e.g., alcohol ID verification, catering review).actions(step-up work and Accepted Completion),policies,context, andsignals.food_establishment(common/types/location_summary.json, extended withmedia),line_item,dish,modification,buyer, andorder_confirmation.dev.ucp.food.fulfillment): Order-widedelivery/pickupmethods with type-discriminated destinations (delivery_addresswithaddressand/orgeo,business_location), ASAP vs. scheduled timing viarequested_fulfillment_time, priced time-windowoptions[], multi-select handoffpreference_options[]/selected_preference_option_ids[], courier/pickupnotes, andavailable_methods[](withfulfillable_onandscheduling).dev.ucp.food.tip): Business-suggestedoptions[](percentageorabsolute), Platform-selectedselected_option_idorcustom_amount, mutual exclusion (oneOf), and resolution into checkouttotals[]astype: "tip".cart_idsupport on Create Checkout for mutually recognized out-of-band carts, with strict precedence and rejection rules when unsupported or unrecognized.out_of_stock,item_unavailable,modification_required,modification_invalid,note_not_supported,location_closed,fulfillment_time_unavailable,address_undeliverable,minimum_order_unmet.note_contains_modification,preference_option_invalid,preference_option_unavailable,preference_option_combination_disallowed.disclosure-tier warnings:consumer_advisory,allergens,nutritional_info, andtotals_changed./checkout-sessions*.payment_ap2_mandateandpayment_authenticationontodev.ucp.food.checkout.main.pyschema macro renderer for filesystem-discovered verticals, relative$refresolution,$def/allOftype resolution, and path-qualified reference anchors; updatedmkdocs.yml,llms.txtdescriptions,reference.md, and schema test scaffolds.Out of Scope
Design Details
1. Single-Establishment Scope & Shared Menu Identifiers
A session is bound to one
food_establishment(or initialized from a mutually recognizedcart_id). On requests the Platform sends only opaque, menu-backed identifiers (food_establishment.id,line_items[].dish.id,line_items[].modifications[].id) plus buyer inputs (quantity,note); all other attributes are Business-authored.{ "food_establishment": { "id": "est_luigis_01" }, "line_items": [ { "quantity": 2, "dish": { "id": "dish_margherita_12" }, "modifications": [ { "id": "mod_extra_mozzarella" }, { "id": "mod_fresh_basil" } ], "note": "Well done crust, please" }, { "quantity": 1, "dish": { "id": "dish_caesar" }, "note": "Dressing on the side" } ] }On every create/update, the Business authoritatively re-validates against live operating hours, item and ingredient availability, modifier-group rules, delivery coverage, and order minimums, and expands the response with titles, media, prices,
line_items[].totals, andtotals[].2. Dish Customization: Structured Modifications vs. Kitchen Notes
The
line_itementity separates the menudishfrom buyer-selected customization:line_items[].modifications[]$0or more)title/price.line_items[].notemodification.quantityapplies per unit of the dish (default1); repeated units MUST be expressed viaquantity, not repetition, and Businesses MUST NOT infer quantity from duplicate modification IDs.subtotal = (dish.price + Σ(mod.price × mod.quantity)) × line_items[].quantity.noterequests a menu-modeled modifier (at any price, including$0removals/substitutions), the Business SHOULD return anote_contains_modificationwarning (and MAY returnnote_not_supportederror when a kitchen request cannot be honored):{ "type": "warning", "code": "note_contains_modification", "path": "$.line_items[0].note", "content": "\"Add avocado\" is a paid add-on (+$2.50). Select the Avocado modification to add it; notes are passed to the kitchen as-is and cannot add charges." }3. Food Fulfillment Extension (
dev.ucp.food.fulfillment)Shares vocabulary with Shopping Fulfillment (
dev.ucp.shopping.fulfillment) but is deliberately flatter because a food order is cooked, bagged, and handed off together from a single kitchen:line_item_ids[])methods[]→groups[]→options[]methods[]→options[]destinations[]+selected_destination_iddestination, discriminated bytyperequested_fulfillment_time)preference_options[]+selected_preference_option_ids[]+notesdelivery_address(Platform-authoredaddressand/orgeo, at least one required) orbusiness_location(Business-authoredlocation_summary, response-only).requested_fulfillment_timemeans ASAP; an RFC 3339 timestamp means scheduled.available_methods[]advertises supported methods (delivery,pickup), earliestfulfillable_on(RFC 3339 timestamp), andscheduling(asap_only,scheduled_only,asap_and_scheduled). If a requested time is unavailable, the Business returns arecoverablefulfillment_time_unavailable(orlocation_closed) error and SHOULD offer nearest alternativeoptions[].preference_options[]andselected_preference_option_ids[]live on the fulfillment method (methods[]) for both delivery and pickup. In responses,selected_preference_option_ids[]contains only the selections the Business will honor; unhonored or conflicting options are dropped without blockingready_for_completeand reported viapreference_option_*warnings.{ "id": "method_delivery", "type": "delivery", "destination": { "id": "dest_home", "type": "delivery_address", "address": { "street_address": "450 Serra Mall", "extended_address": "Apt 3B", "address_locality": "Stanford", "address_region": "CA", "postal_code": "94305", "address_country": "US" } }, "preference_options": [ { "id": "pref_leave_at_door", "label": "Leave at my door" }, { "id": "pref_hand_to_me", "label": "Hand it to me" }, { "id": "pref_meet_outside", "label": "Meet outside" }, { "id": "pref_ring_bell", "label": "Ring the doorbell" } ], "selected_preference_option_ids": ["pref_leave_at_door", "pref_ring_bell"], "notes": "Gate code #4210, second floor", "selected_option_id": "opt_standard", "options": [ { "id": "opt_priority", "title": "Priority Delivery", "description": "Sent directly to you with no other stops", "earliest_fulfillment_time": "2026-04-10T18:25:00-07:00", "latest_fulfillment_time": "2026-04-10T18:35:00-07:00", "totals": [{ "type": "total", "amount": 599 }] }, { "id": "opt_standard", "title": "Standard Delivery", "earliest_fulfillment_time": "2026-04-10T18:35:00-07:00", "latest_fulfillment_time": "2026-04-10T18:50:00-07:00", "totals": [{ "type": "total", "amount": 299 }] } ] }4. Food Tip Extension (
dev.ucp.food.tip)The
dev.ucp.food.tipextension adds a top-leveltipobject separating what the Business suggests from what the buyer chooses, whiletotals[]holds the resolved money:tip.options[], Business-authored):id,unit(percentage|absolute), andamount(percent or ISO 4217 minor units). No labels — Platforms render"18%","$5".oneOfadmits Preset (selected_option_idon update), Custom (custom_amounton create or update;0= no tip), or Unset (neither set; adds nothing tototals[]until an explicit selection is submitted).subtotalentry intotals[]. Any non-zero selected tip MUST appear as atype: "tip"entry intotals[]withdisplay_textREQUIRED. If a fulfillment switch replacestip.options[]and invalidates a priorselected_option_id, the Business clearsselected_option_idback to Unset and surfaces anoticewarning.{ "tip": { "options": [ { "id": "tip_15", "unit": "percentage", "amount": 15 }, { "id": "tip_18", "unit": "percentage", "amount": 18 }, { "id": "tip_20", "unit": "percentage", "amount": 20 }, { "id": "tip_5usd", "unit": "absolute", "amount": 500 } ], "selected_option_id": "tip_18" }, "totals": [ { "type": "subtotal", "display_text": "Subtotal", "amount": 5000 }, { "type": "fulfillment", "display_text": "Standard Delivery", "amount": 299 }, { "type": "fee", "display_text": "Service & Regulatory Fees", "amount": 550, "lines": [ { "display_text": "Service Fee", "amount": 350 }, { "display_text": "City Courier Regulatory Fee", "amount": 200 } ] }, { "type": "tax", "display_text": "Tax (8.75%)", "amount": 438 }, { "type": "tip", "display_text": "Courier Tip (18%)", "amount": 900 }, { "type": "total", "display_text": "Total", "amount": 7187 } ] }5. Error Handling, Disclosures & Order Confirmation
out_of_stock,item_unavailable,modification_required,modification_invalid,note_not_supported,location_closed,fulfillment_time_unavailable,address_undeliverable,minimum_order_unmet) with precise JSONPathpathtargeting so Platforms can offer targeted recovery.consumer_advisory,allergens,nutritional_info, andtotals_changedusepresentation: "disclosure"and MUST be shown prominently near the referenced item and never auto-dismissed. Operational context (e.g.,high_demand) usesnotice.completed,ordercarriesid(required),tracking_url(required, live preparation/courier status), an optional shortlabelused at the counter, shelf, or locker, and an optional committed fulfillment window (earliest_fulfillment_time/latest_fulfillment_time).{ "order": { "id": "ord_food_9876543210", "label": "#42", "tracking_url": "https://food.example.com/orders/ord_food_9876543210", "earliest_fulfillment_time": "2026-04-10T18:35:00-07:00", "latest_fulfillment_time": "2026-04-10T18:50:00-07:00" } }6. Documentation Engine Enhancement (
main.py)Adding the
foodvertical exposed several assumptions in the schema macro renderer, which previously defaulted toshoppingand resolved$refs by bare filename. Because food and shopping share file names (e.g.,food/fulfillment.jsonvs.shopping/fulfillment.json,food/types/line_item.jsonvs.shopping/types/line_item.json), this produced incorrect cross-links and table contents.main.pywas refactored to:source/schemas/sub-directory exceptcommon/andtransports/), with no vertical treated specially.$refs relative to the containing file first (standard JSON Schema semantics), falling back to name-based lookup across protocol, common, the active vertical, and — only if unambiguous — other verticals.#food-types-fulfillment) fromauto_generate_schema_reference, so schemas sharing a title across verticals remain individually addressable, and point every type link to the page that actually renders that schema.reference.mdnow passes an explicitbase_dirfor shopping and adds food sections alongside common, shopping, and lodging.Category (Required)
ucp-schematool (resolver, linter, validator). (Requires Maintainer approval)Related Issues
#518
Checklist
!for breaking changes).Screenshots / Logs (if applicable)