Skip to main content
Booking with Jinko is a staged workflow. Once you’ve picked a candidate flight or hotel, every action mutates a server-side trip until you ship the user to a Stripe checkout page. This page explains the moving parts. If you just want to ship code, jump to the Flight booking guide.

​
The pipeline

discovery → live pricing → trip → travelers → (ancillaries?) → quote → checkout → user pays → fulfillment
Each arrow is a server call. The session state lives on the trip, you never reconstruct it client-side.

​
Discovery vs live pricing

Two tools play here:
  • Discovery (find_destination, flight_calendar, find_dates, lowest_fare) is cached. Returns broad, fast, exploratory results. Prices may be 5-30 minutes stale.
  • Live pricing (flight_search, hotel_search) hits the upstream provider directly. Returns a trip_item_token you can add to a trip.
You always go discovery → live pricing before adding to a trip. The discovery offer_token is not bookable on its own, pass it to flight_search (price-check mode) to get a fresh trip_item_token.

​
Tokens and IDs

TokenWhere it comes fromWhat it does
offer_tokenDiscovery (find_destination, flight_calendar, find_dates, lowest_fare)Identifies a candidate itinerary. Pass to flight_search to get pricing.
trip_item_tokenLive pricing (flight_search, hotel_search)Identifies a price-checked item. Pass to trip(add_item).
htl_* tokenhotel_search ratesSame role as trip_item_token for hotels. Pass to trip(add_item).
trip_id (sometimes cart_id in legacy infra)First call to trip()Identifies the mutable trip for the rest of the flow.
quoted_cart_id / quoted item IDsInternal to the quote responseUsed by select_ancillaries to target a specific quoted item. The quoted_cart_id is the trip-side echo of trip_id.
checkout_url / session_idbook() responseStripe-hosted page where the user completes payment.
booking_ref (JNK-*)After fulfillmentCustomer-facing booking reference. Use with get_booking and refund/exchange tools.
pnrAfter fulfillmentAirline-side reservation locator. Surface in confirmation emails.
Tokens are scoped, an offer_token from yesterday won’t work today. Always go through the pipeline fresh.

​
Trip vs cart vs quote

  • Trip is the canonical user-facing name across SDK / CLI / MCP / API docs. All public examples and tool names use it (trip, getTrip, trip_id).
  • Cart is a legacy internal name that surfaces in one place: some server responses still return cart_id (numeric, the storage primary key) alongside trip_id. They identify the same object — prefer trip_id in your code.
  • A quote is the price-locked snapshot of a trip at a point in time. book() schedules a quote internally before creating the Stripe session, you don’t manipulate quotes directly.

​
Multi-domain trips

A single trip can hold flight items AND hotel items. They go through one Stripe checkout. To build a multi-domain trip: 
// 1. Add a flight
await client.trip({ add_item: { trip_item_token: 'offer_abc:fare_xyz' } })
// 2. Add a hotel to the same trip
await client.trip({ trip_id: '42', add_item: { trip_item_token: 'htl_def...' } })
// 3. Set travelers (one set, applies to all items)
await client.trip({ trip_id: '42', upsert_travelers: { /* ... */ } })
// 4. Single book() schedules a unified checkout
await client.book('42')

​
Providers

The API aggregates multiple upstream providers behind a unified API. As of this writing:
  • Flights: TravelFusion (NDC + LCC), Sabre (GDS).
  • Hotels: Nuitée (LiteAPI).
You usually don’t need to think about providers, the API picks the cheapest / fastest match. The provider field is exposed on responses (and accepted as an override on refund/exchange) for cases where you need to target one explicitly.

​
Hosted checkout

Jinko owns the payment surface. You never touch credit-card data. Flow:
  1. book() returns a checkout_url pointing at app.gojinko.com/checkout?sid=<session>.
  2. Send the user there (open in browser, deep-link from a widget, etc.).
  3. They pay on Stripe-hosted UI.
  4. Stripe webhooks finalize the booking, no client confirm step needed.
  5. Poll getTrip to watch fulfillment status (pending → fulfilling → completed | failed).
The user’s money never enters your system. You don’t need PCI compliance to use Jinko.

​
Async fulfillment

Booking confirmation isn’t always instant, TravelFusion bookings can take up to 72 hours to confirm with the airline. The API handles this with a job queue (River + Postgres). You poll getTrip to watch state; the user gets confirmation emails directly from Jinko when their booking lands. For end-to-end mechanics, see the Flight booking guide or the Flight + Hotel guide for a multi-item trip.