UCP Well Known Manifest Configuration: 11 Key Settings

Last quarter a mid-market apparel brand asked us why an AI shopping agent kept skipping their catalog while sending buyers to a smaller competitor. Their products were priced well, their inventory was healthy, and their Shopify theme scored fine on Core Web Vitals. The problem was invisible to human eyes: their `/.well-known/ucp.json` manifest returned a 200 status but shipped a malformed capabilities block, a stale endpoint URL, and no signature. Every agent that fetched it silently discarded the store as untrusted. For three weeks they lost agentic traffic and never saw a single error in their own logs, because the failure lived in a file most teams never open. That is the quiet risk of getting your UCP well known manifest configuration wrong, and it is exactly what this guide exists to fix.

We ship manifest configurations for merchants every week, and the same handful of settings account for most of the failures we see. Below are the 11 configuration settings that matter most, ordered by impact, followed by a repeatable framework, the KPIs we track at 30, 60, and 90 days, and answers to the questions we get asked in every onboarding call. If you are new to the standard itself, start with our definitive guide to what UCP is and then come back here to configure it properly.

TL;DR

Placement and reachability first: A correct UCP well known manifest configuration begins with serving a valid JSON document at `/.well-known/ucp.json` over HTTPS with a 200 status, correct content type, and permissive CORS, because agents abandon anything they cannot fetch cleanly.
Signatures and capabilities are non-negotiable: The two settings that most often separate a discovered store from an ignored one are a valid cryptographic signature and an accurate capabilities declaration that matches what your checkout can actually do.
Validation is a caveat, not a finish line: According to UCP Checker, roughly 71% of the storefronts it tracks pass full UCP validation, but a conformant manifest is not the same as an agent completing a real checkout, so you must test end to end, not just lint the file.

1. Correct Manifest Placement at the Well-Known Path

The single most common failure we see is a manifest served from the wrong location. UCP well known manifest configuration mandates that the document live at exactly `https://yourdomain.com/.well-known/ucp.json`, with no redirect chains, no trailing path variation, and no subdomain drift. Agents follow the RFC 8615 well-known convention rigidly, so a file parked at `/ucp.json` or `/manifest/ucp.json` will never be discovered, even if it is perfectly formed.

Placement sounds trivial until you account for how CDNs and reverse proxies rewrite paths. We routinely find stores where the well-known directory is intercepted by an ACME challenge handler for TLS certificates, or where a caching layer serves a 301 to a marketing landing page. Every hop you add is a chance for an agent to bail. Test the raw path with a plain `curl -I` and confirm you get a `200 OK` on the first request, not a redirect.

Placement precision: Serve the file at the literal `/.well-known/ucp.json` path with zero redirects and confirm reachability from outside your own network, not just from a logged-in admin session.

Best for: Any team that has never actually fetched their own manifest from an anonymous client, which is most teams.

2. A Valid, Machine-Parseable JSON Structure

A manifest that returns 200 but fails to parse is functionally invisible. The second setting in any solid UCP well known manifest configuration is strict, schema-valid JSON: no trailing commas, no comments, no BOM characters, and UTF-8 encoding throughout. Agents do not forgive sloppy JSON the way a browser forgives sloppy HTML. One stray comma and the entire document is discarded.

We treat the manifest as a build artifact, not a hand-edited file. Generate it programmatically, validate it against the published UCP schema in CI, and fail the deploy if it does not parse. This is the same discipline you would apply to a product feed, and for good reason: the machine-readable manifest is the agentic equivalent of your product data layer. Our piece on how UCP changes SEO, feeds, and product data explains why this file now sits at the center of discovery.

Structure validation: Run the manifest through a JSON schema validator on every deploy and block releases that produce invalid output, because a single syntax error silently removes you from every agent’s index.

Standout feature: Programmatic generation means your manifest can never drift out of sync with your live catalog and endpoints.

3. Accurate Capabilities Declaration

The capabilities block tells agents what your store can actually do: browse, search, add to cart, checkout, refund, subscribe, and so on. This is where UCP well known manifest configuration most often lies to agents by accident. A team copies a template that declares `full_checkout` support, but their backend only handles cart creation and hands off to a hosted payment page the agent cannot drive. The agent trusts the declaration, attempts a checkout, fails, and downranks the store.

Declare only what you can prove. If your checkout requires a human to complete a redirect, do not advertise autonomous checkout. Under-declaring is far safer than over-declaring, because an honest, narrow capabilities set still gets you discovered, whereas a false claim gets you blacklisted after the first failed transaction. The relationship between accurate capabilities and real conversions is something we dig into in our analysis of agentic commerce conversion rate under UCP.

