Codes on first orders

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. See 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 still apply. See 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 and 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.

All changes