Trip

Assemble and edit a trip before sending it to checkout. Use it to add a flight, hotel, or car offer, set traveler details, swap one item for another, or attach ancillaries like bags and seats. Flights, hotels, and cars can sit side by side in the same trip and settle through a single checkout.

Tool description (what the LLM sees)

Create and manage a trip: add flight, hotel, or car items, remove items, set traveler details, and select ancillaries.

Operations:
- add_item: Add a flight, hotel, or car item to the trip. Pass trip_item_token from flight_search (one per fare), hotel_search (htl_* tokens) or car_search. Omit trip_id to create a new trip. MULTI-ROOM HOTEL: to book several rooms of the SAME hotel and stay as ONE booking with ONE reference, make ONE add_item call with rooms: [{trip_item_token: "htl_..."}, ...] (2-8 entries, one htl_* rate token per room, mutually exclusive with trip_item_token; not every hotel rate can be booked this way), do NOT add the same hotel twice as separate items.
- remove_item: Remove an existing item from the trip by item_id (from trip response items[].item_id). Requires an existing trip_id. Can be combined with add_item in a single call to swap an item, remove runs first, then add.
- upsert_travelers: Set traveler details and contact info on an existing trip_id.
- select_ancillaries: Select bags, seats, meals for a quoted trip item. Requires trip_id and item_id.

Returns trip_id for use with the checkout tool. Flights, hotels, and cars can coexist in the same trip (single checkout).

IMPORTANT, TRAVELER DATA:
NEVER invent or fabricate traveler data. Before calling upsert_travelers, you MUST ask the user for the required fields:
- Always: first_name, last_name, traveler_type
- date_of_birth (YYYY-MM-DD), required when the trip contains a flight, and for a child or infant staying at a hotel (the room is priced by the children's ages); optional for an adult on a hotel-only trip
- Flights only: gender (MALE/FEMALE), required when the trip contains a flight, optional for hotel-only trips
- Contact: email, phone in international format with a leading + and the country code (e.g. +12025550147); a number without the + is rejected with INVALID_PHONE_NUMBER
If a required field is missing, ASK the user. Do not use placeholder or default values.

ANCILLARY FLOW:
Ancillaries (bags, seats) appear as available_ancillaries on trip items once checkout has quoted the trip; offer them to the user before they pay.
Use select_ancillaries with offer_ids from available_ancillaries. Full replacement, send every desired selection (bags and seats) in each call.

SEATS (flights):
1. get_trip after checkout: each available_ancillaries entry with type "seat" covers one segment (segment_ref_ids) and lists seat_map.seats[] {seat_number, available, chargeable, price_money}.
2. Take each traveler's traveler_ref from the trip's travelers[].traveler_ref.
3. Send one selection per traveler per segment: {offer_id, traveler_ref, segment_ref_ids: [that offer's segment], seat_number}. Pick only available seats; no two travelers share a seat.
Read price_money for the exact seat price. Chargeable seats add their price to the trip total (the server sets the price); call checkout again to pay it. Ask before choosing a paid seat.

Flows:
- Flights: flight_calendar → flight_search → trip(add_item) → trip(upsert_travelers) → [checkout → trip(select_ancillaries)] → checkout
- Hotels: hotel_search → trip(add_item) → trip(upsert_travelers) → checkout
- Cars: car_search → trip(add_item) → trip(upsert_travelers) → checkout
- Mixed: supported item kinds in the same trip, one checkout

Parameters

Name	Type	Required	Description
`trip_id`	`string \| null`	No	Existing trip ID returned by trip or get_trip. Pass it back exactly as returned; omit it to create a new trip.
`add_item`	`object \| null`	No	Add a flight, hotel, or car item to the trip. For MULTIPLE ROOMS of the same hotel stay, make ONE add_item call with the rooms array (2-8 htl_* tokens), do NOT add the same hotel twice as separate items.
`remove_item`	`object \| null`	No	Remove an existing item from the trip. Requires an existing trip_id, you cannot remove from a trip that has not been created yet. Can be combined with add_item in a single call to swap an item (remove runs first, then add).
`upsert_travelers`	`object \| null`	No	Set or update travelers and contact info on the trip. Optional per call (you can add_item while building the trip), but travelers and a contact must be present before booking.
`select_ancillaries`	`object \| null`	No	Select ancillaries (bags, seats, meals) for a quoted trip item. Uses full-replacement semantics, send all desired selections.
`user_intent`	`string`	No	The end user’s current request in their own words, e.g. “help me with my travel plans”. Pass it as-is when short; otherwise condense the goal and constraints into 1-2 sentences. Strip personal identifiers (names, emails, phone numbers, addresses, payment details), replace them with placeholders like “[name]”. Optional. Jinko uses it to understand demand, and hotel_search uses it to rank hotel results against what the user asked for (e.g. “quiet, with a gym, near Times Square”), so keep the user’s stated preferences in it.

Examples

Create a new trip (add flight + set travelers in one call):

{
  "name": "trip",
  "arguments": {
    "add_item": {
      "trip_item_token": "offer_abc123:fare_xyz"
    },
    "upsert_travelers": {
      "travelers": [
        {
          "first_name": "Jane",
          "last_name": "Doe",
          "date_of_birth": "1990-01-15",
          "gender": "FEMALE",
          "traveler_type": "adult",
          "frequent_flyer": { "airline": "LH", "number": "992100100" }
        }
      ],
      "contact": {
        "email": "jane@example.com",
        "phone": "+33612345678"
      }
    }
  }
}

Add a hotel to an existing trip:

{
  "name": "trip",
  "arguments": {
    "trip_id": "42",
    "add_item": { "trip_item_token": "htl_abc..." }
  }
}

Update travelers only (no new items):

{
  "name": "trip",
  "arguments": {
    "trip_id": "42",
    "upsert_travelers": {
      "travelers": [
        { "first_name": "Jane", "last_name": "Doe", "date_of_birth": "1990-01-15", "gender": "FEMALE", "traveler_type": "adult", "frequent_flyer": { "airline": "LH", "number": "992100100" } },
        { "first_name": "John", "last_name": "Doe", "date_of_birth": "2015-05-20", "gender": "MALE", "traveler_type": "child" }
      ],
      "contact": { "email": "jane@example.com", "phone": "+33612345678" }
    }
  }
}

Add a frequent-flyer number: Each traveler can carry an optional frequent_flyer object so miles are credited on the booking. airline is the IATA code of the program issuer (e.g. LH for Lufthansa Miles & More), not necessarily the operating carrier, since alliances credit miles on partner flights. Both airline and number are required when the object is present. Include upsert_travelers.contact with every MCP traveler update, even when only adding a frequent-flyer number. Use the booking contact’s email and phone; the phone must be in international format with a leading + and country code, e.g. +12025550147.

{
  "name": "trip",
  "arguments": {
    "trip_id": "42",
    "upsert_travelers": {
      "travelers": [
        {
          "first_name": "Jane",
          "last_name": "Doe",
          "date_of_birth": "1990-01-15",
          "gender": "FEMALE",
          "traveler_type": "adult",
          "frequent_flyer": { "airline": "LH", "number": "992100100" }
        }
      ],
      "contact": {
        "email": "jane@example.com",
        "phone": "+33612345678"
      }
    }
  }
}

Traveler details must match real travel documents, airlines enforce name / DOB matching and reject bookings where they don’t. Never let an agent fabricate these.

The response includes trip_id, the current item list, and totals. Use trip_id with checkout when you’re ready to check out.

Introduction

Flights

Hotels

Cars

Trip & Payment

Marketing claim

Parameters

Examples

​Parameters

​Examples

Parameters

Examples