feat: formalize totals contract

docs/specification/cart.md

@@ -222,6 +222,10 @@ requirements.
 
 ### Total
 
+The same totals contract applies to cart and checkout. See
+[Checkout Totals](checkout.md#totals) for the rendering contract, accounting
+identity, well-known types, repeating types, and sub-line semantics.
+
 {{ schema_fields('types/total_resp', 'checkout') }}
 
 Taxes MAY be included where calculable. Platforms SHOULD assume cart totals

docs/specification/checkout.md

@@ -610,12 +610,144 @@ field or omitting them.
 
 {{ extension_schema_fields('capability.json#/$defs/response_schema', 'checkout') }}
 
-### Total
-
-#### Total
+### Total {: #totals }
 
 {{ schema_fields('types/total_resp', 'checkout') }}
 
+#### Rendering Contract
+
+Businesses are the authoritative source for presented totals — their content
+and order — because the correct presentation is subject to regional, product,
+and regulatory requirements that the business is obligated to satisfy (e.g.,
+multi-jurisdiction tax itemization, mandatory fee disclosures).
+
+Platforms MUST render all top-level entries in the order provided:
+
+```python
+for entry in totals:
+    render_line(entry.display_text, entry.amount)
+```
+
+Platforms MAY render sub-lines as supplementary detail:
+
+```python
+for entry in totals:
+    render_line(entry.display_text, entry.amount)
+    if entry.lines:
+        for sub in entry.lines:
+            render_detail_line(sub.display_text, sub.amount)
+```
+
+Platforms MUST NOT interpret, filter, reorder, aggregate, or apply display
+logic of their own.
+
+Invariants of `totals[]`:
+
+* Every entry carries a `type` and an `amount`. Platforms SHOULD use
+  `display_text` when provided. Well-known types have default display labels
+  as fallback (see table below); unknown types MUST include `display_text`.
+* Amounts are signed integers — negative values are subtractive (e.g.,
+  discounts), positive values are additive. The sign IS the direction.
+* Exactly one `type: "subtotal"` MUST be present.
+* Exactly one `type: "total"` MUST be present.
+
+#### Verification
+
+Platforms MUST NOT substitute their own computed totals for the business's
+values. Platforms MAY verify the provided totals:
+
+```python
+assert sum(e.amount for e in totals if e.type != "total") == total_entry.amount
+```
+
+If the computed sum does not match the `type: "total"` entry, the platform
+MUST NOT alter the rendered output — the business's presented totals are
+authoritative for display. However, platforms MUST NOT autonomously complete
+a checkout with mismatched totals. Platforms SHOULD reject the checkout or
+escalate and ask for buyer review via `continue_url`.
+
+#### Well-Known Types
+
+| Type              | Sign | Default label    | Meaning                                   |
+| ----------------- | ---- | ---------------- | ----------------------------------------- |
+| `subtotal`        | +    | Subtotal         | Sum of line item prices                   |
+| `discount`        | −    | Discount         | Order or line-item level discount         |
+| `items_discount`  | −    | Item Discounts   | Rollup of line-item discounts             |
+| `fulfillment`     | +    | Shipping         | Shipping, delivery, or pickup charges     |
+| `tax`             | +    | Tax              | Tax charges                               |
+| `fee`             | +    | Fee              | Fees and surcharges                       |
+| `total`           | =    | Total            | Authoritative grand total (exactly one)   |
+
+When `display_text` is provided, platforms MUST use it. When omitted on a
+well-known type, platforms SHOULD use the default label above. The sign
+convention for well-known types is schema-enforced: subtractive types
+(discount, items_discount) MUST have negative amounts; additive types
+(subtotal, fulfillment, tax, fee) MUST have non-negative amounts.
+
+The `type` field is an open string — businesses MAY use values beyond the
+well-known set. Unknown types MUST include `display_text` (schema-enforced)
+and the sign on the amount is self-describing.
+
+#### Repeating Types
+
+All types except `subtotal` and `total` MAY appear multiple times —
+for example, multi-jurisdiction tax lines or itemized fees.
+
+#### Sub-Lines (`lines`)
+
+Each top-level entry MAY include a `lines` array. Sub-lines share the same
+base shape as top-level entries — `display_text` and `amount` — providing an
+itemized breakdown under the parent.
+
+**Invariant:** `sum(lines[].amount)` MUST equal the parent entry's `amount`.
+
+The business controls what MUST be rendered (top-level entries) versus what
+MAY be optionally surfaced (sub-lines). Platforms SHOULD render sub-lines
+when provided.
+
+#### Examples
+
+**Split tax, itemized at top-level:**
+
+```json
+"totals": [
+  { "type": "subtotal",    "display_text": "Subtotal",    "amount": 5750 },
+  { "type": "fulfillment", "display_text": "Shipping",    "amount": 899 },
+  { "type": "tax",         "display_text": "Federal Tax", "amount": 332 },
+  { "type": "tax",         "display_text": "State Tax",   "amount": 465 },
+  { "type": "total",       "display_text": "Total",       "amount": 7446 }
+]
+```
+
+**Collapsed fees with optional breakdown:**
+
+```json
+"totals": [
+  { "type": "subtotal", "display_text": "Subtotal", "amount": 4999 },
+  {
+    "type": "fee", "display_text": "Fees", "amount": 549,
+    "lines": [
+      { "display_text": "Service Fee", "amount": 399 },
+      { "display_text": "Recycling Fee", "amount": 150 }
+    ]
+  },
+  { "type": "tax",   "display_text": "Tax",   "amount": 444 },
+  { "type": "total", "display_text": "Total", "amount": 5992 }
+]
+```
+
+**Discount and account credit — negative amounts:**
+
+```json
+"totals": [
+  { "type": "subtotal",       "display_text": "Subtotal",       "amount": 10000 },
+  { "type": "discount",       "display_text": "Summer Sale",    "amount": -1500 },
+  { "type": "tax",            "display_text": "Tax",            "amount": 680 },
+  { "type": "account_credit", "display_text": "Account Credit", "amount": -2500 },
+  { "type": "total",          "display_text": "Amount Due",     "amount": 6680 }
+]
+```
+
 ### UCP Response Checkout {: #ucp-response-checkout-schema }
 
 {{ extension_schema_fields('ucp.json#/$defs/response_checkout_schema', 'checkout') }}

docs/specification/discount.md

@@ -80,6 +80,9 @@ When this capability is active, cart and/or checkout are extended with a
 ## Allocation Details
 
 The `applied` array explains how discounts were calculated and distributed.
+The `applied[].amount` describes the magnitude of the applied discount (always
+positive); the corresponding `totals[]` entry amount represents its signed
+effect on the receipt (negative for discounts).
 
 ### Allocation Method
 
@@ -274,7 +277,7 @@ stacking and allocation details:
       },
       "totals": [
         {"type": "subtotal", "display_text": "Subtotal", "amount": 5000},
-        {"type": "items_discount", "display_text": "Discounts", "amount": 250},
+        {"type": "items_discount", "display_text": "Discounts", "amount": -250},
         {"type": "total", "display_text": "Total", "amount": 4750}
       ]
     }
