DEV Community

Cover image for UCP Cart, Catalog, and Identity Linking: What to Validate (and What Can Wait)
Peter
Peter

Posted on • Edited on

UCP Cart, Catalog, and Identity Linking: What to Validate (and What Can Wait)

#ecommerce #webdev #ai #ucp

Google shipped the first major UCP update on March 19, 2026 - three new capabilities: Cart, Catalog, and Identity Linking. If you're a merchant or platform developer implementing UCP, you now have more to validate.

But here's the thing most guides won't tell you: not all three capabilities have the same stability level. Cart and Catalog are draft specs. Identity Linking is stable. Treating them the same way in your validation pipeline is a mistake.

This post breaks down what changed, what to validate strictly, what to treat as warnings, and provides a minimal checklist for keeping your /.well-known/ucp profile working.

What Changed on March 19

Capability Namespace Status What It Does
Cart dev.ucp.shopping.cart Draft Multi-item basket management before checkout
Catalog Search dev.ucp.shopping.catalog.search Draft Product search by keyword, category, attributes
Catalog Lookup dev.ucp.shopping.catalog.lookup Draft Direct product lookup by ID
Identity Linking dev.ucp.common.identity_linking Stable OAuth 2.0 account linking via RFC 8414 discovery

Cart and Catalog are published under ucp.dev/draft/specification/ - note the /draft/ path. Identity Linking shipped in the stable spec at launch in January.

This distinction matters for validation.

Draft vs Stable: Why Your Validator Needs to Know

If you hard-fail on a draft capability's schema mismatch, you'll generate noise. Draft specs change. That's the point of a draft.

If you silently pass a broken /.well-known/ucp endpoint, you'll miss the errors that actually prevent AI agents from discovering your store.

The right approach: severity-aware validation.

Stable capabilities  -> errors on failure
Draft capabilities   -> warnings on failure
Discovery blockers   -> always errors, regardless of capability status
Enter fullscreen mode Exit fullscreen mode

Here's a concrete example. Say a merchant adds Cart support but uses an outdated schema URL that doesn't match the current draft:

{
  "name": "dev.ucp.shopping.cart",
  "version": "2026-01-11",
  "spec": "https://ucp.dev/draft/specification/cart/",
  "schema": "https://ucp.dev/schemas/shopping/cart.json"
}
Enter fullscreen mode Exit fullscreen mode

Should your validator fail this? No - warn. The schema URL might be temporarily ahead of or behind the draft. The capability is structurally valid. The merchant is doing the right thing by declaring Cart support early.

But if that same profile is missing signing keys entirely? That's an error. No agent can trust the merchant without them, draft or not.

The Cart Capability: What to Validate

Cart (dev.ucp.shopping.cart) supports four operations:

  1. Create Cart - initialize a basket with line items
  2. Get Cart - retrieve current cart state
  3. Update Cart - full replacement of cart contents
  4. Cancel Cart - terminate the session

Required Fields in Cart Response 

