Ancillaries

Help travelers choose the extras they need before payment and follow each booking outcome. Availability depends on the supplier and selected offer. An empty ancillary list means that no purchasable option was returned for that item.

Booking flow

Capabilities

Discover

Find the extras available for the selected travel items.

Select

Choose extras for each traveler or for the booking.

Payment

Review the total and pay with the latest checkout.

Manage

Check each flight ancillary and explain pending or failed outcomes.

Build the flow

Discover: add the travel items and travelers to a trip, then retrieve the available extras.
Select: check what is included and keep every extra the traveler wants in the selection.
Payment: review the total, create checkout, and collect payment.
Manage: retrieve the booking and check each flight ancillary separately.

Discover available extras

Show travelers what they can add to the selected offer. Ancillaries are optional products or requests attached to a travel item. Flights offer a catalog of extra checked bags and seats. Car rental rates can offer extras paid at checkout or at the rental desk. Hotels handle options through the selected rate and special requests.

Retrieve the available extras

Add the travel item and travelers to a trip, then let the item finish pricing. Use the same endpoint to retrieve every purchasable ancillary available for the items in the 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 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 returns the catalogs in items[].available_ancillaries; seats can still be loading. Check each seat offer’s seat_map_status and read again while it is pending.

Show the available options

Each offer carries a lowercase type, such as bag or seat. The set is open: new types can appear, so handle a type you do not recognize by showing its display_label. Car rental extras use provider-defined types. Hotel special requests are not purchasable ancillaries. They remain in special_requests on the hotel item and are not returned as ancillary offers. Example questions

“What extras can I add to this flight?”
“Can I add a second checked bag?”
“Which extras are available with this rental?”

Seats

Choose a seat for each traveler and flight segment, then follow its booking outcome. See Seats for the seat map, availability, selection, charges, and refunds.

Bags

Check the fare’s included baggage allowance before adding extra bags. See Bags for selection and booking outcomes.

Car rental extras

Show which extras the traveler can add and when they will pay for them. 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.

This illustrative extra is paid at the rental desk. Use the returned offer_id when selecting it.

