Capabilities Reference

UCP capabilities are the building blocks of agentic commerce. Each capability is a feature within a service that a merchant can advertise in their profile. This page covers the core capabilities in the dev.ucp.shopping and dev.ucp.common services.

dev.ucp.shopping.checkout

The checkout capability is the core of UCP commerce. It handles the conversion of a cart into a completed order.

Checkout Session States

Status	Meaning
incomplete	Checkout created but missing required fields (buyer info, fulfillment, payment)
ready_for_complete	All required fields present. Ready for payment submission.
completed	Payment processed successfully. Order created.
requires_escalation	Human input needed. continue_url provided for buyer.
expired	Checkout session has timed out
cancelled	Checkout was cancelled

REST Endpoints

Method	Endpoint	Description
POST	/checkout-sessions	Create checkout from line items
GET	/checkout-sessions/{id}	Get current checkout state
PUT	/checkout-sessions/{id}	Update checkout (full state replacement)
POST	/checkout-sessions/{id}/complete	Submit payment and finalize
DELETE	/checkout-sessions/{id}	Cancel checkout

Example Checkout Object

{
  "ucp": { "version": "2026-04-08" },
  "id": "chk_123456789",
  "status": "ready_for_complete",
  "currency": "USD",
  "buyer": {
    "email": "e.beckett@example.com",
    "first_name": "Elisa",
    "last_name": "Beckett"
  },
  "line_items": [
    {
      "id": "li_1",
      "item": {
        "id": "item_123",
        "title": "Monos Carry-On Pro suitcase",
        "price": 26550
      },
      "quantity": 1
    }
  ],
  "totals": [
    { "type": "subtotal", "amount": 26550 },
    { "type": "tax", "amount": 2124 },
    { "type": "total", "amount": 28674 }
  ],
  "payment": { ... },
  "fulfillment": { ... }
}

dev.ucp.shopping.catalog

The catalog capability lets agents search and retrieve product information. Two scopes:

• Global Catalog - Search across all UCP merchants. Each result includes seller.domain to identify the merchant.
• Storefront Catalog - Search within a single merchant's catalog (scoped via --business parameter).

dev.ucp.shopping.cart

Build carts as buyers iterate across multiple conversation turns. Add line items, apply localization, estimate totals. When the buyer is ready, convert the cart into a checkout session.

dev.ucp.shopping.fulfillment

Extension of checkout. Declares fulfillment methods (shipping, pickup, digital), destinations, and options:

"fulfillment": {
  "methods": [
    {
      "id": "method_1",
      "type": "shipping",
      "line_item_ids": ["li_1"],
      "selected_destination_id": "dest_1",
      "destinations": [
        {
          "id": "dest_1",
          "first_name": "Elisa",
          "last_name": "Beckett",
          "street_address": "1600 Amphitheatre Pkwy",
          "address_locality": "Mountain View",
          "address_region": "CA",
          "postal_code": "94043",
          "address_country": "US"
        }
      ],
      "groups": [
        {
          "id": "group_1",
          "line_item_ids": ["li_1"],
          "selected_option_id": "free-shipping",
          "options": [
            {
              "id": "free-shipping",
              "title": "Free Shipping",
              "totals": [{ "type": "total", "amount": 0 }]
            }
          ]
        }
      ]
    }
  ]
}

dev.ucp.shopping.discount

Multi-parent extension that extends both checkout and cart. Supports discount codes, loyalty program discounts, and promotional pricing. The extension schema defines different fields for each parent:

• For checkout: discounts_applied, loyalty_earned
• For cart: discount_preview, loyalty_preview

dev.ucp.common.identity_linking

OAuth 2.0 based identity linking. Enables agents to maintain secure, authorized relationships with merchants without sharing user credentials.

"dev.ucp.common.identity_linking": [
  {
    "version": "2026-04-08",
    "spec": "https://ucp.dev/.../identity-linking",
    "schema": "https://ucp.dev/.../identity_linking.json",
    "config": {
      "scopes": {
        "dev.ucp.shopping.order:read": {},
        "dev.ucp.shopping.order:manage": {}
      }
    }
  }
]

Order Management

Post-purchase lifecycle: order confirmation, fulfillment events, tracking, returns, refunds, exchanges, and cancellations.

Order Object

{
  "ucp": { "version": "2026-04-08" },
  "id": "order_123456789",
  "checkout_id": "chk_123456789",
  "line_items": [ ... ],
  "fulfillment": {
    "expectations": [
      {
        "id": "exp_1",
        "method_type": "shipping",
        "destination": { ... },
        "description": "Arrives in 2-3 business days",
        "fulfillable_on": "now"
      }
    ],
    "events": [
      {
        "id": "evt_1",
        "occurred_at": "2026-01-11T10:30:00Z",
        "type": "delivered",
        "tracking_number": "123456789",
        "tracking_url": "https://fedex.com/track/123456789",
        "description": "Delivered to front door"
      }
    ]
  },
  "adjustments": [
    {
      "id": "adj_1",
      "type": "refund",
      "occurred_at": "2026-01-12T14:30:00Z",
      "status": "completed",
      "line_items": [{ "id": "li_1", "quantity": -1 }],
      "totals": [{ "type": "total", "amount": -26550 }],
      "description": "Defective item"
    }
  ]
}

Webhook Events

Event Type	Description
created	Order created after checkout completion
fulfilled	All items shipped/delivered
delivered	Package delivered
cancelled	Order cancelled
refunded	Refund processed
returned	Return processed
exchanged	Exchange processed

Extension Pattern

Extensions are how UCP stays extensible without bloating the core spec. The pattern:

1. Extension declares extends field naming parent capability(s)
2. Extension schema has $defs entry for each parent
3. Schema composition uses allOf to merge with parent
4. Optional requires object declares version constraints
5. At runtime, platform resolves and composes schemas

// Extension schema example
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ucp.dev/.../discount.json",
  "name": "dev.ucp.shopping.discount",
  "requires": {
    "protocol": { "min": "2026-04-08" },
    "capabilities": {
      "dev.ucp.shopping.checkout": { "min": "2026-04-08" }
    }
  },
  "$defs": {
    "dev.ucp.shopping.checkout": {
      "allOf": [
        { "$ref": "checkout.json" },
        {
          "type": "object",
          "properties": {
            "discounts": { "$ref": "#/$defs/discounts_object" }
          }
        }
      ]
    }
  }
}