From 5250831951060a2f9ca1b75e3d77b7e87704d370 Mon Sep 17 00:00:00 2001 From: Vishal Katyal Date: Fri, 31 Jul 2026 17:20:35 -0400 Subject: [PATCH 1/2] docs(consent): exempt buyer.consent from the cart and checkout full-replacement 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. --- docs/specification/shopping/cart/index.md | 5 +++++ docs/specification/shopping/checkout/index.md | 5 +++++ docs/specification/shopping/checkout/rest.md | 10 +++++++++- .../shopping/extensions/buyer-consent.md | 11 ++++++++++- 4 files changed, 29 insertions(+), 2 deletions(-) diff --git a/docs/specification/shopping/cart/index.md b/docs/specification/shopping/cart/index.md index a5c4427b5..4129c1299 100644 --- a/docs/specification/shopping/cart/index.md +++ b/docs/specification/shopping/cart/index.md @@ -214,6 +214,11 @@ Performs a full replacement of the cart session. The platform **MUST** send the entire cart resource. The provided resource replaces the existing cart state on the business side. +Captured `buyer.consent` is an exception when the buyer-consent capability is +active: an update that omits `consent` MUST NOT clear previously submitted +consent. See [Buyer Consent](../extensions/buyer-consent.md#normative-requirements) for +the persistence rule. + * [REST Binding](rest.md#update-cart) * [MCP Binding](mcp.md#update_cart) diff --git a/docs/specification/shopping/checkout/index.md b/docs/specification/shopping/checkout/index.md index 0aba1d4dd..0661f7304 100644 --- a/docs/specification/shopping/checkout/index.md +++ b/docs/specification/shopping/checkout/index.md @@ -1083,6 +1083,11 @@ general replacement rule does not apply during `complete_in_progress` because Update Checkout is not permitted; see [Accepted completion](#accepted-completion) for the frozen operation contract. +Captured `buyer.consent` is also an exception when the buyer-consent capability +is active: an update that omits `consent` MUST NOT clear previously submitted +consent. See [Buyer Consent](../extensions/buyer-consent.md#normative-requirements) +for the persistence rule. + {{ method_fields('update_checkout', 'shopping/rest.openapi.json', 'shopping/checkout') }} ### Complete Checkout diff --git a/docs/specification/shopping/checkout/rest.md b/docs/specification/shopping/checkout/rest.md index 1faa4e40f..2532e8f7b 100644 --- a/docs/specification/shopping/checkout/rest.md +++ b/docs/specification/shopping/checkout/rest.md @@ -237,12 +237,20 @@ supplied resource replaces the existing Checkout session state. The Platform new Update Checkout request in that state, it **MUST** leave the Checkout unchanged and return the current Checkout with a recoverable error Message. +When the buyer-consent capability is active, captured `buyer.consent` is exempt +from the full replacement: an update that omits `consent` MUST NOT clear +previously submitted consent. See +[Buyer Consent](../../buyer-consent.md#normative-requirements). + #### Update Buyer Info All fields in `buyer` are optional, allowing the Platform to progressively build the Checkout state across multiple calls. Outside `complete_in_progress`, each Update Checkout replaces the entire Checkout session, so the Platform **MUST** -include all previously set fields it intends to retain. +include all previously set fields it intends to retain. Captured `buyer.consent` +is the exception when the buyer-consent capability is active: an update that omits +`consent` MUST NOT clear it (see +[Buyer Consent](../../buyer-consent.md#normative-requirements)). === "Request" diff --git a/docs/specification/shopping/extensions/buyer-consent.md b/docs/specification/shopping/extensions/buyer-consent.md index 397186b73..582056fc6 100644 --- a/docs/specification/shopping/extensions/buyer-consent.md +++ b/docs/specification/shopping/extensions/buyer-consent.md @@ -371,7 +371,16 @@ Handling](../checkout/index.md#error-handling) flow. 2. **Confirm semantics.** The `consent` field is optional on requests; omitting it provides no consent update and the business retains its prior - position. When submitting `consent`, platforms MUST include every advertised + position. This persistence is an explicit exception to the cart and checkout + full-replacement rules (see + [Update Cart](shopping/cart/index.md#update-cart) and + [Update Checkout](shopping/checkout/index.md#update-checkout)): a business + MUST retain the last submitted `buyer.consent` state across subsequent cart + or checkout updates that omit `consent`, and MUST NOT reset it to + advertised defaults, so that an update sent for an unrelated field (for + example a fulfillment change) does not silently discard captured consent. + When submitting `consent`, + platforms MUST include every advertised purpose and segment key, carrying both `granted` and `source` for each. Omitting an advertised key within a submitted `consent` map MUST NOT be used to signal any value. From b7973b9e487b27740754fdd3205ee624b0e55222 Mon Sep 17 00:00:00 2001 From: Vishal Katyal Date: Wed, 26 Aug 2026 21:22:01 -0400 Subject: [PATCH 2/2] docs(consent): fix relative link depths for the reorganized tree --- docs/specification/shopping/checkout/rest.md | 4 ++-- docs/specification/shopping/extensions/buyer-consent.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/specification/shopping/checkout/rest.md b/docs/specification/shopping/checkout/rest.md index 2532e8f7b..79e2da739 100644 --- a/docs/specification/shopping/checkout/rest.md +++ b/docs/specification/shopping/checkout/rest.md @@ -240,7 +240,7 @@ unchanged and return the current Checkout with a recoverable error Message. When the buyer-consent capability is active, captured `buyer.consent` is exempt from the full replacement: an update that omits `consent` MUST NOT clear previously submitted consent. See -[Buyer Consent](../../buyer-consent.md#normative-requirements). +[Buyer Consent](../extensions/buyer-consent.md#normative-requirements). #### Update Buyer Info @@ -250,7 +250,7 @@ Update Checkout replaces the entire Checkout session, so the Platform **MUST** include all previously set fields it intends to retain. Captured `buyer.consent` is the exception when the buyer-consent capability is active: an update that omits `consent` MUST NOT clear it (see -[Buyer Consent](../../buyer-consent.md#normative-requirements)). +[Buyer Consent](../extensions/buyer-consent.md#normative-requirements)). === "Request" diff --git a/docs/specification/shopping/extensions/buyer-consent.md b/docs/specification/shopping/extensions/buyer-consent.md index 582056fc6..aa7846664 100644 --- a/docs/specification/shopping/extensions/buyer-consent.md +++ b/docs/specification/shopping/extensions/buyer-consent.md @@ -373,8 +373,8 @@ Handling](../checkout/index.md#error-handling) flow. omitting it provides no consent update and the business retains its prior position. This persistence is an explicit exception to the cart and checkout full-replacement rules (see - [Update Cart](shopping/cart/index.md#update-cart) and - [Update Checkout](shopping/checkout/index.md#update-checkout)): a business + [Update Cart](../cart/index.md#update-cart) and + [Update Checkout](../checkout/index.md#update-checkout)): a business MUST retain the last submitted `buyer.consent` state across subsequent cart or checkout updates that omit `consent`, and MUST NOT reset it to advertised defaults, so that an update sent for an unrelated field (for