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

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

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. checkout() 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:

​
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. checkout() 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.