UCP Orders & Webhooks
Before writing code
Fetch live spec: Web-search site:ucp.dev specification order and fetch the page for the exact order data model, webhook envelope, and signature format.
Also fetch https://ucp.dev/latest/specification/reference/ for adjustment types, fulfillment event types, and line item status derivation rules.
Conceptual Architecture
Order Capability (dev.ucp.shopping.order)
Orders represent the post-purchase lifecycle. An order is created when a checkout completes successfully. The order contains:
- Line items with quantity tracking (total, fulfilled)
- Fulfillment expectations (estimated delivery) and fulfillment events (shipped, delivered, etc.)
- Adjustments (refunds, returns, credits, disputes, cancellations)
- Totals (subtotal, tax, discount, fulfillment, fee, total)
Line Item Status Derivation
Status is derived from quantities, not stored:
fulfilled == total → "fulfilled"
fulfilled > 0 → "partial"
fulfilled == 0 → "processing"
Fulfillment Event Types (open string enum)
Common values: processing, shipped, in_transit, delivered, failed_attempt, canceled, undeliverable, returned_to_sender. The set is extensible — new values may appear.
Adjustment Types (open string enum)
Common values: refund, return, credit, price_adjustment, dispute, cancellation. Also extensible.
Webhook Delivery
- Business POSTs the full order entity (not incremental deltas) to the Platform's webhook URL.
- Each delivery includes an
event_id (unique) and created_time (RFC 3339).
- Platform MUST respond with 2xx immediately and process asynchronously.
- Business should implement retry with exponential backoff on non-2xx responses.
Webhook Signature (Detached JWT)
This is critical for security:
Signing (Business side):
- Select an EC P-256 key from
signing_keys in the Business's /.well-known/ucp profile
- Create a Detached JWT (RFC 7797) over the request body
- Set
kid in the JWT header to match the key ID
- Include the signature in the
Request-Signature HTTP header
Verification (Platform side):
- Extract
Request-Signature header
- Parse JWT header for
kid
- Fetch Business's
/.well-known/ucp profile, find the matching key
- Verify the JWT signature against the request body
- Reject if verification fails
Implementation Guidance
Business:
- Generate EC P-256 key pair; publish public key in discovery profile
- After checkout completion, create order entity
- On every fulfillment event or adjustment, POST the full updated order to the platform webhook URL with a fresh signature
- Implement retry logic (exponential backoff, max attempts)
Platform:
- Expose a webhook endpoint URL (declared in order capability config)
- Verify
Request-Signature on every incoming webhook
- Process order updates asynchronously (respond 2xx first)
- Handle idempotency using
event_id
Fetch the conformance test suite at https://github.com/Universal-Commerce-Protocol/conformance for webhook test cases.
1---2name: ucp-orders-webhooks-23description: Implement UCP Order capability and webhook delivery — post-purchase order management with fulfillment tracking, adjustments (refunds/returns), and cryptographically signed webhook notifications. Use when building order management or webhook infrastructure.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/ucp-orders-webhooks-27---89# UCP Orders & Webhooks1011## Before writing code1213**Fetch live spec**: Web-search `site:ucp.dev specification order` and fetch the page for the exact order data model, webhook envelope, and signature format.1415Also fetch https://ucp.dev/latest/specification/reference/ for adjustment types, fulfillment event types, and line item status derivation rules.1617## Conceptual Architecture1819### Order Capability (`dev.ucp.shopping.order`)2021Orders represent the post-purchase lifecycle. An order is created when a checkout completes successfully. The order contains:2223- **Line items** with quantity tracking (total, fulfilled)24- **Fulfillment expectations** (estimated delivery) and **fulfillment events** (shipped, delivered, etc.)25- **Adjustments** (refunds, returns, credits, disputes, cancellations)26- **Totals** (subtotal, tax, discount, fulfillment, fee, total)2728### Line Item Status Derivation2930Status is derived from quantities, not stored:31- `fulfilled == total` → `"fulfilled"`32- `fulfilled > 0` → `"partial"`33- `fulfilled == 0` → `"processing"`3435### Fulfillment Event Types (open string enum)3637Common values: `processing`, `shipped`, `in_transit`, `delivered`, `failed_attempt`, `canceled`, `undeliverable`, `returned_to_sender`. The set is extensible — new values may appear.3839### Adjustment Types (open string enum)4041Common values: `refund`, `return`, `credit`, `price_adjustment`, `dispute`, `cancellation`. Also extensible.4243### Webhook Delivery4445- Business POSTs the **full order entity** (not incremental deltas) to the Platform's webhook URL.46- Each delivery includes an `event_id` (unique) and `created_time` (RFC 3339).47- Platform MUST respond with 2xx immediately and process asynchronously.48- Business should implement retry with exponential backoff on non-2xx responses.4950### Webhook Signature (Detached JWT)5152This is critical for security:53541. **Signing (Business side):**55 - Select an EC P-256 key from `signing_keys` in the Business's `/.well-known/ucp` profile56 - Create a Detached JWT (RFC 7797) over the request body57 - Set `kid` in the JWT header to match the key ID58 - Include the signature in the `Request-Signature` HTTP header59602. **Verification (Platform side):**61 - Extract `Request-Signature` header62 - Parse JWT header for `kid`63 - Fetch Business's `/.well-known/ucp` profile, find the matching key64 - Verify the JWT signature against the request body65 - Reject if verification fails6667### Implementation Guidance6869**Business:**70- Generate EC P-256 key pair; publish public key in discovery profile71- After checkout completion, create order entity72- On every fulfillment event or adjustment, POST the full updated order to the platform webhook URL with a fresh signature73- Implement retry logic (exponential backoff, max attempts)7475**Platform:**76- Expose a webhook endpoint URL (declared in order capability config)77- Verify `Request-Signature` on every incoming webhook78- Process order updates asynchronously (respond 2xx first)79- Handle idempotency using `event_id`8081Fetch the conformance test suite at https://github.com/Universal-Commerce-Protocol/conformance for webhook test cases.