Ancillaries

Ancillaries are the purchasable add-ons on a flight: extra baggage, seat selection, meals, priority boarding, lounge access, and more. They surface on each flight item in a quoted cart, and you select them before checkout.

How to list ancillaries (REST)

Ancillaries only exist after the flight is priced (the provider, TravelFusion, only emits the catalog at pricing time). They are not on the raw flight_search result, and you should not call checkout() to read them (that mints a checkout URL). Use the dedicated endpoint instead: it runs the price quote transparently and returns the catalog without generating a checkout URL:

GET /v1/trip/{trip_id}/ancillaries

Lifecycle:

flight_search → live-priced offer
trip (add item) → flight in the cart
trip (set travelers), required; ancillaries are priced per passenger
GET /v1/trip/{trip_id}/ancillaries → runs the quote behind the scenes and returns items[].available_ancillaries[]
select_ancillaries → move chosen offers into selected_ancillaries[], updating total_with_ancillaries
checkout() → checkout

Response: `ready` vs `pricing`

The quote runs upstream and can take a few seconds, so the call is two-state:

200 { "status": "ready", "items": [...] }: the catalog is ready; read available_ancillaries off each item.
202 { "status": "pricing", "retry_after_seconds": 2 } + a Retry-After header: the quote is still pricing; poll the same URL until it returns 200.

A completed quote is reused while valid (expires_at), so repeat calls return instantly. The response never contains a checkout_url.

The SDK exposes this as client.getAncillaries(tripId). The MCP trip tool surfaces the same available_ancillaries[] on the quoted trip item inside the widget flow. On the Jinko-hosted checkout page, ancillary selection is not currently exposed: build your own UI against available_ancillaries + select_ancillaries.

// Set travelers first, then list ancillaries (quote runs transparently).
let res = await client.getAncillaries(tripId)
while (res.status === 'pricing') {
  await new Promise(r => setTimeout(r, (res.retry_after_seconds ?? 2) * 1000))
  res = await client.getAncillaries(tripId)        // poll the same call
}
const bags = res.items[0].available_ancillaries.filter(a => a.type === 'bag')
await client.selectAncillaries({
  trip_id: tripId,
  item_id: res.items[0].item_id,
  selections: [{ offer_id: bags[0].offer_id }],
})

Two response shapes. The REST endpoint above returns a simplified offer per item: { offer_id, type, label, display_label, description, price_per_unit, per_pax, max_quantity } (where type is the lower-cased category, e.g. bag, seat, meal, assistance, cabin_bag_upgrade, sports_equipment, other). label is the raw provider string; display_label is a cleaned, human-readable version (HTML entities decoded, provider & component-joiners normalized to , ). Prefer it for display, falling back to label. The richer Ancillary object documented below (category, scope, *_details, …) is what the MCP trip tool returns on the quoted trip item. Both carry the same offer_id you pass to select_ancillaries.

The cart item

{
  "trip_item_token": "...",
  // ... flight fields ...
  "available_ancillaries": [ /* Ancillary[], see below */ ],
  "selected_ancillaries":  [ /* SelectedAncillary[] */ ],
  "total_with_ancillaries": { "amount": 48500, "currency": "EUR", "decimal_places": 2 }
}

The `Ancillary` object

Field	Type	Notes
`offer_id`	string	Pass this to `select_ancillaries`
`category`	enum	See the 11 values below
`label`	string	Human-readable, e.g. `"1 bag · 23kg"`
`description`	string	Longer description
`price`	Money	`{ amount, currency, decimal_places }`; absent = free
`scope`	enum	Who/what it applies to (see below)
`max_quantity`	integer	Max units selectable
`mutually_exclusive`	string[]	`offer_id`s that conflict with this one
`segment_ref_ids`	string[]	Segments it applies to
`journey_ref_id`	string	Journey it applies to
`applicable_pax_types`	string[]	e.g. `["ADT"]`
`provider_metadata`	`map<string,string>`	Pass-through provider data
`baggage_details`	object	Present when `category = BAGGAGE` / `CABIN_BAG_UPGRADE`
`seat_details`	object	Present when `category = SEAT`
`meal_details`	object	Present when `category = MEAL`
`assistance_details`	object	Present when `category = SPECIAL_ASSISTANCE`

