Bookings

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

POSThttps://api.maple.inc/v1/booking_holdsAPI 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. The samples read the key from MAPLE_KEY and the base URL from MAPLE_BASE, as set up in the Quickstart.

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.

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

Hold a slot

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

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())

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());

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

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