Capabilities honesty: List only the operations your checkout can complete end to end without human intervention, and verify each declared capability against a live transaction test.

Best for: Merchants transitioning from a redirect-based checkout who need to expose partial capabilities without overpromising.

4. A Valid Cryptographic Signature

Signatures are what turn a manifest from a claim into a verifiable identity. A well-configured manifest includes a cryptographic signature (typically JWS or an equivalent detached signature referencing a key you publish) so agents can confirm the document has not been tampered with in transit. Unsigned manifests are increasingly treated as second-class or rejected outright by security-conscious agents.

We have seen more discovery failures traced to signatures than to almost anything else, because the signing key expires, the key rotation breaks the reference, or the signature is computed over a version of the JSON that no longer matches what is served. The signature must cover the exact bytes delivered. If your CDN minifies or re-serializes the JSON after signing, the signature breaks. Sign last, serve exactly what you signed.

A conformant UCP manifest gets you seen, but only an honest, signed, end-to-end-tested one gets you bought from.

Signature integrity: Compute the signature over the final serialized bytes, publish your public key at a stable URL, and monitor key expiry at least 30 days before it lapses.

Standout feature: A valid signature is what unlocks trust tiers with agents that refuse to transact against unsigned stores.

5. Correct Endpoint URLs and Versioned API Base

The manifest points agents to the endpoints where the real work happens: catalog queries, cart operations, checkout, and order status. Every one of these URLs must be absolute, HTTPS, and live. A stale endpoint from a previous environment is the second-most-common silent failure we find, right behind wrong placement. The agent parses your manifest cleanly, then hits a 404 or a dead staging URL, and gives up.

Version your API base explicitly in the manifest so agents know which contract they are speaking. When you ship a breaking change, you can run the old and new versions in parallel and update the manifest to point at the new base only when it is fully live. This is standard practice in the UCP technical architecture, and it prevents the whole-catalog outages that come from swinging every agent to an untested endpoint at once.

Endpoint hygiene: Confirm every URL in the manifest returns the expected response from an external client, and never ship a manifest that references a staging or localhost host.

Best for: Teams running multiple environments where staging URLs leak into production configs.

6. Precise Content-Type and Caching Headers

Headers are configuration too, and they are easy to overlook because the JSON itself looks fine. Serve the manifest with `Content-Type: application/json` (some agents also accept a UCP-specific media type, which you should add if your version supports it). Serving it as `text/html` because your server guessed the type from a missing extension will cause strict parsers to reject it.

Caching deserves equal care. Set a `Cache-Control` header that balances freshness against load: we typically recommend a `max-age` between 300 and 3600 seconds depending on how often your capabilities or endpoints change. Too aggressive and agents act on stale data after you fix a problem; too loose and you take unnecessary origin traffic on every fetch. Pair caching with an `ETag` so agents can revalidate cheaply.

Header correctness: Serve the manifest as `application/json` with a `Cache-Control` of 300 to 3600 seconds and an ETag, so agents get fresh data without hammering your origin.

Standout feature: A tuned ETag lets high-frequency agents revalidate in a single conditional request instead of a full re-download.

7. Permissive and Correct CORS Configuration

Many agents fetch your manifest from browser-based or sandboxed contexts that enforce CORS. If your server omits `Access-Control-Allow-Origin` or scopes it too narrowly, those agents cannot read the file at all, and you will see a discovery gap that never appears in your server logs as an error. This is one of the sneakiest problems in UCP well known manifest configuration because the request succeeds server-side and fails only in the client.

For the manifest specifically, a permissive `Access-Control-Allow-Origin: *` is generally appropriate, because the well-known manifest is public discovery data by design. Reserve tighter CORS policies for your authenticated transactional endpoints, not the public manifest. Test with an actual cross-origin request, not just a `curl` from the same host, because `curl` ignores CORS entirely and will happily hide the problem.

CORS coverage: Return `Access-Control-Allow-Origin: *` on the public manifest and verify it with a genuine cross-origin fetch, since same-host tools mask CORS failures completely.

Best for: Stores whose manifests validate in CLI tools but still fail to appear in browser-based agent environments.

8. Rich Product and Catalog Metadata Hooks

The manifest is the entry point, but the value it unlocks is your catalog. A strong configuration includes the hooks agents need to reach structured product data: the search endpoint, pagination contract, filtering vocabulary, and the fields you expose per product. Agents that can filter by size, price band, availability, and shipping speed convert dramatically better than agents forced to fetch and parse everything.

