Setting Up UCP for Your Store
A technical guide for developers and agencies implementing the current Universal Commerce Protocol manifest, including cart, catalog, checkout, and optional identity capability planning.
Where UCP fits
UCP is one of five protocol layers Colter checks. It handles the commerce primitives Google-native agents care about most: checkout, cart, catalog, order updates, and authenticated buying flows.
UCP is the Google commerce layer. For the wider map, start with What Is Agentic Commerce?.
ACP covers conversational transactions for ChatGPT-style agents and is the closest adjacent protocol if you want cross-ecosystem coverage.
MCP gives Claude-style agents structured tool access, while WebMCP makes important browser forms legible to agents.
A2A adds an agent card at /.well-known/agent.json so other agents can discover your capabilities. The broader implementation checklist lives in the discoverability guide.
If you are building UCP, you should usually think about A2A at the same time. One handles commerce operations; the other advertises capabilities to the wider agent ecosystem.
What UCP requires
UCP gives agents a structured way to discover and interact with your store through a manifest hosted at a well-known endpoint.
The March 2026 update moved capability declarations into a namespaced map. Agents now expect you to declare individual capabilities like checkout, cart, catalog, order, and identity linking rather than a flat list of generic verbs.
Prerequisites: You need public product data plus cart and checkout APIs under your control. If Google rolls out Merchant Center onboarding for your platform, treat that toggle as step one, not the last step. Colter is the verification layer that tells you whether the capability wiring actually worked.
The UCP manifest
The manifest is a JSON file served at /.well-known/ucp and must return 200 with Content-Type: application/json.
{
"name": "Your Store Name",
"url": "https://store.com",
"ucp": {
"version": "2026-03-19",
"capabilities": {
"dev.ucp.shopping.checkout": [
{
"version": "2026-03-19",
"spec": "https://ucp.dev/2026-01-23/specification/checkout",
"schema": "https://ucp.dev/2026-01-23/schemas/shopping/checkout.json"
}
],
"dev.ucp.shopping.cart": [
{
"version": "2026-03-19",
"spec": "https://ucp.dev/2026-01-23/specification/cart",
"schema": "https://ucp.dev/2026-01-23/schemas/shopping/cart.json"
}
],
"dev.ucp.shopping.catalog": [
{
"version": "2026-03-19",
"spec": "https://ucp.dev/2026-01-23/specification/catalog",
"schema": "https://ucp.dev/2026-01-23/schemas/shopping/catalog.json"
}
],
"dev.ucp.shopping.order": [
{
"version": "2026-03-19",
"spec": "https://ucp.dev/2026-01-23/specification/order",
"schema": "https://ucp.dev/2026-01-23/schemas/shopping/order.json"
}
]
},
"payment_handlers": {
"stripe": {
"type": "redirect"
}
}
}
}The manifest is the contract. Keep capability versions current and only declare surfaces you have actually wired. Agents punish stale or aspirational declarations quickly.
Implementation steps
Publish the spec-compliant manifest
Add a route that serves the manifest at /.well-known/ucp. If your platform now offers a Merchant Center or dashboard toggle, enable that first, then inspect the actual manifest output before you trust it.
app.get('/.well-known/ucp', (req, res) => {
res.json({
name: "My Store",
url: "https://store.com",
ucp: {
version: "2026-03-19",
capabilities: {
"dev.ucp.shopping.checkout": [{ version: "2026-03-19" }],
"dev.ucp.shopping.cart": [{ version: "2026-03-19" }],
"dev.ucp.shopping.catalog": [{ version: "2026-03-19" }]
}
}
});
});Wire catalog and checkout first
The fastest path is usually checkout first, then catalog, then cart. Catalog is what lets AI agents browse your full inventory. Cart is what removes checkout friction. Order and identity linking can come after the public commerce loop is stable.
Level 1: Present
- Valid manifest at /.well-known/ucp
Level 2: Transactional
- dev.ucp.shopping.checkout
Level 3: Full Commerce
- dev.ucp.shopping.cart
- dev.ucp.shopping.catalog
Level 4: Personalized
- dev.ucp.common.identity_linkingAdd platform-specific capability wiring
Shopify and Salesforce may expose native or partner-managed UCP surfaces over time. WooCommerce typically maps these capabilities onto existing REST endpoints. Custom stacks still need to host the manifest and wire each capability explicitly.
Platform map: Shopify and Salesforce: check the current platform docs or partner integrations before assuming a native toggle exists. WooCommerce: use a UCP plugin or map the manifest to existing REST surfaces.
Verify with Colter
Run colter check once the manifest and endpoints are live. Colter Check validates the UCP manifest, endpoint availability, and the surrounding discovery stack.
colter check yourstore.comFix failures, rerun, and keep going until Colter shows the capability breakdown you expect. If you have checkout but not cart or catalog, you are close. Colter will show readiness percentages for each missing capability so you can prioritize the shortest path to Level 3.
Common issues
Manifest returns 404
Ensure your framework routes /.well-known/ucp correctly. Dot-prefixed paths are easy to miss.
Wrong Content-Type
Return application/json and keep the manifest parseable without redirects or HTML wrappers.
Capability keys use old flat names
Use dev.ucp.* reverse-domain keys under ucp.capabilities. Legacy flat arrays still get parsed by Colter, but the current spec expects namespaced capability objects.
CORS blocking agent requests
If agents call your endpoints cross-origin, allow the required methods and origins explicitly.
Endpoints require hidden auth assumptions
Product listing and manifest routes should be public. Cart and checkout can require session state, but the requirements need to be explicit.
Capability version is stale
Update the capability version dates and spec/schema URLs when the UCP spec moves. Colter flags capabilities that are more than six months behind the latest baseline.
Ongoing verification
UCP can regress after deploys, API changes, or infrastructure updates. Keep verification in CI and treat the manifest like production surface area, not documentation.
- name: Verify UCP compliance
run: |
npx colter check yourstore.com --ci --threshold 60Your store is already being evaluated by agents
Run a Colter Check to validate your UCP stack and see how the rest of the storefront scores across 30+ signals.
See What Agents See