Ancillaries

Ancillaries are optional products or requests attached to a travel item. Flights can offer baggage, seats, meals, and other services. Car rental rates can offer extras paid at checkout or at the rental desk. Hotels handle options differently through the selected rate and special requests. Availability always depends on the supplier and selected offer. An empty ancillary list means that no purchasable option was returned for that item.

Ancillaries by travel product

Product	What Jinko supports
Flights	A structured catalog of purchasable ancillaries, including baggage, seats, meals, and assistance.
Car rentals	Rate extras with a quantity, price, and payment timing.
Hotels	Meal plans, taxes, and fees inside the selected rate, plus free-text special requests. Hotels do not currently expose a separate catalog of purchasable ancillaries.

One endpoint for every ancillary

Use the same endpoint to retrieve every purchasable ancillary available for the items in a trip:

GET /v1/trip/{trip_id}/ancillaries

The response groups the available ancillaries by trip item. A trip that contains a flight and a rental car can therefore return both flight ancillaries and car extras in the same response. The endpoint can take a few seconds to price the items. A 202 response means pricing is still running; call the same endpoint again after retry_after_seconds. A 200 response means the catalogs are ready in items[].available_ancillaries. Hotel special requests are not purchasable ancillaries. They remain in special_requests on the hotel item and are not returned as ancillary offers.

The ancillary model

Object	What it represents
`available_ancillaries[]`	The add-ons available for a flight item.
`Ancillary`	One available add-on, including its category, price, scope, and provider details.
`SelectedAncillary`	An add-on selected for a traveler, segment, journey, or booking.
`BookedAncillary`	The confirmed, pending, or failed outcome of a booked flight seat.
`total_with_ancillaries`	The item total after selected ancillaries are added.

Purchasable ancillaries are returned after the travel item and travelers have been added to a trip and the item has been priced.

Flight ancillary types

Jinko supports eleven flight ancillary categories:

Category	What it covers	Additional object
`BAGGAGE`	Checked baggage and additional pieces.	`baggage_details`
`SEAT`	Seat selection, including free and paid seats.	`seat_details` or `seat_map`
`MEAL`	Standard and special meals.	`meal_details`
`CABIN_BAG_UPGRADE`	Larger or additional cabin baggage.	`baggage_details`
`SPORTS_EQUIPMENT`	Equipment such as skis, golf bags, or bicycles.	Provider details when available
`PRIORITY_BOARDING`	Priority boarding or fast-track options.	Provider details when available
`SPECIAL_ASSISTANCE`	Mobility and other assistance requests.	`assistance_details`
`INSURANCE`	Insurance offered with the flight.	Provider details when available
`LOUNGE`	Airport lounge access.	Provider details when available
`FREQUENT_FLYER`	Loyalty-related services or benefits.	Provider details when available
`OTHER`	An add-on that does not match another category.	Provider details when available

The `Ancillary` object

Field	Type	What it means
`offer_id`	string	The opaque identifier used to select the ancillary.
`category`	enum	One of the eleven supported categories.
`label`	string	The provider label.
`display_label`	string	A cleaned label ready to show to the traveler, when returned.
`description`	string	A longer description of the add-on.
`price`	Money	The price. It can be absent for a free ancillary.
`scope`	enum	Who or what the ancillary applies to.
`paid_at`	enum	For car extras, whether the traveler pays `now` or `local` at the rental desk.
`max_quantity`	integer	The maximum number of units that can be selected.
`mutually_exclusive`	string[]	Other `offer_id` values that cannot be selected with this one.
`segment_ref_ids`	string[]	The flight segments covered by the ancillary.
`journey_ref_id`	string	The journey covered by the ancillary.
`applicable_pax_types`	string[]	The passenger types that can use the ancillary.
`baggage_details`	object	Baggage-specific information.
`seat_details`	object	Seat-specific information.
`meal_details`	object	Meal-specific information.
`assistance_details`	object	Assistance-specific information.

Type-specific objects

These objects are optional. They appear only when the category and provider support them.

Object	Fields it can contain
`baggage_details`	Number of pieces, weight in kilograms or pounds, and dimensions.
`seat_details`	Flight number, seat type, characteristics, and available seats.
`seat_map`	Segment, flight number, and numbered seats with availability, characteristics, and price.
`meal_details`	Meal code, meal name, available meals, and price.
`assistance_details`	The assistance information returned by the provider.

Treat every type-specific object as optional. Do not assume that a category always includes every field.

Baggage details

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

Seat details

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

