Well-Known Manifest UCP Example: Hand vs Auto 2026

TL;DR

Two paths, same endpoint: Every conformant well-known manifest UCP example lives at the same URL, but a hand-written manifest gives you control and a generated one gives you speed; we recommend generated-first for most merchants and hand-written for anyone with non-standard checkout logic.
Validation is not the finish line: According to UCP Checker, which independently monitors 20,886+ storefronts, roughly 78% pass full UCP validation, but a conformant manifest is not the same as an agent completing a real checkout, and we have watched that gap sink launches.
Structure decides everything downstream: Getting the endpoints, capabilities, and auth blocks right in your manifest is what determines whether an AI agent can discover, price, and buy from you, so treat the file as production infrastructure, not metadata.

We got a call last quarter from a merchant whose UCP integration had been “live” for eleven days. Their manifest validated green in every linter they tried. The problem: no agent had ever completed a purchase, and nobody could say why. When we pulled their `/.well-known/ucp.json`, the file was technically perfect and functionally useless. It advertised a checkout capability that pointed at a staging endpoint someone had forgotten to update. This is the exact trap a good well-known manifest UCP example is supposed to help you avoid, and it is why the choice between hand-writing that file and auto-generating it matters more than most teams realize.

This article is a head-to-head comparison of the two ways we build the UCP well-known manifest for clients: writing it by hand with full control over every field, versus generating it from a platform or tool that reads your catalog and emits the file for you. We will show you a real, complete well-known manifest UCP example, break down what each field does, and give you a decision framework mapped to specific merchant profiles. If you are still deciding whether to adopt the protocol at all, our definitive guide to what UCP is covers the fundamentals; here we assume you are committed and now need the file itself to be correct.

The Two Approaches at a Glance

Before we go deep, here is how the two approaches compare across the criteria that actually decide outcomes in production. We built this table from the patterns we see repeatedly across implementations, not from spec theory.

Criterion	Hand-Written Manifest	Auto-Generated Manifest
Time to first valid file	3 to 8 hours	10 to 30 minutes
Control over field granularity	Full, every capability tunable	Limited to what the generator exposes
Risk of stale endpoints	High, humans forget to update	Low, regenerated on deploy
Non-standard checkout support	Excellent	Poor to moderate
Ongoing maintenance burden	You own every change	Platform owns most changes
Handles catalog scale (10k+ SKUs)	Painful	Native
Best for	Custom stacks, unusual auth	Shopify, WooCommerce, standard flows
Failure mode	Drift and human error	Opaque generator assumptions

The short version of our take: most merchants should start with an auto-generated manifest and only move to hand-editing when a generator cannot express something their business actually needs. But that recommendation has real exceptions, and the rest of this article is about knowing which camp you are in.

What a Well-Known Manifest UCP Example Actually Looks Like

Let us get concrete immediately, because a comparison is useless without the thing being compared. Here is a complete, working well-known manifest UCP example, the kind we deploy for a mid-sized merchant with a standard product catalog and a single checkout flow. This file lives at `https://yourstore.com/.well-known/ucp.json`.

{ "ucp_version": "1.0", "merchant": { "id": "urn:ucp:merchant:yourstore", "name": "Your Store", "legal_entity": "Your Store LLC", "contact": "commerce@yourstore.com" }, "endpoints": { "catalog": "https://api.yourstore.com/ucp/v1/catalog", "pricing": "https://api.yourstore.com/ucp/v1/pricing", "checkout": "https://api.yourstore.com/ucp/v1/checkout", "order_status": "https://api.yourstore.com/ucp/v1/orders/{order_id}" }, "capabilities": { "discovery": true, "real_time_pricing": true, "cart_creation": true, "checkout": true, "returns": false, "subscriptions": false }, "auth": { "type": "oauth2", "token_endpoint": "https://auth.yourstore.com/ucp/token", "scopes": ["catalog:read", "checkout:write"] }, "fulfillment": { "regions": ["US", "CA"], "currencies": ["USD", "CAD"], "shipping_available": true }, "policies": { "returns_url": "https://yourstore.com/returns", "privacy_url": "https://yourstore.com/privacy", "terms_url": "https://yourstore.com/terms" }, "updated_at": "2026-01-15T09:00:00Z" }

