feat(shopping): add Fee Extension for checkout and cart (Option B) by maximenajim · Pull Request #245 · Universal-Commerce-Protocol/ucp

maximenajim · 2026-03-09T18:19:25Z

Summary

Implements the Fee Extension (dev.ucp.shopping.fee) per Issue #219 (Option B), enabling businesses to surface itemized fees on checkout sessions and carts.

Key design decisions

Shared allocation type: Extracts types/allocation.json as a reusable type referenced by both discount and fee extensions — eliminates cross-extension coupling (fee no longer depends on discount's $defs)
fee_type required: Fees without a type are ambiguous for platform rendering/categorization
exclusiveMinimum: 0: Zero-amount fees are not permitted — waived fees are omitted from the array entirely
additionalProperties: false on fee type for strict validation
readOnly: true on fees.applied for generic tooling/codegen compatibility
$ref to amount.json on all monetary fields to preserve the canonical amount type chain
RFC 9535 JSONPath dialect explicitly named in allocation path descriptions
Conditional language in total.json descriptions ("When the Fee Extension is present…")

Files changed (8)

New (4):

source/schemas/shopping/types/allocation.json — Shared allocation type
source/schemas/shopping/types/fee.json — Individual fee schema
source/schemas/shopping/fee.json — Fee Extension schema (checkout + cart)
docs/specification/fee.md — Full specification page

Modified (4):

source/schemas/shopping/discount.json — Allocation now $refs shared type
source/schemas/shopping/types/total.json — Conditional fee language in descriptions
mkdocs.yml — Nav + llmstxt entries
.cspell/custom-words.txt — New terms

Spec highlights

Mismatch handling: platforms MUST NOT complete checkout if totals[type=fee] diverges from sum(fees.applied[].amount)
Receiver rejection: business receivers MUST reject (not ignore) client-supplied fee fields
Sanitization: title/description/display_text are plain text — renderers MUST escape
Waived fees: omitted from array (not zero-amount entries)

Closes #219
Related: #220

google-cla · 2026-03-09T18:19:31Z

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

Implement structured fee support via dev.ucp.shopping.fee extension, enabling businesses to surface itemized fees (service, handling, recycling, etc.) with allocation breakdowns, taxability, and waivability metadata. Extracts shared allocation type to decouple fee and discount extensions. Closes #219.

ACSchil · 2026-03-09T22:19:39Z

docs/specification/fee.md

+!!! note "Partial adoption"
+    A business MAY support fees on checkout only, cart only, or both. Each
+    `extends` entry is independent. Platforms should check which base
+    capabilities the fee extension extends before expecting `fees` in responses.


I'm curious if this needs to be in docs/specification/overview.md, as this should be true for all extensions, correct?

ACSchil · 2026-03-09T22:31:27Z

docs/specification/fee.md

+| Total Type       | Description                                                   |
+| ---------------- | ------------------------------------------------------------- |
+| `subtotal`       | Sum of line item prices before any adjustments                |
+| `items_discount` | Discounts allocated to line items                             |
+| `discount`       | Order-level discounts (shipping, flat amount)                 |
+| `fulfillment`    | Shipping, delivery, or pickup costs                           |
+| `tax`            | Tax amount                                                    |
+| `fee`            | **Single aggregated fee total** — sum of all `fees.applied[]` |
+| `total`          | Grand total: `subtotal - discount + fulfillment + tax + fee`  |


Should this table be here under docs/specification/fee.md or should fee.md just call out the new total type? I ask because it could make the docs harder to maintain if every extension that affects totals recreates the totals table (e.g. Discount also could have this table).

ACSchil · 2026-03-09T22:32:29Z

docs/specification/fee.md

+| `discount`       | Order-level discounts (shipping, flat amount)                 |
+| `fulfillment`    | Shipping, delivery, or pickup costs                           |
+| `tax`            | Tax amount                                                    |
+| `fee`            | **Single aggregated fee total** — sum of all `fees.applied[]` |


This language is helpful, and we should consider being this crisp with the other total types.

ACSchil · 2026-03-09T22:40:09Z

docs/specification/fee.md

+Businesses MUST ensure this invariant holds. If a platform detects a mismatch
+between the aggregated fee total and the sum of itemized fees, the platform
+SHOULD treat the response as invalid and MUST NOT complete the checkout without
+surfacing the discrepancy to the user.


Even if the discrepancy is surfaced, is it appropriate for the platform to proceed? Should the Platform use the continue_url is such a case? If yes, should the continue_url be a required field? Currently, it doesn't seem like we have a good way for platforms to handle these cases.

ACSchil · 2026-03-09T22:44:42Z

docs/specification/fee.md

+SHOULD treat the response as invalid and MUST NOT complete the checkout without
+surfacing the discrepancy to the user.
+
+!!! note "When the Fee Extension is absent"


This still feels a bit ambiguous. Does this note deserve the same normative language as the Invariant above? That is, "totals[type=fee] MUST represent the aggregated fee total"; or alternatively, something about there MAY be n number of totals[type=fee] objects in totals (the question that sparked issue #219 ).

ACSchil · 2026-03-09T22:49:43Z

source/schemas/shopping/types/allocation.json

+    },
+    "amount": {
+      "$ref": "amount.json",
+      "description": "Amount allocated to this target in ISO 4217 minor units."


We should adopt this across the spec. In other places we are simply saying "minor units (cents)" which is inadequate for all currencies.

ACSchil · 2026-03-09T22:51:23Z

source/schemas/shopping/types/fee.json

+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Unique fee identifier. Unlike applied discounts, fees always require an id to enable stable referencing across updates."


Are fee ids expected to be consistent across checkout sessions? Or just across requests within a checkout session or cart?

ACSchil · 2026-03-09T22:54:13Z

source/schemas/shopping/types/fee.json

+    },
+    "description": {
+      "type": "string",
+      "description": "Optional explanation of why the fee is charged."


Also human-readable, I assume. As with conversations around disclosure, I wonder how Platforms should navigate Businesses potentially wanting richer text, or even images.

ACSchil · 2026-03-09T22:58:30Z

docs/specification/fee.md

+| `service`       | General service fee for order processing         | Platform service fee               |
+| `handling`      | Physical handling and packaging of goods         | Oversized item handling fee        |
+| `recycling`     | Disposal or recycling of materials               | Electronics recycling fee          |
+| `processing`    | Payment or order processing surcharge            | Credit card processing fee         |
+| `regulatory`    | Government-mandated fee or compliance charge     | Mattress recycling surcharge       |
+| `convenience`   | Fee for using a particular ordering channel      | Online ordering convenience fee    |
+| `restocking`    | Fee for processing returns or exchanges          | Return restocking fee              |
+| `environmental` | Environmental impact or sustainability surcharge | Carbon offset fee                  |


What is the value of this spec defining types, especially so many of them? Does a Platform need to know the various types?

ACSchil · 2026-03-09T23:01:07Z

docs/specification/fee.md

+
+3. **Positive amounts only:** All fee amounts use `exclusiveMinimum: 0` —
+   zero-amount fees are not permitted. If a fee does not apply, it MUST be
+   omitted from the `applied` array entirely. This includes waived fees: when a


Is there perhaps a need to communicate to the Platform / User that a fee was waived? If we do not allow zero-amount fees, how should this be communicated in the response?

ACSchil · 2026-03-09T23:05:42Z

docs/specification/fee.md

+operations, meaning platforms never send fee data in requests — fees are
+determined entirely by the business and returned in responses.
+
+Business receivers MUST reject any `fees` fields provided by platforms in


Shall we add an error code to source/schemas/shopping/types/error_code.json for this?

ACSchil · 2026-03-09T23:11:00Z

docs/specification/fee.md

+        "amount": 500,
+        "fee_type": "recycling",
+        "taxable": true,
+        "description": "State-mandated electronics recycling fee."


This made me think of #222 . Is a plain-text description adequate, or are there fees that may need to be more expressive; perhaps we handle those with disclosures?

maximenajim requested review from a team as code owners March 9, 2026 18:19

maximenajim requested review from DanielFalconGuedes, MitkoDeyanovMitev, nicholasjameshall and westeezy March 9, 2026 18:19

maximenajim mentioned this pull request Mar 9, 2026

feat: Add itemized fee extension for checkout and cart #220

Closed

10 tasks

maximenajim force-pushed the feat/fee-extension branch from 080e343 to c491a72 Compare March 9, 2026 18:31

maximenajim added the TC review Ready for TC review label Mar 9, 2026

ACSchil reviewed Mar 9, 2026

View reviewed changes

Conversation

maximenajim commented Mar 9, 2026

Summary

Key design decisions

Files changed (8)

Spec highlights

Uh oh!

google-cla bot commented Mar 9, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants