DEV Community

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

Posted on

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

#ecommerce #ai #webdev #tutorial

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 dev.ucp.shopping.catalog Draft Real-time product search, variants, pricing, stock
Identity Linking Part of core spec Stable OAuth 2.0 account linking for loyalty/member pricing

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 Capability: What to Validate

Catalog enables two patterns:

  • Search - agents query by keyword, category, or attributes
  • Direct lookup - agents fetch a specific product by ID

The value is real-time data. Instead of relying on static product feeds, agents can check live inventory, current pricing, and variant availability.

Validation Checklist for Catalog

  • [ ] Capability declared with correct namespace
  • [ ] Spec URL points to draft path
  • [ ] Endpoint responds with valid product data (not HTML error pages)
  • [ ] Stock/pricing fields use correct types (string amounts, ISO 4217 currency)
  • [ ] 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 OAuth 2.0 to connect shopper accounts across platforms. The practical outcome: a shopper's loyalty points, member pricing, and saved preferences travel with them when shopping through Google AI Mode or Gemini.

Validation Checklist for Identity Linking

  • [ ] OAuth 2.0 authorization endpoint is HTTPS
  • [ ] Token endpoint is HTTPS
  • [ ] Scopes are clearly defined
  • [ ] Redirect URIs use HTTPS
  • [ ] 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 schema matches draft WARN Draft spec, may change
Identity Linking OAuth endpoints valid 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
  • [ ] Spec URL: https://ucp.dev/draft/specification/catalog/
  • [ ] Endpoint reachable and returns JSON
  • [ ] Product data includes required fields (id, title, price)

Adding Identity Linking (stable):

  • [ ] OAuth 2.0 authorization endpoint HTTPS
  • [ ] Token endpoint HTTPS
  • [ ] Scopes defined
  • [ ] 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 (1)

Collapse
 
firekey_browser profile image
FireKey Team •

Solid technical piece. For multi-tenant e-commerce tooling: major platforms cross-reference Canvas fingerprint (GPU hash), WebGL renderer, timezone-proxy consistency, and regional font sets alongside IP. Two accounts with identical Canvas hashes look like one device regardless of IP rotation. Worth factoring this into compliance and trust/safety architecture.