Confirm with the person's code

October 1, 2026API

Until now a build grant could build a cart for someone you provisioned, but never confirm it: the person had to reply YES to Layout's text or open the Layout app. Now your application can confirm it, with the code Layout texts the person for that cart.

What changed

POST /v1/carts/:id/confirm accepts a live build grant. The first call without a code answers 400 code_required and Layout texts the person a 6-digit code. Send the same request again, with the same idempotencyKey, plus code, and it answers 202 placing.
The order tool's confirm action works the same way on a production build session over MCP. The first call answers code_required. codeSent: true means a code just went out; codeSent: false means one texted in the last 10 minutes is still good, so ask the person for it.
POST /v1/carts/:id/confirm/resend-code and the MCP resend stage text a fresh code to a build grant's person. The new code replaces the last. Layout texts at most four codes per cart, and each application has a daily code allowance; past either the answer is 429 rate_limited.
POST /v1/carts/:id/cancel, and cancel: true with an orderId over MCP, release a cart your application built.
A build grant's cart reads codeRequired: true.

POST /v1/carts/crt_9b1f0c2a4eN2YzYzJhOWUtY2FydC0x/confirm
{ "expectedTotalMinor": 750, "idempotencyKey": "7f3c2a9e-confirm-1" }

400 { "error": { "code": "code_required", "message": "Layout just texted the person a 6-digit code. Ask them for it and send this same request again with code.", "orderId": "ord_7c21" } }

POST /v1/carts/crt_9b1f0c2a4eN2YzYzJhOWUtY2FydC0x/confirm
{ "expectedTotalMinor": 750, "idempotencyKey": "7f3c2a9e-confirm-1", "code": "482913" }

202 { "order": { "id": "ord_7c21", "status": "placing" } }

How the code works

On a build grant the code is asked for on every live confirm, whatever the total and whatever the person's own code setting. It is how the person, not your application, agrees to the charge.
Layout writes the text, from Layout's number: Layout: 482913 approves $7.50 at Layout test kitchen on your Visa ending 4242. Sharing this code places the order. It names the total, the store and the card that will be billed. Nothing your application sends appears in it.
A confirm without a code texts a new code only when none texted in the last 10 minutes is still good. A text that could not be sent is 502 send_failed: retry shortly.
The code works once, for that cart and that total, for 10 minutes. A wrong code is 400 code_invalid. One that expired, was used, was replaced, or was texted for another total is 400 code_expired.
It cannot sign anybody in to Layout. Never ask the person for a Layout sign-in code.
Every other check still runs: the price lock, the person's daily limit, Layout's risk checks, and whether the restaurant's session is still open. Only carts your application built can be confirmed or released.
The person must have finished joining Layout. Until then the confirm answers 403 build_only, says which step is missing (sign up with this number and add a card, approve a connect link because the number already has a Layout account, be provisioned again, verify their number, or add a card), and texts nothing.
Sandbox is unchanged: a sandbox grant confirms with no code, as a simulation.

Why it matters

Your own chat, app or assistant can now carry an order from the cart to the confirm without sending the person to Layout. If you turned off the cart-ready text, this is how your application confirms.

What to do

Show the person the cart's items, store and totalMinor. When they say yes, call confirm with no code, ask them for the code Layout texts them, and confirm again with it. Handle code_required, code_invalid, code_expired, send_failed, rate_limited and build_only. See Confirming with a build grant and Confirm with the person's code.

Breaking changes

None for an integration that only builds. A live build grant's confirm used to be refused with 403 build_only and did nothing; it now texts the person a code, so call it only after the person has said yes. build_only now means the person has not finished joining Layout. A cancel over MCP on a build session must name the orderId.

All changes