We advise merchants to expose canonical identifiers (GTIN, MPN, or a stable SKU) in the data agents reach through the manifest, because that is how agents deduplicate the same product across marketplaces and decide whether you are the cheapest trustworthy seller. When AI agents become the primary shoppers, the depth and cleanliness of this metadata is the difference between being a considered option and being noise, a shift we cover in what happens when AI agents become the primary shoppers.

Metadata depth: Expose canonical product identifiers and a documented filtering vocabulary through the manifest’s catalog hooks, because agents reward stores that let them narrow results precisely.

Standout feature: Clean canonical IDs let agents match your listing to price-comparison intents and surface you at the exact moment of decision.

Make Your Manifest Agent-Ready with UCPhub

Getting every one of these settings right by hand, and keeping them right through catalog changes, key rotations, and API versioning, is exactly the work our platform automates. UCPhub’s Universal Commerce Protocol implementation generates, signs, validates, and monitors your well-known manifest continuously, so agents see an accurate, trusted store every time they fetch it rather than the silent failures that cost that apparel brand three weeks of traffic. If you would rather ship a correct configuration once and have it stay correct, talk to our team about a managed UCP rollout. You can also compare the tradeoffs in our UCP hub vs custom integration comparison before you decide.

9. Authentication and Session Handshake Settings

Once an agent decides to transact, it needs to know how to authenticate. The manifest declares the auth scheme your transactional endpoints expect: OAuth-style token exchange, delegated payment authorization, or a scoped API handshake. Misconfiguring this section is where discovery success turns into checkout failure, because the agent found you, trusted you, chose you, and then could not complete the handshake.

Declare the exact grant types and scopes you support, and make sure the token endpoint URL in the manifest matches your live auth server. We see teams rotate an auth secret or migrate identity providers without updating the manifest, which quietly severs the checkout path. Treat the auth declaration as a first-class part of your deploy checklist, not an afterthought bolted on when transactions start failing.

Auth accuracy: Declare only the auth schemes your live endpoints accept, keep the token endpoint URL in lockstep with your identity provider, and re-test the full handshake after any auth migration.

Best for: Merchants who have discovery working but see agents abandoning at the point of authentication.

10. Localization, Currency, and Region Declarations

Agents shop globally, and they need to know which markets you serve before they route a buyer to you. A complete UCP well known manifest configuration declares supported currencies, shipping regions, supported languages, and any region-specific capability differences. An agent shopping for a buyer in Germany will skip a store that cannot price in EUR or ship to the EU, and it makes that decision from your manifest, not by attempting a checkout and failing.

Be honest about regional capability variance. If autonomous checkout works in your home market but requires manual review for cross-border orders, declare that difference rather than presenting a uniform capability set. Agents that hit an unexpected regional block downrank the store for everyone, not just the blocked region. Precision here protects your standing globally.

Region clarity: List supported currencies, shipping regions, and languages explicitly, and flag any market where your capabilities differ so agents route only buyers you can actually serve.

Standout feature: Accurate region data gets you surfaced to international buyers you would otherwise never appear for.

11. Continuous Validation and Change Monitoring

The final setting is not a field, it is a discipline: monitor the manifest continuously after you ship it. Manifests rot. Endpoints move, keys expire, capabilities drift as your checkout evolves, and a config that was perfect at launch quietly breaks three months later. The apparel brand we opened with had a manifest that passed validation on the day it went live and degraded silently afterward.

Set up automated fetching from an external vantage point that checks placement, parse validity, signature, endpoint liveness, and capability accuracy on a schedule, and alert when any of them fail. According to UCP Checker, which independently monitors 16,171-plus storefronts, roughly 71% pass full UCP validation, but that figure skews heavily to Shopify and, more importantly, a conformant manifest is not the same as an agent completing a real checkout. So monitor the manifest and run periodic live transaction tests. Validation tells you the file is well-formed; only an end-to-end test tells you an agent can actually buy from you.

Ongoing monitoring: Fetch and validate the manifest from an external client on a fixed schedule, alert on any regression, and pair validation with periodic live checkout tests because passing the schema is not proof of a working purchase.

Best for: Every store, because the failure mode here is silence, not an error you would otherwise catch.

The SIGNED Framework for UCP Manifest Configuration

We use a repeatable five-step framework internally so nothing gets skipped. We call it SIGNED, and each step builds on the last.