Meal details

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

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",
      "segment_ref_ids": ["seg_1"],
      "seat_details": {
        "flight_number": "AF1234",
        "available_seats": [
          {
            "seat_number": "12A",
            "seat_type": "STANDARD",
            "characteristics": ["WINDOW"]
          }
        ]
      }
    },
    {
      "offer_id": "anc_priority",
      "category": "PRIORITY_BOARDING",
      "label": "Priority boarding",
      "price": {
        "amount": 800,
        "currency": "EUR",
        "decimal_places": 2
      },
      "scope": "PER_PAX_PER_BOOKING"
    }
  ]
}

Scope

Scope determines how an ancillary applies and how often it can be charged.

Scope	Meaning
`PER_PAX_PER_SEGMENT`	One traveler on one flight segment.
`PER_PAX_PER_JOURNEY`	One traveler across a journey.
`PER_PAX_PER_BOOKING`	One traveler across the booking.
`PER_BOOKING`	The booking as a whole.

The `SelectedAncillary` object

Field	What it means
`offer_id`	The selected ancillary offer.
`pax_ref_id`	The traveler it applies to, when the scope is per traveler.
`quantity`	The selected quantity.
`type`	The ancillary family, such as `seat` or `bag`.
`seat_number`	The selected seat, when applicable.
`segment_ref_ids`	The segments covered by the selection.
`price_money`	The exact unit price, when returned.
`status`	`PENDING`, `CONFIRMED`, or `FAILED` after booking.
`failure_reason`	The reason for a failed or unresolved outcome, when available.

Selecting ancillaries replaces the previous selection for that item. Send every ancillary that should remain selected.

The `BookedAncillary` object

After booking, Jinko can return the outcome of a selected seat as a BookedAncillary.

Field	What it means
`type`	The booked ancillary type. Booked outcomes currently expose seats.
`seat_number`	The assigned seat.
`pax_ref_id`	The traveler assigned to the seat.
`segment_ref_ids`	The segments covered by the seat.
`status`	`CONFIRMED`, `PENDING`, or `FAILED`.
`failure_reason`	A public explanation when the outcome is unresolved or failed.
`price`	The seat price when it was not included for free.
`refund`	Refund information when a paid seat is refunded.

Car rental extras

Car rental extras use the same available and selected ancillary lists, but their types are provider-defined rather than limited to the eleven flight categories. Each extra can include a label, quantity, unit price, and payment timing.

`paid_at`	Meaning
`now`	Jinko collects the extra at checkout and includes it in the item price.
`local`	The rental company collects the extra at the desk. It is not included in the Jinko charge.

{
  "offer_id": "anc_car_infant_seat",
  "label": "Infant seat",
  "display_label": "Infant seat",
  "price_per_unit_money": {
    "value": 3000,
    "currency": "EUR",
    "decimal_places": 2,
    "display": "EUR 30.00"
  },
  "per_pax": false,
  "max_quantity": 2,
  "paid_at": "local"
}

The rental offer also carries its included coverages, optional insurance lines, mandatory fees, amount due at the desk, and security deposit. These are part of the rate breakdown and should not be presented as selected extras unless the supplier returns them in available_ancillaries.

Hotel options and requests

Hotels do not currently return a separate catalog of purchasable ancillaries. The selected hotel rate already defines the room, meal plan, taxes, fees, and cancellation terms. Free-text special requests can be added to the hotel item before checkout. Common examples include a late arrival, quiet room, high floor, baby cot, or non-smoking room.

{
  "special_requests": [
    "Expected arrival around 11:30 PM",
    "Quiet room on a high floor, if available",
    "Baby cot requested"
  ]
}

Special requests are sent to the property, but they are not guaranteed. A confirmed booking does not mean the hotel accepted them.

Getting started

Guides

Marketing claim

Authentication

Connect

Developer Platform

Concepts

Ancillaries by travel product

One endpoint for every ancillary

The ancillary model

Flight ancillary types

The `Ancillary` object

Type-specific objects

Baggage details

Seat details

Meal details

Available ancillaries

Scope

The `SelectedAncillary` object

The `BookedAncillary` object

Car rental extras

Hotel options and requests

​Ancillaries by travel product

​One endpoint for every ancillary

​The ancillary model

​Flight ancillary types

​The Ancillary object

​Type-specific objects

​Baggage details

​Seat details

​Meal details

​Available ancillaries

​Scope

​The SelectedAncillary object

​The BookedAncillary object

​Car rental extras

​Hotel options and requests

Ancillaries by travel product

One endpoint for every ancillary

The ancillary model

Flight ancillary types

The `Ancillary` object

Type-specific objects

Baggage details

Seat details

Meal details

Available ancillaries

Scope

The `SelectedAncillary` object

The `BookedAncillary` object

Car rental extras

Hotel options and requests