# Codes on first orders

October 2, 2026 · API

**Update 2026-10-21:** There is no per-person code setting. On `build_only`, a person who has not verified answers `verify_required`: verify them with `verify/start` and `verify`. A person you provisioned gets no `url` on `card_required`: mint a [card link](https://docs.layout.link/card-links). See [Every error code](https://docs.layout.link/errors#every-error-code).

**Since then:** connecting your application is the person's agreement, so a person who connects after Layout began saying so owes no code just for it being their first order; the other reasons in [When a code is due](https://docs.layout.link/how-it-works#when-a-code-is-due) still apply. See [Connecting is agreeing](https://docs.layout.link/changelog/connecting-is-agreeing). The rest of this entry is as it was published.

A build grant used to need the code Layout texts the person on every live confirm. It now needs it until the person approves an order through your application with it. After that the code is asked for exactly when ordering anywhere else in Layout would ask for it.

## What changed

- Until a person has placed an order through your application with the code Layout texts them, every live confirm needs the code, whatever the total and whatever their own code setting. Only that code counts: an order placed by replying to Layout's text, in the Layout app, or through an OAuth connection does not, and consent to another application does not carry over. It ends when the person disconnects your application, you deprovision them, or they connect again.
- After that, a build grant's confirm needs the code when the person keeps codes on, the total is over Layout's amount limit for codes, which can change, Layout's risk checks ask for one, or a code is already out for the cart. Otherwise the confirm without a code answers `202 placing` over REST and `placing` over MCP.
- A build grant's cart reads `codeRequired` from the same rule. `resend-code` on a cart that needs no code answers `409 code_not_needed` and texts nothing.
- A `403 build_only` confirm now carries `error.next`: `step` is `sign_up_required`, `connect_required`, `link_expired`, `phone_required` or `card_required`, and `url`, when present, is the Layout page where the person finishes it. The MCP `confirm` result carries the same `next`.
- Provisioning's `session.expiresIn` now states 900, the 15 minutes a build session lasts.

```
403 {
  "error": {
    "code": "build_only",
    "message": "This person has not finished joining Layout, so the cart cannot be confirmed yet. They need to sign up to Layout with this number and add a card, then you confirm again. Nothing was charged.",
    "orderId": "ord_7c21e4b9a0d3",
    "next": { "step": "sign_up_required", "url": "https://account.layout.link/join" }
  }
}
```

## Why it matters

The first code is how the person agrees to let your application order for them. Once they have, a second small order does not need a text, the same as in the Layout app. And your code can tell the person what to do next without reading the message.

## What to do

Keep calling confirm with no code first, and handle `code_required` on every confirm: the confirm decides. On `build_only`, switch on `error.next.step` and send the person `error.next.url` when there is one. See [Confirming with a build grant](https://docs.layout.link/carts#relayed-code) and [Errors](https://docs.layout.link/errors).

## Breaking changes

None. A confirm that already handles `code_required` and `202 placing` works unchanged. On MCP, a grant's `build_only` confirm result used to carry `next` as the string `"connect"` or `"provision"`; it is now the object above.