That is the whole thing, and it is deliberately not enormous. A well-known manifest UCP example that sprawls across hundreds of lines is usually a sign someone is stuffing catalog data into a discovery file, which is the wrong layer. The manifest is a signpost, not a warehouse. It tells an agent where to go and what you support, then the agent hits your endpoints for the actual data. If you want the architecture reasoning behind that separation, our technical architecture deep dive walks through why the protocol splits discovery from execution.

Now, the same merchant could arrive at that identical file two ways. One team writes it by hand in a text editor, commits it, and deploys. Another team runs a generator against their store, and the tool emits it. Same output, very different tradeoffs, and those tradeoffs are what we compare next.

Field-level checklist for any manifest, regardless of how you produce it:

ucp_version present: Never omit the version; agents branch parsing logic on it and a missing version is treated as invalid by most parsers.
Endpoints resolve to production: Every URL in the endpoints block must return a real response, not a staging or 404 target.
Capabilities match reality: If capabilities.checkout is true, the checkout endpoint must actually accept and complete orders end to end.
Auth block is complete: The token_endpoint and scopes must correspond to a live auth server the agent can reach.
updated_at is honest: Stamp the real deploy time so agents and monitors can detect staleness.

Hand-Written UCP Manifests: Strengths and Weaknesses

Writing the manifest by hand means one of your engineers owns the file directly. Every field is a deliberate decision, committed to your repo, versioned in Git, reviewed in a pull request. We build hand-written manifests for clients whose commerce stack does something a generator cannot anticipate, and in those situations it is clearly the right call.

Full control over capability declarations: When we work with a merchant who supports partial fulfillment, region-specific pricing, or a checkout that requires a pre-authorization step, we need to express that precisely. A hand-written manifest lets us set exactly which capabilities are true and shape the endpoints block to route agents through the correct flow. Generators, in our experience, tend to flatten these into a lowest-common-denominator representation that either overpromises or underpromises what the store can do.

Auditability and change history: Because the file lives in version control, every change is attributable. When something breaks, we can `git blame` the manifest and see who changed the checkout endpoint and when. That traceability has saved us on more than one incident where a “harmless” config change silently redirected agent traffic.

The weakness is real, though, and it is the failure mode we opened this article with. Drift is the enemy: Humans forget. Someone spins up a new pricing service, updates it everywhere except the manifest, and now agents are quoting stale prices for three days before anyone notices. A hand-written well-known manifest UCP example is only as current as the last human who remembered to touch it. We have found this is the single most common reason a technically valid manifest produces zero completed purchases.

Scale is the other problem. If your capabilities or fulfillment regions change frequently, or you operate multiple storefronts, hand-maintaining a manifest per store becomes a coordination tax nobody wants to pay.

When hand-writing is the right choice:

Non-standard checkout: Your purchase flow has steps a generator cannot model, like manual approval or B2B quotes.
Custom commerce stack: You are not on Shopify or WooCommerce and have no first-party generator available.
Strict change governance: Your org requires every production change to go through code review, and the manifest must live in that pipeline.
Low change frequency: Your capabilities and endpoints are stable and rarely move, so drift risk is naturally low.
Multi-region logic: You need per-region routing that off-the-shelf tools flatten incorrectly.

Auto-Generated UCP Manifests: Strengths and Weaknesses

The generated approach means a platform, plugin, or hub reads your existing store data and emits the manifest for you, usually regenerating it whenever your catalog or config changes. For the majority of merchants we onboard, especially those on standard platforms, this is where we start.

Speed to a valid file: A merchant on Shopify can go from nothing to a validating well-known manifest UCP example in under thirty minutes with the right integration. Compare that to the three to eight hours a careful hand-written first pass takes. Our Shopify UCP integration guide walks through exactly this path, and it is genuinely fast.

Endpoints stay current: This is the killer advantage. When the manifest regenerates on every deploy, the stale-endpoint failure mode largely disappears. The generator reads live config, so if you move your pricing service, the manifest follows automatically. For merchants who ship frequently, this eliminates the number one cause of silent failure we see.

