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 charge and receives a single confirmation with a single Jinko booking reference covering both bookings. This guide builds a week-long Paris trip (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 + contact) → trip(add_item hotel) → checkout → user pays → get_trip

Prerequisites

A Jinko account and an API key (jnk_t_...). 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_t_....
For the MCP path: any MCP client connected to https://mcp.builders.gojinko.com/mcp.

1) Discover the flight

Use discovery to compare cached options, then search live fares for the chosen route and dates. The examples below use today’s UTC date plus 60 days for departure and 67 days for return. These are sample dates; replace them with the traveler’s intended local departure and return dates before booking. See the Flight booking guide for the full distinction between route search and offer price-check.

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

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

const dateInDays = (days: number) =>
  new Date(Date.now() + days * 86_400_000).toISOString().slice(0, 10)
const departureDate = dateInDays(60)
const returnDate = dateInDays(67)

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: [departureDate],
  return_dates: [returnDate],
})

console.log(destinations)

// Search live fares for the selected route and dates, without offer_token.
// 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: departureDate,
  return_date: returnDate,
  trip_type: 'roundtrip',
})
const flight = priced.offers[0]
if (!flight?.fares?.[0]?.trip_item_token) {
  const recovery = priced.result === 'no_matches'
    ? 'No offer matched. Ask the traveler whether to change the filters, dates or airports before searching again.'
    : 'No live fare token returned. Inspect the response before continuing.'
  throw new Error(priced.instruction ?? recovery)
}
const flightToken = flight.fares[0].trip_item_token
// The returned arrival timestamp uses the destination airport’s local date.
const hotelCheckin = flight.outbound.arrival_datetime.slice(0, 10)

DEPARTURE_DATE=$(node -p "new Date(Date.now() + 60 * 86400000).toISOString().slice(0, 10)")
RETURN_DATE=$(node -p "new Date(Date.now() + 67 * 86400000).toISOString().slice(0, 10)")

jinko find-destination --origins JFK --destinations CDG \
  --origin-type airport --destination-type airport \
  --trip-type roundtrip --departure-dates "$DEPARTURE_DATE" --return-dates "$RETURN_DATE" \
  --format json | jq '.destinations[0]'

jinko flight-search \
  --origin JFK --destination CDG \
  --departure-date "$DEPARTURE_DATE" --return-date "$RETURN_DATE" \
  --format json > flight-search.json || exit 1
FLIGHT_TOKEN=$(jq -er '.offers[0].fares[0].trip_item_token // empty' flight-search.json) || {
  jq -r '.instruction // (
    if .result == "no_matches" then "No offer matched. Ask the traveler whether to change the filters, dates or airports before searching again."
    else "No live fare token returned. Inspect the response before continuing."
    end)' flight-search.json >&2
  exit 1
}
HOTEL_CHECKIN=$(jq -r '.offers[0].outbound.arrival_datetime[:10]' flight-search.json)

“Using today’s UTC date, what can I book from JFK to Paris (CDG), departing 60 days later and returning one week after departure?”

The agent calls find_destination to show cached options, then flight_search for the chosen route and dates. Pick a live fare; its trip_item_token is ready to drop into a trip.

The SDK and CLI calls above use route-search mode. Do not add offer_token to those requests: price-check is a separate mode that accepts a known offer token plus passengers, currency and locale, without route or date fields. If no live fare is returned, stop before deriving the hotel check-in date or building the trip. Read result and surface the returned instruction: no_matches means the search succeeded, so follow the instruction: it asks which filter to relax when the search sent a narrowing filter, otherwise whether to try other dates or airports. A search that could not be completed returns an error instead, which does not mean there are no flights: follow the remedy for the error code; retry a 503 or 504 later with the same filters. Continue only after selecting an available flight fare.

2) Find the hotel

Search hotels from the selected outbound flight’s local arrival date until the return departure date. An overnight flight can arrive the day after departure; confirm check-in against the actual itinerary. Hotel rates are already live offers, no separate price-check step is needed.

const hotels = await client.hotelSearch({
  query: 'Paris',
  checkin: hotelCheckin,
  checkout: returnDate,
  adults: 1,
})

const offer = hotels.hotels[0]?.offers?.[0]
if (!offer?.trip_item_token) {
  throw new Error('No hotel rate matched. Adjust the destination, dates or filters and search again before building the trip.')
}
const hotelToken = offer.trip_item_token // htl_*

