feat: Add itemized fee extension for checkout and cart

[poojithg14]

Add structured fee support via a new extension schema, enabling businesses to surface itemized fees (service, handling, recycling, etc.) on checkout sessions and carts. Closes #219.

Description

Closes #219

Adds a new dev.ucp.shopping.fee extension schema and documents the Fee Extension in the specification. The extension enables businesses to surface itemized fees (service, handling, recycling, regulatory, etc.) on checkout sessions and carts, formalizing the existing fee type in totals[]. Fees are business-determined, read-only to platforms, and support allocation breakdowns, taxability, and waivability metadata. The fee_type field is an open string — platforms SHOULD handle unknown values gracefully.

Type of change

• New feature (non-breaking change which adds functionality)
• Documentation update

---

Is this a Breaking Change or Removal?

No. Adds new optional extension schema and documentation.

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• 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
• Any dependent changes have been merged and published in downstream modules

[poojithg14]

@igrigorik @wry-ry This PR is ready for review. It implements the Fee Extension (Option B) discussed in #219. Schema linting and pre-commit checks pass. Would appreciate a review when you get a chance.

[maximenajim]

Hey @poojithg14 — thanks for putting this together! We took a close look at this PR and used it as a starting point for our thinking.

We ended up opening a separate PR (#245) that takes a different approach on a few architectural points:

1. Shared allocation type instead of cross-extension $ref: This PR references ../discount.json#/$defs/allocation from within fee.json, which creates a coupling between the Fee and Discount extensions. If the discount allocation shape ever changes, fees would break. We extracted a shared types/allocation.json that both extensions reference independently.

2. fee_type as required: Without a fee type, platforms can't categorize or render fees meaningfully. We made it a required field.

3. exclusiveMinimum: 0 instead of minimum: 0: Zero-amount fees shouldn't exist in the array — if a fee is waived, it should be omitted entirely. This avoids ambiguity about what a $0 fee means.

4. additionalProperties: false on the fee type for strict schema validation.

5. $ref to amount.json on all monetary fields to preserve the canonical amount type chain (rather than inlining type: integer).

6. Separate extends entries per base capability (checkout and cart as independent entries, not an array) to support per-capability versioning.

7. Spec-level trust boundary language: mismatch handling invariants, receiver rejection semantics, sanitization guidance, and waived fee clarification.

We also addressed some of the review feedback that would apply to both PRs (RFC 9535 JSONPath dialect, ISO 4217 language, conditional totals descriptions).

Would love your thoughts — happy to discuss any of these choices!

[poojithg14]

Closing this in favor of #245. Thanks, @maximenajim, for reviewing and considering my initial design and building on top of that. We will continue our discussion in #245