Feat/cart loyalty post order

docs/specification/cart.md

@@ -0,0 +1,52 @@
+<!--
+   Copyright 2026 UCP Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+
+# Cart Capability
+
+* **Capability Name:** `dev.ucp.shopping.cart`
+* **Version:** `2026-01-11`
+
+## Overview
+
+The Cart capability provides a first-class basket for multi-item shopping before
+checkout. It allows platforms to build, validate, and update carts without
+collecting payment details.
+
+A cart can be converted into a checkout session by sending the cart's
+`line_items` to the Checkout create endpoint.
+
+## Endpoints
+
+### Create Cart
+
+{{ method_fields('create_cart', 'rest.openapi.json', 'cart') }}
+
+### Get Cart
+
+{{ method_fields('get_cart', 'rest.openapi.json', 'cart') }}
+
+### Update Cart
+
+{{ method_fields('update_cart', 'rest.openapi.json', 'cart') }}
+
+## Schema
+
+{{ schema_fields('cart_resp', 'cart') }}
+
+## Related Specs
+
+* [Checkout Capability](checkout.md)
+* [HTTP/REST Binding](checkout-rest.md)

docs/specification/loyalty.md

@@ -0,0 +1,93 @@
+<!--
+   Copyright 2026 UCP Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+
+# Loyalty Extension
+
+* **Capability Name:** `dev.ucp.shopping.loyalty`
+* **Version:** `2026-01-11`
+* **Extends:** `dev.ucp.shopping.checkout`
+
+## Overview
+
+The Loyalty extension lets platforms link a shopper's membership and apply
+eligible benefits during checkout. It pairs with Identity Linking for account
+connection and uses standard checkout updates to apply benefits or redeem
+points.
+
+## Discovery
+
+Businesses advertise loyalty support in their discovery profile:
+
+```json
+{
+  "name": "dev.ucp.shopping.loyalty",
+  "version": "2026-01-11",
+  "spec": "https://ucp.dev/specification/loyalty",
+  "schema": "https://ucp.dev/schemas/shopping/loyalty.json",
+  "extends": "dev.ucp.shopping.checkout"
+}
+```
+
+## Account Linking Flow
+
+1.  The platform links the user's account using the Identity Linking capability.
+2.  The business returns a loyalty `member_id` or indicates linking is required.
+
+See [Identity Linking Capability](identity-linking.md) for OAuth requirements.
+
+## Benefit Application Flow
+
+1.  Platform submits `loyalty` details in a checkout update.
+2.  Business applies benefits and returns `benefits_applied` with updated totals.
+
+### Example checkout update
+
+```json
+{
+  "id": "chk_123",
+  "loyalty": {
+    "program_id": "loyalty_prime",
+    "member_id": "member_456",
+    "redemption": { "points": 1200 }
+  }
+}
+```
+
+### Example checkout response
+
+```json
+{
+  "id": "chk_123",
+  "loyalty": {
+    "program_id": "loyalty_prime",
+    "member_id": "member_456",
+    "status": "linked",
+    "tier": "gold",
+    "points_balance": 4200,
+    "benefits_applied": [
+      {
+        "type": "points_redemption",
+        "amount": 1200,
+        "description": "Redeemed 1,200 points"
+      }
+    ]
+  }
+}
+```
+
+## Schema
+
+{{ extension_schema_fields('loyalty.json#/$defs/loyalty_object', 'checkout') }}

docs/specification/order.md

@@ -95,6 +95,11 @@ fulfillment:
 - Include amount when relevant
 - Can happen at any time regardless of fulfillment status
 
+### Post-Order Management Extension
+
+For structured return, exchange, and refund events, see the
+[Post-Order Management Extension](post-order.md).
+
 ## Schema
 
 ### Order

docs/specification/overview.md

