UCP Technical Implementation

Shopify Is Rolling Out UCP—But Most Merchants Don't Have It Yet

Shopify announced UCP support in early 2026 with a gradual rollout plan. If you're waiting for native support, you might be waiting until Q4 2026 or later.

The Official Rollout Timeline

Q1 2026: Beta testing with select Shopify Plus merchants only
Q2 2026: Rollout to all Shopify Plus tier
Q3 2026: Rollout to standard Shopify plans begins
Q4 2026: Full availability expected (maybe)

Translation: If you're on standard Shopify, you're probably waiting 6-9 months minimum.

What "Native Support" Will Include

When it arrives, Shopify's UCP will:

• Auto-generate /.well-known/ucp manifests
• Handle OAuth and identity linking built-in
• Configure endpoints without custom code
• Update automatically when UCP spec changes
• Integrate with Shopify Payments for AP2 support
• One-click enablement in admin panel

Basically, flip a switch and you're compliant.

Current Workarounds (Get Compliant Now)

Option 1: Third-Party Shopify Apps

Several apps in the Shopify App Store provide UCP now:

• UCP Compliant for Shopify - $99-199/year
• AI Commerce Ready - $149/year
• Universal Protocol Connect - $129/year

How they work:

1. Install app from Shopify App Store
2. App generates UCP manifest using Shopify's API
3. Proxies UCP requests to Shopify endpoints
4. Handles CORS and authentication
5. Setup time: 15-30 minutes

Option 2: External Proxy Service

Middleware service sits between AI agents and your Shopify store:

• Hosts manifest file externally
• Translates UCP requests to Shopify API calls
• No code changes to your store
• Works even if you change themes

Option 3: Wait for Native Support

The risk: Losing 6-12 months of AI-referred traffic to competitors

The cost at $847/day average:

• 6 months wait: $152,460 in missed revenue
• 9 months wait: $228,690 in missed revenue
• 12 months wait: $304,920 in missed revenue

Plus competitors building trust scores you can never catch up to.

Why Shopify Is Moving Slowly

They support 4+ million stores - Rolling out infrastructure changes at that scale takes time

They need rock-solid implementation - One bug affects millions of merchants

They're coordinating with payment providers - AP2 integration with Shopify Payments is complex

This is smart engineering but bad timing for merchants who need UCP now.

Will Third-Party Apps Still Be Needed?

Eventually no, but there's a migration path:

1. Use third-party app NOW to get compliant
2. Build AI traffic and trust scores for 6-9 months
3. When Shopify native support arrives, migrate seamlessly
4. Keep all the revenue and trust you've already built

You don't lose anything by starting with third-party solutions. You lose everything by waiting.

Shopify Plus Gets Priority

If you're on Shopify Plus ($2,000+/month plans), you'll get native UCP sooner—probably Q2 2026.

If you're on standard Shopify ($29-299/month plans), you're in the later waves—Q3-Q4 2026 at best.

The Smart Play for Shopify Merchants

Don't wait. Get compliant today with a third-party app.

Start capturing AI traffic NOW. Build trust with AI platforms while competitors wait. Generate revenue for 6-9 months before native support even arrives.

When Shopify's native support launches, migrate to it if you want. But you'll already have:

• Months of AI-referred revenue
• Established trust scores
• First-mover advantages locked in
• ROI many times over

See Shopify-compatible solutions →

UCP Evolves—You Need a Strategy to Keep Up

The UCP specification changes over time with new features, security patches, and improvements. Your implementation needs to handle updates without breaking.

Current Version Declaration

In your manifest, you declare which UCP version you're using:

{
  "version": "1.0",
  ...
}

AI agents see this and interact with your store using that version's rules.

How Backward Compatibility Works

The good news: AI agents support multiple UCP versions simultaneously.

If you declare version 1.0, agents use 1.0 rules—even if they support 2.0. This prevents breaking changes from disrupting your store.

Example:

• You implement UCP 1.0 in January 2026
• UCP 2.0 releases in July 2026
• Your store keeps working with 1.0
• You upgrade to 2.0 when ready

Version Support Timeline

Current version: Fully supported, recommended for new implementations

Previous version: Supported for 12 months after new version release

Older versions: May work but not officially supported

Deprecated versions: AI agents will eventually stop accepting them

