Week of September 28

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.

Breaking changes

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

All changes