Table of Contents

Booking flow

Holding a booking with the V2 API is a four-stage flow: search → create → optional modify (cabin choice, 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}
Read the held booking GET /bookings/create/voyage-only/{:sessionId} GET /bookings/create/package/{:sessionId}
List available cabin numbers GET /bookings/create/voyage-only/{:sessionId}/cabin-numbers GET /bookings/create/package/{:sessionId}/cabin-numbers
Book a specific cabin POST /bookings/create/voyage-only/{:sessionId}/cabin-numbers POST /bookings/create/package/{:sessionId}/cabin-numbers
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. Cabins are reserved at grade level: the booking holds a guarantee cabin of that grade, and the individual cabin number is assigned before departure unless one is chosen explicitly (see below). 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.

Where the port the ship boards at (departurePort) carries an embarkation instruction for the traveller — when to be at the terminal, or that boarding is by tender boat — the held booking carries it in embarkationNotification, as does every later response that carries the booking. It is a localized array ([{ locale, value }], see Locale and market) and is null when no instruction applies to this departure. The text is informational — it never affects pricing or availability — and is intended to be shown to the traveller. Read it from the booking response rather than caching it against a port code; port information changes.

3. Choose a specific cabin (optional)

A held booking can be moved off its guarantee cabin onto a named one, and back again by sending null. Some grades do not correspond to specific cabins at all; for those, both calls below return 400. GET .../cabin-numbers?cabinGrade= lists the cabin numbers currently available for one grade on the booking, grouped by deck; POST .../cabin-numbers books a chosen number. Both take the grade code the booking already holds, so call the GET once per grade, and call it again before each POST — the available numbers are recorded against the session and discarded once an apply succeeds.

Availability is shared with every other booking, so a cabin can be taken between listing and applying. That returns 409 with the booking unchanged; nothing is ever silently substituted. Once the booking is confirmed the cabins are fixed.

See List Available Cabin Numbers and Apply a Cabin Number — and the package equivalents.

4. 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. Cabin numbers are not one of them — they have no DELETE, and are covered above.

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.

5. 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 full booking — the persistent booking id, its status, the booking contents (same shape as the held-booking response), and the customer details supplied in the request mirrored back under guests[].customerDetails.

See also