# Docs that match the API

October 1, 2026 · Docs

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](https://developer.layout.link/changelog/confirm-with-the-persons-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](https://developer.layout.link/reference/errors#every-error-code) 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](https://developer.layout.link/reference/errors#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](https://developer.layout.link/reference/events) 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](https://developer.layout.link/changelog/event-ids-on-every-webhook)). [Webhooks](https://developer.layout.link/reference/webhooks#payload) 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](https://developer.layout.link/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](https://developer.layout.link/reference/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](https://developer.layout.link/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.