Flight + Hotel booking

Most real journeys involve more than one item. Jinko’s trip is a single booking unit: you can put a flight and a hotel into the same trip, set the travelers once, and check out once. The user pays a single Stripe charge and receives a single confirmation with a single Jinko booking reference covering both bookings. This guide builds a Paris weekend (a flight from JFK to CDG and a hotel in Paris) end to end with side-by-side examples for SDK, CLI, and MCP. The one-line version of the flow:

flight discovery → flight_search → hotel_search → trip(add_item flight + travelers) → trip(add_item hotel) → checkout → user pays → get_trip

Prerequisites

A Jinko account and an API key (jnk_...). Get one.
For the SDK path: Node.js 20 or later, then npm install @gojinko/api-client.
For the CLI path: npm install -g @gojinko/cli && jinko auth login --key jnk_....
For the MCP path: any MCP client connected to https://mcp.builders.gojinko.com/mcp.

1) Discover the flight

Discover flights for the route and dates, then confirm pricing on the candidate the user picks. This is the same first two steps as the Flight booking guide, so we keep it short.

import { createJinkoClient } from '@gojinko/api-client'

const client = await createJinkoClient({ apiKey: process.env.JINKO_API_KEY })

const { destinations } = await client.findDestination({
  origins: ['JFK'],
  destinations: ['CDG'],          // filter discovery to your target airport
  origin_type: 'airport',
  destination_type: 'airport',
  trip_type: 'roundtrip',
  departure_dates: ['2026-06-15'],
  return_dates: ['2026-06-22'],
})

// flight_search is flat: origin/destination/departure_date are required;
// offer_token (optional) re-prices the discovered candidate. The returned
// fare's trip_item_token is ready to add to a trip as-is.
const priced = await client.flightSearch({
  origin: 'JFK',
  destination: 'CDG',
  departure_date: '2026-06-15',
  return_date: '2026-06-22',
  trip_type: 'roundtrip',
  offer_token: destinations[0].flights[0].offer_token,
})
const flightToken = priced.offers[0].fares[0].trip_item_token

FLIGHT_OFFER=$(jinko find-destination --origins JFK --destinations CDG \
  --origin-type airport --destination-type airport \
  --trip-type roundtrip --departure-dates 2026-06-15 --return-dates 2026-06-22 \
  --format json | jq -r '.destinations[0].flights[0].offer_token')

FLIGHT_TOKEN=$(jinko flight-search \
  --origin JFK --destination CDG \
  --departure-date 2026-06-15 --return-date 2026-06-22 \
  --offer-token "$FLIGHT_OFFER" \
  --format json | jq -r '.offers[0].fares[0].trip_item_token')

“From JFK, what can I book to Paris (CDG), leaving June 15 and returning June 22?”

The agent calls find_destination to surface candidates. Pick one; it then calls flight_search to confirm the live price and surface fare options. The agent now has a flight trip_item_token ready to drop into a trip.

2) Find the hotel

Search hotels at the destination for the same dates. Hotel rates are already live offers, no separate price-check step is needed.

const hotels = await client.hotelSearch({
  destination: { query: 'Paris' },
  checkin: '2026-06-15',
  checkout: '2026-06-22',
  adults: 1,
})

const hotelToken = hotels.hotels[0].rooms[0].rates[0].offer_id // htl_*

HOTEL_TOKEN=$(jinko hotel-search \
  --destination '{"query":"Paris"}' \
  --checkin 2026-06-15 --checkout 2026-06-22 \
  --adults 1 \
  --format json | jq -r '.hotels[0].rooms[0].rates[0].offer_id')

“And find me a 4-star hotel near the Louvre for the same dates.”

The agent calls hotel_search and shows you matching hotels and rates. Pick one. The agent now has a hotel htl_* offer ID ready for the next step.

3) Build the trip with both items

Now the key step. Add the flight to a new trip and set travelers in the same call. Then add the hotel to the same trip with a second trip(add_item) call. Both items now live on the same trip and will check out together.

// Create the trip with the flight + travelers in one call.
const trip = await client.trip({
  add_item: { trip_item_token: flightToken },
  upsert_travelers: {
    travelers: [{
      first_name: 'Jane',
      last_name: 'Doe',
      date_of_birth: '1990-01-15',
      gender: 'FEMALE',
      passenger_type: 'ADULT',
    }],
    contact: {
      email: 'jane@example.com',
      phone: '+33612345678',
    },
  },
})
const tripId = trip.trip_id

// Append the hotel to the same trip.
await client.trip({
  trip_id: tripId,
  add_item: { trip_item_token: hotelToken },
})

# Create the trip with the flight + travelers in one call.
TRIP_ID=$(jinko trip \
  --trip-item-token "$FLIGHT_TOKEN" \
  --travelers '[{"first_name":"Jane","last_name":"Doe","date_of_birth":"1990-01-15","gender":"FEMALE","passenger_type":"ADULT"}]' \
  --contact '{"email":"jane@example.com","phone":"+33612345678"}' \
  --format json | jq -r '.trip_id')

# Append the hotel to the same trip.
jinko trip --trip-id "$TRIP_ID" --trip-item-token "$HOTEL_TOKEN"

