negotiate payment terms as a checkout selection

source/schemas/common/types/warning_code.json

@@ -8,6 +8,7 @@
     "final_sale",
     "prop65",
     "fulfillment_changed",
+    "payment_term_changed",
     "age_restricted"
   ]
 }

source/schemas/shopping/payment_terms.json

@@ -2,9 +2,8 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://ucp.dev/schemas/shopping/payment_terms.json",
   "name": "dev.ucp.shopping.payment_terms",
-  "version": "2026-01-23",
   "title": "Payment Terms Extension",
-  "description": "Extends Checkout with flexible payment terms support, enabling deferred payments, installments, and per-line-item payment schedules.",
+  "description": "Extends Checkout with selectable payment terms, letting a Business offer alternative schedules for when payment for the checkout is due, and projects the accepted term onto the resulting Order.",
   "requires": {
     "protocol": { "min": "2026-04-08" },
     "capabilities": {
@@ -13,83 +12,54 @@
     }
   },
   "$defs": {
-    "available_payment_term": {
-      "$ref": "types/available_payment_term.json"
-    },
     "payment_term": {
       "$ref": "types/payment_term.json"
     },
-    "payment_schedule": {
-      "$ref": "types/payment_schedule.json"
-    },
-    "schedule_ref": {
-      "$ref": "types/entity_ref.json"
-    },
-    "available_payment_instrument": {
-      "title": "Available Payment Instrument (Payment Terms)",
-      "description": "Extends available_payment_instrument with term reference constraints.",
-      "allOf": [
-        { "$ref": "types/available_payment_instrument.json" },
-        {
-          "type": "object",
-          "properties": {
-            "constraints": {
-              "type": "object",
-              "properties": {
-                "term_refs": {
-                  "type": "array",
-                  "items": { "$ref": "#/$defs/schedule_ref" },
-                  "description": "Payment terms and schedules this instrument supports. References can target a payment term by `id`, a payment schedule by `schedule_id`, a schedule class by `schedule_type`, or a combination. If omitted, the instrument supports all terms and schedules unless constrained by the payment handler."
-                }
-              }
-            }
-          }
-        }
-      ]
-    },
-    "payment_instrument": {
-      "title": "Payment Instrument (Payment Terms)",
-      "description": "Payment instrument extended with payment term and payment schedule assignment.",
-      "allOf": [
-        { "$ref": "types/payment_instrument.json" },
-        {
-          "type": "object",
-          "properties": {
-            "term_refs": {
-              "type": "array",
-              "items": { "$ref": "#/$defs/schedule_ref" },
-              "description": "Payment terms or schedules this instrument pays for. References can target a payment term by `id`, a payment schedule by `schedule_id`, a schedule class by `schedule_type`, or a combination. If omitted, the instrument can be applied by the business according to the selected terms and handler constraints."
-            }
-          }
-        }
-      ]
-    },
     "payment": {
       "title": "Payment with Terms",
-      "description": "Payment object extended with payment terms.",
+      "description": "Payment object extended with selectable payment terms.",
       "allOf": [
         { "$ref": "payment.json" },
         {
           "type": "object",
+          "required": ["terms"],
           "properties": {
-            "available_terms": {
+            "terms": {
               "type": "array",
-              "items": { "$ref": "#/$defs/available_payment_term" },
-              "description": "Available payment terms the buyer can choose from. Each term defines schedules for when payments are due.",
+              "items": { "$ref": "#/$defs/payment_term" },
+              "minItems": 1,
+              "description": "Payment terms the Buyer can choose from. An unselected term's amounts are indicative; the selected term's schedule totals sum to the checkout total.",
               "ucp_request": "omit"
             },
-            "instruments": {
-              "type": "array",
-              "items": { "$ref": "#/$defs/payment_instrument" },
-              "description": "Payment instruments, optionally assigned to selected payment terms or schedules."
+            "selected_term_id": {
+              "type": "string",
+              "description": "ID of the selected payment term. MUST match one `terms[].id` from the latest Checkout response. Always present in responses: the Checkout total is the selected term's total, so a response without a selection would show an amount that matches no stated terms. Where the Buyer has made no choice, the Business selects a default. Omitted on create requests because term IDs are checkout-scoped and no terms exist yet. Selecting a term is a Checkout mutation: the Business response is authoritative for all derived state.",
+              "ucp_request": {
+                "create": "omit",
+                "update": "optional",
+                "complete": "optional"
+              },
+              "ucp_response": "required"
             }
           }
         }
       ]
     },
+    "order_payment": {
+      "title": "Order Payment with Accepted Term",
+      "description": "Order payment details carrying the term the Buyer accepted at checkout.",
+      "type": "object",
+      "required": ["accepted_term"],
+      "properties": {
+        "accepted_term": {
+          "$ref": "#/$defs/payment_term",
+          "description": "The payment term the Buyer accepted at checkout. Businesses MUST carry it forward so the Order states the amounts owed and when, and MUST ensure its schedule totals sum to the Order total. The available terms are checkout state and are not projected."
+        }
+      }
+    },
     "dev.ucp.shopping.checkout": {
       "title": "Checkout with Payment Terms",
-      "description": "Checkout extended with payment terms and payment schedules.",
+      "description": "Checkout extended with selectable payment terms.",
       "allOf": [
         { "$ref": "checkout.json" },
         {
@@ -109,22 +79,17 @@
       ]
     },
     "dev.ucp.shopping.order": {
-      "title": "Order with Payment Terms",
-      "description": "Order extended with the payment terms accepted during checkout.",
+      "title": "Order with Accepted Payment Term",
+      "description": "Order extended with the payment term accepted at checkout.",
       "allOf": [
         { "$ref": "order.json" },
         {
           "type": "object",
           "properties": {
             "payment": {
-              "type": "object",
-              "properties": {
-                "terms": {
-                  "type": "array",
-                  "items": { "$ref": "#/$defs/available_payment_term" },
-                  "description": "Complete payment terms accepted for the originating checkout."
-                }
-              }
+              "$ref": "#/$defs/order_payment",
+              "description": "Payment details for the Order, including the accepted payment term.",
+              "ucp_response": "required"
             }
           }
         }

source/schemas/shopping/types/payment_schedule.json

@@ -2,25 +2,48 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://ucp.dev/schemas/shopping/types/payment_schedule.json",
   "title": "Payment Schedule",
-  "description": "A named payment obligation within a payment term. Timing is disclosed in buyer-facing text while totals provide a structured allocation amount.",
+  "description": "A single payment that settles part or all of the checkout under a payment term. Timing is stated in buyer-facing text; `type` and `due_at` are supplementary machine-readable signals derived from it.",
   "type": "object",
-  "required": ["id", "type", "description", "totals"],
+  "required": [
+    "id",
+    "type",
+    "description",
+    "totals"
+  ],
+  "additionalProperties": true,
   "properties": {
     "id": {
       "type": "string",
-      "description": "Unique identifier for this payment schedule."
+      "description": "Identifier for this payment schedule, unique within its payment term. Businesses SHOULD keep it stable across responses while the schedule remains the same payment."
     },
     "type": {
-      "$ref": "schedule_type.json",
-      "description": "Broad payment timing class. Well-known values: `immediate` and `deferred`."
+      "type": "string",
+      "description": "Timing class, drawn from an open vocabulary. `immediate` is the only value with defined meaning: the payment is captured when the checkout is completed. Any other value means the payment is not captured at completion, and `description` states when it is due. Businesses MAY use additional values (e.g. `deferred`, `on_shipment`); Platforms MUST treat unrecognized values as not captured at completion."
     },
     "description": {
+      "$ref": "../../common/types/description.json",
+      "description": "Complete buyer-facing statement of when and how this payment is due. Businesses MUST make this field sufficient on its own: a Platform that recognizes no `type` value and reads no other field MUST be able to present this schedule correctly. Platforms MAY use `type` and `due_at` for enhanced presentation, but MUST NOT present derived timing that contradicts this field."
+    },
+    "due_at": {
       "type": "string",
-      "description": "Complete buyer-facing explanation of when and how the payment is due."
+      "format": "date-time",
+      "description": "Absolute RFC 3339 date-time when this payment is due, when the Business can determine one at checkout. Supplementary to `description`, never a replacement for it. Omitted when the due date depends on a future event (e.g. 'due on delivery'); the timing is then stated in `description` alone."
     },
     "totals": {
-      "$ref": "totals.json",
-      "description": "Aggregate pricing breakdown for every payment represented by this schedule. The entry with `type: total` is the complete amount allocated to the schedule in the checkout or order currency."
+      "type": "array",
+      "items": {
+        "allOf": [
+          { "$ref": "total.json" },
+          {
+            "if": { "properties": { "type": { "const": "total" } }, "required": ["type"] },
+            "then": { "properties": { "amount": { "minimum": 0 } } }
+          }
+        ]
+      },
+      "contains": { "properties": { "type": { "const": "total" } }, "required": ["type"] },
+      "minContains": 1,
+      "maxContains": 1,
+      "description": "What this one payment costs. Businesses MUST include exactly one `total` entry with a non-negative amount: the final amount charged when this payment is taken, inclusive of tax and every other charge, in the checkout currency's minor units (ISO 4217). Unlike checkout totals, no `subtotal` is required, because the purchase is priced at the checkout rather than once per payment."
     }
   }
 }

source/schemas/shopping/types/payment_term.json

@@ -2,13 +2,34 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://ucp.dev/schemas/shopping/types/payment_term.json",
   "title": "Payment Term",
-  "description": "A buyer's selection of a payment term for specific line items.",
+  "description": "A way of paying for the checkout: one or more payment schedules that together cover its total.",
   "type": "object",
-  "required": ["id"],
+  "required": [
+    "id",
+    "title",
+    "schedules"
+  ],
+  "additionalProperties": true,
   "properties": {
     "id": {
       "type": "string",
-      "description": "ID of the selected payment term from available_terms."
+      "description": "Unique identifier for this payment term within the checkout. Referenced by `payment.selected_term_id`."
+    },
+    "title": {
+      "type": "string",
+      "description": "Short label that distinguishes this term from its siblings (e.g. 'Pay now', 'Pay in 4', 'Deposit + balance at check-in')."
+    },
+    "description": {
+      "$ref": "../../common/types/description.json",
+      "description": "Supplementary context for the title (e.g. 'Save 5% by paying today'). Directly renderable; MUST NOT repeat the title."
+    },
+    "schedules": {
+      "type": "array",
+      "items": {
+        "$ref": "payment_schedule.json"
+      },
+      "minItems": 1,
+      "description": "Payment schedules that settle this checkout under this term, in the order they come due."
     }
   }
 }