Skip to main content

​
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:
StatusMeaningDescription
processingProcessingOrder confirmed; items are being prepared for shipment
partialPartially fulfilledSome quantity of the line item has shipped (e.g., ordered 3, shipped 2)
fulfilledFulfilledAll quantity has been delivered
removedRemovedLine 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 TypeMeaning
processingBeing processed / prepared
shippedShipped; handed off to carrier
in_transitIn transit
out_for_deliveryOut for delivery
attempted_deliveryDelivery attempted but unsuccessful
deliveredDelivered
ready_for_pickupReady for pickup at designated location
picked_upPicked up by customer
failedDelivery failed
returned_to_senderReturned 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 TypeMeaningInitiated By
refundRefundMerchant or consumer
returnReturnConsumer
creditStore credit / loyalty pointsMerchant
exchangeExchangeConsumer
price_adjustmentPrice 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:
  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)
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

EventTrigger
order.createdCheckout completed; order created
order.fulfillment.updatedFulfillment status changed (shipped, delivered, etc.)
order.adjustment.createdNew adjustment request created
order.adjustment.updatedAdjustment status changed (approved, completed, etc.)
order.canceledOrder 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