Skip to content
Maple

    Bookings

    Create booking

    Books the party a hold claims, synchronously, and returns the full `booking`.

    POSThttps://api.maple.inc/v1/bookingsAPI key

    Books the party a hold claims, synchronously, and returns the full booking. The location is the hold’s. status follows the venue’s acceptance mode (confirmed, or requested where the venue confirms by hand) and version starts at 0. A guest contact is required on this channel. Writes carry a body-level idempotency_key. Native and provider writes replay the same booking without reapplying the mutation. An uncertain provider result answers 409 operation_in_progress; retry the same key and body. If details.reason is replay_window_expired, contact support with the operation id rather than issuing a new key. Typed refusals: 409 hold_expired / hold_consumed / overlapping_booking / idempotency_key_reused; 422 guest_contact_required, outside_booking_window, payment_instrument_required, provider_rejected; 400 invalid_phone. 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.

    • hold_id string required

      The hold to book from (POST /booking_holds).

    • slot_token string or null

      Optional for existing integrations. The persisted hold supplies the authoritative quote for native and provider-managed locations.

    • guest object required

    • guest.first_name string required

    • guest.last_name string required

    • guest.phone string required

      E.164. A partner booking must carry a reachable guest contact; the venue contacts the guest here.

    • guest.email string or null

    • notes string or null

      The guest’s note to the venue.

    • intake_answers object[] or null

      Structured intake for native bookings. OpenTable does not support these answers and returns 422 capability_unsupported instead of dropping them.

    • intake_answers[].question_ref string required

      The venue’s intake question reference.

    • intake_answers[].answer string or boolean or number or string[] required

      Free text, yes/no, a number, or the chosen option references — per the question’s kind.

    • idempotency_key string required

      Your unique key for this write (body-level, scoped to your app). Retrying with the same key and the same request replays the same booking; the same key with a different request 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.

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