feat!: update Order capability

docs/index.md

@@ -326,7 +326,7 @@ image: assets/banner.png
   {
     "ucp": { ... },
     "id": "order_123456789",
-    "checkout_id": "chk_123456789",
+    "checkouts": [{ "id": "chk_123456789", "created_at": "..." }],
     "permalink_url": ...,
     "line_items": [ ... ],
     "fulfillment": {
@@ -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/order.md

@@ -31,17 +31,20 @@ 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)
 
 **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 may append new entries or update existing ones in place
+  (e.g. a single `return` adjustment can transition from `pending` to `completed`)
 
 ## Data Model
 
@@ -50,7 +53,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 +86,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,15 +108,15 @@ 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
 }
 ```
@@ -165,13 +170,15 @@ Examples: `refund`, `return`, `credit`, `price_adjustment`, `dispute`,
     }
   },
   "id": "order_abc123",
-  "checkout_id": "checkout_xyz789",
+  "checkouts": [
+    { "id": "checkout_xyz789", "created_at": "2025-01-05T09:00:00Z" }
+  ],
   "permalink_url": "https://business.com/orders/abc123",
   "line_items": [
     {
       "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 +188,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 +245,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"
     }
   ],

generate_ts_schema_types.js

@@ -2,7 +2,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { compile } = require('json-schema-to-typescript');
 
-const SOURCE_ROOT = path.resolve(__dirname, 'spec');
+const SOURCE_ROOT = path.resolve(__dirname, 'source');
 const OUTPUT_FILE = path.resolve(__dirname, './generated/schema-types.ts');
 const WRAPPER_NAME = 'SCHEMA_WRAPPER';