Skip to content

docs(consent): exempt buyer.consent from the cart and checkout full-replacement rules - #660

Open
vishkaty wants to merge 2 commits into
Universal-Commerce-Protocol:mainfrom
vishkaty:fix/consent-exempt-from-full-replace
Open

docs(consent): exempt buyer.consent from the cart and checkout full-replacement rules#660
vishkaty wants to merge 2 commits into
Universal-Commerce-Protocol:mainfrom
vishkaty:fix/consent-exempt-from-full-replace

Conversation

@vishkaty

@vishkaty vishkaty commented Jul 31, 2026

Copy link
Copy Markdown
Contributor

Problem

The buyer-consent extension says omitting consent on a request "retains the prior position," but core Update Cart and Update Checkout are full replacements: the platform sends the entire resource and it replaces the stored session state. A business implementing the literal full-replacement contract drops captured consent on the next update that omits buyer.consent (for example a fulfillment change), re-exposing advertised defaults. A buyer who explicitly opted out can be reset toward an opted-in default, which is the failure mode a consent record most needs to prevent. Two conformant implementations diverge on the outcome.

Fix

Consent rides both cart.buyer.consent and checkout.buyer.consent, so the exception is added to every place the full-replacement rule is stated:

  • buyer-consent.md: state that consent persistence is an explicit exception to the cart and checkout full-replacement rules, cross-referencing both.
  • shopping/checkout/index.md and shopping/cart/index.md: add the exception note to each full-replacement rule (the checkout document already carries the complete_in_progress exception).
  • shopping/checkout/rest.md: the rule is restated twice here, and both now carry the carve-out — the general Update Checkout rule, and the buyer-specific Update Buyer Info paragraph, which draws the drop-if-omitted consequence as a MUST over the buyer object (and so is the most on-point site, since consent is buyer.consent).

The MCP and cart-rest bindings link back to the capability docs and do not restate the rule; the embedded-* docs mention it only in example code comments.

Alternative

The other option is to require platforms to re-send the full consent map on every update once submitted. The exemption approach is proposed here as the smaller change; happy to switch if maintainers prefer the re-send contract.

@damaz91 damaz91 added the status:needs-triage Signal that the PR is ready for human triage label Jul 31, 2026
@vishkaty
vishkaty force-pushed the fix/consent-exempt-from-full-replace branch from 44667ef to 7168971 Compare July 31, 2026 23:12
@damaz91 damaz91 added bug Something isn't working documentation Improvements or additions to documentation status:under-review and removed status:needs-triage Signal that the PR is ready for human triage labels Aug 3, 2026
@damaz91
damaz91 requested review from jingyli and westeezy August 3, 2026 07:52
@vishkaty

Copy link
Copy Markdown
Contributor Author

@jingyli companion to #658. This keeps captured buyer consent from being dropped by the full replacement update rules. Glad to rework if you see a better shape.

@vishkaty
vishkaty force-pushed the fix/consent-exempt-from-full-replace branch from 7168971 to f6ad270 Compare August 21, 2026 17:48
…eplacement rules

Buyer consent says that omitting `consent` on a request retains the prior
position, but core Update Cart and Update Checkout are full replacements that
require the platform to send the entire resource and replace the stored session
state. A business implementing the literal full-replacement contract drops
captured consent on the next update that omits `buyer.consent` (for example a
fulfillment change), re-exposing advertised defaults, so a buyer who opted out
can be reset toward an opted-in default.

Consent rides both `cart.buyer.consent` and `checkout.buyer.consent`, so the
exception is added to every place the full-replacement rule is stated:

- buyer-consent.md: state that consent persistence is an explicit exception to
  the cart and checkout full-replacement rules, cross-referencing both.
- checkout.md and cart.md: add the exception note to each full-replacement rule
  (checkout.md already carries the complete_in_progress exception).
- checkout-rest.md: the rule is restated twice here (the general Update Checkout
  rule and the buyer-specific Update Buyer Info paragraph, which draws the
  drop-if-omitted consequence as a MUST over the buyer object); both now carry
  the carve-out.

The MCP and cart-rest bindings link back to the capability docs and do not
restate the rule.
@vishkaty
vishkaty force-pushed the fix/consent-exempt-from-full-replace branch from f6ad270 to 5250831 Compare August 27, 2026 00:35
@vishkaty

Copy link
Copy Markdown
Contributor Author

Re-anchored on released v2026-08-25: the branch already targets the new docs/specification/shopping paths and applies cleanly. The release sharpens the case rather than absorbing it, since buyer-consent.md L372-373 now asserts that the business retains its prior position while checkout/rest.md L242-245 states a MUST over the same buyer object that replaces everything not resent. The discount extension already carries per-field replacement semantics in its own doc (discount.md L134), which is the shape proposed here for consent.

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

Labels

bug Something isn't working documentation Improvements or additions to documentation status:under-review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants