Bookings

Bookings are the heart of the API. A booking reserves capacity on an availability slot of an experience option for a specific variant (group-size / pricing tier), on behalf of a traveler.

Lifecycle

Bookings are created through orders (POST /v2/booking-orders) and start in ON_HOLD (reserved in a shopping cart for 15 minutes). Confirming the order transitions each booking to ACCEPTED (instantly-confirmable slots) or PENDING (organizer must accept within an expiration window). From there:

  • PENDING → ACCEPTED — organizer accepts (POST /v2/bookings/{id}/accept)
  • PENDING → REJECTED — organizer rejects (POST /v2/bookings/{id}/reject), or the reservation timer (reservationExpiresAt) runs out
  • PENDING (alternatives offered) → ACCEPTED — traveler accepts one of the organizer's alternative slots (POST /v2/bookings/{id}/accept-alternative)
  • REJECTED → PENDING — reinstated with a fresh response window (POST /v2/bookings/{id}/reinstate)
  • REJECTED → ACCEPTED — organizer or the booking's reseller recovers a rejected booking (reseller-collected payments only; see accept)
  • ACCEPTED → COMPLETED — the experience time passes (scheduled task), or manually for past-dated bookings (POST /v2/bookings/{id}/mark-completed)
  • COMPLETED → ACCEPTED — a completed booking rescheduled to a future slot re-enters the lifecycle (POST /v2/bookings/{id}/reschedule)
  • ACCEPTED/COMPLETED → NO_SHOW — traveler did not show up (in-house only)
  • any live status → CANCELLED — via POST /v2/bookings/{id}/cancel
  • ON_HOLD → EXPIRED — hold timer runs out, or the ON_HOLD booking is cancelled
  • REMOVED — removed from the cart; never returned by this API

Status values

ON_HOLD, PENDING, ACCEPTED, COMPLETED, CANCELLED, EXPIRED, NO_SHOW, REJECTED, REMOVED. The list/retrieve endpoints exclude REMOVED and soft-deleted bookings entirely.

Access scoping

All endpoints authenticate with the global API-key scheme (x-api-key + x-partner-id). Resellers see only bookings they sold (reseller = caller); organizers see only bookings on their own experiences; BOTH partners see the union. A booking outside the caller's scope behaves as if it does not exist (404), so existence is never leaked across partners.

All wire payloads are camelCase; request bodies accept camelCase or snake_case.

Endpoints