@@ -181,6 +181,9 @@ Extensions can be:
 -   **Official**: `dev.ucp.shopping.fulfillment` extends `dev.ucp.shopping.checkout`
 -   **Vendor**: `com.example.installments` extends `dev.ucp.shopping.checkout`
 
+Common extensions include `dev.ucp.shopping.discount`, `dev.ucp.shopping.fulfillment`,
+`dev.ucp.shopping.loyalty`, and `dev.ucp.shopping.post_order`.
+
 ### Schema Composition
 
 Extensions can add new fields and modify shared structures (e.g., discounts
@@ -976,6 +979,7 @@ UCP defines a set of standard capabilities:
 
 | Capability Name      | ID (URI)                                         | Description                                                                                                  |
 | :------------------- | :----------------------------------------------- | :----------------------------------------------------------------------------------------------------------- |
+| **Cart**             | `{{ ucp_url }}/schemas/shopping/cart.json`             | Provides a first-class basket for multi-item shopping prior to checkout.                                       |
 | **Checkout**         | `{{ ucp_url }}/schemas/shopping/checkout.json`         | Facilitates the creation and management of checkout sessions, including cart management and tax calculation. |
 | **Identity Linking** | - | Enables platforms to obtain authorization via OAuth 2.0 to perform actions on a user's behalf.               |
 | **Order**            | `{{ ucp_url }}/schemas/shopping/order.json`            | Allows businesses to push asynchronous updates about an order's lifecycle (shipping, delivery, returns).      |
@@ -1168,4 +1172,4 @@ Vendors control their own release schedules and versioning strategy.
 | **Payment Service Provider**      | PSP     | The financial infrastructure provider that processes payments, authorizations, and settlements on behalf of the business.               |
 | **Platform**                      | -       | The consumer-facing surface (AI agent, app, website) acting on behalf of the user to discover businesses and facilitate commerce.                              |
 | **Verifiable Digital Credential** | VDC     | An Issuer-signed credential (set of claims) whose authenticity can be verified cryptographically. Used in UCP for secure payment authorizations.              |
-| **Verifiable Presentation**       | VP      | A presentation of one or more VDCs that includes a cryptographic proof of binding, used to prove authorization to a business or PSP.                          |
+| **Verifiable Presentation**       | VP      | A presentation of one or more VDCs that includes a cryptographic proof of binding, used to prove authorization to a business or PSP.                          |

docs/specification/post-order.md

@@ -0,0 +1,78 @@
+<!--
+   Copyright 2026 UCP Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+
+# Post-Order Management Extension
+
+* **Capability Name:** `dev.ucp.shopping.post_order`
+* **Version:** `2026-01-11`
+* **Extends:** `dev.ucp.shopping.order`
+
+## Overview
+
+The Post-Order Management extension standardizes how businesses report returns,
+exchanges, and refunds after a checkout completes. These events supplement the
+base `adjustments` and fulfillment logs with explicit, structured post-order
+signals.
+
+## Return Flow
+
+1.  Platform initiates a return with the business (outside the core UCP flow).
+2.  Business appends a return event to the order response.
+
+## Exchange Flow
+
+1.  Platform requests an exchange with desired replacements.
+2.  Business appends an exchange event to the order response.
+
+## Refund Flow
+
+1.  Business issues a refund after return approval or cancellation.
+2.  Business appends a refund event to the order response.
+
+## Example Order Response
+
+```json
+{
+  "id": "order_123",
+  "post_order": {
+    "returns": [
+      {
+        "id": "ret_1",
+        "status": "approved",
+        "occurred_at": "2026-01-11T14:30:00Z",
+        "line_items": [{ "id": "li_1", "quantity": 1 }],
+        "reason_code": "defective",
+        "description": "Defective item"
+      }
+    ],
+    "refunds": [
+      {
+        "id": "ref_1",
+        "status": "completed",
+        "occurred_at": "2026-01-12T10:15:00Z",
+        "amount": 26550,
+        "line_items": [{ "id": "li_1", "quantity": 1 }],
+        "reason_code": "return_completed",
+        "description": "Refund after return"
+      }
+    ]
+  }
+}
+```
+
+## Schema
+
+{{ extension_schema_fields('post_order.json#/$defs/post_order_object', 'order') }}

mkdocs.yml

@@ -30,6 +30,8 @@ nav:
   - Playground: playground.md
   - Specification:
     - Overview: specification/overview.md
+    - Cart Capability:
+      - Overview: specification/cart.md
     - Checkout Capability:
       - Overview: specification/checkout.md
       - HTTP/REST Binding: specification/checkout-rest.md
@@ -40,7 +42,10 @@ nav:
       - Buyer Consent Extension: specification/buyer-consent.md
       - Discounts Extension: specification/discount.md
       - Fulfillment Extension: specification/fulfillment.md
-    - Order Capability: specification/order.md
+      - Loyalty Extension: specification/loyalty.md
+    - Order Capability:
+      - Overview: specification/order.md
+      - Post-Order Extension: specification/post-order.md
     - Identity Linking Capability: specification/identity-linking.md
     - Payment Handlers:
       - Guide: specification/payment-handler-guide.md
@@ -187,6 +192,8 @@ plugins:
           - documentation/roadmap.md
         Specification Overview:
           - specification/overview.md
+        Cart Capability:
+          - specification/cart.md
         Checkout Capability:
           - specification/checkout.md
           - specification/checkout-rest.md
@@ -198,8 +205,10 @@ plugins:
           - specification/discount.md
           - specification/embedded-checkout.md
           - specification/fulfillment.md
+          - specification/loyalty.md
         Order Capability:
           - specification/order.md
+          - specification/post-order.md
         Identity Linking Capability:
           - specification/identity-linking.md
         Payment Handlers:

source/schemas/shopping/cart.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/schemas/shopping/cart.json",
+  "name": "dev.ucp.shopping.cart",
+  "version": "2026-01-11",
+  "title": "Cart",
+  "description": "Cart schema for multi-item baskets prior to checkout.",
+  "type": "object",
+  "required": [
+    "ucp",
+    "id",
+    "line_items",
+    "status",
+    "currency",
+    "totals"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "ucp": {
+      "$ref": "../ucp.json#/$defs/response_cart",
+      "ucp_request": "omit"
+    },
+    "id": {
+      "type": "string",
+      "description": "Unique cart identifier.",
+      "ucp_request": {
+        "create": "omit",
+        "update": "required"
+      }
+    },
+    "line_items": {
+      "type": "array",
+      "items": {
+        "$ref": "types/line_item.json"
+      },
+      "description": "List of line items in the cart."
+    },
+    "buyer": {
+      "$ref": "types/buyer.json",
+      "description": "Representation of the buyer."
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "active",
+        "ready_for_checkout",
+        "converted",
+        "abandoned",
+        "expired"
+      ],
+      "description": "Cart lifecycle status.",
+      "ucp_request": "omit"
+    },
+    "currency": {
+      "type": "string",
+      "description": "ISO 4217 currency code."
+    },
+    "totals": {
+      "type": "array",
+      "items": {
+        "$ref": "types/total.json"
+      },
+      "description": "Different cart totals.",
+      "ucp_request": "omit"
+    },
+    "messages": {
+      "type": "array",
+      "items": {
+        "$ref": "types/message.json"
+      },
+      "description": "Messages about cart state.",
+      "ucp_request": "omit"
+    },
+    "links": {
+      "type": "array",
+      "items": {
+        "$ref": "types/link.json"
+      },
+      "description": "Links to policies and terms.",
+      "ucp_request": "omit"
+    },
+    "expires_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "RFC 3339 expiry timestamp.",
+      "ucp_request": "omit"
+    },
+    "checkout_id": {
+      "type": "string",
+      "description": "Checkout session created from this cart, if converted.",
+      "ucp_request": "omit"
+    }
+  }
+}