Table of Contents

Frequently Asked Questions

How do I get credentials? Contact our support team via the support portal to have your credentials created. You will receive a client_id and client_secret for Auth0 authentication, plus a user_key identifying your agency.

Which API should I use?

  • Flat files API — the simplest way to get bulk product data (sailings, ships, cabin grades, excursions, ports, pricing, itineraries) as a downloadable ZIP archive. Best for keeping a local copy of inventory in sync.
  • Seaware API (SwOTA) — a real-time cruise booking API for searching, booking, and managing reservations directly against our Seaware reservation system.

The Polar Global API is obsolete and should not be used for new integrations.

What environments are available?

Always build and test against staging before moving to production.

How do I authenticate? All APIs use Auth0 bearer tokens. Request a token from the Auth0 token endpoint using your client_id and client_secret, then pass it as a bearer token in the Authorization header.

How long are tokens valid? Tokens are short-lived. Cache the token and reuse it until it is close to expiry rather than requesting a new token per call.

My request returns 401 Unauthorized — what's wrong? Check that the token is valid and not expired, that you are sending it in the Authorization: Bearer header, and that you requested it with the correct audience for the environment you are calling.

Which value identifies the product I'm booking? In the booking process you must use the TourCode exactly as it appears in the SourceMarket flat file, including the leading underscore-at prefix. Do not strip or modify it. For example, given this SourceMarket record:

{
  "MasterSailingId": 1241,
  "MasterPackageId": 102801,
  "Currency": "GBP",
  "Category": "MF",
  "VoyageLink": "ARUSH-ARUSH-10N",
  "RateCode": "BESTPRICE",
  "TourCode": "_@FNANT01-261109",
  "TourStartDate": "2026-11-09",
  "TourEndDate": "2026-11-20"
}

the value to pass in the booking request is _@FNANT01-261109.

Note

A single sailing can carry multiple TourCode variants (e.g. FNANT01 and FNANT01R) representing different bookable products on the same sailing, so make sure you book the exact TourCode you intend.

Can I place a booking that includes children via the API? Yes, but we do have varying rules across some of our destinations.

  • Antarctica & South Georgia — we're unable to carry children under 5 years.
  • Galapagos Islands — we're unable to carry children under 5 years, and travellers under 12 require a signed release of responsibility. These bookings must be made by our GX team, who will make the necessary checks.

Can I place a booking that includes infants via the API? Not at the moment. Please reach out to our support team directly and they'll take care of the booking for you. We're aware this is a gap and are working on adding support for bookings that include infants to the API.

Which source should I trust for sailing availability? The API and flat files are the primary, authoritative sources for sailing availability and always contain the most up-to-date information. The B2C website is a secondary, downstream view: it can take a few hours to catch up after data changes. If the website and the API/flat files disagree, the API/flat files are correct.

Why does the website show a sailing that I can't book via the API/flat file? Bookings close 14 days prior to sailing. Because the website updates on a delay, you may still see a sailing on the website after it has already become unavailable to book in the flat file or API. This is expected — treat the API/flat file as the source of truth for what is bookable.

Note

Always validate what is bookable against the API/flat files, not the website.

How should I test availability? Do not validate availability from Flat files V1/V3 against the B2C portal — the portal lags behind and will give misleading results. Test availability against the API instead.

What's the difference between DepartureDate and EmbarkationTime? Package bounds — whole booked trip incl. pre/post hotel nights, flights, transfers, land add-ons vs actual ship boarding/leaving (sailing window only).

"DepartureDate": "2026-09-06",
"ArrivalDate": "2026-09-23"

Ex: Sept 6 = arrive Seattle, hotel night (not on ship). Sept 23 = final day of package, disembark morning.

"EmbarkationTime": "2026-09-07T22:00:00",
"DisembarkationTime": "2026-09-23T08:00:00"

Ex: board ship Sept 7 22:00, after day 2 flight Seattle→Nome. Leave ship Sept 23 08:00. Gap Sept 6→7 is pre-cruise hotel plus flight to embarkation port, not sailing yet.

Where do I get itinerary details (FHT)? The SwOTA API does not return the FHT in its descriptions. To retrieve full itinerary details, use flat files V1/V3.

Why are some cruises missing from my SailingDateRange search? Check whether you're setting both a start date window and an end date window. Together they filter on both ends: only sailings starting after the start window's earliest date AND ending before the end window's latest date are returned. A cruise that starts inside your window but ends after that latest date, because of its length, gets excluded.

How do I search for cruises starting between two dates, regardless of when they end? Set the earliest and latest date on the start date window only, and omit the end date window entirely:

<SailingDateRange>
    <StartDateWindow EarliestDate="2027-05-27" LatestDate="2027-05-31"/>
</SailingDateRange>

This filters purely on sailing start date.

When should I use an end date window? Use it when you need to constrain the sailing's end date too — e.g. it must finish by a given date — independent of or in addition to a start-date constraint. Combining it with the start date window narrows results further and may exclude longer cruises that start in your desired window.

Why don't waitlisted voyages show up in my availability results? Availability calls return only available (36) and guarantee (47) inventory by default. To see waitlisted voyages, list the statuses you want in SearchQualifiers/Status. These replace the default filter, so 46 (Waitlisted) on its own returns waitlisted results only. Status 38 (Closed) maps to Seaware's ALL availability mode, so the 38/46/47 combination below returns everything — available, guarantee and waitlisted — which is normally what you want.

Where the element goes differs per call:

<SearchQualifiers>
    <Status Status="38"/>
    <Status Status="46"/>
    <Status Status="47"/>
</SearchQualifiers>

Each returned sailing or category carries its own Status attribute, so waitlisted results can be told apart from bookable ones.

Where do I report issues or ask questions? Open a ticket in the support portal. Include the environment, the endpoint, a request/response sample, and a timestamp so we can locate the call in our logs.