category (11 values): BAGGAGE, SEAT, MEAL, CABIN_BAG_UPGRADE, SPORTS_EQUIPMENT, PRIORITY_BOARDING, SPECIAL_ASSISTANCE, INSURANCE, LOUNGE, FREQUENT_FLYER, OTHER. scope (4 values): PER_PAX_PER_SEGMENT, PER_PAX_PER_JOURNEY, PER_PAX_PER_BOOKING, PER_BOOKING.

Baggage: `baggage_details`

{ "pieces": 1, "weight_kg": 23, "weight_lb": 50, "dimensions": "158cm" }

Seat: `seat_details`

{
  "flight_number": "AF1234",
  "seat_type": "STANDARD",
  "characteristics": ["WINDOW", "EXTRA_LEGROOM"],
  "available_seats": [
    {
      "seat_number": "12A",
      "seat_type": "STANDARD",
      "characteristics": ["WINDOW"],
      "csp_value": "...",
      "price": { "amount": 1500, "currency": "EUR", "decimal_places": 2 }
    }
  ]
}

For full seat-map rendering there is also a SeatMap shape (rows[] → seats[] with availability + features), but for ancillary purchase you use seat_details.available_seats.

Meal: `meal_details`

{
  "meal_code": "VGML", "meal_name": "Vegetarian",
  "available_meals": [
    { "meal_code": "VGML", "meal_name": "Vegetarian", "csp_value": "...",
      "price": { "amount": 1200, "currency": "EUR", "decimal_places": 2 } }
  ]
}

Example `available_ancillaries`

"available_ancillaries": [
  {
    "offer_id": "anc_bag_23",
    "category": "BAGGAGE",
    "label": "1 checked bag · 23kg",
    "price": { "amount": 4500, "currency": "EUR", "decimal_places": 2 },
    "scope": "PER_PAX_PER_SEGMENT",
    "max_quantity": 3,
    "segment_ref_ids": ["seg_1"],
    "applicable_pax_types": ["ADT"],
    "baggage_details": { "pieces": 1, "weight_kg": 23, "weight_lb": 50 }
  },
  {
    "offer_id": "anc_seat_12A",
    "category": "SEAT",
    "label": "Seat 12A (window)",
    "price": { "amount": 1500, "currency": "EUR", "decimal_places": 2 },
    "scope": "PER_PAX_PER_SEGMENT",
    "mutually_exclusive": ["anc_seat_12B"],
    "segment_ref_ids": ["seg_1"],
    "seat_details": {
      "flight_number": "AF1234",
      "available_seats": [
        { "seat_number": "12A", "seat_type": "STANDARD", "characteristics": ["WINDOW"],
          "price": { "amount": 1500, "currency": "EUR", "decimal_places": 2 } }
      ]
    }
  },
  {
    "offer_id": "anc_priority",
    "category": "PRIORITY_BOARDING",
    "label": "Priority boarding",
    "price": { "amount": 800, "currency": "EUR", "decimal_places": 2 },
    "scope": "PER_PAX_PER_BOOKING"
  }
]

Which ancillaries are returned depends entirely on the airline/provider: many fares return none, LCCs typically return baggage + seats. Always render defensively: any *_details block is optional and only present for its category.

Selecting ancillaries

REST / CLI: discrete operation:

POST /v1/select_ancillaries
{
  "trip_id": "trip_1048576",
  "item_id": "prod_abc123",
  "selections": [ { "offer_id": "anc_bag_23", "quantity": 1, "pax_ref_id": "pax_1" } ]
}

Pass the offer_id(s) you read from available_ancillaries. Returns the updated selected_ancillaries[] + total_with_ancillaries. (@gojinko/cli: jinko select-ancillaries.) MCP / plugin: ancillary selection is not a standalone tool; it’s an action of the umbrella trip tool. mcp-apps handles it inside the trip/book widget flow.

Getting started

Guides

Authentication

Connect

Concepts

How to list ancillaries (REST)

Response: `ready` vs `pricing`

The cart item

The `Ancillary` object

Baggage: `baggage_details`

Seat: `seat_details`

Meal: `meal_details`

Example `available_ancillaries`

Selecting ancillaries

​How to list ancillaries (REST)

​Response: ready vs pricing

​The cart item

​The Ancillary object

​Baggage: baggage_details

​Seat: seat_details

​Meal: meal_details

​Example available_ancillaries

​Selecting ancillaries

How to list ancillaries (REST)

Response: `ready` vs `pricing`

The cart item

The `Ancillary` object

Baggage: `baggage_details`

Seat: `seat_details`

Meal: `meal_details`

Example `available_ancillaries`

Selecting ancillaries