Flight Exchange

Tool description (what the LLM sees)

Exchange a booked flight for a different itinerary. No login required, authenticate with the Jinko booking reference and traveler last name.

WORKFLOW:
1. action="shop" with booking_ref + last_name + optional preferred_departure_date → browse exchange options
2. action="price" with booking_ref + last_name + offer_id → get exact pricing (fare difference, penalties)
3. If user confirms, action="commit" with booking_ref + last_name + offer_id + session_reference → execute the exchange
4. action="status" with booking_ref + last_name → poll exchange progress

IMPORTANT:
- Always shop before pricing, price before committing.
- Get explicit user confirmation before committing, exchanges may involve fare differences (additional payment or refund).
- The session_reference from pricing must be passed to commit.

Parameters

Name	Type	Required	Description
`action`	`enum ("shop" \| "price" \| "commit" \| "status")`	Yes	Action to perform: “shop” to browse exchange alternatives, “price” to get exact pricing for an offer, “commit” to execute the exchange, “status” to poll exchange progress
`booking_ref`	`string`	Yes	Jinko booking reference (e.g. JNK-A7B3X9). Found in the booking confirmation email.
`last_name`	`string`	Yes	Last name of the primary traveler on the booking.
`order_id`	`string`	No	Provider order ID. Optional, provided only by authenticated DevPlatform callers who already resolved it.
`provider`	`string`	No	Provider code (e.g., “travelfusion”, “sabre”). Usually auto-detected from the booking.
`ticket_numbers`	`array<string>`	No	Specific ticket numbers to exchange (for partial exchanges). Omit for full booking.
`offer_id`	`string`	No	Exchange offer ID returned from a previous shop action (canonical name). Required for price and commit actions. Preferred over exchange_offer_id.
`session_reference`	`string`	No	Session reference returned from a previous price action. Required for commit action.
`preferred_departure_date`	`string`	No	Preferred departure date for the new flight (YYYY-MM-DD format). Used with shop action.
`user_intent`	`string`	No	The end user’s current request in their own words, e.g. “find a cheap flight to Tokyo in mid-June”. 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 and never changes the result of the call; Jinko uses it to understand demand and improve results.

Examples

Shop for exchange options (guest path):

{
  "name": "flight_exchange",
  "arguments": {
    "action": "shop",
    "booking_ref": "JNK-ABC123",
    "last_name": "Doe",
    "preferred_departure_date": "2026-07-15"
  }
}

Response lists alternative itineraries with offer_id per option. Price a specific offer:

{
  "name": "flight_exchange",
  "arguments": {
    "action": "price",
    "booking_ref": "JNK-ABC123",
    "last_name": "Doe",
    "offer_id": "exch_offer_abc"
  }
}

Returns price_delta (can be positive or negative), airline_penalty, service_fee, and a session_reference to commit against. Commit the exchange:

{
  "name": "flight_exchange",
  "arguments": {
    "action": "commit",
    "booking_ref": "JNK-ABC123",
    "last_name": "Doe",
    "offer_id": "exch_offer_abc",
    "session_reference": "sess_xyz789"
  }
}

Poll status:

{
  "name": "flight_exchange",
  "arguments": {
    "action": "status",
    "booking_ref": "JNK-ABC123",
    "last_name": "Doe",
    "exchange_reference": "EXC-abc123"
  }
}

The 4-step flow is serial, each step produces the token/reference the next needs. Always surface the priced delta (step 2) to the user for confirmation before calling commit (step 3).

Introduction

Flights

Hotels

Cart & Payment

Parameters

Examples

​Parameters

​Examples

Parameters

Examples