Loading…
Docs
Learn how to set up UCP capability discovery endpoints to allow AI agents to discover your commerce capabilities.
Last updated: February 3, 2026
This content is based on official sources and ecosystem developments:
The .well-known/ucp endpoint allows AI agents to discover your UCP capabilities without prior knowledge of your implementation.
Create .well-known/ucp (or .well-known/ucp.json) with:
{
"version": "1.0",
"capabilities": {
"product_catalog": {
"endpoint": "https://yourdomain.com/ucp/products",
"format": "json",
"version": "1.0"
},
"checkout": {
"endpoint": "https://yourdomain.com/ucp/checkout",
"supported_methods": ["POST"],
"version": "1.0"
},
"shipping": {
"endpoint": "https://yourdomain.com/ucp/shipping",
"supported_methods": ["POST"],
"version": "1.0"
}
}
}
{
"version": "1.0",
"capabilities": {
"product_catalog": {
"endpoint": "https://example.com/api/ucp/products"
},
"checkout": {
"endpoint": "https://example.com/api/ucp/checkout"
}
}
}
{
"version": "1.0",
"capabilities": {
"product_catalog": {
"endpoint": "https://example.com/api/ucp/products",
"format": "json",
"supports_search": true,
"supports_filters": ["category", "price", "availability"]
},
"checkout": {
"endpoint": "https://example.com/api/ucp/checkout",
"supported_methods": ["POST"],
"requires_authentication": false
},
"shipping": {
"endpoint": "https://example.com/api/ucp/shipping",
"supported_methods": ["POST"]
},
"orders": {
"endpoint": "https://example.com/api/ucp/orders",
"supported_methods": ["GET", "POST"]
}
}
}
Problem: File not accessible at .well-known/ucp
Solution: Ensure .well-known directory is in web root and accessible via HTTP.
Problem: JSON syntax errors prevent parsing
Solution: Validate JSON before deploying. Use a JSON validator.
Problem: AI agents can't discover products or checkout
Solution: Always include product_catalog and checkout capabilities.
Problem: Endpoints return 404 errors
Solution: Verify endpoint URLs are correct and accessible.
curl https://yourdomain.com/.well-known/ucp
Test each endpoint listed in capabilities:
curl https://yourdomain.com/ucp/products
curl -X POST https://yourdomain.com/ucp/checkout