jinko hotel-search \
  --query Paris \
  --checkin "$HOTEL_CHECKIN" --checkout "$RETURN_DATE" \
  --adults 1 \
  --format json > hotel-search.json || exit 1
HOTEL_TOKEN=$(jq -er '.hotels[0].offers[0].trip_item_token // empty' hotel-search.json) || {
  echo 'No hotel rate matched. Adjust the destination, dates or filters and search again before building the trip.' >&2
  exit 1
}

“And find me a 4-star hotel near the Louvre, checking in on the selected flight’s local arrival date and checking out on my return departure date.”

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.

If the hotel search returns no rate, stop here and adjust the search. Continue only after choosing an available hotel rate; do not add a missing or null hotel token to the trip.

3) Build the trip with both items

Now the key step. Add the flight to a new trip and set travelers and booking contact 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.

Travelers identify the passengers and guests; the booking contact supplies an email and phone. Both belong to the trip and apply to its flight and hotel items. With REST or the SDK, you can omit upsert_travelers.contact while building the trip, but provide both contact.email and contact.phone before calling checkout. The phone must be in international format: a leading + and country code, e.g. +12025550147. Spaces, hyphens, dots and parentheses are accepted and removed; a number without the leading + (including a 00 prefix) is rejected with INVALID_PHONE_NUMBER. Passenger details alone are not enough to book either product.With MCP, every upsert_travelers call must include contact. You can add trip items first, then submit travelers and contact together once both are available.

// Create the trip with the flight, travelers, and booking contact 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',
      traveler_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, and booking contact 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","traveler_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. Trip creation does not price them. Treat search prices as provisional and read the authoritative combined total after checkout successfully quotes the trip.

4) Checkout

Once the shared travelers and booking contact are set, call checkout once. You get one 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 Jinko checkout 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, and enters payment once. Jinko holds the authorization until the bookings settle.

6) Fulfillment

Once the payment is authorized, fulfillment starts for both items. They book in parallel and the booking is completed once both providers confirm. Read booking_state on get_trip for the booking’s progress:

`booking_state`	Terminal	Meaning
`awaiting_payment`	no	Waiting on the customer’s payment authorization. It appears when the customer presses Pay (or an agent submits a payment) and stays until the payment is authorized.
`processing`	no	At least one item is still being booked or confirmed.
`needs_review`	no	A person at Jinko is resolving the booking. Keep polling; it is not final.
`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, or the quote expired before the payment was authorized. The authorization is released or refunded automatically.
`cancelled`	yes	Fulfillment was cancelled before it completed.

fulfillment.status keeps the detailed status behind booking_state, for example preparing, confirming or expired_quote, if you need it for support.

fulfillment is absent until the customer pays. POST /v1/checkout does not create a fulfillment record. It quotes the trip 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 booking_state, no fulfillment and no bookings.fulfilling is a value of the trip’s own top-level status field, not of booking_state. Trip status and booking state explains how the fields relate.

A two-item trip is not atomic

One item can book while the other fails. Handle each item’s outcome independently.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 and does not say which one booked; the webhook below does.
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, checking booking_state when present. Stop when it reaches a terminal value or the trip’s top-level status is expired. If bookings is present, it lists the flight and hotel entries, failed ones included; booking_state gives the outcome.

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

const trip = await client.getTrip(tripId)
const status = trip.booking_state

if (status && TERMINAL.includes(status)) {
  // bookings[] lists every attempted item, failed ones included, and
  // carries no per-item outcome: never assume it is all confirmations.
  // On 'partial', the booking.partial webhook says which item booked.
  for (const booking of trip.bookings ?? []) {
    console.log(status, booking.item_id, booking.kind, booking.supplier_references)
  }
}

Each entry is { item_id, kind, supplier_references }. supplier_references lists the supplier confirmations, each { issuer, reference }, and is [] when none is known. kind is "flight" or "hotel".

jinko trip-status --trip-id "$TRIP_ID" --format json \
  | jq -r '.bookings[]? | "\(.item_id)\t\(.kind)\t\([.supplier_references[]?.reference] | join(",") | if . == "" then "-" else . end)"'

bookings can be absent, so this filter skips a missing list. If it prints no rows, inspect the full trip-status response: check booking_state when present and the trip’s top-level status. Stop polling if the trip is expired. An absent bookings list alone does not tell you the outcome.

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 a rental car too: see the Car rental guide; the car_* offer is added with the same trip(add_item) call.
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

Marketing claim

Authentication

Connect

Developer Platform

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?