> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dev.gojinko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Flight Exchange

> Exchange a booked flight for a different itinerary

<Accordion title="Tool description (what the LLM sees)" defaultOpen={false}>
  ```text theme={null}
  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.
  ```
</Accordion>

## 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.                        |
| `exchange_offer_id`        | `string`                                           | No       | Deprecated alias for offer\_id. Use offer\_id instead.                                                                                                                     |
| `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.                                                                                    |

## Examples

**Shop for exchange options (guest path):**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

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

**Poll status:**

```json theme={null}
{
  "name": "flight_exchange",
  "arguments": {
    "action": "status",
    "booking_ref": "JNK-ABC123",
    "last_name": "Doe",
    "exchange_reference": "EXC-abc123"
  }
}
```

<Note>
  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).
</Note>