Order Capability¶

Capability Name: dev.ucp.shopping.order

Overview¶

Orders represent confirmed transactions resulting from a successful checkout submission. They provide a complete record of what was purchased, how it will be delivered, and what has happened since order placement.

Key Concepts¶

Orders have three main components:

Line Items — what was purchased at checkout:

Includes current quantity counts (total, fulfilled)
Can change post-order (e.g. order edits, exchanges); MUST include all line items that ever existed on the order regardless of edits or alterations

Fulfillment — how items get delivered:

Expectations — buyer-facing promises about when/how items will arrive
Events (append-only log) — what actually happened (e.g. 👕 was shipped)

Adjustments — post-order events independent of fulfillment:

Typically money movements (refunds, returns, credits, disputes, cancellations)
Can be any post-order change
Can happen before, during, or after fulfillment
Businesses SHOULD append new entries rather than mutating existing ones; append-only ledger is preferred. Businesses that do not maintain adjustment history MAY perform in-place updates of existing entries (e.g. a single return adjustment can transition from pending to completed)

Data Model¶

Line Items¶

Line items reflect what was purchased at checkout and their current state:

Item details (product, price, quantity ordered)
Quantity counts and fulfillment status

Fulfillment¶

Fulfillment tracks how items are delivered to the buyer.

Expectations¶

Expectations are buyer-facing groupings of items (e.g., "package 📦"). They represent:

What items are grouped together
Where they're going (destination)
How they're being delivered (method_type)
When they'll arrive (description, fulfillable_on)

Expectations can be split, merged, or adjusted post-order. For example:

Group everything by delivery date: "what is coming when"
Use a single expectation with a wide date range for flexibility
The goal is setting buyer expectations - for the best buyer experience

Fulfillment Events¶

Fulfillment Events are an append-only log tracking physical shipments:

Reference line items by ID and quantity
Include tracking information
Type is an open string field - businesses can use any values that make sense (common examples: processing, shipped, in_transit, delivered, failed_attempt, canceled, undeliverable, returned_to_sender)

Attribution¶

Businesses MAY surface a snapshot of the originating checkout's attribution on the order. Read-only on the order — agents do not write order.attribution. See Attribution for the underlying contract.

Adjustments¶

Adjustments are post-order events that exist independently of fulfillment:

Type is an open string field - businesses can use any values that make sense (typically money movements like refund, return, credit, price_adjustment, dispute, cancellation)
Can be any post-order change
Optionally link to line items (or order-level for things like shipping refunds)
Quantities and amounts are signed—negative for reductions (returns, refunds), positive for additions (exchanges)
Include totals breakdown when relevant
Can happen at any time regardless of fulfillment status

Schema¶

Order¶

Name	Type	Requirement	Description
ucp	any	Required	UCP metadata for order responses. No payment handlers needed post-purchase.
id	string	Required	Unique order identifier.
label	string	Optional	Human-readable label for identifying the order. MUST only be provided by the business.
checkout_id	string	Required	Associated checkout ID for reconciliation.
permalink_url	string	Required	Permalink to access the order on merchant site.
line_items	Array[Order Line Item]	Required	Line items representing what was purchased — can change post-order via edits or exchanges.
fulfillment	object	Required	Fulfillment data: buyer expectations and what actually happened.
adjustments	Array[Adjustment]	Optional	Post-order events (refunds, returns, credits, disputes, cancellations, etc.) that exist independently of fulfillment.
currency	string	Required	ISO 4217 currency code. MUST match the currency from the originating checkout session.
totals	Totals	Required	Different totals for the order.
messages	Array[Message]	Optional	Business outcome messages (errors, warnings, informational). Present when the business needs to communicate status or issues to the platform.
attribution	Attribution	Optional	Snapshot of the attribution associated with the originating checkout. Read-only on the order.

Order Line Item¶

Line items reflect what was purchased at checkout and their current state.

