> ## 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. # List bookings > Lists bookings across the locations the app is granted (or one `location_id`). GET`https://api.maple.inc/v1/bookings`API key Lists bookings across the locations the app is granted (or one `location_id`). Two modes: a bounded slot window (`start`/`end`, at most 31 days, default the next 7 days) ordered by slot start, or `updated_since`, which drains bookings updated after an exclusive checkpoint oldest-first so a partner can catch up after downtime. Page with `limit` and the previous page’s `next_cursor` as `starting_after`; `has_more` says whether another page exists. Ties on the ordering timestamp never skip or repeat, and a booking that changes between pages simply re-enters the feed. Take the next `updated_since` checkpoint from the newest `updated_at` you have processed minus a few seconds of overlap and dedupe by `id` + `version`: a booking committed after your drain can carry an `updated_at` set when its transaction began. To find the booking a guest is calling about, pass `location_id` with `phone` and/or `confirmation_code`: without a window this matches bookings at any time, ordered by slot start; add `start`/`end` to narrow it. At a provider-managed location a lookup with `phone` first checks the provider, so a reservation made directly there is found; a code-only lookup covers the reservations Maple already knows about. A lookup without `location_id` answers 400 `location_required`, an unusable phone 400 `invalid_phone`. Locations the bookings surface is not switched on for are omitted (an explicit `location_id` answers 422 `bookings_not_enabled`). Requires `bookings:read`. ## Authorization Send your API key as `Authorization: Bearer `: `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 - `location_id` string or null query - `start` string or null query - `end` string or null query - `updated_since` string or null query - `status` string or null query - `phone` string or null query - `confirmation_code` string or null query - `starting_after` string or null query - `limit` string or null query ## Responses ### 200 OK - `object` string required Always `list`. - `data` object\[] required - `data[].object` string required Always `booking`. - `data[].id` string required Opaque, prefixed `bkg_…`. - `data[].livemode` boolean required - `data[].created` number required - `data[].version` number required - `data[].location_id` string required - `data[].status` string required One of `requested`, `confirmed`, `seated`, `completed`, `declined_by_venue`, `cancelled_by_guest`, `cancelled_by_venue`, `cancelled_unattributed`, `no_show`. - `data[].service_state` string or null required - `data[].confirmation_code` string required - `data[].starts_at` string required ISO-8601 UTC instant. - `data[].starts_at_local` string required Venue wall-clock, `YYYY-MM-DDTHH:MM`. - `data[].service_date` string required The venue service day the booking belongs to, `YYYY-MM-DD`. - `data[].duration_minutes` number or null required Turn duration; null on provider-managed bookings, where Maple never invents one. - `data[].party_size` number required - `data[].guest` object required - `data[].guest.first_name` string or null required - `data[].guest.last_name` string or null required - `data[].guest.phone` string or null required E.164, when the guest left one. - `data[].guest.phone_last_four` string or null required - `data[].guest.email` string or null required - `data[].notes` string or null required The guest-facing note; venue-internal notes are never exposed. - `data[].channel` string required The channel the booking originated on, e.g. `api_partner`, `voice_ai`, `internal`. - `data[].provider` string required One of `maple`, `opentable`, `resy`, `sevenrooms`. - `data[].cancellation_policy` object or null required - `data[].cancellation_policy.type` string required - `data[].cancellation_policy.currency` string or null required ISO-4217. - `data[].cancellation_policy.policy_text` string or null required - `data[].cancellation_policy.tiers` object\[] required - `data[].cancellation_policy.tiers[].within_hours_before_start` number required - `data[].cancellation_policy.tiers[].basis` string required `per_party` or `per_person`. - `data[].cancellation_policy.tiers[].amount_cents` number or null required - `data[].cancellation_policy.tiers[].percent_bps` number or null required Basis points of the party value, when the fee is a percentage. - `data[].cancellation_policy.deposit` object or null required - `data[].cancellation_policy.deposit.amount_cents` number required - `data[].cancellation_policy.deposit.currency` string required - `data[].cancellation_policy.deposit.basis` string required - `data[].experience` object or null required The experience booked (prix fixe, ticketed seating), or null for a standard reservation. - `data[].experience.id` string required - `data[].experience.name` string or null required Null when Maple has not seen the name. - `data[].updated_at` string required ISO-8601 UTC instant. - `has_more` boolean required - `next_cursor` string or null required Opaque cursor for the next page — pass it back as `starting_after`. Null on the last page. It encodes the position observed on this page, so it stays correct even if the last booking changes in between. ### Errors - `400` Bad request DeveloperApiBadRequest - `401` Unauthorized DeveloperApiUnauthorized - `403` Forbidden DeveloperApiForbidden - `404` Not found DeveloperApiNotFound - `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. List bookings ```sh curl "$MAPLE_BASE/bookings" \ -H "Authorization: Bearer $MAPLE_KEY" ``` ```python import os import requests r = requests.get( f"{os.environ['MAPLE_BASE']}/bookings", headers={"Authorization": f"Bearer {os.environ['MAPLE_KEY']}"}, timeout=30, ) r.raise_for_status() print(r.json()) ``` ```js const res = await fetch(`${process.env.MAPLE_BASE}/bookings`, { headers: { Authorization: `Bearer ${process.env.MAPLE_KEY}`, }, }); if (!res.ok) throw new Error(`HTTP ${res.status}`); console.log(await res.json()); ``` ```json { "object": "list", "data": [ { "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": null, "basis": "string", "amount_cents": null, "percent_bps": null } ], "deposit": { "amount_cents": null, "currency": "USD", "basis": "string" } }, "experience": { "id": "string", "name": "string" }, "updated_at": "string" } ], "has_more": true, "next_cursor": "string" } ``` ```json { "_tag": "DeveloperApiBadRequest", "code": "string", "message": "string", "feedback": "string" } ```