Catalog scale is handled: A store with 40,000 SKUs and constantly shifting availability is a nightmare to represent by hand. Generators built for scale handle this natively, keeping the discovery layer thin and pointing agents at endpoints for the heavy data. The same principle we cover in the rise of machine-readable commerce applies here: the machines do the reading, so the data has to be programmatically maintained.

The weakness is opacity. Generator assumptions can bite: A tool decides how to map your store’s concepts onto UCP fields, and those decisions are sometimes invisible. We onboarded a merchant whose generator quietly marked `returns` as false because it could not detect their returns endpoint, even though returns worked fine through a different system. Agents saw “no returns” and some declined to transact. Nobody wrote that field; the tool assumed it. When you generate, you inherit the generator’s worldview, and you have to verify it against reality.

When generating is the right choice:

Standard platform: You run Shopify, WooCommerce, or another platform with a mature UCP integration.
High change frequency: Your catalog, pricing, or availability shifts daily and manual maintenance would drift instantly.
Large catalog: You have thousands of SKUs where hand-representation is impractical.
Small engineering team: You do not have bandwidth to own a manifest as production infrastructure.
Fast launch mandate: You need to be discoverable by agents this week, not this quarter.

How Do You Decide Which Approach Fits Your Store?

The honest answer we give clients is that this is not a religious question, it is a fit question. Here is the decision logic we actually use, mapped to concrete profiles rather than abstractions.

Choose auto-generated if you are a standard-platform merchant with a conventional checkout. If your store is Shopify or WooCommerce, your checkout is a normal cart-to-payment flow, and your team ships regularly, generate the manifest and let the platform keep it current. This covers, in our experience, the clear majority of merchants. The generated file will be correct, current, and low-maintenance. Pair it with our WooCommerce UCP integration guide if that is your stack.

Choose hand-written if your commerce logic is genuinely non-standard. B2B quoting, manual order approval, pre-authorization holds, multi-warehouse partial fulfillment, or a bespoke stack with no first-party generator all push you toward hand-writing. In these cases the control is worth the maintenance burden, and the drift risk is manageable because you will be reviewing the file deliberately anyway.

Choose hybrid, and this is what we increasingly deploy, if you want the best of both. Generate the baseline manifest, then apply a small set of hand-authored overrides for the two or three fields the generator gets wrong for your business. This is the pattern we lean on most for mid-market merchants: the generator handles endpoints and catalog scale, and a thin override layer corrects the capability or fulfillment fields that need human judgment.

A validating manifest is a promise; a completed agent checkout is the only proof the promise was true, and we have learned to trust the checkout, never the linter.

The context that makes this stance concrete: According to UCP Checker, which independently monitors 20,886+ storefronts, roughly 78% pass full UCP validation, which sounds like a solved problem. It is not. A conformant UCP manifest is not the same as an agent being able to complete a real checkout, and that number skews heavily to Shopify stores where generation is easy. The validation rate tells you the file parses; it tells you nothing about whether an agent can actually buy. Our entire decision framework is built around closing that gap, not celebrating the linter.

Decision checklist:

Map your checkout complexity: If it is standard, lean generated; if it is unusual, lean hand-written.
Assess change frequency: Daily changes favor generation; stable configs tolerate hand-writing.
Count your SKUs: Thousands of items push you toward generation.
Weigh your team’s bandwidth: No spare engineering time means generate.
Consider hybrid explicitly: Generate the base, hand-override the two or three fields that matter.

Ship-Ready UCP Manifest Framework: Our Four-Step Method

Whichever approach you pick, the file has to survive contact with real agents. This is the framework we run for every client, and each step exists because we have watched a launch fail without it.

Step one, Draft against the real spec. What this achieves: It gives you a manifest that parses on the first validation attempt instead of failing on version or field-name mistakes. Start from a known-good well-known manifest UCP example like the one above, set your `ucp_version`, and fill in your real merchant identity and endpoints. If you generate, this step is your generator run; if you hand-write, it is your first commit. Either way you end this step with a file that validates.

