portage-ucp 0.1.0

data/schemas/2026-04-08/schemas/shopping/checkout.json

@@ -0,0 +1,131 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json",
+  "name": "dev.ucp.shopping.checkout",
+  "title": "Checkout",
+  "description": "Base checkout schema. Extensions compose onto this using allOf.",
+  "type": "object",
+  "required": [
+    "ucp",
+    "id",
+    "line_items",
+    "status",
+    "currency",
+    "totals",
+    "links"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "ucp": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/ucp.json#/$defs/response_checkout_schema",
+      "ucp_request": "omit"
+    },
+    "id": {
+      "type": "string",
+      "description": "Unique identifier of the checkout session.",
+      "ucp_request": "omit"
+    },
+    "line_items": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/line_item.json"
+      },
+      "description": "List of line items being checked out.",
+      "ucp_request": {
+        "create": "required",
+        "update": "required",
+        "complete": "omit"
+      }
+    },
+    "buyer": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/buyer.json",
+      "description": "Representation of the buyer.",
+      "ucp_request": {
+        "create": "optional",
+        "update": "optional",
+        "complete": "omit"
+      }
+    },
+    "context": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/context.json",
+      "ucp_request": {
+        "create": "optional",
+        "update": "optional",
+        "complete": "omit"
+      }
+    },
+    "signals": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/signals.json",
+      "ucp_request": "optional"
+    },
+    "attribution": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/attribution.json",
+      "ucp_request": "optional"
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "incomplete",
+        "requires_escalation",
+        "ready_for_complete",
+        "complete_in_progress",
+        "completed",
+        "canceled"
+      ],
+      "description": "Checkout state indicating the current phase and required action. See Checkout Status lifecycle documentation for state transition details.",
+      "ucp_request": "omit"
+    },
+    "currency": {
+      "type": "string",
+      "description": "ISO 4217 currency code reflecting the merchant's market determination. Derived from address, context, and geo IP—buyers provide signals, merchants determine currency.",
+      "ucp_request": "omit"
+    },
+    "totals": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/totals.json",
+      "description": "Different cart totals.",
+      "ucp_request": "omit"
+    },
+    "messages": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/message.json"
+      },
+      "description": "List of messages with error and info about the checkout session state.",
+      "ucp_request": "omit"
+    },
+    "links": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/link.json"
+      },
+      "description": "Links to be displayed by the platform (Privacy Policy, TOS). Mandatory for legal compliance.",
+      "ucp_request": "omit"
+    },
+    "expires_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "RFC 3339 expiry timestamp. Default TTL is 6 hours from creation if not sent.",
+      "ucp_request": "omit"
+    },
+    "continue_url": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL for checkout handoff and session recovery. MUST be provided when status is requires_escalation. See specification for format and availability requirements.",
+      "ucp_request": "omit"
+    },
+    "payment": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/payment.json",
+      "ucp_request": {
+        "create": "optional",
+        "update": "optional",
+        "complete": "required"
+      }
+    },
+    "order": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/order_confirmation.json",
+      "description": "Details about an order created for this checkout session.",
+      "ucp_request": "omit"
+    }
+  },
+  "version": "2026-04-08"
+}

