Overview
Kaptio Connect is the integration layer that bridges external supplier systems into the Kaptio packaging platform. It enables Live components — package components that receive real-time pricing and availability from external systems rather than relying on static price categories managed inside Kaptio.
Without Connect, every rate and availability figure must be manually loaded into inventory seasons and allotment days. This works well for contracted rates that change infrequently, but falls apart when:
- A supplier’s rates change daily or dynamically (yield-managed rail fares, floating hotel rates)
- Availability is volatile and must be confirmed at booking time (limited cabin inventory on ferries, last-seat availability on trains)
- The external system is the system of record for confirmation — Kaptio must send a booking request and receive a confirmation number
Connect solves these problems by establishing a standardised gateway between Kaptio and external supplier APIs. Rates flow in, availability is checked in real time, and bookings are confirmed through the external system — all without manual intervention.
By the end of this guide you will understand the Connect architecture, know how to configure a gateway, set up rate loading and availability checking, and create Live components in packages that use Connect pricing.
Prerequisites
Before configuring a Connect integration, ensure the following are in place:
- Kaptio platform configured with Business Units, currency, and tax settings (Organization Structure Guide, Currency & Tax Configuration)
- Supplier account created in Salesforce with the appropriate record type
- Supplier API credentials obtained — endpoint URLs, authentication tokens or keys, and any environment-specific configuration (sandbox vs production)
- Supplier booking flow documented — understand the external system’s rate format, availability check mechanism, and booking confirmation protocol before starting configuration
- Service types mapped — decide how the supplier’s services map to Kaptio item types (accommodation, transport, activity)
- Admin or Integration Manager access in Kaptio
Part 1: Understanding Kaptio Connect
The Integration Architecture
Connect uses a gateway model. Each external supplier system is represented by a gateway — a configured connection that knows how to communicate with that system. Gateways implement a standardised Service Provider Interface (SPI), which means the rest of the Kaptio platform interacts with all external systems through the same contract, regardless of the supplier’s native API format.
The architecture has three layers:
| Layer | Responsibility | Examples |
|---|---|---|
| Kaptio Platform | Packaging, pricing, booking management | Package search, itinerary builder, booking engine |
| Connect Gateway | Protocol translation, rate caching, request routing | Rate import jobs, availability proxying, booking dispatch |
| External System | Source of truth for rates, availability, and confirmation | Regional transport operator API, hotel distribution platform, experience marketplace |
The gateway handles all the complexity of communicating with the external system — authentication, request formatting, response parsing, error handling, and retry logic. The Kaptio platform only ever interacts with the gateway’s standardised interface.
Key principle: Connect gateways are stateless translators. They do not store bookings or own availability. They translate between the Kaptio data model and the external system’s data model. The external system remains the system of record for confirmation and fulfilment.
Live Components vs Static Components
Kaptio packages contain components — the individual service segments that make up a trip (accommodation nights, transport legs, activities). Each component is either Static or Live, and this distinction determines where pricing comes from.
| Aspect | Static Component | Live Component |
|---|---|---|
| Pricing source | Price categories and inventory seasons managed in Kaptio | External system via Connect gateway |
| Rate updates | Manual — someone updates the price category or inventory season | Automatic — rates pushed from the external system or pulled on demand |
| Availability | Allotment day records in Kaptio | Real-time check against the external system |
| Booking confirmation | Internal to Kaptio | Sent to the external system; confirmation number returned |
| Best for | Contracted rates, stable pricing, self-managed inventory | Dynamic pricing, volatile availability, third-party fulfilment |
| Setup complexity | Lower — all configuration is within Kaptio | Higher — requires gateway configuration and external system coordination |
Most packages use static components. Live components are added when a specific service segment requires real-time integration with an external system — typically transport, dynamically priced accommodation, or third-party experiences.
Supported Integration Patterns
Connect supports three integration patterns, which can be used independently or together:
1. Rate Loading (Push)
The external system pushes rate data to Kaptio Connect on a schedule. Rates are cached locally so that package search can return pricing without making a real-time call to the external system for every search request.
2. Availability Check (Pull)
When a guest selects dates, Kaptio makes a real-time call through the gateway to the external system to confirm availability. This happens after the initial search (which uses cached rates) and before the booking is committed.
3. Booking Confirmation (Push/Pull)
When a booking is confirmed in Kaptio, Connect sends a booking request to the external system. The external system responds with a confirmation number (or a rejection), which is recorded against the booking in Kaptio.
Tip: Not every integration uses all three patterns. A rate-only integration (pattern 1) is valid — it simply means availability and booking are managed outside Kaptio. Discuss with the supplier which patterns their system supports before configuring the gateway.
Part 2: Gateway Configuration
Step 1: Register a Gateway
Navigate to the Connect configuration area and create a new gateway record.
Required fields:
| Field | Description | Example |
|---|---|---|
| Gateway Name | Human-readable name for the integration | ”Regional Rail Operator — Production” |
| Gateway Type | The SPI implementation to use | Transport, Accommodation, Activity, Custom |
| External System ID | Identifier for the external system | Provided by the supplier |
| Status | Whether the gateway is active | Active / Inactive / Testing |
Screenshot of the New Gateway form showing Gateway Name, Gateway Type picklist, External System ID, and Status fields
Important: Create separate gateway records for sandbox and production environments of the same external system. Never point a production gateway at a sandbox endpoint or vice versa. Naming them explicitly (e.g., “Regional Rail — Sandbox”, “Regional Rail — Production”) prevents costly mistakes.
Step 2: Configure Connection Settings
After creating the gateway, configure the connection details that tell Connect how to communicate with the external system.
| Setting | Description | Notes |
|---|---|---|
| Base URL | The external system’s API endpoint | e.g., https://api.supplier.com/v2 |
| Authentication Type | How the gateway authenticates | API Key, OAuth 2.0, Basic Auth, Certificate |
| Credentials | Authentication credentials | Stored encrypted — never visible after save |
| Timeout (seconds) | Maximum wait time for a response | Recommended: 10s for availability, 30s for booking |
| Retry Policy | How to handle transient failures | e.g., 3 retries with exponential backoff |
| Rate Limit | Maximum requests per second | Respect the external system’s published limits |
Screenshot of the Gateway Connection Settings panel showing Base URL, Authentication Type dropdown, Timeout, Retry Policy, and Rate Limit fields
Warning: Timeout values directly affect guest experience. A 30-second availability check timeout means the guest waits 30 seconds on a spinning page. Set availability timeouts aggressively (5-10 seconds) and booking timeouts more generously (15-30 seconds). If the external system cannot respond within these windows, the integration needs architectural discussion with the supplier.
Step 3: Map Service Types
Connect needs to know how the external system’s service types correspond to Kaptio’s service types. This mapping ensures that rates and availability from the external system are applied to the correct components in a package.
| External Service Type | Kaptio Service Type | Notes |
|---|---|---|
RAIL_STANDARD | Transport — Rail | Standard class seating |
RAIL_FIRST | Transport — Rail | First class — mapped to a separate price category |
HOTEL_ROOM | Accommodation — Hotel | Standard room type |
EXPERIENCE | Activity | Day experience or excursion |
The mapping is configured per gateway and determines:
- Which Kaptio service type receives imported rates
- How availability responses are matched to package components
- Which service level (if applicable) is assigned to the pricing
Screenshot of the Service Type Mapping table showing external types in the left column and Kaptio types in the right column with a dropdown selector
Gateway Health Monitoring
Once a gateway is active, monitor its health through the Connect dashboard:
| Indicator | Meaning | Action |
|---|---|---|
| Connected (green) | Last health check succeeded | None |
| Degraded (amber) | Elevated error rate or slow response times | Check external system status; review timeout settings |
| Disconnected (red) | Health check failed or no response | Verify credentials, endpoint URL, and network connectivity |
| Last Rate Import | Timestamp of the most recent successful rate load | If stale, check the import schedule and logs |
| Error Rate (24h) | Percentage of failed requests in the last 24 hours | Investigate if above 5% |
Tip: Set up monitoring alerts for gateway status changes. A gateway going from Connected to Degraded is an early warning — investigate before it becomes Disconnected and blocks bookings.
Part 3: Rate Loading
How Rate Loading Works
Rate loading is the process of importing pricing data from the external system into Kaptio’s local cache. This cache enables fast package search — instead of calling the external system for every search request, Kaptio uses cached rates and only makes real-time calls for availability confirmation.
The flow:
- The external system exposes rate data through its API (or pushes it to a Connect endpoint)
- A scheduled import job runs on a configured interval (e.g., every 6 hours)
- Connect fetches the latest rates, transforms them to the Kaptio format using the service type mapping, and stores them in the rate cache
- Package search uses cached rates for pricing calculations
- At booking time, a real-time availability and rate confirmation check is made (if the gateway supports pattern 2)
Step 4: Configure Rate Import
Set up the rate import schedule and mapping for the gateway.
| Setting | Description | Example |
|---|---|---|
| Import Schedule | How often to fetch rates | Every 6 hours, daily at 02:00 UTC, on-demand |
| Rate Endpoint | The external system’s rate API path | /rates/bulk or /pricing/export |
| Date Range | How far ahead to import rates | 365 days from today |
| Currency | The currency of imported rates | The external system’s base currency |
| Mapping Rules | How external rate fields map to Kaptio pricing | Per-service-type configuration |
Screenshot of the Rate Import Configuration panel showing schedule dropdown, rate endpoint field, date range selector, and a mapping rules table
Each import job is logged with:
- Start and end timestamps
- Number of rates imported
- Number of rates updated (changed since last import)
- Number of errors (rates that could not be mapped)
- Overall status (success, partial, failed)
Rate Caching and Freshness
Cached rates have a freshness window — the period during which they are considered valid for search results. After this window expires, the rates are still used for search (to avoid blank results) but are flagged as potentially stale.
| Setting | Default | Description |
|---|---|---|
| Cache TTL | 24 hours | How long cached rates are considered fresh |
| Stale Grace Period | 48 hours | How long stale rates are still used for search (with a freshness warning) |
| Hard Expiry | 7 days | After this period, expired rates are excluded from search entirely |
Tip: Set the Cache TTL to match the import schedule. If you import rates every 6 hours, a 12-hour TTL ensures rates are always fresh if at least one import succeeds. If rates change infrequently (e.g., seasonal contracts), a longer TTL reduces unnecessary reimports.
Handling Rate Changes
When an import job detects that rates have changed since the last import:
- New rates are added to the cache immediately
- Updated rates replace the previous cached values
- Removed rates (rates that were in the previous import but not the current one) are flagged but not immediately removed — they enter the stale grace period
- Active sessions that already loaded the previous rates continue using them until the session refreshes — guests mid-search are not disrupted
This means there is a brief window where different guests may see different prices for the same product. This is inherent to any system with cached dynamic pricing and is consistent with how airline and hotel search engines operate.
Part 4: Availability and Booking
Real-Time Availability Check
While cached rates power fast search, availability must be confirmed against the external system before a booking can proceed. The availability check happens at a specific point in the booking flow:
- Guest searches for a package — cached rates are used for pricing
- Guest selects dates and proceeds toward booking
- Kaptio sends an availability check request through the gateway to the external system
- The external system responds with confirmed availability (and optionally an updated price)
- If available, the guest proceeds to booking; if unavailable, they are prompted to select alternative dates
The availability check is the moment where cached data meets reality. It catches situations where:
- Inventory has sold out since the last rate import
- The external system has changed prices since the last import
- The specific date/route/cabin combination is not available despite general availability
Step 5: Configure Availability Endpoints
Set up the availability check configuration for the gateway.
| Setting | Description | Example |
|---|---|---|
| Availability Endpoint | API path for availability checks | /availability/check |
| Request Format | What data to send | Date range, service type, passenger count, class |
| Response Mapping | How to interpret the response | Available/unavailable, confirmed price, alternatives |
| Timeout | Maximum wait for a response | 5-10 seconds recommended |
| Fallback Behaviour | What to do if the check times out | Block booking (safe) or allow with warning (risky) |
Screenshot of the Availability Configuration panel showing endpoint URL, timeout setting, and fallback behaviour dropdown
Warning: The fallback behaviour setting is critical. If set to “allow with warning”, a booking can proceed even if the external system did not confirm availability. This risks overbooking. The safer default is “block booking” — the guest sees a timeout message and can retry.
Booking Confirmation Flow
When a booking is confirmed in Kaptio, Connect sends a booking request to the external system for each Live component in the itinerary. The flow is:
- Kaptio commits the booking internally (creates the Itinerary and booking records)
- For each Live component, Connect sends a booking request through the gateway
- The external system processes the request and responds with either:
- Confirmation — includes a confirmation number, which is stored against the component
- Rejection — includes a reason (sold out, price changed, invalid request)
- The booking status in Kaptio is updated based on the responses
If all Live components are confirmed, the booking proceeds normally. If any component is rejected, the booking enters a pending confirmation state and the operations team is notified for manual resolution.
| Response | Booking Status | Action Required |
|---|---|---|
| All confirmed | Confirmed | None — booking is complete |
| Partial confirmation | Pending Confirmation | Operations team reviews rejected components |
| All rejected | Failed | Guest is notified; manual rebooking required |
| Timeout | Pending Confirmation | Retry automatically; escalate if retries fail |
Error Handling
External system integrations are inherently unreliable. Connect includes several error-handling mechanisms:
Transient Errors (network timeouts, 5xx responses):
- Automatic retry with exponential backoff (configurable per gateway)
- After max retries, the request is marked as failed and queued for manual review
Business Errors (sold out, invalid request, price mismatch):
- No retry — the error is logged and surfaced to the operations team
- The booking component enters a manual resolution workflow
Rate Mismatches:
- If the confirmed price from the external system differs from the cached rate used during search, Connect flags the discrepancy
- Configurable tolerance (e.g., allow up to 2% variance without flagging)
- Beyond tolerance, the booking is paused for review before confirmation
Part 5: Using Live Components in Packages
Step 6: Create a Live Component
When building a package, add a component and set its type to Live. This tells the packaging engine that pricing for this component comes from an external system via Connect rather than from static price categories.
Navigate to the package record, open the component editor, and create a new component:
| Field | Description | Example |
|---|---|---|
| Component Name | Descriptive name for the trip segment | ”Outbound Rail — Standard Class” |
| Component Type | Must be set to Live | Live |
| Service Category | The type of service | Transport, Accommodation, Activity |
| Gateway | The Connect gateway to use | ”Regional Rail Operator — Production” |
Screenshot of the New Component form with Component Type set to “Live” and a Gateway lookup field populated with a gateway name
Step 7: Link to Gateway
After creating the Live component, configure how it maps to the external system’s services through the gateway:
| Setting | Description | Example |
|---|---|---|
| External Service ID | The service identifier in the external system | RAIL_LDN_PAR_STD |
| Route / Property | Additional routing information | ”London to Paris” or “City Centre Hotel” |
| Default Duration | Default number of nights or segments | 1 (for a single rail journey) |
| Passenger Mapping | How Kaptio passenger types map to external types | Adult = ADULT, Child = CHILD_2_11 |
The gateway uses this configuration to:
- Look up the correct cached rates during package search
- Send correctly formatted availability requests
- Include the right service identifiers in booking requests
Pricing Behaviour
Live components contribute to package pricing differently from static components:
| Behaviour | Static Component | Live Component |
|---|---|---|
| Search pricing | Reads from allotment day records | Reads from Connect rate cache |
| Price per guest | Determined by price category and occupancy | Determined by external system rate for that passenger type |
| Currency | Matches the Business Unit currency | May be in the external system’s currency — converted at package level |
| Price updates | Only when someone edits the inventory season | Automatically when the rate import job runs |
| Discounts and adjustments | Applied via Kaptio pricing rules | External system pricing is typically net — Kaptio margin is applied on top |
When a package contains Live components, the total package price is the sum of all component prices — some from static pricing, some from Connect cached rates. The pricing engine handles this transparently.
Mixed Packages
Most real-world packages combine static and Live components. A typical pattern:
| Component | Type | Pricing Source |
|---|---|---|
| Accommodation — 3 nights | Static | Price categories and inventory seasons |
| Outbound rail transfer | Live | Connect gateway to rail operator |
| Return rail transfer | Live | Connect gateway to rail operator |
| City walking tour | Static | Price categories |
| Airport transfer | Static | Price categories |
This is the intended architecture. Connect is not an all-or-nothing proposition — you integrate the specific components that benefit from real-time pricing and keep everything else on static pricing.
Tip: Start with one Live component type (e.g., transport) and validate the full flow — rate loading, search, availability check, booking confirmation — before adding more. Each integration is a separate gateway with its own configuration and operational characteristics.
Validation Checklist
After configuring a Connect integration, validate the full flow end-to-end:
- Gateway record created with correct name, type, and external system ID
- Connection settings configured — base URL, authentication, timeout, retry policy
- Service type mapping completed — external types mapped to Kaptio types
- Gateway health check shows Connected status
- Rate import job configured with appropriate schedule and date range
- First rate import executed successfully — rates visible in the cache
- Cache TTL and freshness settings appropriate for the rate change frequency
- Availability endpoint configured with appropriate timeout (5-10 seconds)
- Fallback behaviour set (recommended: block booking on timeout)
- Live component created in a test package and linked to the gateway
- Package search returns pricing from cached rates (not blank or zero)
- Availability check returns a response within the configured timeout
- Test booking sent to the external system’s sandbox environment
- Booking confirmation number received and stored against the component
- Error scenarios tested — timeout, rejection, rate mismatch
- Operations team briefed on the manual resolution workflow for failed confirmations
- Monitoring and alerting configured for gateway health changes
Common Issues and Solutions
| Issue | Likely Cause | Solution |
|---|---|---|
| Gateway shows Disconnected | Incorrect base URL, expired credentials, or network issue | Verify the endpoint URL is reachable; check credentials have not expired; confirm any IP allowlisting is in place |
| Rate import returns 0 rates | Mapping mismatch — external service types do not match the configured mapping | Review the service type mapping; check the external system’s rate API response format |
| Cached rates are stale | Import job failing silently or schedule too infrequent | Check import job logs for errors; increase import frequency if rates change often |
| Availability check times out | External system slow to respond, or timeout set too low | Increase the timeout (within reason); discuss response time SLAs with the supplier |
| Booking rejected — “price mismatch” | Cached rate differs from the external system’s current rate | Run an on-demand rate import to refresh the cache; review the price tolerance setting |
| Booking rejected — “sold out” | Availability changed between the check and the booking request | This is a race condition inherent to distributed systems; ensure the availability check is as close to booking as possible |
| Guest sees different prices on retry | Rate import ran between searches, updating cached rates | Expected behaviour for dynamic pricing; consider showing a “prices may change” notice |
| Mixed package shows partial pricing | Live component gateway is disconnected; static components price normally | Check gateway health; the packaging engine shows cached rates if available, or flags the component if the gateway is down |
Related Schema Objects
| Object | Description | Key Fields |
|---|---|---|
| Connect Gateway | The integration connection record | Gateway Name, Type, Status, Base URL |
| Service Type Mapping | Maps external to Kaptio service types | External Type, Kaptio Type, Gateway (lookup) |
| Rate Cache | Cached pricing from external systems | Service ID, Date, Rate, Currency, Gateway (lookup), Imported At |
| Live Component | Package component linked to a gateway | Component Name, Gateway (lookup), External Service ID |
| Booking Confirmation | External system confirmation record | Confirmation Number, Status, External System Response, Component (lookup) |
See Also
- Package Fundamentals — core package structure, components, and pricing foundations
- Supplier & Service Setup — foundation layer for services and price categories (static components)
- Cost & Pricing Architecture — how pricing works across static and Live components
- Anyday Package Setup Guide — building packages that can include Live components
- Inventory Operations Guide — managing availability for static components
- Package Search Troubleshooting — diagnosing search issues including Connect-related pricing gaps