> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dev.gojinko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Concepts

> Trip, quote, fulfillment, the mental model for Jinko's booking flow.

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](/guides/flight-booking).

## 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

| Token                                           | Where it comes from                                                            | What it does                                                                                                            |
| ----------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `offer_token`                                   | Discovery (`find_destination`, `flight_calendar`, `find_dates`, `lowest_fare`) | Identifies a candidate itinerary. Pass to `flight_search` to get pricing.                                               |
| `trip_item_token`                               | Live pricing (`flight_search`, `hotel_search`)                                 | Identifies a price-checked item. Pass to `trip(add_item)`.                                                              |
| `htl_*` token                                   | `hotel_search` rates                                                           | Same 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 IDs              | Internal to the quote response                                                 | Used by `select_ancillaries` to target a specific quoted item. The `quoted_cart_id` is the trip-side echo of `trip_id`. |
| `checkout_url` / `session_id`                   | `checkout()` response                                                          | Stripe-hosted page where the user completes payment.                                                                    |
| `agent_spt_params`                              | `checkout()` response                                                          | Constraints (max amount, currency, profile) an agent uses to mint a Shared Payment Token for `submit_agent_payment`.    |
| `booking_ref` (`JNK-*`)                         | After fulfillment                                                              | Customer-facing booking reference. Use with `get_booking` and refund/exchange tools.                                    |
| `pnr`                                           | After fulfillment                                                              | Airline-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. `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:

```typescript theme={null}
// 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 checkout() schedules a unified checkout
await client.checkout('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. `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](/guides/flight-booking) or the [Flight + Hotel guide](/guides/flight-hotel-booking) for a multi-item trip.