> ## Documentation Index > Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt > Use this file to discover all available pages before exploring further. # UCP order management and fulfillment events > UCP order management capability — line item status, fulfillment events, adjustments, Webhook signatures (RFC 9421), and order lifecycle # Order Management ## 4.1 Capability Identifier The order management namespace is `dev.ucp.shopping.order`. It covers the complete post-checkout lifecycle — from order confirmation through final delivery (or return and refund). ## 4.2 Line Item Status UCP manages orders at the **line item level**, giving each product its own independent status tracking. This supports complex scenarios such as partial shipments and partial refunds: | Status | Meaning | Description | | ------------ | ------------------- | ------------------------------------------------------------------------ | | `processing` | Processing | Order confirmed; items are being prepared for shipment | | `partial` | Partially fulfilled | Some quantity of the line item has shipped (e.g., ordered 3, shipped 2) | | `fulfilled` | Fulfilled | All quantity has been delivered | | `removed` | Removed | Line item has been removed from the order (canceled or return completed) | ```json theme={null} { "order": { "id": "ord_20260411_xyz789", "status": "active", "line_items": [ { "id": "li_001", "product_id": "prod_abc123", "name": "Classic Canvas Sneakers - White Size 9", "quantity": 2, "status": "partial", "fulfilled_quantity": 1, "unit_price": { "amount": 5900, "currency_code": "USD" } }, { "id": "li_002", "product_id": "prod_def456", "name": "Athletic Socks 3-Pack", "quantity": 1, "status": "fulfilled", "fulfilled_quantity": 1, "unit_price": { "amount": 990, "currency_code": "USD" } } ] } } ``` ## 4.3 Fulfillment Events UCP defines standardized fulfillment event types that cover every logistics milestone from shipment to delivery: | Event Type | Meaning | | -------------------- | --------------------------------------- | | `processing` | Being processed / prepared | | `shipped` | Shipped; handed off to carrier | | `in_transit` | In transit | | `out_for_delivery` | Out for delivery | | `attempted_delivery` | Delivery attempted but unsuccessful | | `delivered` | Delivered | | `ready_for_pickup` | Ready for pickup at designated location | | `picked_up` | Picked up by customer | | `failed` | Delivery failed | | `returned_to_sender` | Returned to sender | Each fulfillment event includes a timestamp, description, and optional tracking information: ```json theme={null} { "fulfillment": { "id": "ful_001", "line_item_ids": ["li_001"], "tracking": { "carrier": "UPS", "tracking_number": "1Z999AA10123456784", "tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784" }, "events": [ { "type": "delivered", "occurred_at": "2026-04-14T14:30:00Z", "description": "Delivered - signed by recipient" }, { "type": "out_for_delivery", "occurred_at": "2026-04-14T08:00:00Z", "description": "Out for delivery" }, { "type": "in_transit", "occurred_at": "2026-04-13T06:00:00Z", "description": "Arrived at regional distribution center" }, { "type": "shipped", "occurred_at": "2026-04-12T10:00:00Z", "description": "Picked up by carrier" } ] } } ``` ## 4.4 Adjustments After an order is placed, various adjustments may be necessary. UCP defines standardized adjustment types: | Adjustment Type | Meaning | Initiated By | | ------------------ | ----------------------------------------- | -------------------- | | `refund` | Refund | Merchant or consumer | | `return` | Return | Consumer | | `credit` | Store credit / loyalty points | Merchant | | `exchange` | Exchange | Consumer | | `price_adjustment` | Price adjustment (e.g., price protection) | Merchant | ### Return / Refund Request ```http theme={null} POST /ucp/orders/{order_id}/adjustments Content-Type: application/json Authorization: Bearer {access_token} { "type": "return", "line_items": [ { "line_item_id": "li_001", "quantity": 1, "reason": "wrong_size" } ], "preferred_resolution": "refund", "notes": "Size runs small, need one size up or a refund" } ``` Response: ```json theme={null} { "adjustment": { "id": "adj_001", "type": "return", "status": "pending_merchant_approval", "created_at": "2026-04-16T10:00:00Z", "line_items": [ { "line_item_id": "li_001", "quantity": 1, "reason": "wrong_size" } ], "return_shipping": { "label_url": null, "instructions": "Return shipping label will be provided after merchant approval" } } } ``` ## 4.5 Querying Orders ```http theme={null} GET /ucp/orders/{order_id} Authorization: Bearer {access_token} ``` Returns the complete order state, including all line items, fulfillment events, and adjustment history. ### Listing Orders ```http theme={null} GET /ucp/orders?limit=20&offset=0&status=active Authorization: Bearer {access_token} ``` ## 4.6 Webhook Notifications When an order status changes, the merchant proactively notifies the AI agent via Webhooks. UCP Webhooks use **RFC 9421 HTTP Message Signatures** to ensure data integrity and source authenticity. ### Webhook Request Format ```http theme={null} POST https://agent.example.com/webhooks/ucp Content-Type: application/json Content-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: Signature-Input: sig1=("@method" "@target-uri" "content-digest" "content-type");created=1712836800;keyid="key-2026-04" Signature: sig1=:MEUCIQDXsM...base64...=: { "event_type": "order.fulfillment.updated", "event_id": "evt_20260414_001", "occurred_at": "2026-04-14T14:30:00Z", "order_id": "ord_20260411_xyz789", "data": { "fulfillment_id": "ful_001", "new_event": { "type": "delivered", "occurred_at": "2026-04-14T14:30:00Z", "description": "Delivered" } } } ``` ### Webhook Signature Verification When an AI agent receives a Webhook, it must verify the signature: 1. Parse `Signature-Input` to extract signature parameters (covered components, creation time, key ID) 2. Retrieve the corresponding public key (JWK) by `kid` from the merchant's `/.well-known/ucp` Profile 3. Verify the request body's SHA-256 hash using the `Content-Digest` header 4. Verify the ES256 signature in the `Signature` header using the public key 5. Check the `created` timestamp and reject expired signatures (recommended window: 5 minutes) ```text theme={null} Verification Flow: 1. Parse Signature-Input -> keyid="key-2026-04" 2. Fetch merchant JWK -> /.well-known/ucp -> signing_keys[kid="key-2026-04"] 3. Verify Content-Digest -> SHA-256(body) == Content-Digest value 4. Construct signature base string -> concatenate components in Signature-Input order 5. Verify ES256 signature ``` ### Webhook Event Types | Event | Trigger | | --------------------------- | ----------------------------------------------------- | | `order.created` | Checkout completed; order created | | `order.fulfillment.updated` | Fulfillment status changed (shipped, delivered, etc.) | | `order.adjustment.created` | New adjustment request created | | `order.adjustment.updated` | Adjustment status changed (approved, completed, etc.) | | `order.canceled` | Order canceled | ## 4.7 Order Lifecycle Overview ```text theme={null} Checkout Complete | v Order Created (line items: processing) | +---> Partial Shipment (partial) ---> Fully Shipped (fulfilled) | | | +---> Return Request (adjustment: return) | | +---> Refund (adjustment: refund) | | +---> Exchange (adjustment: exchange) | | | +---> Complete | +---> Canceled (removed) ``` *** **Next chapter**: [Product Data and Transports](/en/book-3/ch5-product-data) — MCP tools, four transport mechanisms, and data formats