Agents fetch your manifest and still skip your store

The file exists, it loads when you open it, and no agent is buying. That is 3 distinct situations wearing one symptom, and they are worth separating before anyone changes the file: the agent never got it, the agent got something it could not parse, or the agent parsed it and decided against you. Only the third is about what the file says.

The reason a browser cannot tell you which is that a browser is the wrong client. It carries your cookies, follows redirects without comment, renders an HTML error page as though it were a page, and is very likely inside your own network. An agent arrives cold from a datacentre address with no session and no patience. What the declaration is supposed to contain is set out in the commerce manifest an agent reads before anything else — this page is about why a correct-looking one still fails.

Fetch it cold, from outside everything you own

1. Request the file from a network you do not control, with a command-line client, no cookies and no custom user agent. Capture the full response headers, not just the body.
2. Record the status. Anything other than 200 on the first request is the answer — a 401, 403 or 404 ends the investigation here.
3. Record the redirect chain. Any hop at all is a finding; a hop to a country-specific storefront is the common one, and it means the agent is being handed a different site.
4. Record the content type. It must be a JSON type. A 200 carrying text/html is the failure that looks perfect in a browser.
5. Parse the body with a strict parser and nothing else — no browser, no forgiving reader. If it does not parse, no agent will read it, whatever it looks like on screen.
6. Repeat from a second network and a second region. A rule that fires only on datacentre address ranges is invisible from an office.

A bot rule or a login is answering before your file does

The most common serving fault is that something in front of your origin replies instead of it. A challenge page, a rate limit that treats an unknown client as hostile, an authentication wall inherited from a staging configuration, or a geo-redirect that sends every unrecognised visitor to a regional storefront. All 4 return something, so nothing in your monitoring goes red.

Getting the edge policy right for agents is a whole problem of its own and it has its own page — your bot protection is blocking the AI surfaces you are trying to sell through. For this diagnostic the point is narrower: whatever your general policy, the declaration file itself must be unauthenticated, uncached-behind-a-session, and exempt from challenges. It contains nothing worth protecting.

The right bytes under the wrong content type

A file served as text/html, text/plain or application/octet-stream is a file most strict clients will not treat as a declaration, even when the bytes are valid JSON. Static hosting that infers types from extensions is the usual cause: a file with no extension, or an unfamiliar one, gets a default that is wrong.

The related trap is a 200 that is not the file at all. Single-page-application routing frequently answers every unmatched path with the application shell, so a missing declaration returns a beautiful HTML document with a success status. Check the first character of the body, not the status code.

A redirect chain, and the path that is no longer well-known

Redirects are a finding even when they resolve. A hop from the apex to www, or from http to https, is survivable but adds a step where a client may stop. A hop into a locale path is worse, because the agent asked about your store and has been sent to one edition of it. And a hop that lands on a login is a serving failure in disguise.

One file, two selling entities

A declaration names the party an order is placed with — the entity that takes the money, owes the goods and answers the dispute. A file describing 2 brands, or a group and its subsidiaries, leaves an agent unable to say who it is transacting with, and a validator that rejects it is doing you a favour.

This catches groups and multi-brand platforms first: shared warehouse, shared catalogue, shared checkout, 3 legal sellers. The infrastructure is an implementation detail and the selling entity is not, so each entity needs its own declaration on its own domain. It also catches stores whose declaration names one entity while their published terms name another — the consistency question behind publishing returns, shipping and warranty terms an agent can quote.

The endpoints you declared fail their own handshake

This is the verdict teams reach last and should reach second. A declaration is a set of promises that an agent will test: it will call the endpoints named, expect the operations declared, and expect the payment configuration to be honoured. A store that declares in-agent completion and then cannot create a session, or creates one and refuses every credential type it advertised, fails on the first real attempt — inside somebody else's product, in front of a shopper who is not yours.

• Call each declared endpoint yourself, unauthenticated where the protocol says it should be reachable, and confirm it answers as declared rather than merely answering.
• Run one complete purchase end to end against your own declaration, including a completion. A session that can be created and not completed is worse than no declaration.
• Declare only capabilities that exist today. Announcing what is on the roadmap is the same failure as product copy that asserts specifications nobody verified — the generated copy invents specifications.
• Test the unhappy paths too, because an agent will meet them: an item that sells out mid-session, and a charge that fails after confirmation — the agent confirmed the order and the charge failed afterwards.
• Generate the file from your systems of record rather than editing it by hand, so a decommissioned endpoint cannot survive in a declaration for a quarter.

A declaration is not marketing. It is a promise an unfamiliar client will test on its first real purchase, and the only version worth publishing is the one you can already honour.

The file is correct and the specification moved under it

The published agentic-commerce specifications are young and actively changing. Required blocks appear, property names change, and the revision your file names may no longer be one an agent will parse. This is not a defect you can design away, so treat it as maintenance: name the revision explicitly in the file, review it whenever that revision changes, and re-run the 6 checks above at least quarterly.

Two things reduce how often that hurts. Keep the declaration short, because every block you did not need is a block that can become invalid. And put the durable effort into the data underneath rather than the file on top: identifiers that resolve, lifecycle state on every record, and policy expressed as data survive every revision — which is also the difference between a store agents can quote and one they can only find, argued in a published feed or a live tool call.

Generating, validating and monitoring the declaration is small, ordinary AI agents and automation work: a build step that emits it, a scheduled cold fetch that alerts on status, content type or parse failure, and a canary purchase against your own endpoints. If those endpoints are backed by a model of your own — a search or recommendation service sitting behind catalogue reads — where it runs is a separate decision with 4 options, set out in private and on-premises LLM deployment. The rest of this silo sits under agentic commerce and AI shopping assistants, inside our retail and e-commerce practice.

• agentic commerce
• manifest
• discovery
• diagnostics