Table of Contents

Booking flow

Holding a booking with the V2 API is a four-stage flow: search → create → optional modify (addons / excursions / supplemental tours) → confirm. Voyage-only and package variants share the same flow; only the entry endpoint and a few package-specific fields differ.

At a glance

Stage Voyage-only Package
Search POST /search/voyages POST /search/packages
Create held booking POST /bookings/create/voyage-only/{:sessionId} POST /bookings/create/package/{:sessionId}
Get applicable addons / excursions / tours GET /bookings/create/voyage-only/{:sessionId}/{addons,excursions,supplemental-tours} GET /bookings/create/package/{:sessionId}/{addons,excursions,supplemental-tours}
Apply / remove a sub-resource POST / DELETE on the same path POST / DELETE on the same path
Confirm POST /bookings/create/voyage-only/{:sessionId}/confirm POST /bookings/create/package/{:sessionId}/confirm

Every call requires the agency user_key query parameter and a bearer token. See Getting Started for the auth handshake.

A search establishes a session that binds the rest of the flow. The response carries a sessionId (UUID) — pass it into every subsequent call until confirm.

Each passenger requested at search receives a 1-based guestId (1, 2, …) used to reference that passenger across every later call.

Vehicles (voyage-only) can only be requested at search time and are bound to the first passenger; they cannot be added to or removed from a held booking later.

2. Create the held booking

The create call reserves the chosen cabin(s) inside the session and produces the held booking. A session can hold one booking at a time; a second create returns 409. The response is the canonical held-booking shape — every booking-API endpoint that carries a held booking returns the same shape.

Mandatory items are auto-included on the held booking and already priced into the total. Do not re-apply them.

3. Modify the held booking

Three sub-resources can be attached before confirm: addons, excursions, and supplemental tours. Each exposes the same triple of endpoints under both variants.

Verb Purpose Returns
GET List items applicable to the current booking. Applicable-list shape (resource-specific).
POST Apply one or more items. Full held booking, with the total recalculated.
DELETE Remove one or more items. Full held booking, with the total recalculated.

Modify the booking any number of times before confirm.

Sub-resource scoping rules:

  • Addons and excursions are per-passenger. Each apply/remove call selects the passengers it applies to.
  • Supplemental tours are whole-booking — always attached to every passenger and removed from every passenger together. At most one pre-cruise (Arrival) tour and one post-cruise (Departure) tour can be on a booking at any time.
  • Items marked mandatory cannot be removed.

4. Confirm

Confirm finalizes the held booking by submitting passenger details, one entry per passenger keyed by the guestId assigned at search. One passenger must be designated the lead and carries additional contact and address fields.

Each passenger's age at the voyage's departure date must fall within the band for the category they were booked under at search.

A successful confirm returns the persistent booking identifier.

See also