Data model
The domain objects the Journeys API works with, their fields, and how they map to the underlying Kaptio platform concepts. Two groups:
- Catalog objects — read-only browse data (trips, categories, rooms/cabins, activities)
- Commerce objects — mutable session state (basket, travellers, pricing, payments, booking)
Trip (Voyage wire type) ──has──► departureDates
│
└─ RoomCategory ──contains──► RoomOption Activity
│ │
▼ ▼
Basket ──contains──► BasketComponent ──holds──► ComponentSelection
├──── Traveller[]
├──── promotions: string[]
├──── BasketPricing (computed)
├──── PaymentSchedule[] (computed)
├──── PaymentRequest[]
│
└──checkout──► BookingResult ──lands as──► Salesforce Itinerary
Catalog objects
Trip (Voyage wire type)
A sellable trip — one Kaptio package departure with its from-prices. Returned by the neutral GET /catalog/trips route or the backward-compatible /catalog/voyages alias. The type and field names retain voyage terminology for wire compatibility.
| Field | Type | Description |
|---|---|---|
voyageCode | string | Package external code — stable across environments |
voyageName | string | Display name |
region | string | Destination region grouping |
durationDays | number | Trip length |
shipName | string | Vessel operating a cruise trip; empty for touring |
departureDates | array | { label, date } per departure — date is ISO 8601 |
fromPrice | number | null | Lowest lead-in price in the tenant's default currency. null when no valid price resolved — never 0 |
currency | string | Currency of fromPrice |
fromPriceUSD … fromPriceCAD | number | null | Lead-in price per configured currency (live.from_price_currencies) |
sellingStatus | string | e.g. Open, Sold Out, On Request |
voyageSeason | string | Season grouping; for touring this can be the departure year |
RoomCategory (CabinCategory wire type)
A room or cabin grade grouped into display tiers configured in journey.yaml → catalog.category_tiers. Cruise examples include Balcony Stateroom; touring examples include Twin Room and Single Room. Returned by GET /catalog/categories.
| Field | Type | Description |
|---|---|---|
kaptioName | string | Canonical category name in Kaptio — the key used when requesting rooms |
label | string | Display label |
tier | string | Tier name from category_tiers |
tierGroup | string | Higher-level grouping for UI sections |
isSolo | boolean | Single-occupancy category |
isPopular | boolean | UI hint for a "most popular" badge |
sortOrder | number | Display ordering |
RoomOption (Cabin wire type)
A bookable room selection with live availability and price. Returned by GET /catalog/rooms or the backward-compatible /catalog/cabins alias. Cruise rows can represent a physical cabin; touring rows represent a priced package room option.
| Field | Type | Description |
|---|---|---|
id | number | string | Cabin row identifier |
cabinNumber | string | Physical cabin number in cruise, or room-option display name in touring |
deck | number | Deck number in cruise; neutral value in touring |
location | string | Cruise location such as Forward, Midship, Aft; empty in touring |
priceAmount | number | Price in the requested currency |
priceCurrency | string | ISO 4217 |
priceBasis | string | e.g. per person |
berthsAvailable | number | Remaining berths |
componentId | string | Selection context — the package component this cabin belongs to |
optionId | number | Selection context — component option |
itemOptionId | string | Selection context — item option |
cabinTypeId | string | Selection context — cabin type |
Selection-context fields are opaque to the UI: pass the values returned for the row back verbatim in a ComponentSelection. Cruise responses can include all four fields; touring selections use the package component, option, and item-option context.
Activity
An optional package add-on for a trip. Returned by GET /catalog/activities. Externally quoted ancillaries use a separate Journeys-owned selection model and are not Basket Service components.
| Field | Type | Description |
|---|---|---|
activityName | string | Display name |
priceAmount | number | Price in the requested currency |
priceCurrency | string | ISO 4217 |
unitsAvailable | number | Remaining capacity |
Commerce objects
Basket
The commerce session — everything selected so far, who is travelling, and which promotions apply. Created by POST /baskets.
| Field | Type | Description |
|---|---|---|
id | string | Basket ID — used in all subsequent calls |
tenant_id | string | Owning tenant. Enforced on every read/write |
channel_id | string | Journey channel the session started in |
package_id | string | Selected package |
departure_id | string | Selected departure |
currency_code | string | Session currency |
occupancy | Occupancy[] | Party shape, one entry per room or cabin |
components | BasketComponent[] | Package components and their selections |
travellers | Traveller[] | Passenger details |
promotions | string[] | Applied promotion codes |
status | string | open → priced → booked |
created_at | string | ISO 8601 |
Occupancy
| Field | Type | Description |
|---|---|---|
adults | number | Adults in the room or cabin |
children | number | Children in the room or cabin |
BasketComponent
A configurable slot in the package (e.g. a room/cabin component or an activities component).
| Field | Type | Description |
|---|---|---|
component_id | string | Package component ID |
selections | ComponentSelection[] | Chosen options — empty until the guest selects |
ComponentSelection
One chosen option within a component — e.g. a touring room configuration, a specific cruise cabin, or an activity.
| Field | Type | Required | Description |
|---|---|---|---|
option_id | string | Yes | Component option (from the cabin/activity selection context) |
item_option_id | string | Yes | Item option (from the selection context) |
cabin_id | string | No | Specific cabin identifier when the cruise inventory model requires it |
travellers | number[] | No | Traveller indexes the selection applies to |
rooms | number[] | No | Room indexes (multi-room baskets) |
units | number[] | No | Unit counts where applicable |
Traveller
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Stable index within the basket ("1", "2", …) |
first_name | string | Yes | |
last_name | string | Yes | |
email | string | Yes | |
phone | string | No | |
date_of_birth | string | No | ISO 8601 date |
contact | boolean | No | Marks the lead passenger |
BasketPricing
Computed by the platform pricing engine from the basket's current state. Returned by GET /baskets/:id/prices.
| Field | Type | Description |
|---|---|---|
subtotal | number | Before taxes |
taxes | number | Tax total per the tenant's tax profile |
total | number | Grand total |
currency | string | ISO 4217 |
deposit_amount | number | Amount due now |
deposit_percentage | number | Deposit rule applied |
balance_due | number | Remaining after deposit |
balance_due_date | string | ISO 8601 date |
commission_amount | number | Optional aggregate reseller commission; omitted when no positive applicable_to: reseller_commission lines are returned |
commission_lines | array | Optional commission lines grouped as { label, amount, currency } from the same KTAPI lines |
external_ancillary_lines | array | Optional signed external selections shown separately from the Kaptio basket total |
external_ancillary_total | number | Optional total of validated external selections |
presentation_total | number | Display-only total + external_ancillary_total; not a Basket Service amount |
line_items | array | Aggregated customer sales lines as { label, amount, currency } |
commission_amount and commission_lines are informational and do not change total. commission_lines groups by display label; it does not allocate commission to individual customer line_items. The underlying KTAPI response can contain separate price lines with applicable_to: sales, supplier, or reseller_commission.
Payment-method surcharges are not part of BasketPricing. Edge Pay calculates method previews from the selected method's payment.yaml surcharge_percent and returns them on the embed session. An itinerary-level KTAPI Fee line remains part of itinerary pricing and is not the same as a payment surcharge.
PaymentSchedule
A payment option for the basket. Returned by GET /baskets/:id/payment-schedules.
| Field | Type | Description |
|---|---|---|
id | string | Schedule rule ID — referenced when creating a payment request |
label | string | Display label |
amount | number | Amount for this schedule |
due_date | string | ISO 8601 date |
type | string | deposit or balance |
PaymentRequest
A payment being collected. Created by POST /baskets/:id/payment-requests.
| Field | Type | Description |
|---|---|---|
id | string | Payment request ID |
basket_id | string | Owning basket |
amount | number | Amount to collect |
currency | string | ISO 4217 |
status | string | pending → completed | failed |
payment_url | string | Hosted payment page URL, when applicable |
surcharge_breakdown | object | Edge Pay surcharge amount; authoritative only on a completed payment |
EmbedSession
The Edge Pay hosted-payment handoff returned by POST /baskets/:id/payment-requests/:paymentRequestId/embed-session.
| Field | Type | Description |
|---|---|---|
session_id | string | Edge Pay session ID |
embed_url | string | Hosted payment URL |
expires_at | string | Session expiry timestamp |
surcharge_options | array | Optional method-specific previews calculated by Edge Pay from current tenant config |
AdvisorAccount
Returned by POST /advisors/lookup for B2B channels.
| Field | Type | Description |
|---|---|---|
account_id | string | Salesforce account ID |
agency_name | string | Agency display name |
iata_number | string | Accreditation number matched |
email | string | Advisor email matched |
country | string | Agency country |
BookingResult
The outcome of checkout. Returned by POST /baskets/:id/bookings.
| Field | Type | Description |
|---|---|---|
itinerary_id | string | Salesforce itinerary record ID |
booking_reference | string | Human-readable booking number |
status | string | Itinerary status after creation |
Mapping to platform concepts
| Journeys object | Kaptio platform concept |
|---|---|
Trip (Voyage) | Package + Package Departure (KTAPI) |
RoomCategory / RoomOption (CabinCategory / Cabin) | Cruise: package component options over cabin inventory. Touring: required PriceCategories package options over room inventory. |
| Activity | Optional package component priced per unit |
| Basket | Basket Service session — the staged commercial state before booking |
| BasketPricing | KTAPI pricing engine result (customer sales lines, promotions, and optional aggregate reseller commission) |
| Promotion code | KTAPI promotion validated for combinability and eligibility |
| PaymentSchedule | Kaptio payment schedule rules for the itinerary-to-be |
| BookingResult | Itinerary record created in the tenant's Salesforce org |
This mapping is why the same data model works for any channel — web, advisor portal, call centre, or an AI agent driving the API directly: every object above is a stable projection of the platform's core commerce model, not a UI-specific construct.
Externally provided ancillaries are intentionally outside this mapping: Journeys keeps a tenant-scoped, tamper-resistant selection, includes the quoted amount in pricing presentation, and orchestrates an ad-hoc itinerary item during checkout. Basket Service does not store that external selection. See Extending journeys with third-party services.