Step 1, Serve: Place the manifest at the literal well-known path over HTTPS with correct headers and CORS. What this achieves: It guarantees any agent, from any context, can reach and read the file on the first request without redirects or type mismatches.

Step 2, Inventory: Enumerate your true capabilities, endpoints, auth schemes, and regions before writing a single line of JSON. What this achieves: It forces honesty up front so you declare what you can deliver rather than copying a template that overpromises.

Step 3, Generate: Build the manifest programmatically from that inventory and validate it against the UCP schema in CI. What this achieves: It eliminates hand-editing errors and keeps the file in permanent sync with your live systems.

Step 4, Notarize: Sign the final serialized bytes and publish your public key at a stable URL. What this achieves: It converts your manifest from an unverifiable claim into a trusted, tamper-evident identity that security-conscious agents will transact against.

Step 5, Enforce, Detect: Deploy, then monitor placement, parse, signature, endpoints, and live checkout on a schedule with alerting. What this achieves: It catches the silent rot that turns a perfect launch-day config into an invisible store three months later.

Configuration discipline checklist:

Serve first: Confirm 200, HTTPS, correct content type, and open CORS before anything else.
Inventory honestly: Declare only capabilities you can complete end to end.
Generate in CI: Never hand-edit the production manifest.
Notarize the exact bytes: Sign what you serve, serve what you signed.
Detect continuously: Alert on regressions and run live checkout tests, not just schema validation.

Measuring Success: 30, 60, and 90 Day KPIs

A manifest is worth configuring only if it moves numbers. Here is what we track, and when we expect to see it.

30-day outcomes:

Discovery rate: Confirm your manifest is fetched by external validators and at least one production agent, targeting a verified fetch within the first week of launch.
Validation pass: Achieve a clean pass on placement, JSON parse, signature, and endpoint liveness across every scheduled external check, aiming for 100% uptime on the file itself.
Error visibility: Establish alerting so that any manifest regression pages a human within 15 minutes rather than surfacing three weeks later.

60-day outcomes:

Agent traffic share: Measure the percentage of sessions or catalog fetches originating from agents, and confirm a steady upward trend as more agents index your manifest.
Checkout success on agent traffic: Track the completion rate of agent-initiated checkouts and target parity with your human checkout completion within this window.
Capability accuracy: Verify zero failed transactions attributable to over-declared capabilities, which signals your inventory step was honest.

90-day outcomes:

Agentic conversion contribution: Attribute a measurable share of revenue to agent-driven purchases and compare it against your baseline before manifest configuration.
Region reach: Confirm agents are routing international buyers to you in markets you declared, validating your localization settings.
Manifest stability: Report on the number of regressions caught and remediated automatically, targeting near-zero unplanned discovery downtime across the quarter.

Getting Started and Auditing an Existing Setup

If you are configuring a UCP well known manifest for the first time, prioritize the fundamentals in order: get the file served correctly at the well-known path, make it parse, then sign it. Those three settings alone move you from invisible to discoverable, and everything else layers on top. Resist the urge to copy a maximal capabilities template; an honest, narrow declaration that works beats a broad one that fails on first contact. If instead you are auditing something already live, start at the end of this list rather than the beginning: assume the file rotted, fetch it from an external client, verify the signature and endpoint liveness first, and only then dig into capability accuracy and region declarations, because silent regressions are almost always in the parts nobody has touched since launch.

Next Steps:

Fetch your own manifest anonymously right now with a plain external request and confirm you get a signed, valid, 200 response from the literal well-known path.
Compare your declared capabilities against a real end-to-end agent checkout and remove anything you cannot actually complete.
Set up external scheduled monitoring with alerting, or talk to our team about a managed configuration that stays correct automatically.

Frequently Asked Questions

How do I configure the UCP well known manifest properly?

Proper configuration starts with placement and works outward. Serve a schema-valid JSON document at exactly `https://yourdomain.com/.well-known/ucp.json` over HTTPS, returning a 200 status with `Content-Type: application/json`, permissive CORS, and sensible caching headers. That gets you readable. Then declare only the capabilities, endpoints, auth schemes, and regions you can genuinely deliver, and sign the final serialized bytes with a published key so agents can verify the document.

The most important discipline is to generate the manifest programmatically and validate it in CI rather than hand-editing production. Hand-edited files drift out of sync with your live catalog and endpoints, which is the root cause of most silent failures we see. If you want the full picture of how the manifest fits into the broader standard, our what is UCP definitive guide sets the context, and beginners will find the simple guide to the future of shopping a gentler on-ramp.

