Docs that match the API

October 1, 2026Docs

Several pages disagreed with the API, or with each other. They now match what the API sends.

What changed

One ordering story. REST carts and the MCP order tool are two doors to the same ordering. A person who connected your application builds and confirms; a build grant builds, reads, and confirms only with the code Layout texts the person for that cart (see Confirm with the person's code). Pages that said ordering was MCP only, or that every confirm happens on a Layout page, are corrected.
Every error code. Errors and status lists every code in the Error schema, with its status, which endpoints send it and what to do. It also names the three flat answers that come from in front of the endpoints.
Failure codes. Every value failure_code takes is published in Failure codes, and in the Order schema. An older order that stored a code outside the list reads as UNKNOWN, and one that stored PAYMENT_DECLINED reads as CARD_DECLINED.
Webhook payload. Event types said order.carted carries items, modifiers and a pickup time. It carries the store's name, the item count and the total, like every event. Only order.failed adds a reason, order.failure_code (see Event ids on every webhook). Webhooks no longer mentions a richer payload, which does not exist.
Verify. A wrong code is 401 bad_code.
Connect. The field that returns the consent link is connectDelivery, as in the specification. One example used another name.
Grants. Provisioning returns no credential, a build grant lasts 15 minutes unless you refresh it, and a build grant cannot read GET /v1/orders/:id (it follows its own order on the cart).
Events feed. The home page and the reference now name the same GET /v1/events parameters, cursor and limit.
Ids. In openapi.json a webhook event's ids accept the fixed ids a console test delivery carries, a path id keeps the shape every route checks, and every example matches its own pattern.
MCP tools. MCP tools has every tool's input and output JSON Schema, which session may call what, and raw JSON-RPC calls. The same contract is machine-readable at mcp-tools.json.

Why it matters

A developer, or an agent integrating for one, builds from what the docs say. Where they said something the API does not do, code written from them failed.

What to do

If you parsed order.carted for items or a pickup time, read the cart with GET /v1/carts/:id instead. If you generate types from the specification or from mcp-tools.json, regenerate them.

Breaking changes

None. Apart from the failure_code mapping above, the API's behaviour did not change; the docs now describe it.

All changes