Codes on first orders

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.
• That code's text says what sharing it unlocks: Sharing this code places the order and lets Acme Assistant place future orders for you without a code. Turn on order codes in Layout to stop that. It names your application as it appears in the console. Codes Layout texts once the person has consented keep the plain wording.
• 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