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?sid=...", ... }

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	Meaning
`pending`	Payment cleared, neither item booked yet
`fulfilling`	At least one item is still being booked
`completed`	Both items confirmed, `booking_ref` populated for each
`failed`	A provider rejected. Refund covers the full amount.

If only one of the two providers fails, Jinko rolls back the other booking and refunds the full charge. You get a single, atomic outcome: both succeed or neither does.

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.

const trip = await client.getTrip(tripId)
if (trip.fulfillment?.status === 'completed') {
  for (const booking of trip.bookings) {
    console.log(booking.type, booking.booking_ref)
  }
}

jinko trip-status --trip-id "$TRIP_ID" --format json | jq '.bookings'

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

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

​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

7) Watch the booking land

What’s next?