Name	Type	Requirement	Description
id	string	Required	Line item identifier.
item	Item	Required	Product data (id, title, price, image_url).
quantity	object	Required	Quantity tracking for the line item.
totals	Array[Total]	Required	Line item totals breakdown.
status	string	Required	Derived status: removed if quantity.total == 0, fulfilled if quantity.total > 0 and quantity.fulfilled == quantity.total, partial if quantity.total > 0 and quantity.fulfilled > 0, otherwise processing. Enum: `processing`, `partial`, `fulfilled`, `removed`
parent_id	string	Optional	Parent line item identifier for any nested structures.

Quantity Structure:

{
  "original": 3,   // Quantity from the original checkout
  "total": 3,      // Current total (may differ after edits/exchanges)
  "fulfilled": 2   // What has been fulfilled
}

Status Derivation:

if (total == 0) → "removed"
else if (fulfilled == total) → "fulfilled"
else if (fulfilled > 0) → "partial"
else → "processing"

Expectation¶

Expectations are buyer-facing groupings representing when/how items will be delivered. They represent the current promise to the buyer and can be split, merged, or adjusted post-order.

Name	Type	Requirement	Description
id	string	Required	Expectation identifier.
line_items	Array[object]	Required	Which line items and quantities are in this expectation.
method_type	string	Required	Delivery method type. Well-known values: `shipping`, `pickup`, `digital`; additional values MAY be used.
destination	Postal Address	Required	Delivery destination address.
description	string	Optional	Human-readable delivery description (e.g., 'Arrives in 5-8 business days').
fulfillable_on	string	Optional	When this expectation can be fulfilled: 'now' or ISO 8601 timestamp for future date (backorder, pre-order).

Fulfillment Event¶

Events are append-only records tracking actual shipments. The type field is an open string - businesses can use any values that make sense for their fulfillment process.

Name	Type	Requirement	Description
id	string	Required	Fulfillment event identifier.
occurred_at	string	Required	RFC 3339 timestamp when this fulfillment event occurred.
type	string	Required	Fulfillment event type. Common values include: processing (preparing to ship), shipped (handed to carrier), in_transit (in delivery network), delivered (received by buyer), failed_attempt (delivery attempt failed), canceled (fulfillment canceled), undeliverable (cannot be delivered), returned_to_sender (returned to merchant).
line_items	Array[object]	Required	Which line items and quantities are fulfilled in this event.
tracking_number	string	Optional	Carrier tracking number (required if type != processing).
tracking_url	string	Optional	URL to track this shipment (required if type != processing).
carrier	string	Optional	Carrier name (e.g., 'FedEx', 'USPS').
description	string	Optional	Human-readable description of the shipment status or delivery information (e.g., 'Delivered to front door', 'Out for delivery').

Examples: processing, shipped, in_transit, delivered, failed_attempt, canceled, undeliverable, returned_to_sender, etc.

Adjustment¶

Adjustments are polymorphic events that exist independently of fulfillment. The type field is an open string - businesses can use any values that make sense to them.

Name	Type	Requirement	Description
id	string	Required	Adjustment event identifier.
type	string	Required	Type of adjustment (open string). Typically money-related like: refund, return, credit, price_adjustment, dispute, cancellation. Can be any value that makes sense for the merchant's business.
occurred_at	string	Required	RFC 3339 timestamp when this adjustment occurred.
status	string	Required	Adjustment status. Enum: `pending`, `completed`, `failed`
line_items	Array[object]	Optional	Which line items and quantities are affected (optional).
totals	Array[Total]	Optional	Adjustment totals breakdown. Signed values - negative for money returned to buyer (refunds, credits), positive for additional charges (exchanges).
description	string	Optional	Human-readable reason or description (e.g., 'Defective item', 'Customer requested').

Examples: refund, return, credit, price_adjustment, dispute, cancellation, etc.

Example¶

