> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maple.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Seat a walk-in

> Seats a party that just arrived at the earliest table that fits it now, as the venue, and returns the `booking` (`status: seated`, `channel: walk_in`).

POST`https://api.maple.inc/v1/locations/{locationId}/walk_ins`API key

Seats a party that just arrived at the earliest table that fits it now, as the venue, and returns the `booking` (`status: seated`, `channel: walk_in`). Maple picks the table; there is no force-book. No table free now answers 409 `slot_unavailable` (its message names the next opening). Retry-safe under `idempotency_key`: a retry returns the same booking. Maple-native locations only (422 `capability_unsupported` otherwise). Requires `bookings:manage`.

## Authorization

Send your API key as `Authorization: Bearer <key>`: `mpk_test_…` against the sandbox (`https://api.staging.maple.inc/v1`), `mpk_live_…` against production. See [Authentication](https://docs.maple.inc/developer-api/concepts/authentication.md). The samples read the key from `MAPLE_KEY` and the base URL from `MAPLE_BASE`, as set up in the [Quickstart](https://docs.maple.inc/developer-api/quickstart.md).

## Parameters

- `locationId` string path required

## Request body

`application/json`, required.

- `party_size` integer required

  At least 1.

- `guest` object required

- `guest.first_name` string required

- `guest.last_name` string or null

- `guest.phone` string required

- `guest.email` string or null

- `notes` string or null

  The guest’s note to the venue.

- `idempotency_key` string required

  Your unique key for this walk-in, scoped to your app across all its locations. Retrying with the same key and the same request returns the same booking, even though its table is now taken; the same key with a different request, including another location, answers 409 `idempotency_key_reused`. Up to 255 characters.

## Responses

### 200 OK

- `object` string required

  Always `booking`.

- `id` string required

  Opaque, prefixed `bkg_…`.

- `livemode` boolean required

- `created` number required

- `version` number required

- `location_id` string required

- `status` string required

  One of `requested`, `confirmed`, `seated`, `completed`, `declined_by_venue`, `cancelled_by_guest`, `cancelled_by_venue`, `cancelled_unattributed`, `no_show`.

- `service_state` string or null required

- `confirmation_code` string required

- `starts_at` string required

  ISO-8601 UTC instant.

- `starts_at_local` string required

  Venue wall-clock, `YYYY-MM-DDTHH:MM`.

- `service_date` string required

  The venue service day the booking belongs to, `YYYY-MM-DD`.

- `duration_minutes` number or null required

  Turn duration; null on provider-managed bookings, where Maple never invents one.

- `party_size` number required

- `guest` object required

- `guest.first_name` string or null required

- `guest.last_name` string or null required

- `guest.phone` string or null required

  E.164, when the guest left one.

- `guest.phone_last_four` string or null required

- `guest.email` string or null required

- `notes` string or null required

  The guest-facing note; venue-internal notes are never exposed.

- `channel` string required

  The channel the booking originated on, e.g. `api_partner`, `voice_ai`, `internal`.

- `provider` string required

  One of `maple`, `opentable`, `resy`, `sevenrooms`.

- `cancellation_policy` object or null required

- `cancellation_policy.type` string required

- `cancellation_policy.currency` string or null required

  ISO-4217.

- `cancellation_policy.policy_text` string or null required

- `cancellation_policy.tiers` object\[] required

- `cancellation_policy.tiers[].within_hours_before_start` number required

- `cancellation_policy.tiers[].basis` string required

  `per_party` or `per_person`.

- `cancellation_policy.tiers[].amount_cents` number or null required

- `cancellation_policy.tiers[].percent_bps` number or null required

  Basis points of the party value, when the fee is a percentage.

- `cancellation_policy.deposit` object or null required

- `cancellation_policy.deposit.amount_cents` number required

- `cancellation_policy.deposit.currency` string required

- `cancellation_policy.deposit.basis` string required

- `experience` object or null required

  The experience booked (prix fixe, ticketed seating), or null for a standard reservation.

- `experience.id` string required

- `experience.name` string or null required

  Null when Maple has not seen the name.

- `updated_at` string required

  ISO-8601 UTC instant.

### Errors

- `400` Bad request DeveloperApiBadRequest

- `401` Unauthorized DeveloperApiUnauthorized

- `403` Forbidden DeveloperApiForbidden

- `404` Not found DeveloperApiNotFound

- `409` Conflict DeveloperApiConflict

- `422` Unprocessable DeveloperApiUnprocessable

- `429` Too many requests DeveloperApiRateLimited

Every error body names the error in `_tag`, explains it in `message`, and says where to report it in `feedback`. See [Errors](https://docs.maple.inc/developer-api/concepts/errors.md).

A `429` also sends `Retry-After`: Seconds to wait before retrying; also returned as retry\_after in the body.

Seat a walk-in

```sh
curl "$MAPLE_BASE/locations/str_123/walk_ins" \
  -H "Authorization: Bearer $MAPLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"party_size":1,"guest":{"first_name":"Ada","phone":"+15555550123"},"idempotency_key":"9f8c7a52-3b1d-4e0a-8c55-2f1e6d4b7a90"}'
```

```python
import os
import requests


r = requests.post(
    f"{os.environ['MAPLE_BASE']}/locations/str_123/walk_ins",
    headers={"Authorization": f"Bearer {os.environ['MAPLE_KEY']}"},
    json={
        "party_size": 1,
        "guest": {
            "first_name": "Ada",
            "phone": "+15555550123",
        },
        "idempotency_key": "9f8c7a52-3b1d-4e0a-8c55-2f1e6d4b7a90",
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())
```

```js
const res = await fetch(`${process.env.MAPLE_BASE}/locations/str_123/walk_ins`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAPLE_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "party_size": 1,
    "guest": {
      "first_name": "Ada",
      "phone": "+15555550123"
    },
    "idempotency_key": "9f8c7a52-3b1d-4e0a-8c55-2f1e6d4b7a90"
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log(await res.json());
```

```json
{
  "object": "booking",
  "id": "string",
  "livemode": true,
  "created": 1.5,
  "version": 1.5,
  "location_id": "str_123",
  "status": "requested",
  "service_state": "expected",
  "confirmation_code": "string",
  "starts_at": "string",
  "starts_at_local": "2026-11-20T18:00",
  "service_date": "string",
  "duration_minutes": 1.5,
  "party_size": 1.5,
  "guest": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "phone": "+15555550123",
    "phone_last_four": "string",
    "email": "guest@example.com"
  },
  "notes": "string",
  "channel": "string",
  "provider": "maple",
  "cancellation_policy": {
    "type": "string",
    "currency": "USD",
    "policy_text": "string",
    "tiers": [
      {
        "within_hours_before_start": 1.5,
        "basis": "string",
        "amount_cents": 1.5,
        "percent_bps": 1.5
      }
    ],
    "deposit": {
      "amount_cents": 1.5,
      "currency": "USD",
      "basis": "string"
    }
  },
  "experience": {
    "id": "string",
    "name": "string"
  },
  "updated_at": "string"
}
```

```json
{
  "_tag": "DeveloperApiBadRequest",
  "code": "string",
  "message": "string",
  "feedback": "string"
}
```