Cruise booking flow
Cruise bookings use Open API v2. The channel client handles itinerary and cabin selection and collects traveler details; the channel server signs requests and manages orders. All endpoints below use POST; the environment host and version prefix are omitted.
sequenceDiagram
accTitle: Cruise booking flow
accDescr: Search itineraries and fares, select and hold a cabin, obtain a quote for the travelers, and book using channel credit. Release the hold if the user abandons the selection.
autonumber
box rgb(235, 247, 243) Channel
participant C as Channel client
participant S as Channel server
end
box rgb(255, 246, 229) YSystem
participant Y as YSystem server
end
C->>S: Search itineraries (dates, destination)
S->>Y: /cruise/itinerary/search
Y-->>S: Itineraries (itineraryId)
S-->>C: Display itineraries
C->>S: Select an itinerary and guest counts
S->>Y: /cruise/fares
Y-->>S: Cabin categories, fares and cancellation policies
S-->>C: Display categories and fares
C->>S: Select a category and fare
S->>Y: /cruise/cabin/availability
Y-->>S: Available cabins
S-->>C: Display cabins
C->>S: Select a cabin (cabinNo)
S->>Y: /cruise/cabin/hold
Y-->>S: holdId, expiresAt
S-->>C: Show hold expiry and request traveler details
C->>S: Submit traveler details
S->>Y: /cruise/price
Y-->>S: priceId, expiresAt, price breakdown
S->>Y: /cruise/cabin/diningOptions
Y-->>S: Dining options
S-->>C: Display quote, terms and dining options
alt User confirms the booking
C->>S: Confirm price, travelers and dining
S->>Y: /cruise/book (priceId, travelers, cabinNo)
Y->>Y: Validate quote and travelers, create order and use channel credit
Y-->>S: Order or business error
S-->>C: Display order status or failure reason
opt Order is awaiting confirmation
S->>Y: /order/search
Y-->>S: Latest order and booking result
S-->>C: Update booking status
end
else User abandons or changes the cabin
C->>S: Cancel current selection
S->>Y: /cruise/cabin/release (holdId)
Y-->>S: Release result
S-->>C: Update cabin selection status
end
Integration notes
/cruise/itinerary/searchreturnsboardingTime,departureTime, andarrivalTimeinitineraries[].stops[]when the supplier provides them. All three useHH:mm; unavailable fields are omitted. The existingtimefield remains an alias for departure time. Stop dates belong to the route's representative itinerary./cruise/faresreturns cabin categories and fares. Use the selectedcategoryCodeandfareCodefor subsequent queries and quotes. Show the price breakdown from/cruise/pricebefore booking.- In cruise
minPriceDetailandpriceDetail,aggregated.quantityis1: the total is calculated as one price item. It is not the guest count./cruise/faresuses the adult and child counts inguestto request fares;/cruise/pricequotes fortravelers. Display the total using the correspondingminPrice,fare.price, orprice. guestPrices[]in the/cruise/priceresponse retains each traveler's supplier USD amount andbreakdown[], and provides converted amounts inapproximateandbreakdown[].approximateusingpreferred.currency. Amounts are rounded separately, so the sum of converted traveler prices may differ slightly from the totalprice.amount. Useprice.amountas the booking total.- Cabin holds and quotes have separate expiry times; use each response's
expiresAt. Recheck cabin availability after a hold expires. Obtain a new quote and ask the user to confirm it after a quote expires. - A
priceIdbelongs to the current channel and quoting user and can only be used for one booking. The booking'stravelersmust match the quote. Request a new quote if traveler details change. - Open API cruise bookings use the channel's cruise credit facility. Arrange access and sufficient credit before booking. Receiving an order does not mean the supplier has confirmed it; check the order status and booking result.
- When the user abandons the booking or changes cabins, release the original hold using its specific
holdId. A cabin hold is temporary and does not create an order. - The channel server signs requests; see Request authentication and signing.
Traveler fields
travelers in /cruise/price is an array. Provide each traveler's own details, and send the same traveler details when calling /cruise/book. The following shows one traveler; the full quote request also needs itineraryId, categoryCode, fareCode, and other parameters:
{
"firstName": "三",
"lastName": "张",
"firstNameEn": "SAN",
"lastNameEn": "ZHANG",
"gender": "M",
"birthday": "1989-01-01",
"nationality": "CN",
"telephoneCountryCode": "86",
"telephone": "13800000000",
"email": "traveler@example.com"
}
firstNameEnis the given name andlastNameEnis the family name. They correspond tofirstNameandlastName, respectively. UseMorFforgender.birthdaymust matchYYYY-MM-DD(recommended) orYYYYMMDDexactly, with zero-padded month and day.1989-1-1is invalid.nationalitymust be an ISO 3166-1 alpha-2 code, such asCNfor China. Do not send1or中国.nationalityNameis for display in order responses and does not replacenationalityin requests.telephoneCountryCodeis the country calling code, such as86for mainland China. Do not use a city area code such as0514.- For
CRUISE_TRAVELER_INVALID, check for missing English names or nationality, an unsupported gender, and an invalid birthday format. The current error message does not identify the specific field. Also use the nationality and country calling code formats above to avoid later quote or booking failures.
Try the Cruise API Demo to explore the flow. See the v2 cruise reference for full field definitions.