The agent calls trip(add_item + upsert_travelers) with the flight token, then a second trip(add_item) with the hotel offer ID and the same trip_id. From the user’s point of view, this is one continuous conversation.

Travelers belong to the trip, not to each item. Set them once with upsert_travelers and they apply to every flight and hotel on the trip.

The trip response now contains two items[]: the flight and the hotel. The total price is the sum of both, in the same currency.

4) Checkout

Call checkout once. You get one Stripe checkout_url covering both items.

const { checkout_url } = await client.checkout(tripId)
console.log('Open in browser:', checkout_url)

jinko checkout --trip-id "$TRIP_ID"
# → { "checkout_url": "https://app.gojinko.com/checkout?t=...", ... }

The agent calls checkout and opens the checkout in a browser window. The Stripe page shows both items, the combined total, and a single payment.

5) User pays

The user opens checkout_url, sees the flight and the hotel side by side with one total, enters payment once, and Stripe holds the authorization.

6) Fulfillment

Stripe webhooks trigger fulfillment for both items. They book in parallel and the trip is completed once both providers confirm.

State	Terminal	Meaning
`awaiting_payment`	no	Fulfillment is scheduled and waiting on the customer’s payment authorization.
`preparing`	no	Assembling what each provider needs.
`prepared`	no	Ready to call both providers.
`processing`	no	At least one item is still being booked.
`confirming`	no	A provider accepted; Jinko is waiting on the final confirmation.
`completed`	yes	Both items confirmed. `bookings[]` has an entry for each.
`partial`	yes	One item booked and the other did not. See below.
`failed`	yes	Neither item booked. The authorization is released or refunded automatically.
`cancelled`	yes	Fulfillment was cancelled before it completed.
`expired_quote`	yes	The quote expired before payment was authorized. Re-quote and check out again.
`exchange_partial_failure`	yes	Exchange flows only. Part of an exchange landed and part didn’t; Jinko support finishes it by hand.

fulfillment is absent until the customer pays. POST /v1/checkout does not create a fulfillment record. It quotes the cart and hands you a checkout_url. The record appears, at awaiting_payment, when the customer presses Pay. Before then get_trip returns quote but no fulfillment and no bookings.pending is an item-level status and never appears as a trip’s fulfillment.status. fulfilling is a value of the trip’s own top-level status field, not of fulfillment.status, despite what older versions of this page said.

A two-item trip is not atomic

One item can book while the other fails. This page previously promised “a single, atomic outcome: both succeed or neither does”. That was never true, and it is the assumption most likely to break a multi-item integration.When exactly one provider confirms, the trip lands on partial:

The item that booked stays booked. Jinko does not roll it back.
You are charged only for the item that booked. The rest of the authorization is released.
bookings[] contains both entries. Read provider_status on each to tell them apart.
A booking.partial webhook fires, carrying the per-item outcome and the amount actually captured.

Deciding what to do next is your call: rebook the failed leg, offer the customer the half that landed, or cancel it. Jinko will not choose for you.

7) Watch the booking land

Poll get_trip until fulfillment.status is terminal. The bookings[] array will contain entries for both the flight and the hotel, including any that failed.

const TERMINAL = [
  'completed',
  'partial',
  'failed',
  'cancelled',
  'expired_quote',
  'exchange_partial_failure',
]

const trip = await client.getTrip(tripId)
const status = trip.fulfillment?.status

if (status && TERMINAL.includes(status)) {
  // Handle 'completed' and 'partial' the same way: walk every entry and
  // check it individually. Never assume bookings[] is all confirmations.
  for (const booking of trip.bookings ?? []) {
    console.log(booking.kind, booking.booking_reference, booking.provider_status)
  }
}

Each entry is { item_id, kind, booking_reference, pnr?, provider_status? }. The field is booking_reference, not booking_ref, and kind is "flight" or "hotel", not type.

jinko trip-status --trip-id "$TRIP_ID" --format json \
  | jq -r '.bookings[] | "\(.kind)\t\(.booking_reference)\t\(.provider_status // "-")"'

The agent calls get_trip and reports both confirmation references back to the user. Jinko also sends a single confirmation email covering the full trip.

What’s next?

Just a flight: see the Flight booking guide for the full eight-step flow.
Just a hotel: see the Hotel booking guide.
Add ancillaries to the flight: see step 4 of the flight guide.
Refund or exchange the flight after booking: flight_refund and flight_exchange.
Troubleshooting: Errors has the full status-code reference.

Getting started

Guides

Authentication

Connect

Concepts

Prerequisites

1) Discover the flight

2) Find the hotel

3) Build the trip with both items

4) Checkout

5) User pays

6) Fulfillment

A two-item trip is not atomic

7) Watch the booking land

What’s next?

​Prerequisites

​1) Discover the flight

​2) Find the hotel

​3) Build the trip with both items

​4) Checkout

​5) User pays

​6) Fulfillment

​A two-item trip is not atomic

​7) Watch the booking land

​What’s next?

Prerequisites

1) Discover the flight

2) Find the hotel

3) Build the trip with both items

4) Checkout

5) User pays

6) Fulfillment

A two-item trip is not atomic

7) Watch the booking land

What’s next?