Platform API surface (exposable)
The Journeys API is a curated wrapper. Behind it sits the full Kaptio commerce platform — this page inventories that surface, so you can see what exists beyond the endpoints exposed today and what a journey can be extended to use.
Four services make up the relevant surface:
| Service | Role | Auth |
|---|---|---|
| Basket Service | Commerce session state — baskets, selections, travellers, promotions, payments, checkout | OAuth 2.0 bearer (Keycloak) |
| KTAPI | Catalog, availability, pricing, promotions, inventory, reservations engine | OAuth 2.0 bearer (Keycloak) or keypair |
| Edge Pay | Hosted payment-method selection and collection, including method-specific surcharges | Signed payment session / platform orchestration |
| Edge Composite | Batched Salesforce orchestration — queries and writes against the tenant org | Service token |
Access to platform APIs beyond the Journeys wrapper is provisioned per tenant during implementation — credentials are issued against your tenant's realm client, and every call is scoped to your tenant's data.
Basket Service
The commerce session engine the Journeys wrapper delegates to. Sixteen endpoints; the service publishes a machine-readable OpenAPI 3 specification with interactive documentation in each environment:
- Reference documentation (ReDoc): basket.staging.kaptioapis.com/redoc
- Machine-readable spec: basket.staging.kaptioapis.com/openapi.json
Production and in-country deployments serve the same documentation at their assigned base URLs.
Baskets
| Method | Path | Purpose |
|---|---|---|
| POST | /baskets | Create a basket for a package departure (occupancy, channel, currency, account, tax profile) |
| GET | /baskets/{basketId} | Retrieve basket with components, travellers, promotions |
| DELETE | /baskets/{basketId} | Delete a basket |
Components and travellers
| Method | Path | Purpose |
|---|---|---|
| PATCH | /baskets/{basketId}/components | Update option/add-on selections on components |
| DELETE | /baskets/{basketId}/components/{componentId} | Reset a single component's selections |
| PUT | /baskets/{basketId}/travellers | Replace the traveller list |
Pricing and promotions
| Method | Path | Purpose |
|---|---|---|
| GET | /baskets/{basketId}/prices | Calculate pricing for the current basket state (selections + promotions) |
| POST | /baskets/{basketId}/promotions | Apply a promotion code (validated against the promotion engine) |
| DELETE | /baskets/{basketId}/promotions/{code} | Remove a promotion code |
Payments and checkout
| Method | Path | Purpose |
|---|---|---|
| GET | /baskets/{basketId}/payment-schedules | Deposit/balance schedule options (pay_per_person supported) |
| POST | /baskets/{basketId}/payment-requests | Create or refresh a payment request |
| GET | /baskets/{basketId}/payment-requests | List payment requests for a basket |
| PUT | /baskets/{basketId}/payment-requests/{paymentRequestId}/complete | Mark a payment complete (payment-processor callback) |
| POST | /baskets/{basketId}/bookings | Convert the basket into a Salesforce itinerary |
Health
| Method | Path | Purpose |
|---|---|---|
| GET | /health/live | Liveness |
| GET | /health/ready | Readiness |
Note the Journeys wrapper exposes almost this entire surface 1:1 — the two exceptions today are DELETE .../components/{componentId} (reset a component) and GET .../payment-requests (list), both exposable on request.
Basket pricing can contain separate upstream price lines. Customer sales lines use applicable_to: sales; reseller commission lines can use applicable_to: reseller_commission. Journeys aggregates the latter into optional BasketPricing.commission_amount without changing the customer total. Commission eligibility comes from Kaptio reseller agreements scoped to the basket account and channel, with commission-group assignments determining the applicable rate.
The public Journeys projection does not expose a per-line commission allocation or a net_amount. If a channel uses “net” to mean customer sales less agent commission, calculate and label that view deliberately; do not confuse it with supplier cost or payment settlement.
KTAPI
The core commerce engine: catalog, availability, pricing, promotions, inventory, and reservations. All endpoints are versioned (/v1.0/, /v2.0/, /v3.0/).
Full reference documentation: KTAPI API reference (Stoplight) — endpoint-by-endpoint schemas, parameters, and examples.
The groups below are the commerce surface relevant to booking experiences; counts are current route counts per group.
Packages — search, availability, pricing (29 routes)
The group the Journeys catalog is built on.
| Endpoint (representative) | Purpose |
|---|---|
GET/POST /v1.0/packages/search | Package search with filters |
GET /v1.0/packages/{id} | Package detail — departures, components, options |
GET /v1.0/packages/availabilities (+ v2) | Availability across packages |
GET /v1.0/packages/{id}/departures, GET /v2.0/packages/departures | Departures, single and bulk |
POST /v1.0/packages/{id}/prices (+ v2/v3 bundle-aware) | Package pricing |
POST /v1.0/packages/{id}/prices_bulk | Bulk pricing across departures |
POST /v1.0/packages/{id}/prices_alternatives | Price alternatives (nearby dates/occupancies) |
POST /v1.0/packages/{id}/options | Component options |
GET/POST /v1.0/packages/{id}/pre_post_options (+ v2 with rooms) | Pre/post-stay extensions |
GET /v1.0/packages/search_cruise | Cruise-specific search |
GET /v1.0/packages/{id}/cruise_details | Ship, cabin-type inventory, cruise pricing |
GET /v1.0/packages/{id}/cabins | Cabin-level availability and prices |
GET /v1.0/packages/cabin_availabilities_prices | Cabin availability + prices across packages |
POST /v1.0/packages/{id}/live_auto_select | Auto-select cheapest valid configuration |
POST /v1.0/packages/timetables | Departure timetables |
Items — search, pricing, inventory, reservations (29 routes)
Item-level commerce for individual services (hotels, transfers, activities) outside a package context.
| Endpoint (representative) | Purpose |
|---|---|
POST /v1.0/items/search/{itemType} | Search items by type |
POST /v1.0/items/prices_bulk (+ v2/v3) | Bulk item pricing |
POST /v1.0/items/inventory_bulk (+ v2) | Bulk inventory checks |
GET /v1.0/items/{id}/inventory | Single-item inventory |
POST /v1.0/items/create_reservation/{itemType} | Create a reservation |
POST /v1.0/items/confirm_reservation/{itemType} | Confirm a reservation |
POST /v1.0/items/price_finder | Cheapest-price discovery |
Promotions (6 routes)
The engine behind promotion codes, campaign discounts, and combinability rules.
| Endpoint | Purpose |
|---|---|
GET/POST /v1.0/promotions | List/create promotions |
POST /v1.0/promotions/check (+ v2) | Validate a code against a booking context |
POST /v1.0/promotions/check_bulk | Validate codes across many contexts |
POST /v1.0/promotions/search | Search promotions |
/v1.0/promotions/combinability_groups | Combinability rules |
Itineraries — pricing, schedules, cancellations (11 routes)
Operations on existing bookings.
| Endpoint (representative) | Purpose |
|---|---|
POST /v1.0/itineraries/bulk_calculate_prices | Bulk reprice itineraries |
POST /v1.0/itineraries/price_breakdown | Line-level price breakdown |
POST /v1.0/itineraries/bulk_calculate_seasons / recalculate_seasons | Season recalculation |
POST /v1.0/itineraries/payment_schedule | Payment schedule calculation |
POST /v1.0/itineraries/cancellations/rules | Cancellation rule generation |
POST /v1.0/itineraries/supplier_cancellation_fees | Supplier-side cancellation fees |
These itinerary routes are underlying platform capabilities, not public Journeys lifecycle endpoints. In particular, cancellation-rule and supplier-fee routes calculate consequences; they do not make POST /api/journeys/v1/.../cancellations exist. The current Journeys API creates bookings only.
Supporting groups
| Group | Routes | Representative endpoints |
|---|---|---|
| Services availability | 1 | POST /v1.0/services/availability |
| Allotment days | 4 | /v1.0/allotment_days, /v2.0/allotment_days, by-date, by-items |
| Rail | 12 | /v1.0/rail/search, reservations, cancellations |
| Channels | 3 | /v1.0/channels, /v2.0/channels |
| Tax profiles | 3 | /v1.0/tax_profiles |
| Service levels | 3 | /v1.0/service_levels |
| Bookings | 1 | POST /v1.0/booking/payment_schedule |
Internal relay, callback, and deprecated route groups exist but are not part of the tenant-facing surface and are excluded here.
AI-native access (MCP)
The exposed Journeys surface is packaged for AI agents as MCP (Model Context Protocol) tools and an SDK — package discovery, availability and pricing, basket management, payment requests, and booking creation. Existing-itinerary amendments, cancellations, and refunds are not agent-callable Journeys tools unless a tenant-specific extension has been explicitly delivered.
Edge Pay
Edge Pay owns the payment page and the amount authorized for the selected payment method. Payment methods are enabled per tenant in payment.yaml; each method can set:
payment_methods:
card:
enabled: true
surcharge_percent: 1.5
Edge Pay calculates method-specific previews from this configuration when it creates a Journeys embed session. Journeys forwards them as surcharge_options but does not independently calculate or persist the fee. The selected method and completed Edge Pay transaction remain authoritative; the completed payment response carries surcharge_breakdown.
This is separate from a KTAPI Fee line:
- An itinerary Fee line belongs to commercial itinerary pricing and exists independently of the payment method.
- A payment-method surcharge is selected at payment time, configured in
payment.yaml, and applied by Edge Pay.
Edge Composite
Batched, declarative orchestration against the tenant's Salesforce org — for workbench and integration scenarios where a frontend needs Salesforce reads/writes without owning Salesforce plumbing.
| Method | Path | Purpose |
|---|---|---|
| POST | /edge/v1/{tenantId}/{sfEnvironment}/composite | Execute an ordered step collection |
| POST | /edge/v1/{tenantId}/{sfEnvironment}/composite/dry-run | Validate a collection structurally without executing |
A collection is a JSON document of ordered steps; each step is one of:
| Step action | Salesforce operation |
|---|---|
query | SOQL query |
create / update / upsert / delete | Batched DML via the Composite API |
apex | Call an Apex REST endpoint in the managed package |
Steps can reference prior steps' outputs, so one request can express "query the itinerary, update its status, call the pricing Apex endpoint" — one round trip from the client, parallel-safe execution on the platform. Salesforce sessions are resolved per tenant and environment from the tenant blueprint; no org credentials are handled by the caller.
Edge Composite is a generic orchestration primitive, not a published Journeys amendment, cancellation, or refund contract. A lifecycle feature still needs a tenant-safe route, validation, authorization, idempotency, and an explicit response schema before a Journeys client can call it.
Requesting surface expansion
If a booking experience needs a platform capability the Journeys wrapper doesn't expose yet — rail search, pre/post options, price alternatives, cancellation quotes, reservation holds, amendments, cancellations, or refunds — raise it with your implementation team. Platform capability does not imply that an execution endpoint already exists. Only routes in the Journeys API reference and OpenAPI contract are callable as the public Journeys API.