{
  "ucp": {
    "version": "draft",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "draft"}]
    }
  },
  "id": "order_abc123",
  "checkout_id": "checkout_xyz789",
  "permalink_url": "https://business.example.com/orders/abc123",
  "currency": "USD",
  "line_items": [
    {
      "id": "li_shoes",
      "item": { "id": "prod_shoes", "title": "Running Shoes", "price": 3000 },
      "quantity": { "original": 3, "total": 3, "fulfilled": 3 },
      "totals": [
        {"type": "subtotal", "amount": 9000},
        {"type": "total", "amount": 9000}
      ],
      "status": "fulfilled"
    },
    {
      "id": "li_shirts",
      "item": { "id": "prod_shirts", "title": "Cotton T-Shirt", "price": 2000 },
      "quantity": { "original": 2, "total": 2, "fulfilled": 0 },
      "totals": [
        {"type": "subtotal", "amount": 4000},
        {"type": "total", "amount": 4000}
      ],
      "status": "processing"
    }
  ],
  "fulfillment": {
    "expectations": [
      {
        "id": "exp_1",
        "line_items": [{ "id": "li_shoes", "quantity": 3 }],
        "method_type": "shipping",
        "destination": {
          "street_address": "123 Main St",
          "address_locality": "Austin",
          "address_region": "TX",
          "address_country": "US",
          "postal_code": "78701"
        },
        "description": "Arrives in 2-3 business days",
        "fulfillable_on": "now"
      },
      {
        "id": "exp_2",
        "line_items": [{ "id": "li_shirts", "quantity": 2 }],
        "method_type": "shipping",
        "destination": {
          "street_address": "123 Main St",
          "address_locality": "Austin",
          "address_region": "TX",
          "address_country": "US",
          "postal_code": "78701"
        },
        "description": "Backordered - ships Jan 15, arrives in 7-10 days",
        "fulfillable_on": "2025-01-15T00:00:00Z"
      }
    ],
    "events": [
      {
        "id": "evt_1",
        "occurred_at": "2025-01-08T10:30:00Z",
        "type": "delivered",
        "line_items": [{ "id": "li_shoes", "quantity": 3 }],
        "tracking_number": "123456789",
        "tracking_url": "https://fedex.com/track/123456789",
        "description": "Delivered to front door"
      }
    ]
  },
  "adjustments": [
    {
      "id": "adj_1",
      "type": "refund",
      "occurred_at": "2025-01-10T14:30:00Z",
      "status": "completed",
      "line_items": [{ "id": "li_shoes", "quantity": -1 }],
      "totals": [
        { "type": "total", "amount": -3000 }
      ],
      "description": "Defective item"
    }
  ],
  "totals": [
    { "type": "subtotal", "amount": 13000 },
    { "type": "fulfillment", "amount": 1200 },
    { "type": "tax", "amount": 1142 },
    { "type": "total", "amount": 15342 }
  ]
}

Scopes¶

The Order capability defines the following well-known scopes for user-authenticated access:

Scope	Description
`dev.ucp.shopping.order:read`	Read access to the user's orders — Get Order on resources owned by the authenticated user.
`dev.ucp.shopping.order:manage`	Post-purchase operations on the user's orders — cancellation, returns, and other modifications.

Scope declaration, derivation, and rules for extending this set with custom scopes are defined in Identity Linking — Scopes.

Operations¶

The order entity is a current-state snapshot: the authoritative latest state of the order at the time of retrieval or delivery. Businesses MUST return the full order entity on every response. The same schema is used for both synchronous retrieval (this section) and asynchronous event delivery (see Events).

The permalink_url is the authoritative reference for the full order experience - timeline, post-purchase operations, returns. The API provides programmatic access to current state for conversational and operational use cases.

Operation	Method	Endpoint	Description
Get Order	`GET`	`/orders/{id}`	Platform retrieves current order state.

For transport-specific details, see REST Binding, and MCP Binding

Get Order¶

Returns the current-state snapshot of an order.

Authorization¶

The business MUST authenticate requests to order data before returning a response, using any supported UCP mechanism - API keys, OAuth 2.0, mutual TLS, or HTTP Message Signatures (see Identity and Authentication). The authentication method determines which orders are accessible to the caller:

Authentication	Accessible Orders
Platform credentials	Orders originated by the platform
Buyer authorization	Orders owned by the buyer, subject to the granted OAuth scopes

Platform credentials (API key, signatures, OAuth client credentials) - businesses MAY allow access for orders the platform originated. The platform provided buyer and payment information during the checkout flow, observed the order confirmation, and is retrieving the latest state of an order it already has context for.

Buyer authorization - the platform obtains buyer authorization via Identity Linking with the necessary scopes, or a similar mechanism. This grants access to the buyer's orders regardless of which platform originated them.