Step two, Verify every endpoint resolves live. What this achieves: It kills the stale-endpoint failure mode before it reaches production. Hit every URL in the endpoints block from outside your network and confirm each returns a real response. We do not trust a manifest until we have manually curled the catalog, pricing, and checkout endpoints and seen production data come back. This is the step the eleven-day-live merchant skipped.

Step three, Run a real agent transaction. What this achieves: It proves the promise the manifest makes, that an agent can actually discover, price, and buy. We drive an agent through discovery, cart creation, and a full checkout using a test order. If capabilities.checkout is true, the agent must complete a purchase. Passing validation here is meaningless; the only signal that counts is a completed order. This is the single most-skipped step in the whole industry, and it is why we keep repeating it.

Step four, Wire in drift monitoring. What this achieves: It catches the day your endpoints move, your capabilities change, or your generator makes a new assumption, before agents do. We monitor the live manifest against expected values and alert on any change, plus run a periodic synthetic checkout. For hand-written manifests this is essential because humans forget; for generated ones it is essential because generators assume. Nobody escapes this step.

Framework checklist:

Draft from a known-good example: Never start from a blank file.
Curl every endpoint from outside: Confirm production, not staging, responses.
Complete one real agent checkout: Treat a completed test order as the true pass condition.
Alert on manifest drift: Monitor the live file and re-run synthetic checkouts on a schedule.
Version the final file: Even generated manifests should have their expected state snapshotted for comparison.

Get Your Manifest Producing Real Agent Sales, Not Just Green Checkmarks

This is where most teams stall: the file validates, and then nothing happens. We built UCPhub’s Universal Commerce Protocol platform precisely to close the gap between a conformant manifest and a completed agent purchase, handling generation, endpoint verification, real transaction testing, and drift monitoring in one place so you are not stitching it together yourself. If you want a well-known manifest UCP example that produces actual sales instead of a technically-perfect file that agents quietly ignore, talk to our team at ucphub.ai/contact and we will map your stack to the right approach. You can also see how we think about the broader shift in our Universal Commerce Protocol insights.

Structuring the Manifest File: Field-by-Field Comparison

Both approaches produce the same field structure, but they get there differently, and knowing what each field does is what lets you catch a generator’s bad assumption or avoid a hand-written mistake. This is the “how do I structure my UCP manifest file” question answered at the field level.

The ucp_version field: This is non-negotiable and both approaches always include it. Hand-writers sometimes hardcode an outdated version and forget to bump it; generators usually track the current version automatically. Advantage generated, marginally.

The endpoints block: This is where generated wins decisively. Endpoints are the fields most likely to drift, and a generator that reads live config keeps them accurate. A hand-written manifest is one forgotten deploy away from pointing agents at a dead URL. If you hand-write, this block is where your drift monitoring earns its keep.

The capabilities block: This is where hand-written wins. Capabilities encode business truth that a generator has to infer. When we hand-write, we set `returns`, `subscriptions`, and `checkout` based on what the business actually supports. Generators guess, and their guesses are the assumptions that bite. This single block is the strongest argument for the hybrid approach: generate everything, hand-override capabilities.

The auth block: Roughly a tie. Both approaches need the token endpoint and scopes to match a live auth server. Generators tend to get this right when the platform owns auth; hand-writers get it right when they own auth directly. The failure here is subtle, an agent obtains a token but lacks the scope to write a checkout, so test the full auth-to-checkout path in step three of the framework.

The fulfillment and policies blocks: These are business facts, so hand-written control helps, but they change rarely enough that generation is usually fine. The one exception is fulfillment.regions, which agents use to decide whether to even attempt a transaction; get this wrong and you silently exclude buyers.

If you want the deeper strategic context on why these fields matter as AI agents become primary buyers, our piece on what happens when AI agents become the primary shoppers frames the stakes well.

Field-structuring checklist:

Pin ucp_version deliberately: Know which version you target and why.
Treat endpoints as the drift-prone block: Generate or monitor these hardest.
Own the capabilities block manually: Never let a tool guess what you support.
Test auth through to checkout: A valid token is not the same as a usable scope.
Set fulfillment.regions honestly: Wrong regions silently exclude real buyers.