data/schemas/2026-04-08/schemas/shopping/discount.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/discount.json",
+  "name": "dev.ucp.shopping.discount",
+  "title": "Discount Extension",
+  "description": "Extends Cart and Checkout with discount support, including discount codes, automatic discounts, and eligibility-triggered provisional discounts.",
+  "$defs": {
+    "allocation": {
+      "type": "object",
+      "description": "Breakdown of how a discount amount was allocated to a specific target.",
+      "required": [
+        "path",
+        "amount"
+      ],
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "JSONPath to the allocation target (e.g., '$.line_items[0]', '$.totals.shipping')."
+        },
+        "amount": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/amount.json",
+          "description": "Amount allocated to this target in ISO 4217 minor units."
+        }
+      }
+    },
+    "applied_discount": {
+      "type": "object",
+      "description": "A discount that was successfully applied.",
+      "required": [
+        "title",
+        "amount"
+      ],
+      "properties": {
+        "code": {
+          "type": "string",
+          "description": "The discount code. Omitted for automatic discounts."
+        },
+        "title": {
+          "type": "string",
+          "description": "Human-readable discount name (e.g., 'Summer Sale 20% Off')."
+        },
+        "amount": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/amount.json",
+          "description": "Total discount amount in ISO 4217 minor units."
+        },
+        "automatic": {
+          "type": "boolean",
+          "default": false,
+          "description": "True if applied automatically by merchant rules (no code required)."
+        },
+        "method": {
+          "type": "string",
+          "enum": [
+            "each",
+            "across"
+          ],
+          "description": "Allocation method. 'each' = applied independently per item. 'across' = split proportionally by value."
+        },
+        "priority": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Stacking order for discount calculation. Lower numbers applied first (1 = first)."
+        },
+        "provisional": {
+          "type": "boolean",
+          "default": false,
+          "description": "True if this discount requires additional verification."
+        },
+        "eligibility": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/reverse_domain_name.json",
+          "description": "The eligibility claim accepted by the Business for this discount. Corresponds to a value from context.eligibility. Omitted for code-based and non-eligibility automatic discounts."
+        },
+        "allocations": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/allocation"
+          },
+          "description": "Breakdown of where this discount was allocated. Sum of allocation amounts equals total amount."
+        }
+      }
+    },
+    "discounts_object": {
+      "type": "object",
+      "description": "Discount codes input and applied discounts output.",
+      "properties": {
+        "codes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Discount codes to apply. Case-insensitive. Replaces previously submitted codes. Send empty array to clear."
+        },
+        "applied": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/applied_discount"
+          },
+          "description": "Discounts successfully applied (code-based and automatic).",
+          "ucp_request": "omit"
+        }
+      }
+    },
+    "dev.ucp.shopping.cart": {
+      "title": "Cart with Discount",
+      "description": "Cart extended with discount capability.",
+      "allOf": [
+        {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/cart.json"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "discounts": {
+              "$ref": "#/$defs/discounts_object",
+              "ucp_request": {
+                "create": "optional",
+                "update": "optional"
+              }
+            }
+          }
+        }
+      ]
+    },
+    "dev.ucp.shopping.checkout": {
+      "title": "Checkout with Discount",
+      "description": "Checkout extended with discount capability.",
+      "allOf": [
+        {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "discounts": {
+              "$ref": "#/$defs/discounts_object",
+              "ucp_request": {
+                "create": "optional",
+                "update": "optional",
+                "complete": "omit"
+              }
+            }
+          }
+        }
+      ]
+    }
+  },
+  "version": "2026-04-08"
+}

data/schemas/2026-04-08/schemas/shopping/fulfillment.json

