UCP configuration
What this gives you: Firmly hosts a UCP (Universal Commerce Protocol) version of your store — a machine-readable commerce surface that AI agents can discover and buy from. You don’t build or maintain UCP yourself: Firmly generates your UCP manifest, answers agent requests, and translates them to your platform behind the scenes. All you do here is point one well-known path — /.well-known/ucp — on your domain at Firmly, then verify it.
For the conceptual background on UCP itself, see Protocols → UCP overview.
The forwarding pattern
Your domain needs to forward /.well-known/ucp requests to Firmly’s hosted UCP endpoint, with an x-firmly-host header set to your own domain:
| Source | Destination |
|---|---|
https://<merchant-domain>/.well-known/ucp |
https://api.firmly.work/.well-known/ucp |
The page walks you through doing this on the platform you’re already on.
Three “What is UCP?” anchors
Above the setup steps, the page summarizes why this exists in three cards:
| Card | Summary |
|---|---|
| Commerce Discovery | A standardized way for agents to discover product data and capabilities |
| AI-Ready | Machine-readable metadata so agents don’t need a custom integration per merchant |
| Secure by Design | Firmly handles auth and abuse mitigation on the well-known endpoint |
Platform-specific setup guides
A dropdown picks the merchant’s edge platform; the steps below it rewrite for that platform:
| Platform | Setup pattern |
|---|---|
| Cloudflare | Worker script intercepting /.well-known/ucp and forwarding with the x-firmly-host header; Worker route assigned in the dashboard |
| Akamai | Origin server pointing to api.firmly.work, path-based rule that injects the x-firmly-host header |
| Fastly | Backend pointing to api.firmly.work, VCL snippet in vcl_recv that sets the backend and the x-firmly-host header on matching requests |
| CloudFront (AWS) | Origin + cache behavior + Lambda@Edge / CloudFront Function to add the header |
Your own domain is interpolated into the code blocks (x-firmly-host: <domain>) so you can copy-paste without editing. Each code / config block has a copy button.
Verification probe
After applying the configuration, you click Verify Configuration. Firmly sends a probe to https://<domain>/.well-known/ucp and checks that your edge forwarded the request with the correct x-firmly-host header and returned Firmly’s UCP manifest.
| Outcome | What happens |
|---|---|
| Success | The page flips into a “Verified by … at …” state and the verification status is recorded server-side |
| Failure | The page surfaces an error pointing you to the most likely misconfigurations |
Once verified — you’re discoverable
A successfully verified UCP endpoint is what makes your store findable to agents on Firmly’s network — without it, agents can’t auto-discover your commerce capabilities.
Role gating
| Action | Who can do it |
|---|---|
| Run verification | Owner, Primary Owner, Firmly admin |
| View configuration | Any role |
Lower roles see the page read-only.
Related
- Protocols → UCP overview — what UCP is
- Protocols → UCP merchant onboarding — Google Merchant Center side of the setup
- Domains and SSO — domain verification (a prerequisite)
- Audit logs — UCP verification events logged here