Everything you need to build for the agentic shopping era.
Start with UCP 101 below - what the protocol requires and how to implement it. Then go deeper with our engineering write-ups, or jump straight to the official UCP and MCP specs.
UCP 101 - Implementation guide
If you're on Shopify, most of this is already done for you.
Shopify natively implements all six UCP steps. For most stores, enabling UCP is a single settings change. The steps below show what UCP requires, what to check, and how to debug if something still isn't working.
See the UCP CLI in action
A real, sanitised trace of the ucp CLI against jbhifi.com.au - discover, search, cart, checkout. The same flow UCP Labs runs on your store.
# Fetch the merchant's UCP profile and supported capabilities $
JB Hi-Fi runs on Shopify behind the scenes - the endpoint URL points at the myshopify.com instance.
UCP Profile Discovery
/.well-known/ucpAI agents start every shopping session by fetching your store's UCP profile from a well-known URL. This declares what capabilities your store supports, which transport it uses, and where the MCP endpoint lives.
Native on Shopify - no configuration needed. Shopify automatically exposes /.well-known/ucp for all stores once UCP is enabled in the Shopify admin.
- 1Go to Shopify Admin → Settings → Customer accounts
- 2Ensure "New customer accounts" is enabled (required for UCP)
- 3UCP profile is automatically live at yourstore.myshopify.com/.well-known/ucp
Serve a JSON response at /.well-known/ucp that declares your MCP endpoint and capabilities:
// GET /.well-known/ucp
{
"ucp": {
"version": "2026-04-08",
"status": "success",
"services": {
"dev.ucp.shopping": [{
"version": "2026-04-08",
"spec": "https://ucp.dev/2026-04-08/specification/overview/",
"schema": "https://ucp.dev/2026-04-08/services/shopping/mcp.openrpc.json",
"transport": "mcp",
"endpoint": "https://yourstore.com/api/ucp/mcp"
}]
},
"capabilities": {
"dev.ucp.shopping.checkout": [{
"version": "2026-04-08",
"spec": "https://ucp.dev/2026-04-08/specification/checkout"
}]
},
"payment_handlers": {
"stripe": { "version": "1" }
}
}
}Common failure modes
- Profile not found (404) - endpoint not deployed or wrong path
- Missing capabilities block - agents can't verify checkout support
- Wrong Content-Type - must be application/json
- Missing payment_handlers - checkout completion requires at least one handler
How UCP Labs tests this: Score 20/20 on Discovery when UCP Labs fetches your profile, validates the endpoint URL, transport, capabilities, and payment handlers.
Catalog Search
search_products toolAgents need to browse your catalog to find products on behalf of buyers. The search tool must return products with variant-level pricing, availability, and checkout URLs.
Automatically implemented by Shopify UCP. No changes needed.
- 1Shopify maps your product catalog to the UCP search schema automatically
- 2Products, variants, pricing, and availability sync in real time
- 3Ensure your products are published to the "Online Store" channel
Implement the search_products MCP tool on your endpoint:
// Tool: search_products
// Request
{
"query": "coffee beans", // search term (empty string = list all)
"context": {
"address_country": "AU",
"currency": "AUD"
},
"filters": {
"available": true,
"price": { "min": 0, "max": 10000 } // minor currency units (cents)
},
"pagination": { "limit": 20 }
}
// Response shape
{
"result": {
"products": [{
"id": "prod_abc123",
"title": "Single Origin Ethiopian",
"description": "...",
"price_range": {
"min": { "amount": 2800, "currency": "AUD" },
"max": { "amount": 4200, "currency": "AUD" }
},
"variants": [{
"id": "var_xyz",
"title": "250g",
"price": { "amount": 2800, "currency": "AUD" },
"availability": { "available": true },
"url": "https://yourstore.com/products/ethiopian",
"checkout_url": "https://yourstore.com/cart/add?id=var_xyz",
"seller": { "name": "Your Store", "domain": "yourstore.com" }
}]
}],
"pagination": { "total": 48, "has_next_page": true }
}
}Common failure modes
- Returning 0 products - try an empty query string (lists all) before keyword queries
- Missing variant IDs - agents need these to add to cart
- Prices not in minor currency units - $28.00 must be 2800, not 28.0
- Missing availability field - agents skip out-of-stock products
How UCP Labs tests this: UCP Labs runs a real search and checks that at least one product is returned with valid variants and pricing.
Product Detail
get_product toolOnce an agent finds a product in search, it calls get_product to retrieve the full variant matrix - all size/colour/option combinations with current pricing and stock. This is what the agent uses to decide which specific variant to add to cart.
Automatically implemented. Shopify returns the full variant matrix, options, and real-time pricing.
- 1No configuration needed - Shopify handles this automatically
- 2Ensure variants have correct prices and inventory tracking enabled
- 3Set inventory policy to "Continue selling when out of stock" only if intentional
Implement the get_product tool:
// Tool: get_product
// Request: positional product ID
{ "id": "prod_abc123" }
// Response shape
{
"result": {
"product": {
"id": "prod_abc123",
"title": "Single Origin Ethiopian",
"description": "Rich, fruity notes...",
"url": "https://yourstore.com/products/ethiopian",
"price_range": {
"min": { "amount": 2800, "currency": "AUD" },
"max": { "amount": 4200, "currency": "AUD" }
},
"options": [
{ "name": "Size", "values": ["250g", "500g", "1kg"] }
],
"variants": [
{
"id": "var_250g",
"title": "250g",
"price": { "amount": 2800, "currency": "AUD" },
"availability": { "available": true },
"options": [{ "name": "Size", "label": "250g" }],
"checkout_url": "https://yourstore.com/cart/add?id=var_250g"
}
]
}
}
}Common failure modes
- Options matrix missing - agents can't compose multi-variant orders
- Variant IDs don't match search results - agents will try to add stale IDs to cart
- Price mismatch between search and detail - causes agent confusion
- No checkout_url on variants - agents can't proceed to cart
How UCP Labs tests this: UCP Labs picks a product from search and calls get_product, checking for complete variant data and consistent pricing.
Cart Creation
create_cart toolThe agent creates a cart with specific variants and quantities. The cart response must include line items with pricing and totals. This is where currency, tax, and initial shipping estimates are first surfaced.
Automatically implemented. Shopify's cart API is fully UCP-mapped.
- 1No configuration needed
- 2Ensure your store currency is set correctly in Shopify Admin → Settings → Store currency
- 3Tax settings apply automatically (inclusive or exclusive depending on region)
Implement the create_cart tool:
// Tool: create_cart
// Request
{
"line_items": [{
"item": { "id": "var_250g" },
"quantity": 2
}],
"context": {
"address_country": "AU",
"currency": "AUD"
}
}
// Response shape
{
"result": {
"id": "cart_abc", // required - used for checkout conversion
"currency": "AUD",
"line_items": [{
"id": "line_1", // required - used for checkout line targeting
"item": {
"id": "var_250g",
"title": "Single Origin Ethiopian - 250g",
"price": { "amount": 2800, "currency": "AUD" }
},
"quantity": 2
}],
"totals": [
{ "type": "subtotal", "label": "Subtotal", "amount": 5600 },
{ "type": "total", "label": "Total", "amount": 5600 }
],
"continue_url": "https://yourstore.com/cart/abc"
}
}Common failure modes
- No cart ID in response - checkout create can't convert the cart
- Missing line_items[].id - checkout update can't target individual lines
- Totals missing or wrong type - 'total' key is required
- Currency mismatch vs product prices - causes agent-side calculation errors
How UCP Labs tests this: UCP Labs creates a real cart with a variant from step 3 and checks for a valid cart ID, line items, and totals.
Checkout Creation
create_checkout toolThe agent converts the cart into a checkout session. This is where fulfillment methods (shipping options), tax calculations, and buyer information are collected. The checkout can be completed in-protocol (agent pays autonomously) or require buyer handoff via continue_url.
Automatically implemented via Shopify Payments and UCP checkout. Stores using Shopify Payments support in-protocol completion; others require buyer handoff.
- 1Enable Shopify Payments for best agent compatibility (supports in-protocol completion)
- 2If using a third-party payment gateway, checkout will return requires_escalation with a continue_url for buyer handoff - this is expected and scores 3/5 on completion
- 3Ensure checkout.liquid or Checkout Extensibility doesn't block API-based checkouts
Implement the create_checkout tool. Two modes: cart conversion (preferred) or direct:
// Tool: create_checkout - cart conversion mode (preferred)
{
"cart_id": "cart_abc",
"line_items": [] // empty when converting a cart
}
// Direct mode (no prior cart)
{
"line_items": [{
"item": { "id": "var_250g" },
"quantity": 2
}]
}
// Response - in-protocol completion possible
{
"result": {
"id": "checkout_xyz", // required
"status": "incomplete", // or "requires_escalation"
"currency": "AUD",
"line_items": [...],
"totals": [...],
"fulfillment": {
"methods": [{
"type": "shipping",
"groups": [{
"id": "grp_1",
"options": [{
"id": "opt_standard",
"label": "Standard Shipping",
"amount": 895,
"currency": "AUD",
"estimated_delivery": "3-5 business days"
}]
}]
}]
},
"continue_url": "https://yourstore.com/checkouts/xyz"
}
}Common failure modes
- No checkout ID returned - most common cause of 0/15 score on this step
- continue_url is the store homepage - UCP endpoint not handling cart checkout conversion
- status missing - agents can't determine if checkout requires escalation
- Fulfillment methods empty when shipping is required - agents can't select a delivery option
How UCP Labs tests this: UCP Labs converts the cart to a checkout and validates the checkout ID, status, and fulfillment method structure.
Checkout Completion
complete_checkout toolThe final step: the agent attempts to complete the purchase autonomously. If successful, an order is created in-protocol and no buyer interaction is needed. If the merchant uses a third-party payment gateway, the checkout enters requires_escalation - partial credit is awarded and the buyer is handed off to continue_url.
Stores using Shopify Payments can support in-protocol completion with a payment instrument token. Stores using external gateways will return requires_escalation.
- 1Shopify Payments stores: agent must supply a payment token via the instruments array in checkout update
- 2Third-party gateway stores: complete_checkout will return requires_escalation - this is normal and awards 3/5 points
- 3Test with: ucp checkout complete <checkout_id> --business https://yourstore.com
Implement the complete_checkout tool:
// Tool: complete_checkout
// Request: positional checkout ID, no body required for escalation flow
{ "id": "checkout_xyz" }
// Response - completed autonomously
{
"result": {
"id": "checkout_xyz",
"status": "completed", // order created
"order_id": "order_abc"
}
}
// Response - buyer handoff required (requires_escalation)
{
"result": {
"id": "checkout_xyz",
"status": "requires_escalation",
"continue_url": "https://yourstore.com/checkouts/xyz/payment",
"messages": [{
"type": "info",
"text": "Payment authorisation required - please complete checkout at the provided URL."
}]
}
}
// Scoring:
// "completed" → 5/5 pts (fully autonomous)
// "requires_escalation" → 3/5 pts (buyer handoff, UCP works but not fully autonomous)
// anything else / error → 0/5 ptsCommon failure modes
- status: 'incomplete' - buyer information (address, payment) still missing from checkout
- status: 'canceled' - checkout session expired; agent must start a new checkout
- Error on complete with no status - checkout create likely failed silently
- continue_url is the store homepage, not a checkout URL - see Checkout Creation step
How UCP Labs tests this: UCP Labs calls complete_checkout and checks for 'completed' or 'requires_escalation'. Either passes; anything else fails.
Deep dives
Engineering write-ups on the patterns and pitfalls we've hit shipping UCP-native commerce.
Engineering · 10 min
Beyond the Storefront: Building Bespoke, UCP-Native Commerce
Building a UCP-compliant store from the ground up: discovery, capabilities, escalation, payment.
Engineering · 12 min
Building a UCP/MCP gateway for agentic commerce
Letting any AI agent discover, cart, checkout, and pay through UCP via MCP.
Official UCP resources
The protocol is open. Start with the spec, browse reference implementations, then come back here to test what you've built.
Want a guided walkthrough?
We've been building on UCP since launch - happy to walk through your specific store, codebase, or platform setup and answer questions over a call. No pitch, no obligation.