Example timeline:

• UCP 2.0 releases July 2026
• UCP 1.0 supported until July 2027
• After July 2027, must upgrade to 2.0 or newer

When You Must Update

Required updates (can't delay):

• Security vulnerabilities: Critical patches need immediate deployment
• Version deprecation: When your version reaches end-of-life
• Platform requirements: If your e-commerce platform forces UCP updates

Optional updates (you decide when):

• New features: Capabilities you want to add
• Performance improvements: Speed optimizations
• Enhanced analytics: Better tracking and insights

Update Process Best Practices

1. Review changelog at ucp.dev
See what changed, what's new, what breaks backward compatibility

2. Test in staging environment first
Never update production without testing. One broken endpoint = lost revenue.

3. Update manifest version number
Change "version": "1.0" to "version": "2.0" after everything works

4. Update endpoint implementations
Modify responses to match new schemas if required

5. Validate against new specification
Run validators to confirm compliance with updated spec

6. Deploy gradually with monitoring
Watch error rates, response times, conversion rates after update

7. Have rollback plan ready
If something breaks, can you quickly revert to previous version?

Staying Informed About Updates

Subscribe to update notifications:

• UCP mailing list at ucp.dev
• GitHub repository releases
• Your managed solution provider (they notify customers)

Check quarterly:
Set calendar reminder to review ucp.dev changelog every 3 months

Managed vs Manual Update Responsibility

Managed solutions (plugins, services):

• Auto-update manifest and endpoints
• Handle version migrations automatically
• Email you when action required
• Zero manual work for most updates

DIY implementations:

• You track specification changes
• You update code manually
• You test and deploy updates
• You're responsible if you fall behind

Breaking vs Non-Breaking Changes

Non-breaking changes (safe):

• New optional fields added
• New capabilities introduced
• Performance optimizations

Your implementation keeps working without modifications.

Breaking changes (require action):

• Required fields removed or renamed
• Response format changes
• Authentication method changes

You must update code or manifest won't validate.

UCP follows semantic versioning: Major version bumps (1.0 → 2.0) can break compatibility. Minor versions (1.0 → 1.1) maintain compatibility.

What Happens If You Don't Update

Short-term (first 12 months):
Nothing. Your old version keeps working fine.

Medium-term (12-24 months):
You miss new features competitors have. Fall behind on capabilities.

Long-term (24+ months):
Version deprecated. AI agents stop accepting your manifest. You become non-compliant and invisible again.

Pro Tip: Let Tools Handle This

Unless you love tracking specifications and updating code, use managed solutions that auto-update for you.

Your time is better spent running your business than managing UCP version migrations.

Check if your version is current →

JSON-RPC Is an Optional Alternative to REST APIs

Most stores use standard REST APIs for UCP. JSON-RPC is a more advanced option for high-volume stores or those needing real-time bidirectional communication.

REST vs JSON-RPC: The Difference

REST (Standard approach - what most stores use):

• Each capability has its own URL endpoint
• Uses standard HTTP methods (GET, POST, PUT, DELETE)
• Stateless request-response pattern
• Easy to implement and debug
• Works great for 99% of stores

JSON-RPC (Advanced approach):

• Single endpoint handles all capabilities
• All requests use POST with method names
• Can support WebSockets for real-time updates
• More efficient for very high-volume interactions
• More complex to implement correctly

When to Consider JSON-RPC

You might benefit from JSON-RPC if:

• You're processing 10,000+ AI agent requests per day
• You need real-time push notifications to AI platforms
• You're already using JSON-RPC in your infrastructure
• You want to reduce endpoint management overhead

Stick with REST if:

• You're just getting started with UCP
• Your traffic is under 10,000 requests/day
• You want simple debugging and monitoring
• Your team is more familiar with REST

What JSON-RPC Looks Like

JSON-RPC request example:

POST /api/ucp/jsonrpc

{
  "jsonrpc": "2.0",
  "method": "dev.ucp.shopping.checkout",
  "params": {
    "items": [{"id": "123", "qty": 1}],
    "shipping_address": {...}
  },
  "id": 1
}

JSON-RPC response:

{
  "jsonrpc": "2.0",
  "result": {
    "session_id": "sess_abc123",
    "total": 49.99
  },
  "id": 1
}

Advantages of JSON-RPC

1. Single endpoint management
Instead of managing separate URLs for checkout, orders, auth—one endpoint handles everything.

2. WebSocket support
Can upgrade connection for real-time bidirectional communication. Useful for inventory updates, order status changes.

3. Batch requests
Send multiple method calls in one HTTP request, reducing network overhead.

4. Consistent error handling
Standardized error response format across all methods.

Disadvantages of JSON-RPC

1. More complex implementation
Need request parsing, method routing, error code mapping—all manual.

2. Harder to debug
All requests go to same URL. Harder to track which capability is failing in logs.

3. Less tooling support
REST has tons of tools (Postman, curl, browser DevTools). JSON-RPC has fewer.

4. Overkill for most stores
Unless you're high-volume, the added complexity isn't worth it.

Real-World Example

Small-to-medium store (REST):
3 endpoints, easy to monitor, works perfectly fine for 500 AI requests/day

High-volume marketplace (JSON-RPC):
50,000 AI requests/day, WebSocket push updates, batch operations—JSON-RPC reduces overhead significantly

Our Recommendation

For 99% of stores: Use REST.

It's simpler, better documented, easier to debug, and works great even at high volume. Most managed solutions and plugins use REST.

Only consider JSON-RPC if:

• You're already doing 10,000+ requests/day
• You have developers experienced with JSON-RPC
• You have specific real-time requirements REST can't meet

Start with REST. You can always add JSON-RPC support later if your volume justifies it. Don't over-engineer at the beginning.

Get started with REST endpoints →

Your Endpoints Are Where AI Agents Actually Do Stuff

The manifest tells AI agents what you can do. Endpoints are where they go to actually do it—checkout, order tracking, authentication.

Basic Endpoint Requirements

1. Must use HTTPS (not HTTP)

• ❌ http://yourstore.com/api/checkout
• ✅ https://yourstore.com/api/checkout

AI agents reject non-secure endpoints. Get an SSL certificate if you don't have one.

2. Must be publicly accessible

• ❌ localhost:3000/api (only works on your machine)
• ❌ 192.168.1.10/api (internal IP)
• ✅ api.yourstore.com/ucp/checkout (public domain)

3. Must return proper HTTP status codes

• 200 OK: Request succeeded
• 400 Bad Request: AI sent invalid data
• 401 Unauthorized: Authentication required
• 404 Not Found: Resource doesn't exist
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Your server messed up

4. Must include CORS headers

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

Without these, browsers block AI agent requests for security reasons.

CORS Configuration Explained

Why CORS exists:
Browsers don't let websites make requests to other domains by default. It's a security feature.

Why UCP needs it:
AI agents run in different domains (chatgpt.com, gemini.google.com). They need permission to call your API.

How to fix it:
Your server must respond to OPTIONS requests (called "preflight") telling the browser "yes, I allow cross-origin requests."

Common CORS mistakes:

• Forgetting to handle OPTIONS requests (60% of failures)
• Setting Allow-Origin to wrong domain
• Missing Allow-Headers for Authorization
• Not setting Allow-Methods correctly

Endpoint URL Structure

Good patterns:

• https://yourstore.com/api/ucp/checkout
• https://api.yourstore.com/ucp/checkout
• https://yourstore.com/ucp/v1/checkout

Bad patterns:

• https://yourstore.com/checkout (too generic, might conflict)
• https://yourstore.com/wp-json/ucp (exposes platform details)
• https://yourstore.com/index.php?ucp=checkout (ugly, breaks caching)

Response Format Requirements

Content-Type must be JSON:

Content-Type: application/json

Response body must be valid JSON:

{
  "status": "success",
  "data": {
    "order_id": "12345",
    "total": 49.99
  }
}

AI agents can't parse HTML or XML. JSON only.

Rate Limiting Best Practices

Why rate limiting matters:
Malicious AI agents (or bugs) might spam your API. Protect yourself.

Recommended limits:

• 100 requests per minute per IP (burst traffic)
• 1,000 requests per hour per API token (normal usage)
• 10,000 requests per day per merchant (prevents abuse)

Return 429 status when exceeded:

{
  "error": "rate_limit_exceeded",
  "retry_after": 60
}

AI agents will back off and retry later.

Platform-Specific Configuration

WooCommerce:
Extend REST API with custom endpoints. Use WooCommerce authentication.

Shopify:
Create custom app with API access. Use Shopify's proxy system.

Custom platform:
Add routes in your framework (Express, Django, Laravel, etc.)

Testing Your Endpoints

Before going live:

1. Test with curl:

curl -X POST https://yourstore.com/api/ucp/checkout \
  -H "Content-Type: application/json" \
  -d '{"items": [{"id": "123", "qty": 1}]}'

2. Check CORS in browser console:
Open DevTools Network tab, look for OPTIONS requests, verify CORS headers

3. Validate response JSON:
Use JSONLint to confirm responses match expected schema

4. Load test:
AI traffic is bursty. Test with 100+ simultaneous requests

Monitoring After Launch

Track these metrics:

• Response times (should be under 500ms)
• Error rates (should be under 1%)
• CORS failures (indicates configuration issues)
• Rate limit hits (might need to adjust limits)

Set up alerts when error rates spike.

Common "It Works On My Machine" Issues

Works in Postman, fails with AI agents:
Usually CORS. Postman doesn't enforce CORS, browsers do.

Works with one AI, fails with another:
Different AI agents have different timeout tolerances. Optimize response times.

Works sometimes, fails others:
Load balancing issues or database connection limits. Check infrastructure.

Validate all your endpoints →

This Lets AI Agents Access Customer Accounts Securely.

Identity linking uses OAuth 2.0 to connect AI assistants with customer accounts on your store—enabling personalized shopping without exposing passwords or sensitive data.

What Identity Linking Enables

With customer authorization, AI agents can:

• Access order history for easy reordering
• Use saved payment methods and addresses
• View wishlists and saved items
• Get personalized product recommendations
• Manage account settings
• Check loyalty points and rewards

How the OAuth Flow Works

Customer: "ChatGPT, reorder my last purchase from Best Running Shoes"

1. AI needs account access
"To access your order history, I need permission to connect with your account"

2. Customer authorizes connection
Gets redirected to your store's login page, signs in, approves AI access

3. Your store returns access token
AI agent receives token proving customer authorized the connection

4. AI uses token for authenticated requests
Can now access order history, saved addresses, etc. on customer's behalf

5. Customer can revoke access anytime
In account settings: "Disconnect ChatGPT" removes AI agent access

Security Features Built Into OAuth 2.0

AI never sees your password
Customer logs in on YOUR website, not in the AI interface. AI only gets an access token.

Granular permissions (scopes)
You control exactly what AI can access:

• read:orders (view order history)
• write:cart (create checkout sessions)
• read:profile (access name, email)
• write:payment (process payments)

Token expiration
Access tokens expire after 1-2 hours. Refresh tokens last 30 days. Customer must reauthorize periodically.

Easy revocation
Customer can disconnect AI access instantly. Revoking permission invalidates all tokens.

Implementation Requirements

You need to build:

• Authorization endpoint: Where customer logs in and approves AI access
• Token endpoint: Where AI exchanges authorization codes for access tokens
• Refresh endpoint: Where AI gets new tokens when old ones expire
• Revocation endpoint: Where customers disconnect AI access
• Scope management: Define what data each permission level allows

OAuth Best Practices

Use PKCE (Proof Key for Code Exchange)
Prevents authorization code interception attacks. Required by modern OAuth specs.

Set appropriate token lifetimes
Access tokens: 1-2 hours (short-lived for security)
Refresh tokens: 30 days (longer for convenience)

Log all authenticated actions
Track what AI agents do with customer accounts for audit trails and dispute resolution.

Show active connections in account settings
"Connected AI Assistants: ChatGPT (last used 2 days ago)" with [Disconnect] button

Privacy Compliance

On authorization screen, clearly show:

• What data will be shared (order history, email, etc.)
• What the AI can do (view orders, make purchases)
• How to revoke access later

Follow data protection laws:

• GDPR (Europe): Explicit consent required
• CCPA (California): Right to know what's shared
• Never share more data than requested scope allows

Why Identity Linking Improves Conversions

Without identity linking:
Customer: "Reorder my usual coffee beans"
AI: "I don't have access to your order history. Can you tell me which product?"
Customer: "Never mind, I'll do it manually"

With identity linking:
Customer: "Reorder my usual coffee beans"
AI: "Reordering Colombian Dark Roast, 2 lbs, same as last month. Confirm?"
Customer: "Yes"
Done in 10 seconds.

When to Implement Identity Linking

Priority order:

1. First: Checkout capability (start generating revenue)
2. Second: Order tracking (reduce support tickets)
3. Third: Identity linking (enable personalization)

Identity linking is powerful but not required to start. Get compliant with checkout first, add OAuth later.

Platform Shortcuts

Most e-commerce platforms already have OAuth:

• Shopify: Built-in OAuth for apps—extend for UCP
• WooCommerce: WordPress OAuth plugins available
• BigCommerce: Native OAuth support

You're often just adapting existing OAuth to work with UCP, not building from scratch.

Test your OAuth implementation →

This Is How AI Agents Answer "Where's My Order?"

The order capability lets AI assistants retrieve order status, tracking info, and history without customers having to log into your website.

What Order Capability Enables

Customer asks AI: "Where's my order from Best Running Shoes?"

AI agent:

1. Authenticates customer (OAuth)
2. Queries your order endpoint
3. Gets current status and tracking info
4. Translates into natural language response

Customer gets answer instantly without opening browser, logging in, or hunting for tracking numbers.

What Your Endpoint Must Provide

For each order, return:

• Order ID and date placed
• Current status (processing, shipped, delivered, etc.)
• Tracking number and carrier
• Expected delivery date
• Line items with prices
• Shipping and billing addresses
• Order total

Order Status Values That AI Agents Understand

Use these exact status strings:

• pending: Order received, payment processing
• processing: Order confirmed, being prepared for shipment
• shipped: Order in transit (must include tracking number)
• delivered: Successfully delivered to customer
• cancelled: Order cancelled before shipment
• refunded: Refund processed

AI agents rely on these to give accurate responses. Custom status names confuse them.

Real-Time Updates Are Critical

Stale data breaks trust:

Customer: "Where's my order?"
AI: "Still processing"
Customer checks manually: "It was delivered 2 days ago!"

Result: Customer loses trust in both your store AND the AI assistant.

Solution: Keep order data synchronized with your shipping provider. Update status within minutes, not hours.

Webhook vs Polling Strategy

Polling (AI agents request updates):

• AI agents periodically check for status changes
• Simple to implement
• Can be delayed (might check every hour)

Webhooks (you push updates to AI platforms):

• Your system notifies AI platforms immediately when status changes
• More complex to implement
• Enables real-time "your order has shipped!" notifications

Start with polling. Add webhooks later for competitive advantage.

Privacy and Security Requirements

Never expose order details without authentication:

• ❌ Allow anyone to query any order by ID
• ✅ Require OAuth token proving customer identity

Redact sensitive information:

• Don't show full credit card numbers
• Don't expose internal customer IDs
• Follow GDPR/CCPA requirements for data access

Support order revocation:

Customers should be able to revoke AI access to their order history in account settings.

Handling Edge Cases

Order not found:
Return clear "no order found" response instead of 404 error. AI can explain to customer.

Multiple orders for same customer:
Support filtering by date range or order ID. AI might ask "show orders from last month."

Partial shipments:
If order ships in multiple packages, return tracking for each package separately.

Returns and refunds:
Include return status and refund processing info when applicable.

Why Order Tracking Matters for Business

Reduces support ticket volume:
"Where's my order?" is the #1 customer service question. AI agents answer it automatically.

Improves customer experience:
Instant answers via AI vs logging in, finding order number, checking tracking manually.

Builds AI trust scores:
Stores that provide accurate real-time updates get higher reliability ratings from AI platforms.

Implementation Priority

If you're just starting out:

1. First: Get checkout capability working (that's where revenue comes from)
2. Second: Add order tracking (improves customer experience)
3. Third: Add identity linking (enables personalization)

Don't try to implement all three at once. Master each before adding the next.

Validate your order endpoint →

This Is Where AI Agents Actually Buy Stuff !

The checkout capability is the money-maker. It lets AI agents create shopping carts, calculate totals, and complete purchases on behalf of customers.

What Checkout Capability Enables

The AI agent can:

• Add products to a cart with quantities
• Apply discount codes
• Calculate tax based on shipping address
• Show shipping options and costs
• Process payment using customer-authorized payment methods
• Return order confirmation and receipt

The Typical Checkout Flow

1. Customer asks AI to buy something
"Order me running shoes under $100"

2. AI agent creates checkout session
Sends POST request to your checkout endpoint with product IDs, quantities, shipping address

3. Your system calculates total
Product price + tax + shipping = total amount

4. AI agent authorizes payment
Using Agent Payments Protocol (AP2), customer authorizes the charge

5. Your system processes payment
Charges the payment method, confirms order

6. AI agent receives confirmation
Gets order ID, tracking info, receipt—passes it to customer

What Your Endpoint Must Handle

Incoming requests must include:

• Product IDs and quantities
• Customer shipping information
• Payment authorization token (from AP2)
• Optional: discount codes, gift messages, delivery instructions

Your response must include:

• Session ID for the checkout
• Total price breakdown (subtotal, tax, shipping, total)
• Available payment methods
• Estimated delivery timeframe
• Order confirmation after payment

Common Implementation Mistakes

1. Not handling out-of-stock scenarios

AI agent tries to buy item that's sold out. Your endpoint crashes or returns unclear error. AI marks you as unreliable.

Solution: Return clear "item unavailable" response with alternative suggestions

2. Tax calculation errors

Calculating wrong tax rate for customer's region. Could be illegal, definitely breaks trust.

Solution: Use proper tax APIs (Stripe Tax, TaxJar, Avalara) for accurate calculations

3. Failing under load

Your endpoint works fine for 10 requests/hour but crashes when 100 AI agents hit it simultaneously.

Solution: Load test before going live. AI traffic is bursty—prepare for spikes

4. Not validating payment authorizations

Processing orders without properly verifying AP2 payment mandates. Opens you to fraud.

Solution: Always validate cryptographic signatures on payment authorizations

Security Considerations

Never store sensitive payment data
Use tokenization. Never log full credit card numbers. AI agents send payment tokens, not raw card data.

Validate everything
Don't trust any data from AI agents. Validate addresses, check inventory, verify payment authorization.

Rate limiting
Protect against malicious AI agents trying to overwhelm your system. Limit requests per IP/token.

Audit logging
Log all transactions for dispute resolution. Include timestamps, AI agent ID, actions taken.

Testing Your Checkout Implementation

Before going live, test:

• Successful purchase flow (happy path)
• Out-of-stock products
• Invalid discount codes
• Address validation failures
• Payment authorization rejections
• High-volume load testing

AI agents are unforgiving. One broken checkout experience and they might avoid your store permanently.

Pro Tip: Use Existing Infrastructure

You don't need to rebuild checkout from scratch. Most implementations:

• Use existing Shopify/WooCommerce checkout APIs
• Create a UCP translation layer on top
• Let platform handle complex logic (tax, shipping, payment)

The UCP endpoint just translates between AI agent requests and your platform's existing checkout.

Test your checkout endpoint →

Capabilities Are Like Your Store's Menu of Services

They tell AI agents exactly what your store can do—from browsing products to completing checkout to tracking orders.

The Core Capabilities Explained

dev.ucp.shopping.checkout
Lets AI agents create shopping carts and complete purchases. This is the most important one—without it, AI agents can't buy from you.

What it enables: Add items to cart, calculate tax, process payment, receive order confirmation

dev.ucp.shopping.order
Lets AI agents check order status and tracking info.

What it enables: "Where's my order?" queries, delivery tracking, order history

dev.ucp.common.identity_linking
Lets AI agents connect to customer accounts using OAuth.

What it enables: Personalized recommendations, saved addresses, order history, one-click checkout

How to Declare Capabilities

In your manifest, list only what you've ACTUALLY implemented:

"capabilities": [
  "dev.ucp.shopping.checkout",
  "dev.ucp.shopping.order"
]

Then map each to its endpoint:

"endpoints": {
  "dev.ucp.shopping.checkout": "https://yourstore.com/api/ucp/checkout",
  "dev.ucp.shopping.order": "https://yourstore.com/api/ucp/orders"
}

Critical Rules You Can't Break

1. Only declare what actually works

AI agents will TEST every capability you declare. If you claim to support checkout but your endpoint returns 404, you get blacklisted.

It's better to support just one capability perfectly than three capabilities poorly.

2. Use exact capability names from the spec

• ❌ "checkout" (too generic)
• ❌ "shopping_checkout" (wrong format)
• ✅ "dev.ucp.shopping.checkout" (exact match)

AI agents won't try to guess what you meant. Typos = rejected.

3. Every capability needs a working endpoint

You can't declare a capability without providing the URL where AI agents can actually use it:

❌ Declaring "checkout" but no endpoint URL
❌ Endpoint returns 500 errors
❌ Endpoint requires authentication when it shouldn't
✅ Endpoint returns valid responses matching schema

Implementation Strategy: Start Small

Phase 1 (Week 1): Just Checkout

• Implement checkout capability only
• Get it working perfectly
• Start generating AI-referred revenue

Phase 2 (Week 2-3): Add Order Tracking

• Once checkout is proven, add order capability
• Enable "where's my order?" queries
• Improve customer experience

Phase 3 (Month 2): Identity Linking

• Add OAuth for customer accounts
• Enable personalization
• Support saved payment methods

Don't try to implement everything at once. One perfect capability beats three broken ones.

What Happens When You Lie About Capabilities

Scenario: You declare "checkout" capability but your endpoint doesn't actually work.

What happens:

1. AI agent tries to create checkout session
2. Your endpoint fails (404, 500, invalid response)
3. AI marks your store as unreliable
4. Future AI agents avoid your store
5. You're effectively blacklisted

AI platforms share reliability data. One failure can hurt you across multiple AI assistants.

Future Capabilities Coming Soon

The UCP spec is evolving. Future capabilities might include:

• Visual search and product discovery
• Voice commerce interactions
• Subscription management
• B2B wholesale ordering
• Multi-vendor marketplace coordination

Early adopters who master current capabilities will be ready to add new ones as they're released.

The Bottom Line

Start with checkout only. Get compliant fast. Add more capabilities later as you grow.

Perfect execution of one capability is infinitely better than broken implementation of all three.

Check which capabilities you need →

JSON Is Picky—One Wrong Character Breaks Everything

AI agents validate your JSON against strict schemas. Even one misplaced comma, and they reject your entire store. No exceptions, no mercy.

The Critical Formatting Rules

1. Field names are case-sensitive

• ❌ `Merchant` (capital M)
• ❌ `MERCHANT` (all caps)
• ✅ `merchant` (lowercase only)

2. Strings must use double quotes

• ❌ 'single quotes'
• ❌ `no quotes`
• ✅ "double quotes"

3. No trailing commas

• ❌ `"currencies": ["USD", "EUR",]` (comma after EUR)
• ✅ `"currencies": ["USD", "EUR"]` (no comma after last item)

4. All URLs must use HTTPS

• ❌ `http://yourstore.com/api`
• ✅ `https://yourstore.com/api`

5. Arrays need brackets even for single items

• ❌ `"capabilities": "dev.ucp.shopping.checkout"`
• ✅ `"capabilities": ["dev.ucp.shopping.checkout"]`

Common JSON Mistakes That Kill Validation

Missing commas between fields:

❌ {
  "version": "1.0"
  "merchant": {...}
}

✅ {
  "version": "1.0",
  "merchant": {...}
}

Extra comma after last field:

❌ {
  "version": "1.0",
  "merchant": {...},
}

✅ {
  "version": "1.0",
  "merchant": {...}
}

Forgetting quotes on field names:

❌ {
  version: "1.0"
}

✅ {
  "version": "1.0"
}

The Validation Process AI Agents Use

1. Parse JSON: Can it even be read as valid JSON?
2. Schema validation: Do all required fields exist?
3. Type checking: Is "version" a string? Are "capabilities" an array?
4. Value validation: Are currency codes valid ISO 4217?
5. URL verification: Do all endpoints return 200 status?

Fail any step? Rejected. No partial credit.

Why AI Agents Are So Strict

Human developers can look at messy JSON and figure out intent. AI agents can't take risks with customer money:

• Wrong field type might charge incorrect amount
• Invalid URL might expose customer data
• Mismatched schema might cause payment failures

So they validate everything exactly against the spec.

JSON Comments Are Not Allowed

Even though it seems helpful, you CANNOT add comments:

❌ {
  // Store configuration
  "version": "1.0",
  "merchant": {...} /* merchant info */
}

✅ {
  "version": "1.0",
  "merchant": {...}
}

JSON spec doesn't support comments. Adding them breaks parsing.

Testing Your JSON Before Going Live

Use these tools to catch errors:

• JSONLint.com - Validates JSON syntax
• UCP-specific validators - Check against UCP schema
• Browser developer console - Test actual AI agent requests

Don't guess if it's valid. Test before deploying.

The Hidden Gotcha: Character Encoding

Your JSON file must be UTF-8 encoded. Other encodings can cause invisible characters that break parsing even though the JSON "looks fine" to human eyes.

Symptoms: JSON validator says it's valid but AI agents reject it.

Pro Tip: Let Tools Handle This

Unless you're a developer who loves debugging JSON syntax errors at 2am, use managed solutions that generate valid JSON automatically.

They handle:

• Proper quoting and escaping
• Correct comma placement
• Valid field naming
• Schema compliance
• Character encoding

Your time is worth more than fighting JSON syntax issues.

Validate your JSON schema →

Your Manifest Is Your Store's Resume for AI Agents

It tells AI assistants everything they need to know: who you are, what you can do, and how to interact with you.

Required Fields (Can't Skip These)

1. Version
Which UCP spec you're using (currently "1.0")

2. Merchant Info

• ID: Unique identifier for your store
• Name: Your store name
• Domain: Your domain (must match where manifest is hosted)
• Contact email: Support email for issues

3. Capabilities Array
List of features you support (like "dev.ucp.shopping.checkout")

4. Endpoints Object
Maps each capability to its API endpoint URL

5. Supported Payment Methods
Array of payment types you accept (credit_card, paypal, etc.)

6. Supported Currencies
Array of currency codes (USD, EUR, GBP, etc.)

Optional But Highly Recommended

• Authentication: OAuth config for customer login
• Security policy: Link to privacy/security docs
• Fulfillment info: Shipping regions and timeframes
• Return policy: Returns and refunds information

AI agents trust stores more when these are filled out.

What a Basic Manifest Looks Like

{
  "version": "1.0",
  "merchant": {
    "id": "store_abc123",
    "name": "Best Running Shoes",
    "domain": "bestrunningshoes.com",
    "contact_email": "support@bestrunningshoes.com"
  },
  "capabilities": [
    "dev.ucp.shopping.checkout"
  ],
  "endpoints": {
    "dev.ucp.shopping.checkout": "https://bestrunningshoes.com/api/ucp/checkout"
  },
  "supported_payment_methods": ["credit_card", "paypal"],
  "supported_currencies": ["USD", "CAD"]
}

Common Mistakes That Break Everything

1. Invalid JSON syntax

• Missing comma between fields
• Extra comma after last item
• Using single quotes instead of double quotes
• Forgetting to close brackets

AI agents are picky. One syntax error = entire manifest rejected.

2. Wrong capability names

• ❌ "checkout" (too generic)
• ✅ "dev.ucp.shopping.checkout" (exact spec format)

3. HTTP instead of HTTPS

• ❌ `http://yourstore.com/api/checkout`
• ✅ `https://yourstore.com/api/checkout`

AI agents reject non-secure endpoints for security reasons.

4. Declaring capabilities you don't actually have

• Saying you support checkout but endpoint returns 404
• Claiming order tracking but no tracking API exists

AI agents test your capabilities. False advertising = instant blacklist.

Field-Level Validation Rules

Merchant ID: Can't change once set (AI agents track your history)
Domain: Must exactly match where manifest is hosted
Capabilities: Only declare what you've fully implemented
Endpoint URLs: Must return 200 status and valid responses
Currency codes: Must follow ISO 4217 (three-letter codes)

Why AI Agents Are So Strict

Unlike humans who can interpret messy data, AI agents need perfect structure. They're making buying decisions on behalf of real people with real money—they can't afford to guess or assume.

One invalid field might mean:

• Charging the wrong currency
• Sending payment to wrong endpoint
• Exposing customer data

So they reject anything that doesn't match the spec exactly.

The Good News

Managed solutions and plugins generate valid manifests automatically. You don't have to memorize these rules or hand-code JSON—the tools handle validation for you.

Validate your manifest structure →