Skip to content
Maple

    Bookings

    Change booking

    Moves a booking using a native reschedule quote (changing_booking_id), or an ordinary provider availability quote, and returns the updated booking.

    POSThttps://api.maple.inc/v1/bookings/{bookingId}/changeAPI key

    Moves a booking using a native reschedule quote (changing_booking_id), or an ordinary provider availability quote, and returns the updated booking. To change only the guest’s note, send notes without slot_token: the booking keeps its time, party size and claim, so no quote is needed; neither field answers 400 change_required. Provider writes claim the mirrored version before I/O; a competing or uncertain write answers 409 operation_in_progress. Retry the same key and body; completed replays bypass the old expected_version. Pass expected_version to refuse a change on a booking that moved on (409 stale_version). A booking the venue’s policy no longer lets the guest change answers 409 not_changeable with details.reason, as does one OpenTable refuses because it has started or is about to (outside_policy_window); a slot whose capacity is gone 409 slot_unavailable; a new time too soon 422 outside_booking_window. 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.

    Parameters

    • bookingId string path required

    Request body

    application/json, required.

    • slot_token string or null

      Moves the booking to this slot: a slot_token for the booking’s location from a reschedule search with changing_booking_id for native bookings, or an ordinary availability quote for provider-managed bookings. Omit it to change only notes; send at least one of the two.

    • notes string or null

      Replaces the guest’s note ("" clears it); at OpenTable, the reservation’s special request. Sent without slot_token, it changes only the note: no new quote, and the time and party size stay as they are. A guest-side note change closes when the reservation starts. If OpenTable does not confirm the note, the change returns 422 capability_unsupported.

    • expected_version integer or null

      Optimistic concurrency: the version you last read. A booking that moved on since answers 409 stale_version with details.expected/actual.

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