Businesses MAY define additional access policies (e.g., trusted partner agreements), enforce data availability constraints (e.g., retention windows, regulatory erasure), and omit or redact optional fields from the response based on context, business policy, or other requirements - independently of authorization.

Error Responses¶

When the business cannot return an order, the response returns an error that includes a messages array describing the outcome:

Order not found:

{
  "ucp": {
    "version": "draft",
    "status": "error",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "draft"}]
    }
  },
  "messages": [
    {
      "type": "error",
      "code": "not_found",
      "severity": "unrecoverable",
      "content": "Order not found."
    }
  ]
}

Not authorized:

{
  "ucp": {
    "version": "draft",
    "status": "error",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "draft"}]
    }
  },
  "messages": [
    {
      "type": "error",
      "code": "unauthorized",
      "severity": "unrecoverable",
      "content": "Not authorized to access this order."
    }
  ]
}

Guidelines¶

Platform:

MUST include UCP-Agent header with profile URL on all requests
SHOULD rely on webhooks (see Events) as the primary order update channel and use Get Order for reconciliation or on-demand retrieval
SHOULD treat order data as ephemeral and discard it when no longer needed for active commerce flows

Business:

MUST authenticate requests to order data before returning a response (see Authorization)

Events¶

Businesses push order lifecycle updates to the platform via webhooks. The payload is the same current-state snapshot described in Operations — the full order entity.

Event	Method	Endpoint	Description
Order Event Webhook	`POST`	Platform-provided URL	Business sends order lifecycle events to the platform.

Order Event Webhook¶

Businesses POST order events to a webhook URL provided by the platform during partner onboarding. The URL format is platform-specific.

Headers follow Standard Webhooks; except for request signing, which follows RFC 9421. See Message Signatures for more details.

Required Headers:

Header	Description
`Webhook-Timestamp`	Event occurrence timestamp (unix)
`Webhook-Id`	Unique event identifier

Inputs

Name	Type	Requirement	Description
ucp	any	Required	UCP metadata for order responses. No payment handlers needed post-purchase.
id	string	Required	Unique order identifier.
label	string	Optional	Human-readable label for identifying the order. MUST only be provided by the business.
checkout_id	string	Required	Associated checkout ID for reconciliation.
permalink_url	string	Required	Permalink to access the order on merchant site.
line_items	Array[Order Line Item]	Required	Line items representing what was purchased — can change post-order via edits or exchanges.
fulfillment	object	Required	Fulfillment data: buyer expectations and what actually happened.
adjustments	Array[Adjustment]	Optional	Post-order events (refunds, returns, credits, disputes, cancellations, etc.) that exist independently of fulfillment.
totals	Totals	Required	Different totals for the order.
messages	Array[Message]	Optional	Business outcome messages (errors, warnings, informational). Present when the business needs to communicate status or issues to the platform.

Output

Name	Type	Requirement	Description
ucp	Ucp	Required

Webhook URL Configuration¶

The platform provides its webhook URL in the order capability's config field during capability negotiation. The business discovers this URL from the platform's profile and uses it to send order lifecycle events.

Platform's order capability configuration.

Name	Type	Requirement	Description
webhook_url	string	Required	URL where merchant sends order lifecycle events (webhooks).

Example:

{
  "dev.ucp.shopping.order": [
    {
      "version": "draft",
      "spec": "https://ucp.dev/draft/specification/order",
      "schema": "https://ucp.dev/draft/schemas/shopping/order.json",
      "config": {
        "webhook_url": "https://platform.example.com/webhooks/ucp/orders"
      }
    }
  ]
}

Webhook Signature Verification¶

Webhook payloads MUST be signed by the business and verified by the platform to ensure authenticity and integrity. Signatures follow the Message Signatures specification using the REST binding (RFC 9421).

Required Headers:

Header	Description
`UCP-Agent`	Business profile URL (RFC 8941 Dictionary)
`Signature-Input`	Describes signed components
`Signature`	Contains the signature value
`Content-Digest`	Body digest (RFC 9530)

Example Webhook Request:

