Skip to main content
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.
upsert_travelers.travelersarray<object>YesList of travelers
upsert_travelers.contactobjectYesContact information
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