{
  "offer_id": "anc_70b5ea55948e40e6",
  "type": "other",
  "display_label": "Infant Seat",
  "price_per_unit_money": {
    "value": 4712,
    "currency": "USD",
    "decimal_places": 2,
    "display": "USD 47.12"
  },
  "per_pax": false,
  "max_quantity": 3,
  "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. Example questions

“Add an infant seat to this rental.”
“Do I pay for the extra now or at the rental desk?”
“Is the security deposit part of the price?”

Hotel options and requests

Help travelers choose the right rate and send their requests before checkout. 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. For example, include add_item.special_requests when adding the hotel to a trip with POST /v1/trip. Use the returned hotel token:

{
  "trip_id": "12345",
  "add_item": {
    "trip_item_token": "<returned hotel trip_item_token>",
    "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. Example questions

“Does this rate include breakfast and taxes?”
“Ask for a quiet room on a high floor.”
“Has the hotel confirmed my request for a baby cot?”

Select extras and check out

Keep the traveler’s full selection together before collecting payment.

Keep every selected extra

Select available extras through the API, Builder MCP trip with select_ancillaries, or CLI. Pass each returned offer_id exactly as received, with the traveler and quantity where applicable. Selecting ancillaries replaces the previous selection for that item. Send every ancillary that should remain selected. The select_ancillaries response includes total_with_ancillaries, the item total after selected ancillaries are added. Read its value in minor units or show its display.

Checkout and payment

Review the extras, payment timing, and total with the traveler. After choosing or changing extras, create checkout again and use the latest checkout link or agent payment parameters. See Trips and checkout for the payment flow. Example questions

“Add one checked bag and keep the seats I chose.”
“What is the total with these extras?”
“Confirm what I pay now and what is due at the rental desk.”

Manage after booking

Check each flight ancillary before telling the traveler it is confirmed. After booking, Jinko can return each selected flight ancillary’s outcome in booked_ancillaries, including seats and bags. Read its status (confirmed, pending, or failed) and any failure_reason. A confirmed flight does not by itself confirm every extra. For seat confirmation, charges, and refunds, follow the Seats guide. Example questions

“Are my seats and bags confirmed?”
“Why is this extra still pending?”
“Was my paid seat refunded?”

Ancillary reference

Use these fields to display available extras, keep selections, and report booking outcomes.

The ancillary model

Object	What it represents
`available_ancillaries[]`	The add-ons available for a flight or rental car item.
Available ancillary	One add-on you can select: its `type`, label, unit price, and, for a seat, its seat map.
`SelectedAncillary`	An add-on selected for a traveler or for the booking.
`BookedAncillary`	The confirmed, pending, or failed outcome of a booked flight ancillary, such as a seat or bag.
`total_with_ancillaries`	The item total after selected ancillaries are added, on the `select_ancillaries` response.

The available ancillary

Field	Type	What it means
`offer_id`	string	The opaque identifier used to select the ancillary. Pass it back exactly as received.
`type`	string	The ancillary family, such as `bag` or `seat`.
`display_label`	string	The label cleaned for display. Show this one.
`description`	string	A longer description of the add-on, when returned.
`price_per_unit_money`	MoneyValue	The unit price in minor units. Absent on a seat offer, which prices each seat in `seat_map`, and on a free add-on.
`per_pax`	boolean	`true` when the price is charged per traveler rather than once per booking.
`max_quantity`	integer	The maximum number of units that can be selected, when returned.
`scope`	string	`PER_PAX_PER_SEGMENT` means the offer applies per traveler and flight segment; returned for seats.
`segment_ref_ids`	string[]	The segments the offer covers, when returned. For a seat, pass its one segment back in the selection.
`seat_map_status`	enum	Seat availability: `pending` while loading, `ready` when listed.
`seat_map`	object	Seat offers only: the numbered seats for that segment, each with `seat_number`, `available`, `characteristics`, and, for a paid seat, `price_money`.
`paid_at`	enum	Car extras only: whether the traveler pays `now` or `local` at the rental desk.

This illustrative item excerpt includes a bag and a seat from items[].available_ancillaries. Use the identifiers returned for your trip when selecting extras.

{
  "available_ancillaries": [
    {
      "offer_id": "anc_bag_23",
      "type": "bag",
      "display_label": "1 checked bag 23kg",
      "price_per_unit_money": { "value": 4500, "currency": "EUR", "decimal_places": 2, "display": "EUR 45.00" },
      "per_pax": true,
      "max_quantity": 3
    },
    {
      "offer_id": "anc_seat_seg1",
      "type": "seat",
      "display_label": "Seat selection",
      "per_pax": true,
      "scope": "PER_PAX_PER_SEGMENT",
      "segment_ref_ids": ["seg_1"],
      "seat_map_status": "ready",
      "seat_map": {
        "flight_number": "AF1234",
        "seats": [
          {
            "seat_number": "12A",
            "available": true,
            "price_money": { "value": 1500, "currency": "EUR", "decimal_places": 2, "display": "EUR 15.00" },
            "characteristics": ["WINDOW"]
          }
        ]
      }
    }
  ]
}

The `SelectedAncillary` object

Field	What it means
`offer_id`	The selected ancillary offer.
`traveler_ref`	The traveler it applies to; absent on a booking-level ancillary.
`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; absent before.
`not_charged`	`true` means this seat is not charged to the traveler.
`failure_reason`	Explains why the ancillary is pending or failed.

The `BookedAncillary` object

After booking, Jinko can return each selected flight ancillary’s outcome in booked_ancillaries as a BookedAncillary, including seats and bags.

Field	What it means
`type`	The booked ancillary type, such as `seat` or `bag`. Treat the list as open: new types can appear.
`seat_number`	The assigned seat, when applicable.
`traveler_ref`	The traveler the ancillary applies to, when returned.
`segment_ref_ids`	The segments covered by the ancillary, when returned.
`status`	`confirmed`, `pending`, or `failed`.
`not_charged`	`true` means this seat is not charged to the traveler.
`failure_reason`	Explains why the ancillary is pending or failed.
`price`	The ancillary price in the trip currency; read `value` in minor units with `currency` and `decimal_places`, or show `display`. Omitted for an included or free ancillary.
`refund`	Refund information when a paid seat is refunded.

Getting started

Guides

Marketing claim

Authentication

Connect

Developer Platform

Concepts

Booking flow

Capabilities

Discover

Select

Payment

Manage

Build the flow

Discover available extras

Retrieve the available extras

Show the available options

Seats

Bags

Car rental extras

Hotel options and requests

Select extras and check out

Keep every selected extra

Checkout and payment

Manage after booking

Ancillary reference

The ancillary model

The available ancillary

The `SelectedAncillary` object

The `BookedAncillary` object

​Booking flow

​Capabilities

Discover

Select

Payment

Manage

​Build the flow

​Discover available extras

​Retrieve the available extras

​Show the available options

​Seats

​Bags

​Car rental extras

​Hotel options and requests

​Select extras and check out

​Keep every selected extra

​Checkout and payment

​Manage after booking

​Ancillary reference

​The ancillary model

​The available ancillary

​The SelectedAncillary object

​The BookedAncillary object

​Related guides

Booking flow

Capabilities

Build the flow

Discover available extras

Retrieve the available extras

Show the available options

Seats

Bags

Car rental extras

Hotel options and requests

Select extras and check out

Keep every selected extra

Checkout and payment

Manage after booking

Ancillary reference

The ancillary model

The available ancillary

The `SelectedAncillary` object

The `BookedAncillary` object

Related guides