@@ -0,0 +1,154 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/fulfillment.json",
+  "name": "dev.ucp.shopping.fulfillment",
+  "title": "Fulfillment Extension",
+  "description": "Extends Checkout with fulfillment support using methods, destinations, and groups.",
+  "$defs": {
+    "fulfillment_option": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/fulfillment_option.json"
+    },
+    "fulfillment_group": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/fulfillment_group.json"
+    },
+    "fulfillment_method": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/fulfillment_method.json"
+    },
+    "fulfillment_available_method": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/fulfillment_available_method.json"
+    },
+    "fulfillment": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/fulfillment.json"
+    },
+    "dev.ucp.shopping.checkout": {
+      "title": "Checkout with Fulfillment",
+      "description": "Checkout extended with hierarchical fulfillment.",
+      "allOf": [
+        {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "fulfillment": {
+              "$ref": "#/$defs/fulfillment",
+              "description": "Fulfillment details.",
+              "ucp_request": {
+                "create": "optional",
+                "update": "optional",
+                "complete": "omit"
+              }
+            }
+          }
+        }
+      ]
+    },
+    "dev.ucp.shopping.fulfillment": {
+      "platform_schema": {
+        "title": "Fulfillment Capability (Platform)",
+        "description": "Platform-level fulfillment capability configuration",
+        "allOf": [
+          {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/capability.json#/$defs/platform_schema"
+          },
+          {
+            "properties": {
+              "config": {
+                "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/platform_fulfillment_config.json",
+                "description": "Platform fulfillment configuration"
+              }
+            }
+          }
+        ]
+      },
+      "business_schema": {
+        "title": "Fulfillment Capability (Business)",
+        "description": "Business-level fulfillment capability configuration",
+        "allOf": [
+          {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/capability.json#/$defs/business_schema"
+          },
+          {
+            "properties": {
+              "config": {
+                "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/business_fulfillment_config.json",
+                "description": "Business fulfillment configuration"
+              }
+            }
+          }
+        ]
+      }
+    }
+  },
+  "embedded": {
+    "delegations": [
+      "fulfillment.address_change"
+    ],
+    "methods": {
+      "ec.fulfillment.change": {
+        "name": "ec.fulfillment.change",
+        "summary": "Fulfillment details changed",
+        "description": "Merchant notifies host that checkout.fulfillment has changed (shipping method selected, delivery options updated).",
+        "params": [
+          {
+            "name": "checkout",
+            "required": true,
+            "schema": {
+              "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json",
+              "description": "Current checkout state with updated fulfillment."
+            }
+          }
+        ]
+      },
+      "ec.fulfillment.address_change_request": {
+        "name": "ec.fulfillment.address_change_request",
+        "summary": "Request address change",
+        "description": "Merchant requests host to present address selection UI for a shipping fulfillment method.",
+        "params": [
+          {
+            "name": "checkout",
+            "required": true,
+            "schema": {
+              "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json",
+              "description": "Current checkout state with fulfillment details."
+            }
+          }
+        ],
+        "result": {
+          "name": "addressChangeResult",
+          "schema": {
+            "oneOf": [
+              {
+                "type": "object",
+                "description": "Checkout state after address selection.",
+                "required": [
+                  "ucp",
+                  "checkout"
+                ],
+                "properties": {
+                  "ucp": {
+                    "$ref": "https://ucp.dev/2026-04-08/schemas/ucp.json#/$defs/success"
+                  },
+                  "checkout": {
+                    "type": "object",
+                    "description": "Partial checkout update with fulfillment address selection.",
+                    "properties": {
+                      "fulfillment": {
+                        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/fulfillment.json",
+                        "description": "Updated fulfillment with new selected destination and destinations."
+                      }
+                    }
+                  }
+                }
+              },
+              {
+                "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json"
+              }
+            ]
+          }
+        }
+      }
+    }
+  },
+  "version": "2026-04-08"
+}

