Merge branch 'main' into main

Author: wry-ry

docs/index.md

@@ -367,8 +367,8 @@ image: assets/banner.png
         "type": "refund",
         "occurred_at": "2026-01-12T14:30:00Z",
         "status": "completed",
-        "line_items": [{ "id": "li_1", "quantity": 1 }],
-        "amount": 26550,
+        "line_items": [{ "id": "li_1", "quantity": -1 }],
+        "totals": [{ "type": "total", "amount": -26550 }],
         "description": "Defective item"
       }
     ],

docs/specification/discount.md

@@ -138,7 +138,7 @@ operations. The same semantics apply to both resources.
 
 - `discounts.applied` contains all active discounts (code-based + automatic)
 - Rejected codes communicated via `messages[]` (see below)
-- Discount amounts reflected in `totals[]` and `line_items[].discount`
+- Discount amounts reflected in `totals[]` and `line_items[].totals[]`
 
 **Cart-to-checkout continuity:** When a cart is converted to a checkout via the
 cart capability's `cart_id` field, businesses MUST carry forward any discount
@@ -302,18 +302,18 @@ with allocations to shipping/fees, contribute to `discount`.
 
 | Discount Type        | Where Reflected                            |
 | -------------------- | ------------------------------------------ |
-| Line-item discount   | `line_items[].discount` + `items_discount` |
-| Order-level discount | `totals[]` with `type: "discount"`         |
+| Line-item discount   | `line_items[].totals[type=items_discount]` |
+| Order-level discount | `totals[type=discount]`                    |
 
 **Invariant:** `totals[type=items_discount].amount` equals
-`sum(line_items[].discount)`.
+`sum(line_items[].totals[type=items_discount].amount)`.
 
 The `discounts.applied` array shows **what** was applied. The `totals[]` and
-`line_items[].discount` show **where** and **how much**.
+`line_items[].totals[]` show **where** and **how much**.
 
-**Amount convention:** All discount amounts are positive integers in minor
-currency units. When presenting totals to users, display discount types as
-subtractive (e.g., "-$13.99").
+**Amount convention:** Discount amounts in `discounts.applied` are positive
+integers (the value of the discount). Discount entries in `totals[]` are
+negative (the effect on the receipt) — the sign is schema-enforced.
 
 ## Examples
 

docs/specification/order.md

@@ -31,17 +31,23 @@ Orders have three main components:
 **Line Items** — what was purchased at checkout:
 
 * Includes current quantity counts (total, fulfilled)
+* Can change post-order (e.g. order edits, exchanges); **MUST** include all
+  line items that ever existed on the order regardless of edits or alterations
 
 **Fulfillment** — how items get delivered:
 
 * **Expectations** — buyer-facing *promises* about when/how items will arrive
 * **Events** (append-only log) — what actually happened (e.g. 👕 was shipped)
 
-**Adjustments** (append-only log) — post-order events independent of fulfillment:
+**Adjustments** — post-order events independent of fulfillment:
 
 * Typically money movements (refunds, returns, credits, disputes, cancellations)
 * Can be any post-order change
 * Can happen before, during, or after fulfillment
+* Businesses SHOULD append new entries rather than mutating existing ones;
+  append-only ledger is preferred. Businesses that do not maintain adjustment
+  history MAY perform in-place updates of existing entries
+  (e.g. a single `return` adjustment can transition from `pending` to `completed`)
 
 ## Data Model
 
@@ -50,7 +56,7 @@ Orders have three main components:
 Line items reflect what was purchased at checkout and their current state:
 
 * Item details (product, price, quantity ordered)
-* Quantity counts and status are derived
+* Quantity counts and fulfillment status
 
 ### Fulfillment
 
@@ -83,15 +89,17 @@ Expectations can be split, merged, or adjusted post-order. For example:
 
 ### Adjustments
 
-**Adjustments** are an append-only log of events that exist independently of
+**Adjustments** are post-order events that exist independently of
 fulfillment:
 
 * Type is an open string field - businesses can use any values that make sense
   (typically money movements like `refund`, `return`, `credit`,
   `price_adjustment`, `dispute`, `cancellation`)
 * Can be any post-order change
 * Optionally link to line items (or order-level for things like shipping refunds)
