Ancillaries

Ancillaries are optional add-ons that let passengers tailor a trip to their needs like extra luggage, bikes, pets, meals, insurance, or carbon offset products. They’re presented during the booking flow (where available), so customers can choose what they want before confirming their reservation. This page provides an overview of how ancillaries are represented within the offers framework in the Retailer API.

Ancillaries are represented as addon offers: offer objects with booking_type: "addon" that appear alongside the standalone fare offer in the connections/vacancy response.

General flow & principle

When a retailer calls connections/vacancy with a selected fare offer_id, the response includes not only fare availability and pricing but also any ancillaries available for purchase alongside that connection — returned as addon offers within the offer_options relationship.

An addon offer cannot be purchased alone. It must always accompany a standalone fare offer. The selected addon offers are passed alongside the fare offer_id when calling reservations/create.

Coverage

Coverage defines the scope of an offer — the passengers and segments it is linked to and how it must be applied. Every offer, whether a fare or an addon, references a set of passengers and segments (via passenger_ids and segment_ids) and carries two coverage fields that govern how to apply the offer across them:

• passenger_coverage_type: individual the offer is applied separately to each linked passenger, and the price shown is per application. For example, if luggage costs €5 and both Jan and Alfred want it, the total is €10. collective means the offer can be applied once and then applies to all passengers linked to that offer. The price does not need to be duplicated per passenger.
• segment_coverage_type: individual means the offer can be applied for each linked segment, each application targets one of the segments referenced on the offer. collective means the offer is applied once across all segments linked to that offer.

The same coverage model used for fare offers applies to addon offers. This is how an ancillary expresses whether it is applied once per linked passenger or once across them collectively, and whether it is applied once per linked segment or once across them collectively.

Coverage combinations

Features

Addon offer concept

An addon offer represents a purchasable ancillary. It shares the same offer structure as a standalone fare offer but has booking_type: "addon" and one additional distinction: max_quantity.

max_quantity defines the maximum number of units this specific offer can be purchased per application. Combined with passenger_coverage_type, it determines whether the limit applies per passenger or in total.

For example: a luggage offer with passenger_coverage_type: "individual" and max_quantity: 3 means each linked passenger can buy up to 3 bags independently. A carbon offset offer with passenger_coverage_type: "collective" and max_quantity: 1 means the product can be purchased once, covering all linked passengers.

An addon offer's price can be 0 when the ancillary is included in the fare price but requires explicit selection (e.g. a mandatory meal choice included in a premium fare).

Offer options and selection constraints

Available addon offers are returned under the offer_options relationship on the connections/vacancy response. Each offer_options entity wraps a set of related offers and carries two bounds on how many selections the retailer can make from the group:

• min_selection — the minimum number of selections required from this group. 0 means the ancillary is optional. 1 means it is mandatory and must be selected for the booking to validate.
• max_selection — the maximum number of selections allowed from this group. For a single-offer group this mirrors the offer's max_quantity.

Common patterns:

max_quantity vs offer_options bounds:

These two mechanisms control different things and must not be conflated:

• max_quantity on an offer controls how many units that single offer can be purchased per application (e.g. up to 3 bags per linked passenger).
• min_selection / max_selection on the group control how many offers can be selected from a group of different options (e.g. pick exactly one meal from six variants).

Worked example:

A connection offering luggage as two separate offers: big bag and small bag. The carrier allows up to 3 bags per passenger in total, but no more than 2 big bags per passenger. The vacancy response would return:

• One offer_options group containing both luggage offer IDs (big bag and small bag), with min_selection: 0, max_selection: 3 — the customer can select up to 3 bags total per passenger, combining the two offer types as they wish.
• The big bag offer carries max_quantity: 2 — at most 2 big bags per passenger application.
• The small bag offer carries max_quantity: 3 — at most 3 small bags per passenger application (the per-offer cap).

So a passenger could buy 2 big + 1 small, or 0 big + 3 small, or 1 big + 2 small — but never 3 big bags, because max_quantity on the big bag offer caps it at 2 even though the group allows 3 total selections.

End-to-end example

The example below follows the flow connections/find → connections/vacancy → reservations/create for a one-way trip with 2 passengers across 2 segments. Two ancillaries are available:

