> ## 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.

# Hold a slot

> Claims a quoted slot’s capacity until `expires_at` (see the location’s `hold_ttl_seconds`), so the party can be booked with `POST /bookings`.

POST`https://api.maple.inc/v1/booking_holds`API key

Claims a quoted slot’s capacity until `expires_at` (see the location’s `hold_ttl_seconds`), so the party can be booked with `POST /bookings`. The location is the one the token was quoted for and must be granted to the app. A slot whose capacity is gone answers 409 `slot_unavailable`; a tampered or stale token 400 `invalid_slot_token` / `expired_slot_token`; a time too soon for the venue 422 `outside_booking_window`; a time that needs a card 422 `payment_instrument_required`. Each app may have ten live or pending holds per location, enforced atomically for native and provider holds. All hold IDs use bkh\_; only the creating app can release or consume them. Over quota answers 429 with retry\_after and Retry-After. Pending provider acquisitions answer 409 operation\_in\_progress; replay the same token. Requires `bookings:write`.

## 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).

## Request body

`application/json`, required.

- `slot_token` string required

  A `slot_token` from a booking availability search, unchanged.

## Responses

### 200 OK

- `object` string required

  Always `booking_hold`.

- `id` string required

  Opaque. `bkh_…` for a hold in Maple’s ledger; at a provider-managed location, the provider’s own hold token. Round-trip it unchanged.

- `livemode` boolean required

- `created` number required

- `location_id` string required

- `starts_at` string required

  ISO-8601 UTC instant of the held slot.

- `party_size` number required

- `expires_at` string required

  ISO-8601 UTC instant after which the hold no longer claims capacity.

### 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.

Hold a slot

```sh
curl "$MAPLE_BASE/booking_holds" \
  -H "Authorization: Bearer $MAPLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slot_token":"string"}'
```

```python
import os
import requests


r = requests.post(
    f"{os.environ['MAPLE_BASE']}/booking_holds",
    headers={"Authorization": f"Bearer {os.environ['MAPLE_KEY']}"},
    json={
        "slot_token": "string",
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())
```

```js
const res = await fetch(`${process.env.MAPLE_BASE}/booking_holds`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAPLE_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "slot_token": "string"
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log(await res.json());
```

```json
{
  "object": "booking_hold",
  "id": "string",
  "livemode": true,
  "created": 1.5,
  "location_id": "str_123",
  "starts_at": "string",
  "party_size": 1.5,
  "expires_at": "string"
}
```

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