Quickstart

Call the Journeys API in the next ten minutes — no credentials, no platform dependencies — then graduate to a live tenant.

Prerequisites

Requirement	Detail
Kaptio managed package version	The Journeys live provider requires your Salesforce org to run the Kaptio managed package on the Hawaii release line or later. Iceland (the current line) is recommended — it carries the full commerce API surface the live provider depends on. Earlier versions (Fiji and before) are not compatible.
Tenant configuration	A journey.yaml in your tenant config repo — see the journey.yaml reference
Live credentials	Issued per tenant during private beta onboarding (see Going live)

The mock provider needs none of this — it runs against fixture data with the identical API contract, which is why it's the right place to start.

From catalog to booking (mock provider)

The meridian cruise reference tenant runs provider: mock on staging, so you can walk the entire booking flow with curl — catalog, basket, room, travellers, pricing, payment, booking.

One session detail: the platform pins your session to a serving instance with a load-balancer cookie, so pass a cookie jar (-c/-b) on every call — exactly as a browser would.

BASE="https://journeys.edge.staging.kaptioapis.com/api/journeys/v1"
TENANT="meridian"
JAR="cookies.txt"

1. Browse the catalog

curl -c $JAR -b $JAR "$BASE/catalog/trips?tenantId=$TENANT"

2. Create a basket (use a departure from the trips response)

curl -c $JAR -b $JAR -X POST "$BASE/baskets" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "'$TENANT'",
    "package_id": "PKG-001",
    "departure_id": "2026-11-18",
    "occupancy": [{ "adults": 2, "children": 0 }],
    "channel_id": "b2c-direct",
    "currency_code": "USD"
  }'

Capture data.id from the response as $BASKET_ID.

3. Select a room (selection context comes from GET /catalog/rooms)

curl -c $JAR -b $JAR -X PATCH "$BASE/baskets/$BASKET_ID/components" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "'$TENANT'",
    "components": [{
      "component_id": "CMP-001",
      "selections": [{ "option_id": "1", "item_option_id": "Balcony Stateroom C", "cabin_id": "512" }]
    }]
  }'

The neutral /catalog/trips and /catalog/rooms routes are aliases of the original /catalog/voyages and /catalog/cabins routes. Existing clients can keep the original paths. The payload and query field names remain backward-compatible.

For a group-touring tenant, the sequence is identical: choose a dated trip, request room options such as Twin or Single from /catalog/rooms, and pass the returned selection context into the basket. Touring catalogs do not require a vessel, deck plan, or physical cabin number.

4. Add travellers and price it

curl -c $JAR -b $JAR -X PUT "$BASE/baskets/$BASKET_ID/travellers" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "'$TENANT'",
    "travellers": [
      { "id": "1", "first_name": "Jane", "last_name": "Smith", "email": "jane@example.com", "contact": true },
      { "id": "2", "first_name": "Alex", "last_name": "Smith", "email": "alex@example.com" }
    ]
  }'

curl -c $JAR -b $JAR "$BASE/baskets/$BASKET_ID/prices?tenantId=$TENANT"

5. Take the deposit — bookings require a completed payment, same as production. Pick a schedule, create a payment request, and (mock only) complete it directly:

curl -c $JAR -b $JAR "$BASE/baskets/$BASKET_ID/payment-schedules?tenantId=$TENANT"
# capture the deposit schedule id as $SCHEDULE_ID

curl -c $JAR -b $JAR -X POST "$BASE/baskets/$BASKET_ID/payment-requests" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "'$TENANT'",
    "pay_per_person": false,
    "passenger_payments": [{ "payment_schedule_rule_id": "'$SCHEDULE_ID'" }]
  }'
# capture data.id as $PAYMENT_REQUEST_ID

curl -c $JAR -b $JAR -X PUT "$BASE/baskets/$BASKET_ID/payment-requests/$PAYMENT_REQUEST_ID/complete" \
  -H "Content-Type: application/json" \
  -d '{ "tenantId": "'$TENANT'" }'

6. Book

curl -c $JAR -b $JAR -X POST "$BASE/baskets/$BASKET_ID/bookings" \
  -H "Content-Type: application/json" \
  -d '{ "tenantId": "'$TENANT'" }'

You now have a booking reference. Skipping the payment step returns 409 — the same guard that protects real checkouts. The full endpoint contract — parameters, response shapes, errors — is in the Journeys API reference, and the same contract is available machine-readable as an OpenAPI specification you can import into Postman, generate clients from, or hand to an AI coding agent.

From evaluation to a built experience

The quickstart and the OpenAPI spec are for evaluation and integration — verifying the contract, wiring the API into systems you already run, and letting your architects (or their AI tooling) inspect exactly what the platform does.

Building a booking experience works differently: you describe the flow you want, and our prompt-to-production pipeline generates it, reviews it, tests it, and deploys it to a branded domain — with the config and UI hosted on Edge in your tenant repository. The same pipeline serves every channel: web, workbench, chatbot, portal.

For runtime agent access — your own bots calling the platform as tools rather than HTTP — see MCP and SDK.

Going live

Live access is currently in private beta. Onboarding is done with your Kaptio implementation team and covers:

1. Tenant provisioning — your journey.yaml, channels, and commercial context (tax profile, accounts, package filter)
2. Credentials — OAuth client-credentials issued against your tenant's realm client; separate credentials per environment
3. Managed package check — verifying your org is on Hawaii or later (Iceland recommended)
4. Environment endpoints — your assigned base URLs, including dedicated in-country endpoints where your deployment requires them

Raise live access through your implementation team or account contact.