POST /webhooks/ucp/orders HTTP/1.1
Host: platform.example.com
Content-Type: application/json
UCP-Agent: profile="https://merchant.example/.well-known/ucp"
Content-Digest: sha-256=:X48E9q...:
Signature-Input: sig1=("@method" "@authority" "@path" "content-digest" "content-type");keyid="merchant-2026"
Signature: sig1=:MEUCIQDTxNq8h7LGHpvVZQp1iHkFp9+3N8Mxk2zH1wK4YuVN8w...:

{"id":"order_abc123","event_id":"evt_123","created_time":"2026-01-15T12:00:00Z",...}

Signing (Business)¶

Compute SHA-256 digest of the raw request body and set Content-Digest header
Build signature base per RFC 9421
Sign using a key from keys in the business's UCP profile
Set Signature-Input and Signature headers

See Message Signatures - REST Request Signing for complete algorithm.

Verification (Platform)¶

Authentication (signature verification):

Parse Signature-Input to extract keyid and signed components
Fetch business's UCP profile from /.well-known/ucp (cache as appropriate)
Locate key in keys with matching kid
Verify Content-Digest matches SHA-256 of raw body
Reconstruct signature base and verify signature

See Message Signatures - REST Request Verification for complete algorithm.

Authorization (order ownership):

After verifying the signature, the platform MUST confirm the signer is authorized to send events for the referenced order:

Extract the order ID from the webhook payload
Verify the order was created with this business (profile URL matches)
Reject webhooks where the signer's profile doesn't match the order's business

This prevents a malicious business from sending fake events for another business's orders, even with a valid signature.

Key Rotation¶

See Message Signatures - Key Rotation for zero-downtime key rotation procedures.

Guidelines¶

Platform:

MUST respond quickly with a 2xx HTTP status code to acknowledge webhook receipt; process events asynchronously after responding

Business:

MUST include UCP-Agent header with profile URL for signer identification
MUST sign all webhook payloads per the Message Signatures specification using RFC 9421 headers (Signature, Signature-Input, Content-Digest)
MUST send "Order created" event with fully populated order entity
MUST send full order entity on updates (not incremental deltas)
MUST retry failed webhook deliveries

Entities¶

Item¶

Name	Type	Requirement	Description
id	string	Required	The product identifier, often the SKU, required to resolve the product details associated with this line item. Should be recognized by both the Platform, and the Business.
title	string	Required	Product title.
price	Amount	Required	Unit price in ISO 4217 minor units.
image_url	string	Optional	Product image URI.

Postal Address¶

See Postal Address in the Schema Reference for the canonical field definition.

Response¶

Capability reference in responses. Only name/version required to confirm active capabilities.

Name	Type	Requirement	Description
version	string	Required	Entity version in YYYY-MM-DD format.
spec	string	Optional	URL to human-readable specification document.
schema	string	Optional	URL to JSON Schema defining this entity's structure and payloads.
id	string	Optional	Unique identifier for this entity instance. Used to disambiguate when multiple instances exist.
config	object	Optional	Entity-specific configuration. Structure defined by each entity's schema.
extends	OneOf[`string`, `array`]	Optional	Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.

Total¶

Name	Type	Requirement	Description
type	string	Required	Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses MAY use additional values.
display_text	string	Optional	Text to display against the amount. Should reflect appropriate method (e.g., 'Shipping', 'Delivery').
amount	Signed Amount	Required	Monetary amount in the currency's minor unit as defined by ISO 4217. Refer to the currency's exponent to determine minor-to-major ratio (e.g., 2 for USD, 0 for JPY, 3 for KWD). May be negative — the sign is intrinsic to the value (e.g., discounts are negative, charges are positive).

UCP Response Order Schema ¶

UCP metadata for order responses. No payment handlers needed post-purchase.

Name	Type	Requirement	Description
version	string	Required	UCP version in YYYY-MM-DD format.
status	string	Optional	Application-level status of the UCP operation. Enum: `success`, `error`
services	object	Optional	Service registry keyed by reverse-domain name.
capabilities	object	Optional	Capability registry keyed by reverse-domain name.
payment_handlers	object	Optional	Payment handler registry keyed by reverse-domain name.
capabilities	any	Optional