@@ -356,7 +359,7 @@ proceeding to checkout.
           },
           "totals": [
             {"type": "subtotal", "amount": 4000},
-            {"type": "items_discount", "amount": 800},
+            {"type": "items_discount", "amount": -800},
             {"type": "total", "amount": 3200}
           ]
         }
@@ -378,7 +381,7 @@ proceeding to checkout.
       "currency": "USD",
       "totals": [
         {"type": "subtotal", "display_text": "Subtotal", "amount": 4000},
-        {"type": "items_discount", "display_text": "Item Discounts", "amount": 800},
+        {"type": "items_discount", "display_text": "Item Discounts", "amount": -800},
         {"type": "total", "display_text": "Estimated Total", "amount": 3200}
       ]
     }
@@ -415,7 +418,7 @@ to the order as a whole and uses `type: "discount"` in totals.
       },
       "totals": [
         {"type": "subtotal", "display_text": "Subtotal", "amount": 5000},
-        {"type": "discount", "display_text": "Order Discount", "amount": 1000},
+        {"type": "discount", "display_text": "Order Discount", "amount": -1000},
         {"type": "total", "display_text": "Total", "amount": 4000}
       ]
     }
@@ -451,7 +454,7 @@ to line items, and an automatic shipping discount at the order level.
           },
           "totals": [
             {"type": "subtotal", "amount": 4000},
-            {"type": "items_discount", "amount": 800},
+            {"type": "items_discount", "amount": -800},
             {"type": "total", "amount": 3200}
           ]
         }
