Skip to main content
Assemble and edit a trip before sending it to checkout. Use it to add a flight or hotel offer, set traveler details, swap one item for another, or attach ancillaries like bags and seats. Flights and hotels can sit side by side in the same trip and settle through a single checkout. 
Create and manage a trip: add flight or hotel items, remove items, set traveler details, and select ancillaries.

Operations:
- add_item: Add a flight or hotel to the trip. Pass trip_item_token from flight_search (offer__* tokens) or offer_id from hotel_search (htl_* tokens). Omit trip_id to create a new trip.
- 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 book tool. Flights and hotels can coexist in the same trip (single Stripe checkout).

IMPORTANT — TRAVELER DATA:
NEVER invent or fabricate traveler data. Before calling upsert_travelers, you MUST ask the user for ALL required fields:
- first_name, last_name, date_of_birth (YYYY-MM-DD), gender (male/female)
- Contact: email, phone (with country code)
If ANY field is missing, ASK the user. Do not use placeholder or default values.

ANCILLARY FLOW:
After adding an item and setting travelers, check trip response for available_ancillaries on trip items.
If ancillaries are available, offer them to the user before proceeding to book.
Use select_ancillaries with the offer_ids from available_ancillaries. Full replacement semantics — send all desired selections.

Flows:
- Flights: flight_calendar → flight_search → trip(add_item) → trip(upsert_travelers) → [trip(select_ancillaries)] → book
- Hotels: hotel_search → trip(add_item) → trip(upsert_travelers) → book
- Mixed: both in the same trip — one cart, one checkout

​
Parameters

NameTypeRequiredDescription
trip_idstringNoExisting trip ID. Omit to create a new trip.
add_itemobjectNoAdd a flight or hotel item to the trip.
add_item.trip_item_tokenstringYesToken from flight_search results (offer__* format) or offer_id from hotel_search results (htl_* format).
remove_itemobjectNoRemove 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).
remove_item.item_idstringYesID of the trip item to remove. Matches the value returned in the trip response items[].item_id field.
upsert_travelersobjectNoSet or update travelers and contact info on the trip. Optional per call (you can add_item while building the cart), but travelers and a contact must be present before booking.
upsert_travelers.travelersarray<object>YesList of travelers (replaces all). Required to complete a booking; the first traveler also supplies the booking contact name.
upsert_travelers.contactobjectYesBooking contact (email + phone, both required). Required before the trip can be booked.
select_ancillariesobjectNoSelect ancillaries (bags, seats, meals) for a quoted trip item. Uses full-replacement semantics — send all desired selections.
select_ancillaries.item_idstringYesID of the trip item to select ancillaries for. Get from trip response trip_items[].id
select_ancillaries.selectionsarray<object>YesAncillary selections. Full replacement — send all desired selections each time. Get offer_ids from trip_item.available_ancillaries[].offer_id

​
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",
          "passenger_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", "passenger_type": "ADULT", "frequent_flyer": { "airline": "LH", "number": "992100100" } },
        { "first_name": "John", "last_name": "Doe", "date_of_birth": "2015-05-20", "gender": "MALE", "passenger_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. 
{
  "name": "trip",
  "arguments": {
    "trip_id": "42",
    "upsert_travelers": {
      "travelers": [
        {
          "first_name": "Jane",
          "last_name": "Doe",
          "date_of_birth": "1990-01-15",
          "gender": "FEMALE",
          "passenger_type": "ADULT",
          "frequent_flyer": { "airline": "LH", "number": "992100100" }
        }
      ]
    }
  }
}
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 book when you’re ready to check out.