Common Manifest Mistakes We See in Both Camps

We audit a lot of manifests, and the mistakes cluster in predictable ways depending on which approach produced the file. Naming them here saves you from repeating them.

Hand-written mistake, the copy-paste ghost: Someone copies a well-known manifest UCP example from a blog, forgets to change the merchant id or an endpoint, and ships another company’s URL. We have seen this in production. Always diff against a template, never assume.

Generated mistake, the silent capability flip: The generator cannot detect a feature and defaults it to false. Your store supports subscriptions, the manifest says it does not, and subscription-seeking agents skip you. Always verify the capabilities block against what your store actually does.

Shared mistake, catalog stuffing: Both camps sometimes try to embed product data in the manifest. Do not. The manifest points to a catalog endpoint; it does not contain the catalog. A bloated manifest slows agent discovery and violates the thin-signpost principle.

Shared mistake, the staging endpoint: The failure we opened with. A checkout endpoint pointing at staging validates perfectly and fails every real transaction. This is why step two of our framework exists and why it is not optional.

Shared mistake, the frozen updated_at: A manifest whose `updated_at` never changes tells monitoring and agents that nothing has been maintained. Stamp it on every deploy so staleness is detectable. For a broader view of how point-solution thinking causes these gaps, see our comparison of UCP versus custom AI integrations.

Mistake-avoidance checklist:

Diff every hand-written file against a template: Catch copy-paste ghosts before deploy.
Verify every generated capability: Never trust a false you did not intend.
Keep the catalog out of the manifest: Point to endpoints, do not embed data.
Confirm production endpoints: Curl every URL from outside your network.
Refresh updated_at on deploy: Make staleness visible to monitors and agents.

Measuring Success: Your 30/60/90 Day UCP Manifest KPIs

A manifest is not a set-and-forget artifact, and “it validates” is not a KPI. Here is how we measure whether a manifest, hand-written or generated, is actually working, across the first ninety days.

By day 30, aim for these baseline outcomes:

Validation pass rate at 100 percent: Your manifest should pass every validator you run, every day, with zero regressions.
First completed agent checkout logged: At least one real agent transaction end to end, proving the file’s promise is true.
All endpoints monitored: Every URL in the manifest under uptime and correctness monitoring, alerting on any change.
Zero staging endpoints in production: Confirmed by external curl of every endpoint.

By day 60, you are proving repeatability:

Agent checkout success rate above 90 percent: Of agent-attempted transactions, over nine in ten complete without manifest-caused failure.
Drift alerts firing and resolving: At least one drift event caught and fixed by monitoring rather than by a customer complaint.
Capabilities audited against reality: Every capability field verified true or false against actual store behavior, no lingering generator guesses.
Auth-to-checkout path validated: A full token-to-completed-order test passing on schedule.

By day 90, you are optimizing for growth:

Agent-originated revenue tracked: You can attribute real revenue to agent transactions flowing through the manifest.
Time to detect drift under one hour: Any manifest change or endpoint failure is caught within sixty minutes.
Capability expansion shipped: You have added at least one new capability (returns, subscriptions) and re-verified it with a real agent transaction.
Manifest change process documented: Whether hand-written or generated, your team has a repeatable, reviewed process for updating the file.

If you cannot yet track agent-originated revenue by day 90, that is your priority signal, not a footnote. The whole point of the manifest is commerce, and revenue is the only KPI that proves the file is doing its job. Our industry impact analysis of who UCP is for is useful context for setting realistic revenue expectations by merchant type.

Final Verdict: Which Should You Choose?

Here is our defensible stance, stated plainly. For most merchants on standard platforms, generate the manifest and monitor it hard. The speed, the automatic endpoint currency, and the catalog-scale handling outweigh the risk of generator assumptions, provided you verify the capabilities block once and set up drift monitoring. This is the right default, and we deploy it more than any other approach.

Hand-write only when your commerce logic genuinely cannot be expressed by a generator, meaning B2B quoting, manual approvals, or a fully custom stack. In those cases the control is worth the maintenance tax, and you should treat the file as first-class production infrastructure in your repo.

