feat: add optional note field to line items

source/schemas/shopping/discount.json

@@ -79,6 +79,41 @@
         }
       }
     },
+    "available_discount": {
+      "type": "object",
+      "description": "A discount available for discovery in the current context.",
+      "required": [
+        "title",
+        "type"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Stable discount identifier."
+        },
+        "title": {
+          "type": "string",
+          "description": "Human-readable promotion name (e.g., 'Summer Sale \u2014 15% off')."
+        },
+        "type": {
+          "type": "string",
+          "enum": ["automatic", "code"],
+          "description": "'automatic' \u2014 business applies when conditions are met, no code needed. 'code' \u2014 buyer must submit a code (the code itself is NOT exposed)."
+        },
+        "conditions": {
+          "type": "string",
+          "description": "Human-readable summary of conditions to qualify (e.g., 'Orders over $50')."
+        },
+        "applied": {
+          "type": "boolean",
+          "description": "Whether this discount is already applied to the current cart/checkout."
+        },
+        "remaining_amount": {
+          "$ref": "../common/types/amount.json",
+          "description": "How much more the buyer needs to spend to qualify, in ISO 4217 minor units. Useful for 'add $12 more for free shipping' prompts."
+        }
+      }
+    },
     "discounts_object": {
       "type": "object",
       "description": "Discount codes input and applied discounts output.",
@@ -97,6 +132,14 @@
           },
           "description": "Discounts successfully applied (code-based and automatic).",
           "ucp_request": "omit"
+        },
+        "available": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/available_discount"
+          },
+          "description": "Discounts available for this cart or checkout context. Business-optional. Includes both automatic promotions and discoverable code-based offers.",
+          "ucp_request": "omit"
         }
       }
     },

source/schemas/shopping/types/fulfillment_event.json

@@ -56,6 +56,30 @@
       "type": "string",
       "description": "Carrier name (e.g., 'FedEx', 'USPS')."
     },
+    "fulfillment_method_id": {
+      "type": "string",
+      "description": "References the fulfillment method selected at checkout (e.g., 'shipping_1'). Links this event back to the checkout fulfillment selection."
+    },
+    "fulfillment_option_id": {
+      "type": "string",
+      "description": "References the fulfillment option selected at checkout (e.g., 'express'). Together with fulfillment_method_id, identifies the exact delivery promise."
+    },
+    "estimated_delivery": {
+      "type": "object",
+      "description": "Updated delivery estimate window for this fulfillment. Business MAY revise this as shipment progresses.",
+      "properties": {
+        "earliest": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Earliest estimated delivery (RFC 3339)."
+        },
+        "latest": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Latest estimated delivery (RFC 3339)."
+        }
+      }
+    },
     "description": {
       "type": "string",
       "description": "Human-readable description of the shipment status or delivery information (e.g., 'Delivered to front door', 'Out for delivery')."

source/schemas/shopping/types/line_item.json

@@ -41,6 +41,15 @@
         "create": "omit",
         "update": "optional"
       }
+    },
+    "note": {
+      "type": "string",
+      "maxLength": 500,
+      "description": "Buyer-supplied free-text note for this line item (e.g., gift wrapping instructions, dietary preferences, engraving text). Business echoes the value in responses and MAY include it in order webhook payloads for downstream fulfillment.",
+      "ucp_request": {
+        "create": "optional",
+        "update": "optional"
+      }
     }
   }
 }