-* Include amount when relevant
+* Quantities and amounts are signed—negative for reductions (returns, refunds),
+  positive for additions (exchanges)
+* Include totals breakdown when relevant
 * Can happen at any time regardless of fulfillment status
 
 ## Schema
@@ -103,23 +111,24 @@ fulfillment:
 ### Order Line Item
 
 Line items reflect what was purchased at checkout and their current state.
-Status and quantity counts should reflect the event logs.
 
 {{ schema_fields('order_line_item', 'order') }}
 
 **Quantity Structure:**
 
 ```json
 {
-  "total": 3,      // Current total quantity
+  "original": 3,   // Quantity from the original checkout
+  "total": 3,      // Current total (may differ after edits/exchanges)
   "fulfilled": 2   // What has been fulfilled
 }
 ```
 
 **Status Derivation:**
 
 ```text
-if (fulfilled == total) → "fulfilled"
+if (total == 0) → "removed"
+else if (fulfilled == total) → "fulfilled"
 else if (fulfilled > 0) → "partial"
 else → "processing"
 ```
@@ -171,7 +180,7 @@ Examples: `refund`, `return`, `credit`, `price_adjustment`, `dispute`,
     {
       "id": "li_shoes",
       "item": { "id": "prod_shoes", "title": "Running Shoes", "price": 3000 },
-      "quantity": { "total": 3, "fulfilled": 3 },
+      "quantity": { "original": 3, "total": 3, "fulfilled": 3 },
       "totals": [
         {"type": "subtotal", "amount": 9000},
         {"type": "total", "amount": 9000}
@@ -181,7 +190,7 @@ Examples: `refund`, `return`, `credit`, `price_adjustment`, `dispute`,
     {
       "id": "li_shirts",
       "item": { "id": "prod_shirts", "title": "Cotton T-Shirt", "price": 2000 },
-      "quantity": { "total": 2, "fulfilled": 0 },
+      "quantity": { "original": 2, "total": 2, "fulfilled": 0 },
       "totals": [
         {"type": "subtotal", "amount": 4000},
         {"type": "total", "amount": 4000}
@@ -238,8 +247,10 @@ Examples: `refund`, `return`, `credit`, `price_adjustment`, `dispute`,
       "type": "refund",
       "occurred_at": "2025-01-10T14:30:00Z",
       "status": "completed",
-      "line_items": [{ "id": "li_shoes", "quantity": 1 }],
-      "amount": 3000,
+      "line_items": [{ "id": "li_shoes", "quantity": -1 }],
+      "totals": [
+        { "type": "total", "amount": -3000 }
+      ],
       "description": "Defective item"
     }
   ],

source/schemas/shopping/order.json

@@ -3,7 +3,7 @@
   "$id": "https://ucp.dev/schemas/shopping/order.json",
   "name": "dev.ucp.shopping.order",
   "title": "Order",
-  "description": "Order schema with immutable line items, buyer-facing fulfillment expectations, and append-only event logs.",
+  "description": "Order schema with line items, buyer-facing fulfillment expectations, and event logs.",
   "$defs": {
     "platform_schema": {
       "title": "Platform Order Schema",
@@ -53,7 +53,7 @@
       "items": {
         "$ref": "types/order_line_item.json"
       },
-      "description": "Immutable line items — source of truth for what was ordered."
+      "description": "Line items representing what was purchased — can change post-order via edits or exchanges."
     },
     "fulfillment": {
       "type": "object",
@@ -80,7 +80,7 @@
       "items": {
         "$ref": "types/adjustment.json"
       },
-      "description": "Append-only event log of money movements (refunds, returns, credits, disputes, cancellations, etc.) that exist independently of fulfillment."
+      "description": "Post-order events (refunds, returns, credits, disputes, cancellations, etc.) that exist independently of fulfillment."
     },
     "currency": {
       "type": "string",

source/schemas/shopping/types/adjustment.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://ucp.dev/schemas/shopping/types/adjustment.json",
   "title": "Adjustment",
-  "description": "Append-only event that exists independently of fulfillment. Typically represents money movements but can be any post-order change. Polymorphic type that can optionally reference line items.",
+  "description": "Post-order event that exists independently of fulfillment. Typically represents money movements but can be any post-order change. Polymorphic type that can optionally reference line items.",
   "type": "object",
   "required": [
     "id",
@@ -45,16 +45,18 @@
           },
           "quantity": {
             "type": "integer",
-            "minimum": 1,
-            "description": "Quantity affected by this adjustment."
+            "description": "Signed quantity affected by this adjustment. Negative values represent reductions (e.g. returns); positive values represent additions (e.g. exchanges)."
           }
         }
       },
       "description": "Which line items and quantities are affected (optional)."
     },
-    "amount": {
-      "$ref": "amount.json",
-      "description": "Amount in ISO 4217 minor units for refunds, credits, or price adjustments."
+    "totals": {
+      "type": "array",
+      "items": {
+        "$ref": "total.json"
+      },
+      "description": "Adjustment totals breakdown. Signed values - negative for money returned to buyer (refunds, credits), positive for additional charges (exchanges)."
     },
     "description": {
       "type": "string",

source/schemas/shopping/types/order_line_item.json

@@ -23,18 +23,23 @@
       "type": "object",
       "required": ["total", "fulfilled"],
       "properties": {
+        "original": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Quantity from the original checkout."
+        },
         "total": {
           "type": "integer",
           "minimum": 0,
-          "description": "Current total quantity."
+          "description": "Current total active quantity. May differ from original due to post-order modifications (e.g., returns or cancellations)."
         },
         "fulfilled": {
           "type": "integer",
           "minimum": 0,
-          "description": "Quantity fulfilled (sum from fulfillment events)."
+          "description": "Quantity fulfilled so far."
         }
       },
-      "description": "Quantity tracking. Both total and fulfilled are derived from events."
+      "description": "Quantity tracking for the line item."
     },
     "totals": {
       "type": "array",
@@ -48,9 +53,10 @@
       "enum": [
         "processing",
         "partial",
-        "fulfilled"
+        "fulfilled",
+        "removed"
       ],
-      "description": "Derived status: fulfilled if quantity.fulfilled == quantity.total, partial if quantity.fulfilled > 0, otherwise processing."
+      "description": "Derived status: removed if quantity.total == 0, fulfilled if quantity.total > 0 and quantity.fulfilled == quantity.total, partial if quantity.total > 0 and quantity.fulfilled > 0, otherwise processing."
     },
     "parent_id": {
       "type": "string",

source/schemas/shopping/types/total.json

@@ -20,8 +20,18 @@
       "ucp_request": "omit"
     },
     "amount": {
-      "$ref": "amount.json",
+      "$ref": "signed_amount.json",
       "ucp_request": "omit"
     }
-  }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "type": { "enum": ["discount", "items_discount"] } }, "required": ["type"] },
+      "then": { "properties": { "amount": { "exclusiveMaximum": 0 } } }
+    },
+    {
+      "if": { "properties": { "type": { "enum": ["subtotal", "fulfillment", "tax", "fee"] } }, "required": ["type"] },
+      "then": { "properties": { "amount": { "minimum": 0 } } }
+    }
+  ]
 }

source/schemas/shopping/types/totals.json

@@ -12,9 +12,6 @@
       {
         "type": "object",
         "properties": {
-          "amount": {
-            "$ref": "signed_amount.json"
-          },
           "lines": {
             "type": "array",
             "items": {
@@ -39,14 +36,6 @@
           }
         }
       },
-      {
-        "if": { "properties": { "type": { "enum": ["discount", "items_discount"] } }, "required": ["type"] },
-        "then": { "properties": { "amount": { "exclusiveMaximum": 0 } } }
-      },
-      {
-        "if": { "properties": { "type": { "enum": ["subtotal", "fulfillment", "tax", "fee"] } }, "required": ["type"] },
-        "then": { "properties": { "amount": { "minimum": 0 } } }
-      },
       {
         "if": {
           "properties": {