And if you are mid-market with a mostly-standard stack but a couple of quirks, choose the hybrid: generate the base, hand-override the two or three fields the tool gets wrong. This is increasingly our recommendation because it captures the strengths of both without inheriting the worst of either.

If you are just getting started, do not agonize over the approach. Generate a manifest from a known-good well-known manifest UCP example today, curl every endpoint to confirm it resolves to production, and run exactly one real agent checkout before you tell anyone you are live. That single completed transaction will teach you more than a week of reading the spec. If instead you are auditing something that already exists, start by pulling your live `/.well-known/ucp.json`, diffing the capabilities block against what your store actually does, and confirming no endpoint quietly points at staging, because that is where the silent failures hide. For the full end-to-end path, our 2026 UCP implementation guide is the companion piece to this comparison.

Next Steps:

Pull your live manifest now: Fetch your current `/.well-known/ucp.json` and diff its capabilities block against what your store truly supports.
Run one real agent checkout: Prove the file works by completing a single end-to-end test transaction, not just a validation pass.
Set up drift monitoring this week: Alert on any manifest change and schedule a recurring synthetic checkout so failures surface in under an hour.

Frequently Asked Questions

Can you show me a UCP well-known manifest example?

Yes, and we included a complete one earlier in this article. The core well-known manifest UCP example we deploy for standard merchants includes a `ucp_version`, a `merchant` identity block, an `endpoints` block pointing at your catalog, pricing, checkout, and order-status services, a `capabilities` block declaring what you support, an `auth` block, and `fulfillment` and `policies` blocks. It lives at `https://yourstore.com/.well-known/ucp.json` and is deliberately compact, because the manifest is a signpost that points agents at your endpoints, not a container for your catalog data.

The most important thing to understand about any example you copy is that the endpoints and capabilities must reflect your real store. We have watched merchants paste a beautiful example and ship it with another company’s merchant id still in place, or with a checkout capability set to true while the checkout endpoint pointed at staging. An example is a starting template, not a finished file. Always diff it against your actual configuration and verify every endpoint resolves to production before you consider it live.

What does a proper UCP manifest look like?

A proper manifest looks thin, current, and honest. Thin means it contains discovery signals and endpoint references, not embedded product data; if your file is hundreds of lines long because you stuffed the catalog into it, that is a structural mistake that slows agent discovery. Current means the `updated_at` timestamp reflects a real recent deploy and every endpoint returns live production responses. Honest means the capabilities block declares exactly what your store can do, with no overpromised true values and no generator-guessed false values.

Beyond structure, a proper manifest is one that has passed a real agent transaction, not just a validator. According to UCP Checker, which independently monitors 20,886+ storefronts, roughly 78 percent pass full UCP validation, but a conformant manifest is not the same as an agent being able to complete a real checkout, and that distinction is the difference between a manifest that looks proper and one that is proper. In our experience the only reliable test of properness is driving an agent through discovery, cart creation, and a completed purchase. If that works, your manifest is proper regardless of how it was produced.

How do I structure my UCP manifest file?

Structure it as nested JSON with clear top-level blocks, following the field structure in the well-known manifest UCP example above. Start with `ucp_version` at the top so parsers can branch correctly. Add a `merchant` block for identity, an `endpoints` block that maps each UCP operation to a production URL, and a `capabilities` block of booleans declaring what you support. Then add `auth` with your token endpoint and scopes, `fulfillment` with your regions and currencies, `policies` with your legal URLs, and a final `updated_at` timestamp.

The structuring decision that matters most is keeping the discovery layer separate from the data layer. Your manifest declares that a catalog exists and where to find it; the catalog endpoint returns the actual products. This separation is what lets a store with tens of thousands of SKUs keep a small, fast manifest. If you are on a standard platform, a generator will produce this structure for you and keep the endpoints current; if you are hand-writing, use a known-good template and put the file under version control so every change is reviewed. Either way, verify the capabilities block manually, because that is the one block a generator is most likely to get wrong and a hand-writer is most likely to leave overpromised.

Should I hand-write my manifest or use a generator?

