Real-Time Cabin Availability & Dynamic Fare Quotes (/v2/quotes)
Handle occupancy pricing, guaranteed vs. assigned staterooms, and transparent tax breakdowns without checkout price mismatches.
Occupancy Modeling and Fare Breakdown Anatomy
Unlike hotel rooms priced per unit, cruise fares are calculated per passenger based on berth occupancy, guest age brackets (adult, child, infant), residency, and loyalty tier. A two-guest balcony quote can differ substantially from a three-guest quote in the exact same stateroom category due to third/fourth-berth promotional rates or lifeboat capacity limits.
Every /v2/quotes response should decompose total price into commissionable base fare, Non-Commissionable Fare (NCCF), government port taxes, and optional prepaid gratuities. Transparent itemization prevents unexpected totals during checkout and enables accurate agency commission accounting.
- Pass explicit passenger_ages arrays rather than generic guest counts.
- Distinguish per-person rates from total cabin checkout totals clearly.
- Surface single-supplement percentages for solo traveler searches.
Assigned Staterooms vs. Guarantee (GTY) Categories
Cruise inventory splits into assigned staterooms—where travelers pick an exact deck and cabin number—and Guarantee (GTY) fares, where the cruise line promises at least the booked meta-category and assigns the specific cabin closer to embarkation. API payloads must expose a clear inventory_type flag so checkout flows do not prompt users to pick a deck location on GTY fares.
For assigned categories, /v2/quotes returns live cabin attributes such as deck number, midship/forward/aft position, obstructed-view flags, connecting-door indicators, and Pullman or sofa-bed capacity.
Quote Tokens and Checkout Price Continuity
Because live cruise inventory moves continuously across global agencies, a fare quoted at 10:00 AM may sell out or reprice minutes later. Issuing a signed, short-lived quote_token with an explicit expires_at timestamp lets /v2/reserve validate that the fare and cabin remain locked before charging a traveler's card.
If a supplier reports a fare delta between /v2/quotes and /v2/reserve, the API should return a structured price-change payload (for example, HTTP 409 with old_total and new_total) so the frontend can prompt explicit user re-confirmation.
Fare & Inventory Components Returned by /v2/quotes
| Component | Typical Behavior | Commissionable | Display Requirement |
|---|---|---|---|
| Base Cruise Fare | Varies by occupancy & promo | Yes | Always itemized per guest |
| NCCF (Port Charges) | Fixed per sailing/guest | No | Included in advertised fare |
| Gov. Taxes & Fees | Port authority & VAT | No | Itemized tax line at checkout |
| Single Supplement | 150%–200% of base fare | Yes | Applied when pax = 1 |
| Prepaid Gratuities | Optional or bundled | Usually No | Flagged as included or add-on |
Exact commissionability and tax bundling rules depend on regional consumer-protection regulations and supplier contracts.
Worked Illustration: Two-Adult + One-Child Quote Calculation
This worked illustration computes a transparent 3-guest Balcony quote from itemized /v2/quotes fields:
- Guests 1 & 2 base fare: $800 each ($1,600); Guest 3 (child promo) base fare: $250.
- NCCF included in cruise fare: $160 per guest ($480 total, excluded from agency commission base).
- Government port taxes & fees: $145 per guest ($435 total across 3 passengers).
- Total checkout due = ($1,600 + $250) + $480 + $435 = $2,765, with a 15-minute quote_token lock.
Worked Illustration Summary: Explicit line-item separation keeps customer totals transparent and isolates commissionable revenue ($1,850) from pass-through fees.
Live Quote & Pricing Verification Checklist
- Require passenger ages in /v2/quotes requests to capture child and senior promos.
- Separate base fare, NCCF, taxes, and gratuities in API responses.
- Flag GTY vs. selectable staterooms with deck and view-obstruction metadata.
- Attach an ISO 8601 expires_at timestamp to every quote_token.
- Handle HTTP 409 price-change responses gracefully in the checkout UI.
- Validate connecting-cabin and multi-berth capacity limits before payment.
Frequently Asked Questions
What is NCCF in cruise API pricing?
Non-Commissionable Fare (NCCF) represents port-related charges bundled into the cruise fare by the cruise line on which travel agencies do not earn commission. Separating it ensures accurate accounting.
Why do cabin prices change when adding a third passenger?
Many cruise lines discount third and fourth guests in the same cabin, while others charge dynamic rates or restrict triple/quad bookings when ship lifeboat zones near capacity.
How long should a /v2/quotes response be cached?
Keep quote caches very brief (30 to 120 seconds) or bypass cache altogether when entering checkout, relying on a fresh live supplier check to obtain the quote_token.
How are obstructed-view cabins indicated?
Normalized cabin objects include boolean flags or severity enums (such as partial_obstruction or full_obstruction) so frontends can display clear disclosures.
Primary Standards & Industry References
- CLIA — Cruise Lines International Association Industry Standards
- OpenTravel Alliance Cruise Category & Cabin Availability Schema
- ISO 4217 — Codes for the Representation of Currencies