The commerce manifest: the file an agent reads before anything else
In short
A commerce manifest is a machine-readable capability declaration served at a fixed path on your domain. It tells an agent which commerce services you run, at which endpoints, and under which payment configuration — nothing about why anyone should buy from you. 3 conditions gate it: public and unauthenticated, parseable JSON, and exactly 1 merchant per file.
Key takeaways
- It declares capability, not merit. No prices, no stock, no copy, nothing a shopper would read.
- 3 serving conditions gate it: unauthenticated, parseable JSON, exactly 1 merchant per file.
- Declaring a capability you have not built is worse than declaring nothing at all.
- 1 file per selling entity. A group with 3 brands needs 3 declarations, not 1 with a list.
- The specifications are young. Clean structured product data underneath is the part that survives.
A commerce manifest is a small machine-readable file at a fixed path on your domain that tells an AI agent what your store can do: which commerce services you run, at which endpoints, under which payment configuration, in which markets. An agent fetches it cold, before it has any relationship with you, and decides from it whether you are worth calling.
The common mistake is treating it as a marketing surface. It carries no prices, no stock, no copy and no argument for choosing you — an agent that wanted persuading would read your site. The useful version of this file is short.
What the file declares, block by block
| Block | What it declares | What an agent does with it |
|---|---|---|
| Merchant identity | The legal selling entity, its domain, a stable identifier | Ties the store to a party that can be held to an order |
| Service endpoints | Addresses for catalogue reads, checkout operations, order status | Learns what it may call, and stops guessing URLs |
| Capabilities | Which operations exist — in-agent completion, handoff, digital goods | Decides whether it can buy here or must send the shopper away |
| Payment configuration | Which schemes and credential types you accept | Checks the shopper's credential is usable before starting |
| Markets and currencies | Countries served, currencies quoted, locales supported | Screens you out for a shopper you cannot ship to |
| Policy references | Where structured returns, shipping and warranty terms live | Finds terms it can quote without paraphrasing |
| Protocol revision | Which published revision the file is written against | Knows how to parse the rest of it |
The capabilities block is where honesty costs money either way. Declaring in-agent completion your checkout cannot honour produces failed purchases inside somebody else's product, which is the fastest way to be dropped. Declaring handoff when you could complete in-agent costs conversions. That trade is argued in completing in the agent versus handing back.
Three serving conditions, and why each one is failed in practice
- Publicly reachable without authentication. An agent fetches it cold — no cookies, no session, often from a datacentre address. A login wall, a geo-redirect to a country storefront, or a bot rule that challenges unknown clients all read as absent.
- Served as parseable JSON, with a JSON content type. The classic failure returns a styled HTML error page under a 200 status, which parses as nothing.
- Describing exactly 1 merchant. The file names the party an order is placed with, so it cannot describe 2 selling entities without making that party ambiguous.
- Generated from your systems of record. A hand-edited declaration drifts from the endpoints it names within a quarter, so treat it as build output — ordinary internal tools and ops work.
Why one merchant per file is a liability boundary, not a formatting rule
The manifest is where an agent works out who it is transacting with. That party takes the money, owes the goods and answers the dispute. Merge 2 brands into 1 declaration and the agent cannot tell which entity an order belongs to — and neither, later, can your finance team.
This bites groups and marketplaces first. If 3 brands sell from 1 platform, each selling entity needs its own declaration on its own domain, even where they share a catalogue and a warehouse. The shared infrastructure is an implementation detail; the selling entity is not.
What the file deliberately leaves out
- Prices and availability. Those are live or feed data, and a cacheable declaration guarantees they will be wrong.
- Anything keyed to a customer. The file is fetched anonymously and cached widely; that boundary is set out in what a catalogue tool server may expose.
- Persuasion. Brand story and awards do nothing here, and a bloated file is slower to fetch and easier to break.
- Capabilities you intend to build. A declaration is a promise the agent tests on its first real purchase.
The part of this that survives whichever protocol settles
The published agentic-commerce specifications are young, and their field names, required blocks and even their names will move. Betting a roadmap on one revision is a poor trade. Betting it on the data underneath is not: identifiers that resolve, variants modelled the way shoppers choose, lifecycle state on every record, policy expressed as data, and a unit of measure that survives the difference between an each, an inner and a case.
The manifest is a day of work. The product data it points at is the year of work, and no revision can take that away.
That is the sequencing answer too. Publishing a declaration is cheap and worth doing early, and it is not a substitute for deciding whether you want an assistant on your own traffic or presence on traffic you do not own — the trade in an assistant on your site versus presence in someone else's. Both sit in agentic commerce, part of our retail and e-commerce practice.
Frequently asked questions
Short answers to the follow-ups this page tends to raise.
Where should a commerce manifest be served from?
From the merchant's own domain, over HTTPS, at the fixed well-known path the protocol you are implementing names. Confirm the exact path against the current specification rather than against any article, because it is one of the details that has moved. What does not move: it must be the selling domain, not a CDN subdomain or a vendor's domain, because the file asserts who the merchant is.
Does publishing a manifest make our products discoverable to AI agents?
No. The manifest declares what your store can do, not what it sells. An agent still has to read your catalogue — through a feed, a tool call or a crawl — before it can recommend anything, and it still has to decide you are worth showing. The declaration removes a reason to skip you; it does not create demand.
Should we publish a manifest before the endpoints behind it exist?
No, and this is the one failure worth avoiding outright. A declaration is tested by the first agent that tries to use it, and a capability that errors is worse than a capability that was never advertised — you get the crawl, the attempt, the failure, and a reputation with that surface. Declare only what returns a correct response today.
- agentic commerce
- protocols
- discovery
- product data
The work behind this page
Builds from our portfolio that this page draws on.
AI Lease Management
AI-powered commercial real estate lease management for multi-brand operators — automates lease data extraction, obligation tracking, and portfolio intelligence.
Real EstateLow Latency Food Ordering Platform
Unified events operations platform: vendor management, order tracking, payments, automated settlements.
MarketplaceRead next
- The agentic checkout session: a cart your server ownsA server-side basket the merchant owns and an AI agent only renders. Every create, update or complete call returns the merchant's full current state — the property that makes agent buying safe to allow.definition
- The delegated payment token: an allowance with an expiry, not a card numberThe credential an AI agent hands your checkout is not a card number. It is a reference to a vaulted card wrapped in 4 constraints, and those constraints — not the encryption around them — are what limit an agent's spending.definition
- Agents fetch your manifest and still skip your storeA file that loads in your browser can be unreachable, unparseable or disqualifying to an agent. Three verdicts, and the ordered checks that tell them apart.diagnostic
- The agent confirmed the order and the charge failed afterwardsAn order exists, the shopper was told it is placed, and no money moved. The cause is almost never the card: it is one of the 4 constraints on the delegated token refusing the charge.diagnostic
- The agent shows one total and your checkout session returns anotherThe shopper saw one number and your server charged another. Replay the call sequence: the agent is nearly always displaying a response that a later call replaced.diagnostic
- The assistant keeps recommending products you stopped sellingA shopping assistant naming products you withdrew is rarely hallucination. It is a stale index, a missing lifecycle field, an unenforced tool call or a tool returning unpublished rows.diagnostic
Related across the site
Working on something in this space?
Tell us where you are in a sentence or two. We'll tell you honestly whether we're the right team, and what a sensible first slice of the work looks like.
Start the conversation