How a store says what is true.
Quote Spec v0.4 · 6 Sep 2026 · supersedes v0.3
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 all of them outward. The interface below is what a store speaks inward, once.
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.
GET
/v1/merchant/:id/record
How often this merchant has honoured the quotes it signed. Public, and the reason routing works.
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 shown separately — a till records when staff tapped a screen, not when the box arrived. The two are never blended.
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"
},
"honour": {
"verified": {
"basis": ["price", "availability", "cancellation"],
"source": "merchant point of sale",
"n": 1840,
"kept": 1824,
"rate": 0.991
},
"attested": {
"basis": ["delivery_window"],
"source": "buyer or agent report",
"n": 612,
"kept": 577,
"rate": 0.943
}
},
"signature": "ed25519:9c1f…a04e"
}Note honour — the merchant’s own record, returned with every quote. verified is read back from the till. attested is what the buyer or the agent 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 how one with three bad weeks behind two good years ranks against a newcomer with no history at all. The shape is settled; the constants need production data to tune against.