Skip to content

feat(order): carry Checkout fulfillment selection onto expectations - #617

Open
hemanth wants to merge 5 commits into
Universal-Commerce-Protocol:mainfrom
hemanth:feat/fulfillment-event-linkage
Open

hemanth wants to merge 5 commits into
Universal-Commerce-Protocol:mainfrom
hemanth:feat/fulfillment-event-linkage

Conversation

@hemanth

@hemanth hemanth commented Jul 20, 2026 •

Copy link
Copy Markdown

Closes #347

Carries the Checkout fulfillment selection and delivery window onto Order expectations, the buyer-facing promise that exists from order creation (fulfillment events remain an append-only shipment log).

Changes

  • source/schemas/shopping/types/expectation.json:
    • Adds optional fulfillment_option ($ref: "fulfillment_option.json"), a snapshot of the fulfillment option selected for these items at Checkout. Never updated if the promise changes, and its id need not still resolve. Order totals remain authoritative.
    • Adds optional earliest_fulfillment_time and latest_fulfillment_time (RFC 3339) for the ready or arrival window, initially matching the selected Checkout option's window and updated if the promise changes (same field names as fulfillment_option and food order_confirmation in feat: Introduce Food Checkout Capability and Fulfillment & Tip Extensions #897).
  • docs/specification/shopping/order/index.md:

Motivation

Follows the optional Order snapshot pattern established by list_price (#1016 / #1031) so Businesses that retain the selected Checkout fulfillment option can surface it on Order expectations without making it mandatory, while keeping the original Checkout promise separate from later post-purchase updates (as requested on #347 and #532). Drops the earlier event-level fields (fulfillment_method_id was redundant with method_type and destination).

Add optional fields to fulfillment_event.json that connect post-purchase
tracking events back to checkout fulfillment selections:

- fulfillment_method_id: references the method selected at checkout
- fulfillment_option_id: references the specific option (e.g. express)
- estimated_delivery: earliest/latest delivery window, revisable over time

All fields are optional — backwards compatible.

Closes Universal-Commerce-Protocol#347
@damaz91 damaz91 added the status:needs-triage Signal that the PR is ready for human triage label Jul 20, 2026
@carolinerg1 carolinerg1 added status:under-review and removed status:needs-triage Signal that the PR is ready for human triage labels Jul 22, 2026
@carolinerg1 carolinerg1 added the gov:needs-tc-review Requires review and approval from the Technical Council label Jul 22, 2026
@damaz91 damaz91 added status:stale-review Applied if a PR is waiting on a reviewer for too long and removed status:under-review labels Aug 12, 2026
@damaz91 damaz91 added the area:shopping Issues and pull requests related to the Shopping vertical label Sep 24, 2026
@gsmith85 gsmith85 added this to the 2026-12-08 milestone Oct 14, 2026
@Fate-Wen Fate-Wen mentioned this pull request Nov 12, 2026
1 of 8 tasks
Moves Checkout fulfillment carry-through from append-only fulfillment events
to Order expectations, following the optional Checkout-snapshot pattern
established by list_price (Universal-Commerce-Protocol#1016 / Universal-Commerce-Protocol#1031) and purchase_option (Universal-Commerce-Protocol#890):

- Restore fulfillment_event.json to main.
- Add optional earliest_fulfillment_time and latest_fulfillment_time
  (RFC 3339) on expectation.json for the current ready or arrival window.
- Add optional fulfillment_option snapshot ( fulfillment_option.json)
  on expectation.json for the Checkout selection as it stood at purchase.
- Document the normative snapshot contract in docs/specification/shopping/order/index.md.
@gsmith85

Copy link
Copy Markdown
Contributor

Thanks @hemanth for opening #347 and putting up this PR, and sorry for the delay getting review eyes on it.

Because fulfillment.events[] is an append-only shipment log (empty at order creation and duplicated across partial shipments), carrying the Checkout selection and current delivery window works much better on fulfillment.expectations[], which exists from order creation and represents the active buyer-facing delivery promise.

I merged main and pushed a proposed commit (b3d90fde) on top of your branch (non-destructive, so easy to revert or adjust) that mirrors the optional Checkout-snapshot pattern we recently landed for list_price (#1016 / #1031) and purchase_option (#890):

  • Restores fulfillment_event.json to main.
  • Adds optional earliest_fulfillment_time and latest_fulfillment_time (RFC 3339) on expectation.json for the current ready or arrival window (matching the existing field names on fulfillment_option and order_confirmation in feat: Introduce Food Checkout Capability and Fulfillment & Tip Extensions #897).
  • Adds an optional fulfillment_option snapshot ($ref: "fulfillment_option.json") on expectation.json capturing the option as it stood at Checkout, with concise normative language in docs/specification/shopping/order/index.md keeping Order totals authoritative.

We are flagging #347 / #617 as our featured Community Contribution in this Friday's Shopping Tech Council (Nov 20) to confirm direction and check whether fulfillment_option should live directly on core expectation.json or compose via dev.ucp.shopping.fulfillment. Let us know what you think of this shape!

@gsmith85 gsmith85 changed the title feat: link fulfillment events to checkout fulfillment selections feat(order): carry Checkout fulfillment selection onto expectations Nov 18, 2026

This branch has not been deployed

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

Labels

area:shopping Issues and pull requests related to the Shopping vertical gov:needs-tc-review Requires review and approval from the Technical Council status:stale-review Applied if a PR is waiting on a reviewer for too long

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Fulfillment extension and order events are disconnected

4 participants