CruiseAPI
Home › Technical Guides › Commerce & FX
Commerce & FX

Dynamic Profit Markup Rules & Multi-Currency Cruise Localization

Automate margin rules across net and gross fares while locking foreign-exchange conversions seamlessly from quote to settlement.

Net vs. Gross Fare Models and Dynamic Markup Engines

Travel distributors operate under two primary commercial models: gross commissionable fares—where the cruise line sets the public retail price and pays a percentage commission—and net wholesale rates, where the agency applies its own retail markup. A dynamic markup rule engine inside the gateway lets operators configure percentage or flat-dollar adjustments by supplier, sailing length, or cabin meta-category.

Applying markups centrally ensures consistent pricing across web storefronts, mobile apps, and sub-agent portals without hardcoding margin tables inside frontend UI components.

  • Apply markups strictly to base cruise fare, never distorting government taxes.
  • Support rule precedence by sub-agent tier, cruise line, and promotional window.
  • Return internal net_cost and retail sell_price fields cleanly on authorized B2B tokens.

FX Rate Locking Between /v2/quotes and /v2/reserve

International travel portals frequently sell USD-denominated sailings to customers paying in EUR, GBP, AUD, or INR. If spot exchange rates shift between browsing and payment capture, displaying unrounded decimals or recalculating totals at checkout creates conversion friction and reconciliation variances.

Attaching an fx_rate and fx_lock_expires timestamp to the /v2/quotes token locks the customer's display currency total through /v2/reserve, absorbing minor intra-day spread inside a predictable settlement tolerance.

Regional Price Display and Tax Transparency

Consumer protection standards vary widely by market: North American shoppers often see base fares plus itemized taxes at checkout, whereas UK, EU, and Australian regulations require all-inclusive headline pricing upfront. Parameterizing display_mode (ALL_INCLUSIVE vs. BASE_PLUS_TAX) lets one API backend power compliant localized storefronts worldwide.

Commercial Pricing & Localization Controls

ControlScopeCalculation RuleCompliance / UX Benefit
Net Markup RulePer line / cabin tierFlat or % on base fareProtects agency margin
FX Quote LockPer quote_tokenISO 4217 rate locked 15mZero checkout price drift
Sub-Agent SplitB2B partner IDTiered override commissionAutomated partner billing
All-Inclusive FlagLocale / storefrontBase + NCCF + TaxesEU/UK/AU price compliance
Rounding PolicyTarget currencyISO minor-unit roundingClean checkout amounts

Always isolate government taxes from markup calculations to maintain transparent audit trails.

Worked Illustration: Net Wholesale USD Fare Sold in EUR

This worked illustration calculates a localized EUR retail price from a USD wholesale cruise fare:

  1. Supplier net base fare = $1,000 USD; NCCF = $150 USD; government port taxes = $130 USD.
  2. Agency markup rule adds 12% on net base fare ($120 USD), yielding $1,120 base + $150 NCCF + $130 taxes = $1,400 USD retail.
  3. Gateway applies locked FX rate (1 USD = 0.92 EUR) with 15-minute quote_token validity: €1,288.00 total.
  4. On /v2/reserve, customer pays €1,288.00 while internal ledger records $1,280 supplier cost and $120 gross margin.

Worked Illustration Summary: Centralized markup plus quote-level FX locking reconciles multi-currency revenue down to the cent.

Markup & Localization Verification Checklist

  • Apply percentage markups only to base fares, excluding government taxes.
  • Pass explicit ISO 4217 currency codes in every /v2/voyages and /v2/quotes call.
  • Lock FX conversion rates inside the signed quote_token through booking commit.
  • Configure locale-aware all-inclusive pricing flags for EU, UK, and AU markets.
  • Round display totals according to ISO 4217 currency minor units.
  • Restrict visibility of net_cost fields strictly to authenticated B2B admin scopes.

Frequently Asked Questions

Should agency markups be visible in public API responses?

No. Customer-facing storefront responses only show final retail totals, while authorized B2B finance tokens can inspect the internal breakdown of net cost, markup, and tax.

How do minor currency units affect rounding?

Currencies like USD and EUR use 2 decimal places, whereas JPY uses 0. Using ISO 4217 exponent metadata ensures payment gateways never reject malformed amounts.

What happens if an FX lock expires before checkout finishes?

The /v2/reserve endpoint returns an expired-quote error prompting the frontend to refresh /v2/quotes with the current spot rate.

Can different markups be assigned to specific cruise lines or ship classes?

Yes. Rule engines evaluate hierarchical selectors—from global default down to cruise line, vessel, and cabin meta-category.

Primary Standards & Industry References

  • ISO 4217 — Currency & Minor-Unit Representation Standard
  • European Union Package Travel Directive (Pricing Transparency)
  • CLIA & Regional Consumer Price Advertising Guidelines

Related Technical Guides