@@ -476,8 +479,8 @@ 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": "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}
       ]
@@ -516,7 +519,7 @@ but not in `discounts.applied`.
       },
       "totals": [
         {"type": "subtotal", "display_text": "Subtotal", "amount": 5000},
-        {"type": "discount", "display_text": "Order Discount", "amount": 1000},
+        {"type": "discount", "display_text": "Order Discount", "amount": -1000},
         {"type": "total", "display_text": "Total", "amount": 4000}
       ],
       "messages": [
@@ -547,7 +550,7 @@ Multiple discounts applied with full allocation breakdown:
           },
           "totals": [
             {"type": "subtotal", "amount": 6000},
-            {"type": "items_discount", "amount": 1500},
+            {"type": "items_discount", "amount": -1500},
             {"type": "total", "amount": 4500}
           ]
         },
@@ -559,7 +562,7 @@ Multiple discounts applied with full allocation breakdown:
           },
           "totals": [
             {"type": "subtotal", "amount": 4000},
-            {"type": "items_discount", "amount": 1000},
+            {"type": "items_discount", "amount": -1000},
             {"type": "total", "amount": 3000}
           ]
         }
@@ -593,7 +596,7 @@ Multiple discounts applied with full allocation breakdown:
       },
       "totals": [
         {"type": "subtotal", "display_text": "Subtotal", "amount": 10000},
-        {"type": "items_discount", "display_text": "Item Discounts", "amount": 2500},
+        {"type": "items_discount", "display_text": "Item Discounts", "amount": -2500},
         {"type": "total", "display_text": "Total", "amount": 7500}
       ]
     }

source/schemas/shopping/cart.json

@@ -90,10 +90,7 @@
       "ucp_request": "omit"
     },
     "totals": {
-      "type": "array",
-      "items": {
-        "$ref": "types/total.json"
-      },
+      "$ref": "types/totals.json",
       "description": "Estimated cost breakdown. May be partial if shipping/tax not yet calculable.",
       "ucp_request": "omit"
     },

source/schemas/shopping/checkout.json

@@ -105,10 +105,7 @@
       }
     },
     "totals": {
-      "type": "array",
-      "items": {
-        "$ref": "types/total.json"
-      },
+      "$ref": "types/totals.json",
       "description": "Different cart totals.",
       "ucp_request": "omit"
     },

source/schemas/shopping/order.json

@@ -87,10 +87,7 @@
       "description": "ISO 4217 currency code. MUST match the currency from the originating checkout session."
     },
     "totals": {
-      "type": "array",
-      "items": {
-        "$ref": "types/total.json"
-      },
+      "$ref": "types/totals.json",
       "description": "Different totals for the order."
     }
   }

source/schemas/shopping/types/signed_amount.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/schemas/shopping/types/signed_amount.json",
+  "title": "Signed Amount",
+  "description": "Monetary amount in the currency's minor unit as defined by ISO 4217. Refer to the currency's exponent to determine minor-to-major ratio (e.g., 2 for USD, 0 for JPY, 3 for KWD). May be negative — the sign is intrinsic to the value (e.g., discounts are negative, charges are positive).",
+  "type": "integer"
+}

source/schemas/shopping/types/total.json

@@ -2,6 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://ucp.dev/schemas/shopping/types/total.json",
   "title": "Total",
+  "description": "A cost breakdown entry with a category, amount, and optional display text.",
   "type": "object",
   "required": [
     "type",
@@ -10,16 +11,7 @@
   "properties": {
     "type": {
       "type": "string",
-      "enum": [
-        "items_discount",
-        "subtotal",
-        "discount",
-        "fulfillment",
-        "tax",
-        "fee",
-        "total"
-      ],
-      "description": "Type of total categorization.",
+      "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses MAY use additional values.",
       "ucp_request": "omit"
     },
     "display_text": {
@@ -29,7 +21,6 @@
     },
     "amount": {
       "$ref": "amount.json",
-      "description": "If type == total, sums subtotal - discount + fulfillment + tax + fee. Should be >= 0. Amount in ISO 4217 minor units.",
       "ucp_request": "omit"
     }
   }