Skip to content

docs(fulfillment): align rendering contract with totals schema #573

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
juanferrub wants to merge 4 commits into
base: main
Choose a base branch
from
+4 −3
Open

docs(fulfillment): align rendering contract with totals schema #573

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4c2265f
fix(schema): allow hyphenated reverse-domain namespaces
juanferrub Jun 11, 2026
d760e84
Revert "fix(schema): allow hyphenated reverse-domain namespaces"
juanferrub Jul 8, 2026
e8cd221
docs(fulfillment): align rendering contract with totals schema
juanferrub Jul 8, 2026
379d512
Merge branch 'main' into codex/pr-ucp-fulfillment-totals-docs
damaz91 Jul 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions docs/specification/fulfillment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,7 @@ human-readable fields that platforms render directly.

**For `options[].description`:**

* **MUST NOT** repeat `title` or `total`—provides supplementary context only
* **MUST NOT** repeat `title` or pricing already conveyed in `totals`—provides supplementary context only
* **SHOULD** include timing, carrier, or other decision-relevant details
* **SHOULD** be a complete phrase (e.g., "Arrives Dec 12-15 via FedEx")
* **MAY** be omitted if title is self-explanatory
Expand All @@ -220,7 +220,8 @@ human-readable fields that platforms render directly.

Platforms **SHOULD** treat fulfillment as a generic, renderable structure:

* Render each option as a card using `title`, `description`, and `total`
* Render each option as a card using `title`, `description`, and pricing from `totals`
* Present options in the order provided by the business
* Present all methods returned—method selection is a buyer decision
* Preserve the method and option structure—do not merge or de-duplicate;
the platform chooses ordering
Expand All @@ -229,7 +230,7 @@ Platforms **SHOULD** treat fulfillment as a generic, renderable structure:
Platforms **MAY** provide enhanced UX for recognized method types (store
selectors
for pickup, carrier logos for shipping), but this is optional. The baseline
contract is: **`title` + `description` + `total` is sufficient to render any
contract is: **`title` + `description` + `totals` together are sufficient to render any
option.**

When a buyer selects an option the platform cannot fully process, the
Expand Down
Loading