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)

{
  "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:

{
  "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

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:

{
  "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

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

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

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:

Parse Signature-Input to extract signature parameters (covered components, creation time, key ID)
Retrieve the corresponding public key (JWK) by kid from the merchant’s /.well-known/ucp Profile
Verify the request body’s SHA-256 hash using the Content-Digest header
Verify the ES256 signature in the Signature header using the public key
Check the created timestamp and reject expired signatures (recommended window: 5 minutes)

Verification Flow:

Parse Signature-Input -> keyid="key-2026-04"
Fetch merchant JWK -> /.well-known/ucp -> signing_keys[kid="key-2026-04"]
Verify Content-Digest -> SHA-256(body) == Content-Digest value
Construct signature base string -> concatenate components in Signature-Input order
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

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 — MCP tools, four transport mechanisms, and data formats

UCP identity linking with OAuth 2.0 UCP product data format and transport methods

Start

Learning Paths

Getting Started with AI Commerce

OTR Open Trust Registry

UCP Universal Commerce Protocol

ACP Agentic Commerce Protocol

MCP Model Context Protocol

SEO for the AI Era

ORBEXA Integrated Solution

Templates & Prompts

Glossary

UCP order management and fulfillment events

Order Management

4.1 Capability Identifier

4.2 Line Item Status

4.3 Fulfillment Events

4.4 Adjustments

Return / Refund Request

4.5 Querying Orders

Listing Orders

4.6 Webhook Notifications

Webhook Request Format

Webhook Signature Verification

Webhook Event Types

4.7 Order Lifecycle Overview

​Order Management

​4.1 Capability Identifier

​4.2 Line Item Status

​4.3 Fulfillment Events

​4.4 Adjustments

​Return / Refund Request

​4.5 Querying Orders

​Listing Orders

​4.6 Webhook Notifications

​Webhook Request Format

​Webhook Signature Verification

​Webhook Event Types

​4.7 Order Lifecycle Overview

Order Management

4.1 Capability Identifier

4.2 Line Item Status

4.3 Fulfillment Events

4.4 Adjustments

Return / Refund Request

4.5 Querying Orders

Listing Orders

4.6 Webhook Notifications

Webhook Request Format

Webhook Signature Verification

Webhook Event Types

4.7 Order Lifecycle Overview