{
  "ucp": {
    "version": "2026-01-15",
    "status": "success"
  },
  "id": "cart_abc123",
  "line_items": [
    {
      "id": "li_1",
      "item": {
        "id": "product_42",
        "title": "Blue Widget",
        "price": { "amount": "29.99", "currency": "USD" }
      },
      "quantity": 2,
      "totals": [
        { "type": "subtotal", "amount": "59.98", "currency": "USD" }
      ]
    }
  ],
  "currency": "USD",
  "totals": [
    { "type": "subtotal", "amount": "59.98", "currency": "USD" }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Validation Checklist for Cart

  • [ ] Capability declared with correct namespace dev.ucp.shopping.cart
  • [ ] Version follows YYYY-MM-DD format
  • [ ] Spec URL points to draft path (ucp.dev/draft/specification/cart/)
  • [ ] If REST binding: endpoint is HTTPS, no trailing slash
  • [ ] Cart-to-checkout conversion: if Checkout capability is also declared, verify cart_id can be passed to Create Checkout
  • [ ] Severity: WARN on schema drift (draft spec may change)
  • [ ] Severity: ERROR on missing required fields (id, line_items, currency, totals)

Cart-to-Checkout Conversion

A key detail from the spec: when Cart is negotiated alongside Checkout, platforms convert carts to checkout sessions by passing cart_id in the Create Checkout request. The spec requires idempotency - if an incomplete checkout already exists for that cart_id, the business must return the existing session.

This is worth testing if you support both capabilities.

The Catalog Capabilities: What to Validate

Per the official spec, Catalog is split into two sub-capabilities:

  • Catalog Search (dev.ucp.shopping.catalog.search) - agents query by keyword, category, or attributes
  • Catalog Lookup (dev.ucp.shopping.catalog.lookup) - agents fetch specific products by ID

Each has its own schema: catalog_search.json and catalog_lookup.json. The value is real-time data - agents check live inventory, current pricing, and variant availability instead of relying on static product feeds.

Validation Checklist for Catalog

  • [ ] Capabilities declared with correct namespaces (...catalog.search and/or ...catalog.lookup)
  • [ ] Spec URL points to draft path (ucp.dev/draft/specification/catalog/)
  • [ ] Schemas point to correct files (catalog_search.json / catalog_lookup.json)
  • [ ] Endpoint responds with valid product data (not HTML error pages)
  • [ ] Product fields include required: id, title, description, price_range, variants
  • [ ] Variant price uses minor currency units + ISO 4217 currency code
  • [ ] Severity: WARN on schema drift
  • [ ] Severity: ERROR on unreachable endpoint or non-JSON response

Identity Linking: What to Validate

Unlike Cart and Catalog, Identity Linking is stable. It was part of the UCP spec at launch. Validate strictly.

Identity Linking uses namespace dev.ucp.common.identity_linking - note the common service, not shopping. It's declared as a capability in the capabilities array with a config object containing supported_mechanisms.

The mechanism uses OAuth 2.0 with RFC 8414 discovery - you declare an issuer URI, and OAuth endpoints are discovered automatically via /.well-known/oauth-authorization-server. You do NOT put authorization_endpoint or token_endpoint directly in the profile.

Validation Checklist for Identity Linking

  • [ ] Capability declared with namespace dev.ucp.common.identity_linking
  • [ ] config.supported_mechanisms array has at least one entry
  • [ ] Each mechanism has a type field (currently only "oauth2")
  • [ ] OAuth2 mechanism has an issuer URI using HTTPS
  • [ ] Issuer supports RFC 8414 discovery
  • [ ] Severity: ERROR on all failures (stable spec)

The 7 Rules That Actually Break Discovery

Before worrying about Cart, Catalog, or Identity Linking, make sure the basics work. These are the validation failures that prevent AI agents from discovering your store at all:

1. Missing or malformed /.well-known/ucp 

Code: UCP_MISSING_ROOT
Fix:  Serve a valid JSON object with a "ucp" property at /.well-known/ucp
Enter fullscreen mode Exit fullscreen mode

If this fails, nothing else matters. The agent can't find you.

2. Missing or invalid version 

Code: UCP_MISSING_VERSION / UCP_INVALID_VERSION_FORMAT
Fix:  Add "version": "2026-01-11" (YYYY-MM-DD format, not semver)
Enter fullscreen mode Exit fullscreen mode

Common mistake: using "1.0" instead of a date string.

3. HTTP endpoints (not HTTPS) 

Code: UCP_ENDPOINT_NOT_HTTPS
Fix:  All endpoint URLs must use https://
Enter fullscreen mode Exit fullscreen mode

No exceptions. HTTP endpoints are rejected by conformant agents.

4. Trailing slashes on endpoints 

Code: UCP_ENDPOINT_TRAILING_SLASH
Fix:  https://example.com/api/ucp (not https://example.com/api/ucp/)
Enter fullscreen mode Exit fullscreen mode

Subtle but real. Some web servers handle this fine. The spec says no trailing slash.

5. Namespace/origin mismatch 

Code: UCP_NS_ORIGIN_MISMATCH
Fix:  Schema URLs must match the namespace authority
Enter fullscreen mode Exit fullscreen mode

If your capability uses the dev.ucp.* namespace, schema URLs must come from ucp.dev. Vendor capabilities must use their own domain. This prevents spoofing.

6. Orphaned extensions 

Code: UCP_ORPHANED_EXTENSION
Fix:  Every extension needs its parent capability declared
Enter fullscreen mode Exit fullscreen mode

If you declare dev.ucp.shopping.fulfillment (an extension of Checkout) but don't declare dev.ucp.shopping.checkout, agents will prune the extension during capability negotiation. It's dead weight.

7. Missing signing keys 

Code: UCP_MISSING_SIGNING_KEYS
Fix:  Add JWK public keys in the signing_keys array
Enter fullscreen mode Exit fullscreen mode 
{
  "signing_keys": [
    {
      "kid": "key-1",
      "kty": "EC",
      "crv": "P-256",
      "x": "...",
      "y": "...",
      "use": "sig",
      "alg": "ES256"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Without signing keys, webhook verification fails. Agents can't trust your responses.

Putting It Together: A Severity Matrix

Check Severity Why
/.well-known/ucp serves valid JSON ERROR Discovery completely blocked
Version is valid YYYY-MM-DD ERROR Agent can't negotiate
All endpoints HTTPS ERROR Spec requirement, agents reject HTTP
No trailing slashes ERROR Spec requirement
Namespace/origin match ERROR Security - prevents spoofing
Signing keys present ERROR Webhook trust broken
No orphaned extensions ERROR Extensions pruned, wasted config
Cart schema matches draft WARN Draft spec, may change
Catalog Search/Lookup schema matches draft WARN Draft spec, may change
Identity Linking has valid mechanisms ERROR Stable spec
Identity Linking issuer is HTTPS ERROR Stable spec
Cart endpoint returns valid JSON ERROR Unreachable = broken
Catalog endpoint returns valid JSON ERROR Unreachable = broken

The pattern: structure and reachability are always errors. Schema conformance on draft specs is a warning.

CI/CD Integration

If you're validating UCP profiles in CI, here's what a validation-as-diff output looks like:

$ npx ucptools validate https://example.com/.well-known/ucp

 PASS  Structural validation
 PASS  Version format (2026-01-11)
 FAIL  UCP_ENDPOINT_NOT_HTTPS
       Path: $.ucp.services.dev.ucp.shopping.rest.endpoint
       Found: http://example.com/api/ucp
       Fix: Change to https://example.com/api/ucp

 FAIL  UCP_MISSING_SIGNING_KEYS
       Path: $.signing_keys
       Fix: Add at least one JWK public key (Ed25519 or ES256)

 WARN  Cart schema URL may not match current draft
       Path: $.ucp.capabilities[2].schema
       Spec: https://ucp.dev/draft/specification/cart/

2 errors, 1 warning
Enter fullscreen mode Exit fullscreen mode

Each issue has a rule ID, a JSON path, and a fix. Copy-paste friendly. Greppable. CI-ready.

What About Merchant Center Onboarding?

Google is also simplifying UCP onboarding through Merchant Center, rolling out "over the coming months." One detail worth noting: only product listings with the native_commerce product attribute will display the checkout button in Google's AI experiences.

This is implementation-specific to Google's surfaces - it's not part of the UCP spec itself. But if you're building for Google AI Mode specifically, it's a requirement you'll need to track.

Quick Reference: The Minimal Checklist

Before adding any new capabilities:

  • [ ] /.well-known/ucp returns valid JSON with Content-Type: application/json
  • [ ] ucp.version is "2026-01-11" (YYYY-MM-DD)
  • [ ] All endpoint URLs are HTTPS, no trailing slashes
  • [ ] Signing keys array has at least one valid JWK
  • [ ] No namespace/origin mismatches
  • [ ] No orphaned extensions

Adding Cart (draft):

  • [ ] Namespace: dev.ucp.shopping.cart
  • [ ] Spec URL: https://ucp.dev/draft/specification/cart/
  • [ ] Endpoint reachable and returns JSON
  • [ ] If also supporting Checkout: test cart-to-checkout conversion

Adding Catalog (draft):

  • [ ] Namespace: dev.ucp.shopping.catalog.search and/or dev.ucp.shopping.catalog.lookup
  • [ ] Spec URL: https://ucp.dev/draft/specification/catalog/
  • [ ] Schema: catalog_search.json / catalog_lookup.json (separate files)
  • [ ] Endpoint reachable and returns JSON
  • [ ] Product data includes required fields (id, title, description, price_range, variants)

Adding Identity Linking (stable):

  • [ ] Namespace: dev.ucp.common.identity_linking (note: common, not shopping)
  • [ ] config.supported_mechanisms has at least one entry
  • [ ] OAuth2 mechanism has issuer using HTTPS
  • [ ] Issuer supports RFC 8414 discovery (/.well-known/oauth-authorization-server)
  • [ ] Test the full authorization flow

Validate Your Profile

You can run all of these checks at ucptools.dev - paste your profile JSON or enter your domain. It's free, no signup required.

For CI integration, the npm package gives you the same validation with JSON output:

npm install -g ucptools
ucptools validate https://your-store.com
Enter fullscreen mode Exit fullscreen mode

UCPtools is an independent community tool. UCP is an open standard developed by Google, Shopify, and partners. Cart and Catalog spec status as of March 25, 2026.

Have questions about validating the new capabilities? Drop a comment - I'm building this in public and happy to help.

Top comments (2)

Some comments may only be visible to logged-in visitors. Sign in to view all comments.