optionals.yaml reference
Everything about a Kaptio Experiences tenant is declared in one file in your config repository:
tenants/meridian/optionals/
├── optionals.yaml # this reference
└── src/ # tenant-owned UI source (React), bundled at runtime
├── main.jsx
└── styles.css
The file is validated against a published schema on every merge request. Changes go live on merge to main — no deployment step.
Complete example
The Meridian reference implementation, abbreviated:
tenant_id: meridian
product_id: td-optionals
provider: mock # mock | live
currencies: [GBP, USD, EUR]
brands:
- id: meridian_uk
name: Meridian Travel UK
logo_url: https://cdn.example.com/meridian/uk-logo.svg
mark_url: https://cdn.example.com/meridian/uk-mark.svg
tagline: Journeys worth taking
theme:
primary: "#0e5a4a"
primary_dark: "#0a3f34"
accent: "#d97f2e"
background: "#faf9f7"
surface: "#ffffff"
text: "#1a1a1a"
text_muted: "#6b6b6b"
font_family: "'Inter', system-ui, sans-serif"
- id: meridian_us
name: Meridian Travel US
logo_url: https://cdn.example.com/meridian/us-logo.svg
theme:
primary: "#28406e"
features:
gratuities: true
vouchers: true
cash_payments: true
split_payments: true
pre_trip_purchase: true
payment:
gateway: simulated # simulated | edge_pay
surcharge_bps: 0
settlement:
admin_fee_percent: 3
cadence: weekly
ui:
title: Meridian Experiences
favicon_url: https://cdn.example.com/meridian/favicon.png
Top-level fields
| Field | Type | Default | Description |
|---|---|---|---|
tenant_id | string | required | Your tenant slug. Must match the tenant directory name. |
product_id | string | td-optionals | Product identifier, echoed in the public GET /config response. |
provider | mock | live | mock | Where reference data (trips, guests, products) comes from. mock serves a complete seeded world for evaluation and training. live connects to your Salesforce org and product content platform — see live. |
currencies | string[] | [EUR, GBP, CHF] | Supported trip currencies (ISO 4217). Guests always see and pay in their trip's currency; settlement runs are grouped per currency. |
Brands
brands is a list with at least one entry. The brand shown to a guest or Tour Director is resolved from the trip, not from the URL — one deployment serves all brands.
Brands here are marketing identities. Legal entities (business units) and where each brand's takings settle are modeled separately, in your payment-gateway merchant accounts and the finance export — several brands can share one legal entity. That mapping is agreed during implementation; see Integration architecture.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Stable brand identifier referenced by trips. |
name | string | Yes | Display name. |
logo_url | string | Yes | Full-size logo for headers. |
mark_url | string | No | Small square mark for favicons and avatars. |
tagline | string | No | Strapline shown on the guest landing screen. |
theme | object | Yes | Color and typography tokens, below. |
Brand theme
| Field | Default | Description |
|---|---|---|
primary | required | Primary brand color. |
primary_dark | — | Darker shade for header bars and button hover states. |
accent | — | Accent color for highlights and calls to action. |
background | #faf9f7 | Page background. |
surface | #ffffff | Card and panel background. |
text | #1a1a1a | Main text color. |
text_muted | #6b6b6b | Secondary text. |
font_family | 'Inter', system-ui, sans-serif | Body font stack. |
heading_font_family | — | Optional heading override. |
Features
Feature flags gate whole capabilities across the UI and the API. All default to true.
| Flag | What it enables |
|---|---|
gratuities | Gratuity items (Tour Director and driver) in guest checkout and assisted sales. |
vouchers | Voucher redemption at checkout, voucher issuance by staff, and voucher management in the console. |
cash_payments | Cash recording by Tour Directors. |
split_payments | Partial payments by named party members against one order. |
pre_trip_purchase | Guest purchasing before the trip departs (otherwise sales open on tour). |
Payment
| Field | Default | Description |
|---|---|---|
gateway | simulated | simulated runs an in-app sandbox gateway with deterministic test cards, clearly labelled in the UI — evaluation and training tenants use this. edge_pay routes card payments through the production Edge Pay path (payment session → Kaptio Pay → the PCI-certified gateway). Switching is this one value; the API surface is identical. |
surcharge_bps | 0 | Card surcharge in basis points applied at checkout (0 = none). |
Settlement
| Field | Default | Description |
|---|---|---|
admin_fee_percent | 3 | Administration fee percent deducted from each Tour Director's gross settled amount. Applied by settlement runs and shown as a credit line in the finance export. |
cadence | weekly | daily or weekly. Informational — drives the default period suggested in the console; runs are always triggered explicitly with an exact period. |
UI
All optional.
| Field | Description |
|---|---|
title | Browser title for the tenant apps. |
favicon_url | Favicon override (falls back to the brand mark_url). |
meta | Map of extra <meta> tags. |
dependencies | Map of extra npm packages available to your UI source, pinned by version. |
demo_credentials | Pre-fills login forms (guest, Tour Director, admin) and simulated payment fields for scripted walkthroughs. Only meaningful for provider: mock tenants — omit it everywhere else. |
Live integration settings
The live block carries the integration contracts used when provider: live. The mock provider ignores it entirely, so an evaluation tenant can stage its live configuration ahead of cutover.
live:
salesforce:
sf_environment: production
trip_object: KaptioTravel__Itinerary__c
writeback: true
| Field | Default | Description |
|---|---|---|
salesforce.sf_environment | required | Which of your configured Salesforce environments serves trips and guests. Connectivity uses the Edge Admin Backend's centralized OAuth — no credentials in this file. |
salesforce.trip_object | KaptioTravel__Itinerary__c | The object trips are read from. |
salesforce.writeback | true | Whether confirmed purchases, refunds, and gratuities post back to the booking record. |
Two further sub-blocks configure the product content feed (feed URL, sync mode — continuous or overnight — and an API key held as a vault:: reference) and the finance export (batch or API delivery, schedule, destination reference). Their exact shape is agreed during your implementation's integration workshops and documented in your tenant repository, because they mirror your content platform's and accounts-payable system's contracts. See Integration architecture for the design of both.
As everywhere in Edge configuration, secrets never appear in YAML. API keys and destination credentials are stored in the platform vault and referenced as vault::key_name.
Tenant UI source
optionals/src/ contains the React source for all three surfaces, bundled server-side at runtime — the same model as Edge Journeys tenant UI. The rules match: .jsx, .js, .css, and .json files only; no Node.js built-ins; no secrets. The UI calls the same-origin /api/optionals/v1 endpoints exclusively.