For most merchants, use a generator and monitor the output, because generation eliminates the stale-endpoint failure mode that causes the majority of silent manifest failures we see. If you are on Shopify or WooCommerce with a conventional checkout flow, a generated manifest will be correct, current, and low-maintenance, and you can be discoverable by agents within an hour. The tradeoff is that generators make assumptions you have to verify, especially in the capabilities block, so plan to audit that block once against your real store behavior.

Hand-write when your commerce logic is genuinely non-standard, meaning B2B quoting, manual order approval, pre-authorization holds, or a custom stack with no first-party generator. In those cases the field-level control is worth the maintenance burden. And consider the hybrid path if you are somewhere in between: generate the base file and apply a thin layer of hand-authored overrides for the two or three fields the generator gets wrong. That hybrid is increasingly what we recommend for mid-market merchants because it captures the speed of generation and the accuracy of hand-control.

Where exactly does the UCP manifest file live?

It lives at the `/.well-known/ucp.json` path on your primary domain, so `https://yourstore.com/.well-known/ucp.json`. The `.well-known` directory is a web standard for machine-discoverable metadata, and agents look for the UCP manifest there by convention. It must be served over HTTPS, return a valid JSON content type, and be reachable without authentication, because agents need to read it before they have any credentials.

A common deployment mistake is placing the file behind a redirect, a login wall, or a CDN rule that blocks non-browser user agents. We have seen manifests that resolved perfectly in a browser but returned a bot-block page when an agent fetched them. Test the file with a plain external request that does not send browser headers, and confirm it returns your JSON directly with a 200 status. If your store spans multiple domains, each customer-facing domain that should be independently discoverable needs its own manifest at its own well-known path.

How often should I update my UCP manifest?

Update it whenever any fact it declares changes, and stamp the `updated_at` field on every deploy. If your endpoints move, your capabilities change, your fulfillment regions expand, or your auth configuration shifts, the manifest must follow immediately, because agents act on what the file says, not on what your store actually does. This is exactly why generated manifests that regenerate on deploy have such an advantage: the update happens automatically the moment the underlying config changes.

For hand-written manifests, the safest practice is to treat the manifest as part of the same change that touches any declared fact, so updating a pricing service and its manifest reference happen in the same pull request. On top of any deliberate update, run drift monitoring that alerts you within an hour if the live manifest diverges from its expected state, plus a scheduled synthetic checkout that catches functional breakage even when the file itself looks unchanged. In our experience the manifests that fail in production are almost never the ones that were updated too rarely; they are the ones nobody was watching between updates.

What is the difference between a valid manifest and a working one?

A valid manifest passes structural validation, meaning the JSON parses, required fields are present, and values match expected types. A working manifest actually enables an agent to discover your store, retrieve real pricing, and complete a purchase end to end. These are different things, and the gap between them is where most launches stall. A manifest can be perfectly valid while pointing its checkout endpoint at a dead staging URL, in which case it validates green and completes zero transactions.

The only reliable test of a working manifest is a completed real agent checkout. That is why our four-step framework treats validation as step one and a real agent transaction as step three, with the transaction being the true pass condition. When we tell clients a manifest is done, we mean an agent has completed a test order through it, not that a linter approved it. If you take one thing from this comparison, make it this: trust the completed checkout, never the checkmark.

Can I have multiple capabilities disabled and still benefit from UCP?

Yes, and starting with a minimal capability set is often the smart move. A manifest that declares only `discovery` and `real_time_pricing` as true, with checkout still false, still makes your products discoverable and priceable by agents, which is real value even before you enable purchasing. Many merchants we work with launch with discovery and pricing, prove the pipeline works, and then flip checkout to true once they have verified the full transaction path. Declaring a capability false is honest and safe; declaring it true when it does not work is what causes agent-facing failures.

The key discipline is to only set a capability true after you have verified it with a real agent transaction, and to expand capabilities one at a time so each addition can be tested in isolation. When you later enable returns or subscriptions, re-run a real agent flow for that specific capability before you consider it live. Growing the capability set deliberately is far safer than shipping everything true on day one and discovering which promises your store cannot actually keep.