Week of September 28

Smaller changes from the week sandbox orders started finishing end to end.

order.challenge is sent

order.challenge was reserved and never sent. It now fires when Layout texts the person a link to approve a purchase and the order is waiting on them.

• It is a pause, not a new state. order.state is where the order was when it paused: building, carted or placing.
• It is sent once per order, and only while the order is still in flight.
• It is off by default. Turn it on for a subscription on the console's Webhooks page.

order.needs_approval is still reserved and not sent. You can subscribe to it, but do not build a handler that waits on it.

The ord_ id in MCP results

Once an order result names an order, from carted on, it also carries publicOrderId: the ord_ id that GET /v1/orders/:id and your webhooks use. It is on build, status and confirm results, and only for orders your build session or your OAuth client drove.

{
  "action": "status",
  "build": { "status": "carted", "orderId": "0b6f2a54-…", … },
  "publicOrderId": "ord_7c21"
}

While a build is still building there may be no order yet. Keep polling, or take the id from the order.building webhook. The id is for your own systems; never read it to the person.

How long build waits

The MCP reference said build returns building immediately. It holds for up to about 15 seconds, so a build that finishes inside that window comes back ready, and otherwise it returns building and you poll status. Nothing changed in the API; the reference now says what it does.

One developer contact

developer@layout.link is the one address for anything about building on Layout, including a limit that Usage cannot raise.

Breaking changes

None. publicOrderId is a new field, and order.challenge reaches only subscriptions that turn it on.

All changes