Skip to content
Maple

    Bookings

    List bookings

    Lists bookings across the locations the app is granted (or one `location_id`).

    GEThttps://api.maple.inc/v1/bookingsAPI 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 <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.

    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.

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