Operational notes
Practical guidance for integrating against the V2 API.
Bearer token caching
The Auth0 token endpoint returns an expires_in value (seconds). Cache the token and re-use it until close to expiry — typically the token is valid for 24 hours. Re-issue before it expires; a 401 from the V2 API most often indicates an expired token.
Inventory polling cadence
Inventory is produced on a periodic cadence — currently twice per day. Polling more frequently does not yield fresher data. See Identifier stability for which identifiers persist across refreshes and which do not.
Image URLs
Image URLs in media fields are protocol-relative — they begin with // (for example, //images.ctfassets.net/...). Prepend https: when fetching, embedding, or storing the URL.
Date and time precision
Dates without a time component use YYYY-MM-DD (for example, 2026-01-10).
Timestamps come in two forms across the API:
- ISO 8601 without timezone:
2026-01-10T20:30:00. Used for voyage departure / arrival timestamps. Treat these as local to the voyage's port. - ISO 8601 with offset:
2025-10-01T06:00:00+02:00. Used for promotion validity windows.
Send timestamps in the form shown by the response sample for the relevant endpoint.
Currency precision
Prices are numeric and may include a fractional component (106.0, 13618, 2500.50). The number of decimals is currency-specific — render prices in your own UI using the locale conventions for the response's currency.
priceBreakdown.totalPrice always equals the sum of its component price arrays. Trust the components if you ever see a mismatch.
Rate limiting
Requests are rate limited per agency. Each agency (identified by its user_key) may make up to 100 requests per 60 seconds across the V2 API.
When you exceed the limit, the API responds with 429 Too Many Requests and a Retry-After header giving the number of whole seconds to wait before the limit resets. Respect it: pause requests until that time has passed, then resume. Limits and windows may change, so treat the Retry-After header — not a hard-coded delay — as the source of truth for how long to back off.