• Carbon offset — a single product covering all passengers and all segments at once (collective / collective).
• Luggage — purchased per passenger, covering all segments (individual / collective), up to 3 bags per passenger.

Step 1: connections/find

A standard connections/find request is made. The response returns standalone fare offers for each connection with booking_type: "standalone". No offer_options are present at this stage.

The selected fare's offer_id is then passed to connections/vacancy in the next step.

Step 2: connections/vacancy

Request the vacancy endpoint with the selected fare offer to retrieve any available addon offers.

The response returns two offer option groups under the offer_options relationship — one for the carbon offset, one for the luggage. Both are optional (min_selection: 0).

{
  "relationships": {
    "offer_options": {
      "data": [
        { "type": "offer_options", "id": "co2-group" },
        { "type": "offer_options", "id": "luggage-group" }
      ]
    }
  },
  "included": [
    {
      "type": "offer_options",
      "id": "co2-group",
      "attributes": { "min_selection": 0, "max_selection": 1 },
      "relationships": {
        "offers": { "data": [{ "type": "offers", "id": "co2-offer-id" }] }
      }
    },
    {
      "type": "offer_options",
      "id": "luggage-group",
      "attributes": { "min_selection": 0, "max_selection": 3 },
      "relationships": {
        "offers": { "data": [{ "type": "offers", "id": "luggage-offer-id" }] }
      }
    },
    {
      "type": "offers",
      "id": "co2-offer-id",
      "attributes": {
        "booking_type": "addon",
        "passenger_coverage_type": "collective",
        "segment_coverage_type": "collective",
        "max_quantity": 1,
        "price": 200,
        "currency": "EUR",
        "passenger_ids": ["pax-1", "pax-2"],
        "segment_ids": ["segment-0", "segment-1"],
        "applied_passenger_types": [
          { "id": "CARRIER-PNOS", "passenger_id": "pax-1" },
          { "id": "CARRIER-PNOS", "passenger_id": "pax-2" }
        ]
      }
    },
    {
      "type": "offers",
      "id": "luggage-offer-id",
      "attributes": {
        "booking_type": "addon",
        "passenger_coverage_type": "individual",
        "segment_coverage_type": "collective",
        "max_quantity": 3,
        "price": 800,
        "currency": "EUR",
        "passenger_ids": ["pax-1", "pax-2"],
        "segment_ids": ["segment-0", "segment-1"],
        "applied_passenger_types": [
          { "id": "CARRIER-PNOS", "passenger_id": "pax-1" },
          { "id": "CARRIER-PNOS", "passenger_id": "pax-2" }
        ]
      }
    }
  ]
}

Reading the key values:

• Carbon offset offer: both axes collective — one application covers all linked passengers across all linked segments. max_quantity: 1 means it can be purchased once.
• Luggage offer: passenger_coverage_type: individual — applied once per chosen passenger. max_quantity: 3 on the offer and max_selection: 3 on the group allow up to 3 bags per passenger.

Step 3: reservations/create

To purchase ancillaries, include the chosen addon offer IDs in the offers array alongside the main fare offer. For individual-coverage offers, specify which passengers the ancillary applies to and the quantity per passenger.

In this example: the passengers buy the carbon offset (one collective application), pax-1 buys 2 bags, and pax-2 buys 1 bag.

{
  "locale": "en",
  "retailer_partner_number": "123456",
  "email": "john.smith@email.com",
  "currency": "EUR",
  "passengers": [
    { "id": "pax-1", "type": "PNOS", "first_name": "Test", "last_name": "User" },
    { "id": "pax-2", "type": "PNOS", "first_name": "Test", "last_name": "User" }
  ],
  "offers": [
    { "id": "fare-offer-id" },
    {
      "id": "co2-offer-id"
    },
    {
      "id": "luggage-offer-id",
      "passenger_ids": ["pax-1"],
      "quantity": 2
    },
    {
      "id": "luggage-offer-id",
      "passenger_ids": ["pax-2"]
    }
  ]
}

Reading the shape:

• The carbon offset offer has passenger_coverage_type: collective — one entry total, no passenger_ids needed in the request. It is applied once across all linked passengers.
• The luggage offer has passenger_coverage_type: individual — one entry per chosen passenger, each with its own quantity (bounded by max_quantity: 3).