UCP Technical Implementation
It's Your Store's Front Door for AI Agents
The `/.well-known/ucp` endpoint is where AI shopping assistants go to find out if your store speaks their language. Think of it as the "hours posted on the door" for robots.
How AI Agents Use It
When an AI wants to shop at your store, here's what happens:
- AI makes a request to `https://yourdomain.com/.well-known/ucp`
- Your server returns a JSON file with your store info and capabilities
- AI reads it and knows: "OK, this store does checkout and order tracking"
- AI proceeds to interact with your store using those capabilities
If that file isn't there or doesn't work? The AI assumes you don't support AI shopping and moves on. No second chances.
Why That Exact Location?
The `/.well-known/` directory is a web standard (IETF RFC 8615) used for discovery files. You've probably seen others:
- `/.well-known/security.txt` - Security contact info
- `/.well-known/change-password` - Password reset flow
- `/.well-known/apple-app-site-association` - iOS app links
AI agents don't guess. They don't search. They check that ONE exact location. If it's not there, game over.
What Makes It Valid
Your `/.well-known/ucp` endpoint must return:
- Valid JSON matching the UCP manifest schema
- Correct header: `Content-Type: application/json`
- HTTP 200 status (not 404, not 500)
- CORS headers allowing cross-origin requests
- No authentication required to access it
Miss even one of these and AI agents treat your store as non-compliant.
Common Mistakes That Kill Discovery
Wrong location:
- ❌ `/ucp` (missing .well-known)
- ❌ `/.well-known/ucp.json` (don't add .json)
- ❌ `/api/ucp` (wrong path entirely)
- ✅ `/.well-known/ucp` (exact match only)
Wrong response:
- ❌ Returns HTML instead of JSON
- ❌ Returns 404 or 500 error
- ❌ Requires login to access
- ❌ Missing CORS headers (AI gets blocked)
Think of It Like Your Store Hours Sign
If you run a physical store, you post hours on the door so customers know when you're open. They don't call you, they don't guess—they just check the sign.
The `/.well-known/ucp` endpoint is the same thing for AI agents. It tells them: "Yes, I'm open for AI shopping. Here's how to interact with me."
No sign on the door? AI agents assume you're closed and go to the next store.
Platform-Specific Challenges
Easy platforms: WooCommerce, custom builds—you control file system
Tricky platforms: Shopify, Wix, Squarespace—no direct file access
That's why managed solutions exist—they handle the platform-specific quirks so you don't have to hack around limitations.
Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.
Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.