Sandbox test restaurants

Each test restaurant scripts one outcome, the way a payment processor's test cards do, so you can test every path your integration handles in CI. They never open a browser, cost nothing, and never count toward your sandbox build allowance.

Who can use them

Sandbox credentials only: a sandbox build grant, or a connected person's token where the person is a sandbox test user. Name a test restaurant by its placeId, which always starts test_place_.

Over MCP that means a session started from a sandbox build grant. An OAuth connector session never reaches them, even when the person it signs in is a test user.

A production credential that names a test restaurant gets exactly the answer it would get for any place that does not exist: store_not_found from POST /v1/carts, a 404 from the place and menu reads, and an unknown store from the MCP order tool. Nothing is built.

Find them

In sandbox, a search that names them lists them, up to limit (5 by default, at most 10) like any search. Add a word to narrow it: layout test slow finds test_place_slow. None of these reads draws your place or menu allowance.

curl "https://api.layout.link/v1/places?query=layout%20test" \
  -H "Authorization: Bearer $LAYOUT_PERSON_TOKEN"

GET /v1/places/test_place_carted reads one, and POST /v1/menus with a test placeId returns the test menu. Over MCP, pass the placeId straight to the order tool's build action; the places and menu tools do not list test restaurants.

The test restaurants

Any other id that starts test_place_ is reserved and finds nothing.

The test menu

Every test restaurant shares one menu, so a total is the same every time you build it.

• Each entry of items, or each comma in request, is one line. A leading number is the quantity: "2 lattes".
• An option named anywhere in the request applies to the items that offer it. A latte with no size named is Small, except at test_place_needs_choices, which asks.
• Anything the menu does not list is priced at $5.00 under the name you sent.
• Tax is 8.75% of the subtotal. The service fee is the same as in production, and totalMinor includes it.

What they write

A test restaurant writes the same order a real build does, marked simulated: true. GET /v1/carts/:id, confirm, GET /v1/orders/:id, the event feed and your webhooks all treat it as an order, and every event it sends carries "simulated": true. No card is shown and no code is asked for.

A question (test_place_needs_choices before it is answered, test_place_needs_location) writes no order and sends nothing. A ready cart nobody confirms expires as it would in production.

The times are approximate. An order moves on within a few seconds of being due. Reading the order, with GET /v1/orders/:id or order_status over MCP, moves it on the moment it is due. Reading a cart moves on only a slow build.

A whole order in CI

Give every run its own idempotency keys, for example from your CI run id. A key reused from an earlier run replays that run's cart and confirm instead of building a new one.

curl https://api.layout.link/v1/carts \
  -H "Authorization: Bearer $LAYOUT_PERSON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "placeId": "test_place_placed", "items": ["latte", "blueberry muffin"], "idempotencyKey": "ci-'"$RUN_ID"'-cart" }'

202 Accepted

{ "cart": { "id": "crt_3f9a1c0b7dY2ktcnVuLTAwMDE", "status": "building" } }

Read the cart until it is ready, confirm it with its totalMinor, then read the order or wait for order.placed.

curl https://api.layout.link/v1/carts/crt_3f9a1c0b7dY2ktcnVuLTAwMDE/confirm \
  -H "Authorization: Bearer $LAYOUT_PERSON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "expectedTotalMinor": 1019, "idempotencyKey": "ci-'"$RUN_ID"'-confirm" }'

202 Accepted

{ "order": { "id": "ord_7c21", "status": "placing", "simulated": true } }

Limits

Test restaurant builds have their own allowance: 10,000 a day for each developer account, across all its applications, inside a pool shared by every developer. They never draw your sandbox build allowance, and they do not appear in Usage. A refusal is build_limit and names the number. Both reset at midnight UTC.

Fire a test webhook

POST /v1/sandbox/webhooks/fire sends one signed test event to every enabled endpoint of your application that subscribes to it, so you can test a handler without building anything. It goes through the real delivery pipeline: the sandbox signing secret, the same headers, the delivery log and the retries. Call it with your sk_test_ key.

curl https://api.layout.link/v1/sandbox/webhooks/fire \
  -H "Authorization: Bearer $LAYOUT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "event": "order.unconfirmed", "orderId": "ord_7c21" }'

200 OK

{
  "event": "order.unconfirmed",
  "deliveries": [
    { "id": "dl_9f3a2c", "url": "https://example.com/layout/webhooks", "outcome": "delivered" }
  ]
}

• event is any event type except order.needs_approval, which is reserved and never sent.
• orderId is optional. With one of your sandbox orders, the event describes that order. Without it, the event describes a test order whose ids match nothing.
• Every fired event carries "test": true, like the console's Send test event.
• outcome is delivered when your endpoint answered 2xx, retry when it did not and the ordinary retry schedule takes over, and dead when retries are exhausted.
• A sk_live_ key is refused with 403 forbidden. No endpoint subscribed to the event, or an orderId that is not one of your sandbox orders, is a 404 not_found that says which.
• 1,000 a day for each developer account and 30 a minute for each key, refused with 429 rate_limited.