How a store says what is true.
Quote Spec v0.6 · 10 Sep 2026 · supersedes v0.5
Working draft · breaking changes carry a version bump
This is the interface a store speaks inward, once, and what every agent gets back outward. It is versioned because anything built against it should know which edition it read. If you are building something that has to buy from real stores, tell us where this breaks.
We are not adding a protocol.
There are enough. ACP, AP2, UCP, Visa’s Trusted Agent Protocol, Mastercard’s Agent Pay, MCP, x402 — they all work, and none of them failed. What failed was upstream of every one of them: nobody could say what was on the shelf. Caravanserai speaks MCP outward today and adds the rest one at a time. The interface below is what a store speaks inward, once — and it does not change as each rail lands.
GET
/v1/catalog
Everything the store sells, with live price and stock. Cursored, and cheap to poll.
POST
/v1/quote
Ask for a commitment: this item, this quantity, to this address. Returns a signed quote with an expiry.
POST
/v1/quote/:id/accept
Convert a live quote into an order on the merchant's own system. The charge runs on the merchant's own processor, under their own account — we hold no card data and take no fee on it. Two kinds of bearer reach this: a developer's key, and a grant a buyer issued to an assistant of their own, which may spend only that buyer's cards, only where their rules allow, and only inside their caps.
Four properties, and the fourth is the company.
01
A quote expires
Every quote carries an expiry, typically minutes. Nothing is promised indefinitely, because nothing is true indefinitely. An expired quote is refused, not silently repriced.
02
A quote is signed
Ed25519 over the canonical body. An agent can show a person the quote and a merchant can verify what they agreed to. Neither side is taking the other's word for it.
03
A quote is addressed
Delivery is quoted to a specific destination and a specific window, not as a generic shipping table. Wrong delivery dates were the single most cited reason the first attempt at this failed.
04
A quote is answerable
If a merchant does not honour a quote it signed, that is recorded against them. Price, availability and cancellation are verified against the merchant's own till. Delivery is attested by the buyer or the agent and counted apart — a till records when staff tapped a screen, not when the box arrived. The record is not published: it decides whether an assistant may buy at a shop unattended, or the buyer is asked first.
Response from POST /v1/quote
{
"quote_id": "cvs_q_8Fk2Rd",
"merchant": "sweet-ash-bakery",
"issued": "2026-08-28T04:37:11Z",
"expires": "2026-08-28T04:52:11Z",
"item": {
"sku": "CAKE-VAN-8",
"name": "8\" vanilla layer",
"available": 3
},
"price": {
"item": 4800,
"delivery": 650,
"tax": 0,
"total": 5450,
"currency": "USD"
},
"fulfil": {
"method": "courier",
"to": "1042 Fulton St, Brooklyn NY 11238",
"window": "2026-08-29T10:00/2026-08-29T12:00"
},
"returns": {
"cancel_free_until": "2026-08-27T18:00"
},
"signature": "ed25519:9c1f…a04e"
}The merchant’s honour record used to ride here, and does not any more. It is kept and not published: it decides whether an assistant may buy at a shop on its own or the buyer is asked first. Inside it, verified is read back from the till and attested is what a person reported. They are counted apart, because a till can prove a price and cannot prove an arrival.
Open questions.
- Liability. Who pays when an agent buys the wrong thing is negotiated company by company today, and no protocol on the list above settles it. The honour record is the beginning of an answer, not the whole of one.
- Sales tax. Unsolved industry-wide as of February 2026, and named in the post-mortem of the first attempt. Our position: quote it, and let the merchant remit it, because they already do.
- Verifying delivery. A till can prove what was charged and what was cancelled. It cannot prove a box arrived at an address — a fulfilment marked complete is a staff tap, not a doorstep. Until a courier’s API or the buyer signs for it, delivery is attested rather than verified, and this spec keeps the two apart. Who is entitled to witness an arrival is not settled by anyone.
- Weighting the honour record. How long a broken quote counts against a store, and where the line sits between a shop an assistant may buy from unattended and one whose buyer should be asked. The shape is settled; the constants need production data to tune against.