Skip to content

feat: Introduce Food Checkout Capability and Fulfillment & Tip Extensions - #897

Merged
jingyli merged 22 commits into
mainfrom
food/checkout
Nov 10, 2026
Merged

jingyli merged 22 commits into
mainfrom
food/checkout

Conversation

@jingyli

@jingyli jingyli commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

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:

  1. Single-Kitchen Freshness Window (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.
  2. Configured Dishes, Not SKUs (line_item, dish, modification): A line item pairs a menu dish with buyer-selected modifications[] (protein, spice level, extra toppings, or $0 removals/substitutions) and a free-form kitchen note. Two units of the same dish with different modifications or notes are distinct line items, and notes MUST NOT alter price or structured modifications.
  3. Volatile Kitchen State: Menus, prices, and prep times seen during discovery are provisional. Dishes get 86'd mid-service, kitchens pause intake under load, and menus switch between dayparts. Every create/update must re-validate against live kitchen state and return authoritative totals and targeted, recoverable errors.
  4. Gratuity as a First-Class Extension (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 priced totals[] entry.
  5. Delivery vs. Pickup, Now vs. Later (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.
  6. Food-Safety Disclosures & Live Handoff: Statutory consumer advisories, allergen, and nutrition notices must be rendered prominently, and on completion buyers need a short callout label (e.g., #42), a committed fulfillment window, and a live tracking link rather than a static receipt.

Scope

In Scope

  • Core Checkout Capability (dev.ucp.food.checkout):
    • Full session lifecycle (incomplete, requires_escalation, ready_for_complete, complete_in_progress, completed, canceled) with deterministic handoffs via continue_url (e.g., alcohol ID verification, catering review).
    • Common checkout features including actions (step-up work and Accepted Completion), policies, context, and signals.
    • Food entities: food_establishment (common/types/location_summary.json, extended with media), line_item, dish, modification, buyer, and order_confirmation.
  • Fulfillment Extension (dev.ucp.food.fulfillment): Order-wide delivery / pickup methods with type-discriminated destinations (delivery_address with address and/or geo, business_location), ASAP vs. scheduled timing via requested_fulfillment_time, priced time-window options[], multi-select handoff preference_options[] / selected_preference_option_ids[], courier/pickup notes, and available_methods[] (with fulfillable_on and scheduling).
  • Tip Extension (dev.ucp.food.tip): Business-suggested options[] (percentage or absolute), Platform-selected selected_option_id or custom_amount, mutual exclusion (oneOf), and resolution into checkout totals[] as type: "tip".
  • Out-of-Band Cart-to-Checkout Conversion: cart_id support on Create Checkout for mutually recognized out-of-band carts, with strict precedence and rejection rules when unsupported or unrecognized.
  • Food-Specific Error, Warning & Disclosure Codes:
    • Recoverable kitchen/fulfillment errors: out_of_stock, item_unavailable, modification_required, modification_invalid, note_not_supported, location_closed, fulfillment_time_unavailable, address_undeliverable, minimum_order_unmet.
    • Warnings: note_contains_modification, preference_option_invalid, preference_option_unavailable, preference_option_combination_disallowed.
    • disclosure-tier warnings: consumer_advisory, allergens, nutritional_info, and totals_changed.
  • Transport Bindings: Complete REST (OpenAPI 3.1) and MCP (OpenRPC / tool definitions) specifications and examples at /checkout-sessions*.
  • Payment Extension Interoperability: Wiring of payment_ap2_mandate and payment_authentication onto dev.ucp.food.checkout.
  • Documentation & Tooling Enhancements: Refactored main.py schema macro renderer for filesystem-discovered verticals, relative $ref resolution, $def/allOf type resolution, and path-qualified reference anchors; updated mkdocs.yml, llms.txt descriptions, reference.md, and schema test scaffolds.

Out of Scope

  • Upstream menu search/discovery service (dish and modification IDs are assumed to come from upper-funnel discovery) & gradual cart building.
  • Post-purchase order management (order status webhooks, modifications, cancellations, refunds, substitutions).
  • Multi-establishment baskets (e.g., food halls / multi-vendor orders) and group ordering.
  • Catering-specific attributes (headcount, setup, deposits) and table reservations / dine-in ordering.

Design Details

1. Single-Establishment Scope & Shared Menu Identifiers

A session is bound to one food_establishment (or initialized from a mutually recognized cart_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, and totals[].

2. Dish Customization: Structured Modifications vs. Kitchen Notes

The line_item entity separates the menu dish from buyer-selected customization:

Mechanism Field Priced? Contract
Structured modifications line_items[].modifications[] Yes ($0 or more) Menu-backed IDs; Business validates modifier-group rules (required choices, min/max, mutual exclusion) and echoes title / price.
Special instructions line_items[].note No Free-form kitchen text. MUST NOT alter price or structured modifications.
  • modification.quantity applies per unit of the dish (default 1); repeated units MUST be expressed via quantity, not repetition, and Businesses MUST NOT infer quantity from duplicate modification IDs.
  • Line arithmetic: subtotal = (dish.price + Σ(mod.price × mod.quantity)) × line_items[].quantity.
  • When a note requests a menu-modeled modifier (at any price, including $0 removals/substitutions), the Business SHOULD return a note_contains_modification warning (and MAY return note_not_supported error 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:

Dimension Shopping Fulfillment Food Fulfillment
Scope Per line item (line_item_ids[]) Whole order
Hierarchy methods[] → groups[] → options[] methods[] → options[]
Destination destinations[] + selected_destination_id One destination, discriminated by type
Timing Chosen only from Business options Platform may request a time (requested_fulfillment_time)
Handoff — preference_options[] + selected_preference_option_ids[] + notes
  • Destinations: delivery_address (Platform-authored address and/or geo, at least one required) or business_location (Business-authored location_summary, response-only).
  • Timing & Availability: Omitting requested_fulfillment_time means ASAP; an RFC 3339 timestamp means scheduled. available_methods[] advertises supported methods (delivery, pickup), earliest fulfillable_on (RFC 3339 timestamp), and scheduling (asap_only, scheduled_only, asap_and_scheduled). If a requested time is unavailable, the Business returns a recoverable fulfillment_time_unavailable (or location_closed) error and SHOULD offer nearest alternative options[].
  • Multi-Select Handoff Preferences: preference_options[] and selected_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 blocking ready_for_complete and reported via preference_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.tip extension adds a top-level tip object separating what the Business suggests from what the buyer chooses, while totals[] holds the resolved money:

  • Suggestions (tip.options[], Business-authored): id, unit (percentage | absolute), and amount (percent or ISO 4217 minor units). No labels — Platforms render "18%", "$5".
  • Choice (Platform-authored): oneOf admits Preset (selected_option_id on update), Custom (custom_amount on create or update; 0 = no tip), or Unset (neither set; adds nothing to totals[] until an explicit selection is submitted).
  • Resolution: Percentage options are computed against the pre-discount subtotal entry in totals[]. Any non-zero selected tip MUST appear as a type: "tip" entry in totals[] with display_text REQUIRED. If a fulfillment switch replaces tip.options[] and invalidates a prior selected_option_id, the Business clears selected_option_id back to Unset and surfaces a notice warning.
{
  "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

  • Recoverable kitchen-state errors: In addition to shared standard errors, food Businesses SHOULD use food-specific codes (out_of_stock, item_unavailable, modification_required, modification_invalid, note_not_supported, location_closed, fulfillment_time_unavailable, address_undeliverable, minimum_order_unmet) with precise JSONPath path targeting so Platforms can offer targeted recovery.
  • Disclosures: consumer_advisory, allergens, nutritional_info, and totals_changed use presentation: "disclosure" and MUST be shown prominently near the referenced item and never auto-dismissed. Operational context (e.g., high_demand) uses notice.
  • Order confirmation: On completed, order carries id (required), tracking_url (required, live preparation/courier status), an optional short label used 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 food vertical exposed several assumptions in the schema macro renderer, which previously defaulted to shopping and resolved $refs by bare filename. Because food and shopping share file names (e.g., food/fulfillment.json vs. shopping/fulfillment.json, food/types/line_item.json vs. shopping/types/line_item.json), this produced incorrect cross-links and table contents.
main.py was refactored to:

  • Discover verticals from the filesystem (every source/schemas/ sub-directory except common/ and transports/), with no vertical treated specially.
  • Resolve $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.
  • Emit path-qualified reference anchors (e.g., #food-types-fulfillment) from auto_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.md now passes an explicit base_dir for shopping and adds food sections alongside common, shopping, and lodging.

Category (Required)

  • Core Protocol: Changes to the base communication layer, global context, or breaking refactors. (Requires Technical Council approval)
  • Governance/Contributing: Updates to GOVERNANCE.md, CONTRIBUTING.md, or CODEOWNERS. (Requires Governance Council approval)
  • Capability: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
  • Documentation: Updates to README, or documentations regarding schema or capabilities. (Requires Maintainer approval)
  • Infrastructure: CI/CD, Linters, or build scripts. (Requires DevOps Maintainer approval)
  • Maintenance: Version bumps, lockfile updates, or minor bug fixes. (Requires DevOps Maintainer approval)
  • SDK: Language-specific SDK updates and releases. (Requires DevOps Maintainer approval)
  • Samples / Conformance: Maintaining samples and the conformance suite. (Requires Maintainer approval)
  • UCP Schema: Changes to the ucp-schema tool (resolver, linter, validator). (Requires Maintainer approval)
  • Community Health (.github): Updates to templates, workflows, or org-level configs. (Requires DevOps Maintainer approval)

Related Issues

#518

Checklist

  • I have followed the Contributing Guide (including Conventional Commits title requirements and ! for breaking changes).
  • I have updated the documentation (if applicable).
  • My changes pass all local linting and formatting checks.
  • I have added tests that prove my fix is effective or that my feature works.
  • New and existing unit tests pass locally with my changes.
  • (For Core/Capability) I have included/updated the relevant JSON schemas.
  • I have regenerated Python Pydantic models by running generate_models.sh under python_sdk.

Screenshots / Logs (if applicable)

food-checkout

@damaz91 damaz91 added the status:needs-triage Signal that the PR is ready for human triage label Oct 3, 2026
@karangoel16

Copy link
Copy Markdown
Contributor

The operation names (create_checkout, complete_checkout, etc.) are now defined in both dev.ucp.shopping.checkout and dev.ucp.food.checkout, and shared concepts are already diverging: shopping's order_confirmation requires permalink_url, food's has tracking_url instead; line_item means SKU+quantity in one and dish+modifications in the other. Nothing documents the relationship between the two shapes.

Two suggestions:

  1. Keep one normative description of the shared operation semantics and reference it from both capabilities instead of restating it.
  2. Add conformance coverage asserting both honor the shared behavior (idempotency, consent gating, platform-performs). As verticals multiply, that's what keeps the shape stable.

@damaz91 damaz91 added status:under-review gov:needs-tc-review Requires review and approval from the Technical Council area:food Issues and pull requests related to the Food ordering vertical and removed status:needs-triage Signal that the PR is ready for human triage labels Oct 5, 2026
@jingyli

jingyli commented Oct 5, 2026

Copy link
Copy Markdown
Contributor Author

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:

  • Services define vertical-specific domains: types & capabilities within these verticals are decoupled and independent (ref from our core concept architecture diagram)
  • Only constructs in the common service (dev.ucp.common.*) are shared across verticals
  • While operations and types might share intuitive names across some verticals (e.g., checkout, fulfillment, order_confirmation, line_items, etc.), they are designed to fit their specific vertical domain models rather than conform to an artificial shared inheritance.

Because of this, there is intentionally no formal relationship or shared normative schema binding between dev.ucp.shopping.checkout and dev.ucp.food.checkout —coupling them would restrict verticals from evolving independently.

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.

Comment thread source/schemas/food/types/buyer.json Resolved
@iantrainor iantrainor added the area:payments Issues and pull requests related to the Payments vertical label Oct 5, 2026
@niranjanmanjunath
niranjanmanjunath self-requested a review October 5, 2026 17:35
@niranjanmanjunath

Copy link
Copy Markdown
Contributor

Thanks for bringing up this PR @jingyli . Below are some comments about it:

1. Singular Delivery Destination

source/schemas/food/types/fulfillment_method.json: allOf and dependentRequired still reference destinations (plural) instead of destination

fulfillment_method.json defines singular "destination": { "$ref": "fulfillment_destination.json" } (line 21), but the allOf if/then branches and dependentRequired (lines 45–99) targets "destinations" as an array.

Because of this mismatch, method.destination isn't narrowed to delivery_destination.json / location_destination.json (or marked ucp_request: "omit" for pickup) based on method.type, and dependentRequired doesn't enforce type when destination is present.

2. source/schemas/food/types/modification.json: Missing quantity property

docs/specification/food/checkout/index.md normatively defines modification.quantity (under both Dish Customization and Entities → Modification), including:

  • Defaulting to 1 when omitted,
  • Requiring quantity > 1 rather than repeating modification ids, and
  • Using modifications[].quantity in the line-item subtotal formula.

However, source/schemas/food/types/modification.json only defines id, title, description, price, and media, so quantity is missing from the schema and from the rendered Modification tables in food/checkout/index.md and reference.md. We should add quantity ("type": "integer", "minimum": 1, "default": 1) to modification.json.

3. REST Endpoint Path Mismatch (/checkouts vs. /checkout-sessions)

source/services/food/rest.openapi.json defines all paths as /checkouts, /checkouts/{id}, /checkouts/{id}/complete, and /checkouts/{id}/cancel.
docs/specification/food/checkout/rest.md (both the Operations table and every HTTP request example) uses /checkout-sessions, /checkout-sessions/{id}, /checkout-sessions/{id}/complete, and /checkout-sessions/{id}/cancel (matching shopping/rest.openapi.json).

Should we align source/services/food/rest.openapi.json and docs/specification/food/checkout/rest.md on the intended path naming (/checkout-sessions to stay consistent with shopping, or update rest.md to /checkouts if intentional).

@chad-agate

Copy link
Copy Markdown

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: requested_fulfillment_time for the slot, method notes, and order.label plus tracking_url at completion. Two gaps:

1. No structured pickup handoff. preference_options[] and selected_preference_option_ids[] exist only on delivery_address. The pickup destination is response-only, so a business can't offer "Counter", "Curbside" or "Pickup shelf", and the platform can't pick one. For a vehicle, curbside is the only handoff that works, and today it can only go in free-text notes. Shopping's method type is open ("Businesses MAY use additional values") and shows "Curbside Pickup" as an option title; food's is a closed delivery | pickup enum. Would the council take handoff preferences on pickup, or should curbside come in as a negotiated extension?

2. The collector is assumed to be the buyer, in person. buyer is the only party on the order. An optional collector on the pickup method would tell staff who or what to hand the order to: a person (name, phone) or a vehicle (description, stall or parking spot, dispatch phone). That covers a friend, a courier the buyer booked, or an autonomous vehicle. notes can carry it, but a business can't validate free text or count on showing it at handoff.

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.

@yingzhehu-TT

Copy link
Copy Markdown
Contributor

Coordination note on food/rest.openapi.json: it follows the current shopping layout, so Authorization, Content-Type and Accept are header parameters and there is no components.securitySchemes. #716 (for #668) moves shopping, common and lodging to securitySchemes plus a document-level security, keeping {} so authentication stays optional, and #914 keeps the HTTP Headers tables listing those headers.

Nothing needs to change here — once this lands I'm happy to send Food the same change as a follow-up. #914 also touches header_fields, which this PR refactors, so whichever lands second will need a small rebase; if it's mine, I'll take care of it.

@frmoretto

Copy link
Copy Markdown

On the allergens disclosure: it works for the person reviewing the checkout, and in the EU it fits the rule for non-prepacked food sold at a distance, where allergen information has to be available before the purchase is concluded (Regulation (EU) No 1169/2011, Art. 14(2) with Art. 44(1)(a)).

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 buyer.json later gets dietary_restrictions, as mentioned in the review thread, a platform could flag a conflict before complete_checkout.

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.
@sawzhang

Copy link
Copy Markdown

+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:

  1. A status, not just a family. contains, may_contain (shared equipment) and free_of are different facts, and only the business can assert free_of. Something like allergens: [{code, status, source}] on the dish or the warning, where source says who declared it (the business, a supplier sheet).

  2. Absence is "not recorded", never "safe". If a family isn't listed, the spec should say in normative text that a platform MUST NOT present the dish as free of it. Without that line, a dish with no allergen message reads as clear, which is the most dangerous default for the one buyer who asked.

  3. A buyer restriction can only tighten. If buyer gains dietary_restrictions, the business MAY use it to refuse or warn, and MUST NOT use it to clear anything. A line that conflicts with a stated restriction could carry code: allergen_conflict with severity: requires_buyer_review, so the session can't reach ready_for_complete until the buyer has seen why.

Happy to share our mapping of these onto the current schemas if useful.

@igrigorik igrigorik left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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_id on checkout.json with the anyOf is 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 both food.checkout and food.cart still fails composition with multiple root capabilities), and as published it validates {}. Delete it; read: omit on cart_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.

@jingyli

jingyli commented Nov 4, 2026

Copy link
Copy Markdown
Contributor Author

Thanks @igrigorik for the follow-up review! Responses to the outstanding flags:

Tips as an extension

I'm personally convinced with the argument that tips may not be a core concept for markets outside of NA & LATAM (e.g., APAC). I'm open to splitting it out into a standalone extension (and should be addressed in cf44d56). However, a couple of related points:

  • Uber Eats example: This actually highlights an adjacent problem on why our current discovery & negotiation mechanism via .well-known/ucp today doesn't solve per-market extension activation well. Because /.well-known/ucp is origin-scoped, a multi-market platform serves one origin profile will need to cover both tipping and non-tipping markets. It cannot offer any per-market feature flag cleanly (e.g., not negotiate tips extension with platforms in APAC countries like Japan because tips is not supported at all).
  • Cross-vertical reuse (common/ vs. vertical scope): Neither discount nor fulfillment lives in common/ today because their domain shapes may diverge across verticals. In a future Services vertical, gratuity may appear in a different shape (e.g., the need to support split-recipient tip). I'd like to avoid prematurely defining it in the common/ service before the actual Services DTC gets an opportunity to consider its domain model.

fulfillable_on: "now" -- re-flagging

This was a miss and should now be addressed.

Mechanical nitpicks

Both points are now addressed with the exception of read: omit annotation per discussion in #897 (comment).

@jingyli jingyli changed the title feat: Introduce Food Checkout Capability and Fulfillment Extension feat: Introduce Food Checkout Capability and Fulfillment & Tip Extensions Nov 4, 2026

@igrigorik igrigorik left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @jingyli, LGTM. 🙇🏻

A couple more nitpicks that I'd love to see fixed before this is merged:

  • fulfillment.md L741: the delivery→pickup example still shows Staff Tip (10%) 500 in the response totals, but the request sent only fulfillment — under the new rule the switch clears selected_option_id and Unset adds nothing to totals[]. 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.md L399: 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.yml llms description for the checkout page still says "cart and checkout operations."

@amithanda

Copy link
Copy Markdown
Contributor

Thanks @jingyli for addressing all the review feedback!

@damaz91

damaz91 commented Nov 10, 2026

Copy link
Copy Markdown
Contributor

📋 Discussed in UCP Shopping Tech Council (STC) Meeting - 2026-11-06

This pull request was referenced under the following agenda topic(s):

  • Donations and Food Domain Working Group Approvals (view section)

See the full meeting minutes for discussion notes and action items.

@jingyli
jingyli merged commit 2d8ce98 into main Nov 10, 2026
18 checks passed
@jingyli
jingyli deleted the food/checkout branch November 10, 2026 18:15
@github-actions github-actions Bot added the enhancement New feature or request label Nov 10, 2026
@andrea-alberto

Copy link
Copy Markdown

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 line_item (dish + sibling modifications[] + note) and lifting preference_options[] onto fulfillment_method makes the foundation super clean.

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 eligibility pattern (review point #10: buyer.dietary_restrictions → Business-evaluated allergen_conflict) is essential for modifications[]

In the thread with @frmoretto and @sawzhang (#964), moving static dish-level allergen declarations to Phase 2's Menu capability while keeping Checkout on the eligibility pattern (buyer.dietary_restrictions in, typed allergen_conflict / restriction_unsupported out) directly reflects how food is actually customized and ordered:

  • Modifier-driven allergen mutation: A base dish rarely tells the full food-safety story once customer options are applied. Adding mod_pesto_sauce introduces tree_nuts and milk to an otherwise clear dish; adding mod_sesame_dressing introduces sesame. Conversely, requesting mod_gluten_free_bun or mod_no_cheese changes the recipe formulation, but whether that clears the hazard or still carries cross-contact warnings depends on the establishment's prep line declarations.
  • Why client-side diffing is hazardous: A buyer's AI agent cannot safely compute the net allergen outcome by guessing or diffing modifiers client-side. Having the Business server authoritatively evaluate buyer.dietary_restrictions against the configured line_item (dish + modifications[]) at checkout—returning a typed allergen_conflict or restriction_unsupported—keeps EU Reg. 1169/2011 food-safety compliance deterministic and server-authoritative.

2. Modular Adoption: Full-Menu AI Discovery vs. Curated "Grab-and-Go" Checkout Subset

Many travel F&B operations do not offer consumer mobile apps because cooked-to-order items cannot be prepared remotely during peak rushes, whereas a curated subset of the menu (signature panini, fresh grab-and-go boxes, bakery, express coffee) has standardized, fast prep procedures ideal for remote agentic ordering:

  • When the council designs Phase 2's Menu (dev.ucp.food.menu), allowing establishments to expose their full menu for AI search/discovery (so a traveler's agent can find restaurants that fit their schedule and dietary needs) while marking which dishes are eligible for remote dev.ucp.food.checkout vs. dine-in/counter-only (echoing the STC discussion on checkout eligibility) will unlock rapid adoption from operators who want UCP checkout on a high-velocity product subset first.

3. Airport In-Terminal ("Deliver-to-Gate") & Indoor Concourse Topology (fulfillment_method.json)

Lifting preference_options[] / selected_preference_option_ids[] onto fulfillment_method.json cleanly supports express shelves and smart lockers (pref_express_shelf, pref_heated_locker) alongside pref_counter and pref_curbside. In transit hubs, two additional fulfillment mechanics arise for Phase 2:

  • Indoor Terminal / Gate Delivery & Security Boundaries: Airport concessions increasingly offer delivery to boarding gates or lounges. Standard 2D WGS 84 geo coordinates and street postal addresses cannot represent Terminal / Concourse / Gate / Security Zone (Airside Schengen vs. Non-Schengen vs. Landside)—where two points 40 meters apart are separated by security checkpoints.
  • Slot Commitment vs. Arrival Kitchen Firing (check_in / prep_release): At checkout, the capacity window is locked via selected_option_id (options[].earliest_fulfillment_time / latest_fulfillment_time). In Phase 2 (Get Order / Post-Purchase), pairing that committed window with a lightweight arrival check-in / prep-release signal (echoing @chad-agate's curbside check-in point) prevents hot food and espresso from sitting 20 minutes early when a highway driver or connecting flight is delayed.

4. Fulfillment Mode & Handoff Impact on European VAT Calculation

To reinforce the contract that totals[] (tax) is strictly Business-computed on every update_checkout: in several EU jurisdictions, statutory VAT rates on food shift based on handoff mode and temperature (e.g., takeaway grab-and-go vs. on-premise consumption). Keeping full-replacement update_checkout authoritative over totals[] handles European fiscal compliance cleanly.

Happy to contribute transit F&B test fixtures and collaborate on the Phase 2 Menu, Order, and Dietary Restrictions working groups once the post-Summit dust settles!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:food Issues and pull requests related to the Food ordering vertical area:payments Issues and pull requests related to the Payments vertical enhancement New feature or request gov:needs-tc-review Requires review and approval from the Technical Council status:under-review

Projects

None yet

Development

Successfully merging this pull request may close these issues.