From bb8e595001356292eea110dc3295211a660431e2 Mon Sep 17 00:00:00 2001 From: Alex Park Date: Thu, 10 Sep 2026 09:35:28 +0900 Subject: [PATCH] docs: correct the free-shipping totals examples Two `totals[]` examples represent one free-shipping discount twice: they zero the `fulfillment` entry and also emit an offsetting `discount` entry for the same benefit, so the declared `total` is short by the discount amount. - Mixed discounts (item + order level): line items net to 3200 and shipping is free, so the total is 3200. The example declared 2601. - Price-Impacting Benefits: same shape, declared 651 where the line items net to 850. Both now show the full shipping charge alongside the offsetting discount, and the correct total. The free-shipping discount uses its own title as `display_text` so the pairing is legible. The `allocations` invariant is also scoped to when `allocations` is present: it read as unconditional, yet `allocations` is optional on `applied_discount` and the free-shipping discount in both examples omits it. --- docs/specification/common/extensions/loyalty.md | 4 ++-- docs/specification/shopping/extensions/discount.md | 10 ++++++---- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/specification/common/extensions/loyalty.md b/docs/specification/common/extensions/loyalty.md index 5f19da69b..8d911d50a 100644 --- a/docs/specification/common/extensions/loyalty.md +++ b/docs/specification/common/extensions/loyalty.md @@ -568,8 +568,8 @@ hold the Retail Club membership and the Retail Card. The platform can then rende {"type": "subtotal", "display_text": "Subtotal", "amount": 1000}, {"type": "items_discount", "display_text": "Club member benefit", "amount": -150}, {"type": "discount", "display_text": "Free shipping for Retail Card holder", "amount": -199}, - {"type": "fulfillment", "display_text": "Shipping", "amount": 0}, - {"type": "total", "display_text": "Estimated Total", "amount": 651} + {"type": "fulfillment", "display_text": "Shipping", "amount": 199}, + {"type": "total", "display_text": "Estimated Total", "amount": 850} ] } ``` diff --git a/docs/specification/shopping/extensions/discount.md b/docs/specification/shopping/extensions/discount.md index 4b538d503..a9b3980d1 100644 --- a/docs/specification/shopping/extensions/discount.md +++ b/docs/specification/shopping/extensions/discount.md @@ -122,7 +122,9 @@ JSONPath to identify targets: This enables platforms to explain exactly how much each discount contributed to each line item, even when multiple discounts stack. -**Invariant:** Sum of `allocations[].amount` equals `applied_discount.amount`. +**Invariant:** When `allocations` is present, the sum of `allocations[].amount` +equals `applied_discount.amount`. `allocations` is optional; a discount that +omits it is reported in `totals[]` as a single `discount` entry. ## Operations @@ -499,9 +501,9 @@ to line items, and an automatic shipping discount at the order level. "totals": [ {"type": "subtotal", "display_text": "Subtotal", "amount": 4000}, {"type": "items_discount", "display_text": "Item Discounts", "amount": -800}, - {"type": "discount", "display_text": "Order Discounts", "amount": -599}, - {"type": "fulfillment", "display_text": "Shipping", "amount": 0}, - {"type": "total", "display_text": "Total", "amount": 2601} + {"type": "discount", "display_text": "Free shipping on orders over $30", "amount": -599}, + {"type": "fulfillment", "display_text": "Shipping", "amount": 599}, + {"type": "total", "display_text": "Total", "amount": 3200} ] } ```