data/schemas/2026-04-08/schemas/shopping/order.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/order.json",
+  "name": "dev.ucp.shopping.order",
+  "title": "Order",
+  "description": "Order schema with line items, buyer-facing fulfillment expectations, and event logs.",
+  "$defs": {
+    "platform_schema": {
+      "title": "Platform Order Schema",
+      "description": "Platform's order capability configuration.",
+      "type": "object",
+      "required": [
+        "webhook_url"
+      ],
+      "properties": {
+        "webhook_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL where merchant sends order lifecycle events (webhooks)."
+        }
+      }
+    }
+  },
+  "type": "object",
+  "required": [
+    "ucp",
+    "id",
+    "checkout_id",
+    "permalink_url",
+    "line_items",
+    "fulfillment",
+    "currency",
+    "totals"
+  ],
+  "properties": {
+    "ucp": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/ucp.json#/$defs/response_order_schema"
+    },
+    "id": {
+      "type": "string",
+      "description": "Unique order identifier."
+    },
+    "label": {
+      "type": "string",
+      "description": "Human-readable label for identifying the order. MUST only be provided by the business."
+    },
+    "checkout_id": {
+      "type": "string",
+      "description": "Associated checkout ID for reconciliation."
+    },
+    "permalink_url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Permalink to access the order on merchant site."
+    },
+    "line_items": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/order_line_item.json"
+      },
+      "description": "Line items representing what was purchased — can change post-order via edits or exchanges."
+    },
+    "fulfillment": {
+      "type": "object",
+      "properties": {
+        "expectations": {
+          "type": "array",
+          "items": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/expectation.json"
+          },
+          "description": "Buyer-facing groups representing when/how items will be delivered. Can be split, merged, or adjusted post-order."
+        },
+        "events": {
+          "type": "array",
+          "items": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/fulfillment_event.json"
+          },
+          "description": "Append-only event log of actual shipments. Each event references line items by ID."
+        }
+      },
+      "description": "Fulfillment data: buyer expectations and what actually happened."
+    },
+    "adjustments": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/adjustment.json"
+      },
+      "description": "Post-order events (refunds, returns, credits, disputes, cancellations, etc.) that exist independently of fulfillment."
+    },
+    "currency": {
+      "type": "string",
+      "description": "ISO 4217 currency code. MUST match the currency from the originating checkout session.",
+      "ucp_request": "omit"
+    },
+    "totals": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/totals.json",
+      "description": "Different totals for the order."
+    },
+    "messages": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/message.json"
+      },
+      "description": "Business outcome messages (errors, warnings, informational). Present when the business needs to communicate status or issues to the platform."
+    },
+    "attribution": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/attribution.json",
+      "description": "Snapshot of the attribution associated with the originating checkout. Read-only on the order.",
+      "ucp_request": "omit"
+    }
+  },
+  "version": "2026-04-08"
+}

data/schemas/2026-04-08/schemas/shopping/payment.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/payment.json",
+  "title": "Payment",
+  "description": "Payment configuration containing handlers.",
+  "type": "object",
+  "properties": {
+    "instruments": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/payment_instrument.json#/$defs/selected_payment_instrument"
+      },
+      "description": "The payment instruments available for this payment. Each instrument is associated with a specific handler via the handler_id field. Handlers can extend the base payment_instrument schema to add handler-specific fields."
+    }
+  }
+}

data/schemas/2026-04-08/schemas/shopping/types/adjustment.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/adjustment.json",
+  "title": "Adjustment",
+  "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",
+    "type",
+    "occurred_at",
+    "status"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Adjustment event identifier."
+    },
+    "type": {
+      "type": "string",
+      "description": "Type of adjustment (open string). Typically money-related like: refund, return, credit, price_adjustment, dispute, cancellation. Can be any value that makes sense for the merchant's business."
+    },
+    "occurred_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "RFC 3339 timestamp when this adjustment occurred."
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "pending",
+        "completed",
+        "failed"
+      ],
+      "description": "Adjustment status."
+    },
+    "line_items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "quantity"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Line item ID reference."
+          },
+          "quantity": {
+            "type": "integer",
+            "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)."
+    },
+    "totals": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/total.json"
+      },
+      "description": "Adjustment totals breakdown. Signed values - negative for money returned to buyer (refunds, credits), positive for additional charges (exchanges)."
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable reason or description (e.g., 'Defective item', 'Customer requested')."
+    }
+  }
+}

data/schemas/2026-04-08/schemas/shopping/types/amount.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/amount.json",
+  "title": "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).",
+  "type": "integer",
+  "minimum": 0
+}

data/schemas/2026-04-08/schemas/shopping/types/attribution.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/attribution.json",
+  "title": "Attribution",
+  "description": "Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.",
+  "type": "object",
+  "additionalProperties": {
+    "type": "string",
+    "description": "URL-style parameter value, encoded as a string. Numeric or boolean values MUST be string-encoded as they would be in a URL query string."
+  }
+}