What are the configuration steps for the UCP well known manifest?

Follow the five-step SIGNED sequence: Serve the file correctly, Inventory your true capabilities and endpoints, Generate the JSON programmatically and validate it in CI, Notarize it with a signature over the exact served bytes, then Enforce and Detect through continuous monitoring and live checkout tests. Each step is a gate; do not proceed until the previous one passes cleanly.

The reason the order matters is that failures cascade. If placement is wrong, no agent ever reaches your capabilities, so validating capabilities first wastes effort. If your signature is computed over a pre-minification version of the JSON, agents reject the whole document regardless of how accurate your capabilities are. Working outward from reachability to trust to accuracy to monitoring keeps you from debugging the wrong layer.

What settings do I need for the UCP well known manifest configuration?

At minimum you need seven things configured correctly: the well-known path placement, valid UTF-8 JSON structure, an accurate capabilities block, a valid cryptographic signature, live and versioned endpoint URLs, correct content-type and CORS headers, and continuous monitoring. Beyond that minimum, add rich catalog metadata hooks, an accurate auth handshake declaration, and localization and region settings to compete for international and complex transactions.

Think of the first seven as the settings that determine whether you exist to agents at all, and the last few as the settings that determine how well you compete once you do. A store with only the minimum is discoverable and transactable; a store with the full set is preferentially surfaced, especially across regions and price-comparison intents. Our deep dive into the UCP technical architecture details how these settings map to the underlying endpoints.

Does a passing validation score mean agents can buy from my store?

No, and this is the caveat we repeat most often. Validation confirms your manifest is well-formed, correctly placed, signed, and points at reachable endpoints. It does not confirm that an agent can complete a real purchase. According to UCP Checker, which monitors more than 16,171 storefronts, roughly 71% pass full validation, but that population skews heavily toward Shopify and passing the schema is not the same as a completed checkout.

The gap usually lives in over-declared capabilities or a broken auth handshake: the file validates, the agent trusts it, then the transaction fails at authentication or at a checkout step the store cannot actually complete autonomously. That is why our framework ends with live end-to-end checkout tests, not schema validation. You have to prove an agent can pay, not just prove the file is valid.

How is the UCP manifest different on Shopify versus WooCommerce?

The manifest specification is platform-neutral, but how you serve and generate it differs. On Shopify, the well-known path and manifest generation are typically handled through an app or platform integration, and the main risks are stale endpoints from theme or app changes and CORS or redirect interference from Shopify’s infrastructure. Our Shopify UCP integration guide walks through those specifics.

On WooCommerce you have more direct control over the server and therefore more responsibility for placement, headers, and signing, which is powerful but easier to misconfigure. WooCommerce stores also face a higher risk of falling behind simply because the tooling is less turnkey, a gap we cover in why WooCommerce stores risk falling behind without UCP and in the broader WooCommerce UCP integration guide. In both cases the settings that matter are identical; only the mechanics of getting them right change.

How often should I re-validate my manifest after launch?

Continuously, with automated external checks. We recommend a scheduled fetch and validation at least every few minutes for placement, parse, and signature, since those are cheap to check and catastrophic when broken. Endpoint liveness and capability accuracy can be checked less frequently, hourly is reasonable, and a full live checkout test at least daily. Set alerting so any regression reaches a human within 15 minutes rather than surfacing weeks later through lost traffic.

Manual, occasional checks are not enough because the failure mode is silence. A signing key expires on a Tuesday, and nothing in your own dashboards changes; your agent traffic just quietly stops. The whole point of continuous validation is to convert an invisible three-week outage into a 15-minute alert. This is the difference between a point-in-time configuration and a durable one, a theme we explore in why point solutions won’t scale.

Should I worry about UCP versus ACP when configuring my manifest?

Configure for the standard your target agents actually use today, and design so you can support both without a full rewrite. The manifest fundamentals, correct placement, valid structure, signatures, honest capabilities, are broadly similar in spirit across competing standards, so getting your inventory and endpoints clean pays off regardless of which standard wins. The strategic question of which will dominate is worth understanding, though, because it affects where you invest declaration effort.

We lay out the competitive landscape in UCP vs ACP: which standard will rule the agentic web and in the companion piece on the battle for the agentic commerce standard. Our practical advice: configure a correct UCP manifest now, because it is live and being fetched, and keep your capability inventory abstracted enough that adding a second standard’s manifest is a serving task, not a rebuild.