Data contracts

This page specifies the reference data Kaptio Experiences expects your systems to supply — the answer to "what feed do you take?". If your side can provide these entities, everything documented in the API reference works on your real trips, guests, and products.

How the data arrives depends on your integration model: pushed by your integration platform to inbound endpoints as changes occur, or pulled by the platform's live provider from Salesforce and your content feed. The entities are the same in both.

Two rules apply throughout:

This is the canonical model. Field names below are the platform's canonical shapes; per-tenant mappings from your systems' payloads onto them are agreed in the interface contract during implementation workshops. Whatever you cannot supply is either entered by users in the app or omitted where optional.
Conventions match the API: money is integer minor units of the trip currency, dates are ISO YYYY-MM-DD, identifiers are stable opaque strings. See API conventions.

Trip

The departure — the unit everything else is scoped to.

Field	Required	Description
`id`	Yes	Stable identifier
`code`	Yes	Operational tour code, e.g. `MERBOI-260812` — also the join key for product applicability
`brandId`	Yes	Which brand the departure belongs to
`name`	Yes	Display name, e.g. `Best of Italy`
`startDate` / `endDate` / `durationDays`	Yes	Departure window
`currency`	Yes	ISO 4217 trip currency — guests see and pay in this currency
`tdId`	Yes	Assigned Tour Director (substitutable by operations)
`status`	Yes	`upcoming` \| `active` \| `completed`
`driverName`	No	Coach driver — required if driver gratuities are enabled
`route`, `heroImageUrl`	No	Display: route summary and hero image

Guest

One record per booking party. Recognition is booking-reference based — this record is why guests never register.

Field	Required	Description
`id`	Yes	Stable identifier
`tripId`	Yes	The departure the party is booked on
`bookingReference`	Yes	The reference the guest knows, e.g. `MT-882401` — used for sign-in and voucher linkage
`firstName` / `lastName`	Yes	Lead guest name — surname is matched at sign-in
`email`	Yes	Magic-link delivery and receipts
`party.size`	Yes	Number of travelers on the booking
`party.memberNames`	Yes	Names of party members — drives per-participant selection and split payments
`packagePrice`, `packagePaidAmount`	No	Read-only mirror of this party's core booking price and paid-to-date, in minor units, for the guest's booking overview. Booking-level values, never shared across parties — core package payment collection stays outside Experiences
`country`	No	Display

Tour Director

Field	Required	Description
`id`	Yes	Stable identifier — settlements are attributed to it
`code`	Yes	Staff code, e.g. `TD-4471`
`firstName` / `lastName` / `email`	Yes	Identity and contact
`tripIds`	Yes	Currently assigned departures
`homeCity`	No	Display

Optional product

The experiences catalog. Your content platform stays the single source of truth — the platform holds no independent pricing layer, so price changes at the source flow through.

Field	Required	Description
`id`	Yes	Stable identifier
`contentRef`	Yes	The product's identifier in your content platform
`title` / `description`	Yes	Display copy (`longDescription`, `gallery` optional)
`imageUrl`	Yes	Card image
`category`	Yes	`sightseeing` \| `dining` \| `entertainment` \| `museum` \| `cruise` \| `adventure` \| `wellness`
`price` / `currency`	Yes	Unit price in minor units — controlled at your source
`supplierName`	Yes	Operating supplier
`supplierCutoffHours`	Yes	Hours before the experience when sales close — drives the enforced cut-off
`capacity`	Yes	Allotment per departure; `null` = unlimited
`applicableTripCodes`	Yes	Which tour codes the product runs on
`tripDay` / `startTime` / `durationMinutes`	No	When it runs — drives itinerary placement and cut-off calculation
`meetingPoint` / `bookingNotes`	No	Guest-facing logistics

Per-trip availability state (sold out, capacity overrides, sold-out policy) is not part of your feed — staff manage it in the app and the platform resolves it against capacity.

Operational extras (optional)

Tenants using the Tour Director trip-operations surface can additionally supply day plans (dayNumber, date, location, summary), itinerary services with statuses, a supplier directory, crew documents, guest operational info (rooms, dietary/medical/accessibility flags, form completion), and on-ground supplier payment lines. Every one of these is optional — the apps degrade gracefully when a feed is absent, and the selling surfaces need none of them.

Example: trip context payload

What the canonical entities look like assembled — a trip, its lead guest, and one product:

{
  "trip": {
    "id": "trip_301",
    "code": "MERBOI-260812",
    "brandId": "meridian_uk",
    "name": "Best of Italy",
    "startDate": "2026-08-12",
    "endDate": "2026-08-20",
    "durationDays": 9,
    "currency": "GBP",
    "tdId": "td_07",
    "driverName": "Stefan Novak",
    "status": "upcoming"
  },
  "guest": {
    "id": "g_014",
    "tripId": "trip_301",
    "bookingReference": "MT-882401",
    "firstName": "Elena",
    "lastName": "Carter",
    "email": "elena.carter@example.com",
    "party": { "size": 2, "memberNames": ["Elena Carter", "James Carter"] }
  },
  "product": {
    "id": "opt_venice_gondola",
    "contentRef": "EXP-90211",
    "title": "Venice by Gondola at Dusk",
    "category": "sightseeing",
    "price": 8500,
    "currency": "GBP",
    "supplierName": "Laguna Experiences",
    "supplierCutoffHours": 48,
    "capacity": 24,
    "applicableTripCodes": ["MERBOI-260812"],
    "tripDay": 4,
    "startTime": "19:30"
  }
}

What flows back

The return path — confirmed purchases, refunds, gratuities, transactions, and settlement batches — is documented in Integration architecture: writeback to the booking record in Salesforce, the outbound feed to your integration platform, and the finance export.

Trip​

Guest​

Tour Director​

Optional product​

Operational extras (optional)​

Example: trip context payload​

What flows back​