API explorerChangelog
API

Sections

API explorer
Changelog

Theme switcher

Ancillaries

Many carriers offer bookable extras to ensure that passengers have all the comfort they need while travelling. Displaying and booking these features is supported by the Distribusion API and fully integrated into the search and book workflow.

Please note that this is an enterprise API feature. Reach out to your Partnership Manager for more information about unlocking this and other advanced features.

Supported Ancillaries

The following ancillaries are the most common ones that can booked through the API, but note that the actual list is subject to carrier availability/support:

  • Extra luggage
  • Bicycles
  • Pets
  • Seat preference / reservation
  • Meals
  • Carbon offsets
  • Insurance
  • and many more!

Types of Ancillaries

Distribusion supports two types of ancillary offers: at passenger level or at booking level. For each case, they can be added for all segments or for specific segments.

Booking Level

These ancillaries apply to the entire booking and are not linked to any specific passenger or segment. They affect all passengers within the reservation.

Example: Travel Insurance covering all passengers in the booking.

Fields in Response from /connections/vacancy

JSON
"segment_relation": "all",
"pax_relation": null,

Fields in Request to /reservations/create

JSON
"ancillaries": [
  {
    "code": "LUGGAGE",
    "price": 1000
  }
]

Booking Segment Level

These ancillaries apply to a specific segment within a booking but are not tied to an individual passenger. They are relevant when services vary between legs.

Example: Seat selection for outbound trip only.

Fields in Response from /connections/vacancy

JSON
"segment_relation": "single",
"pax_relation": null,

Fields in Request to /reservations/create

JSON
"ancillaries": [
  {
    "code": "SEAT",
    "price": 1000,
    "segment_index": "0"
  }
]

Passenger Level

These ancillaries apply to a specific passenger in the booking, regardless of the segments. They ensure personalized services for each passenger.

Example: Extra baggage allowance which is applicable per traveler in the booking.

Fields in Response from /connections/vacancy

JSON
"segment_relation": "all",
"pax_relation": 1,

Fields in Request to /reservations/create

JSON
"passengers": [
  {
    "first_name": "Jane",
    "last_name": "Doe",
    "type": "PNOS",
    "ancillaries": [
      {
        "code": "BAG",
        "price": 1000
      }
    ]
  }
]

Passenger Segment Level

These ancillaries apply to an individual passenger for a specific segment within the journey. They allow different selections for different legs of the trip.

Example: Seat selection per segment or window seat on one segment and aisle on another.

Fields in Response from /connections/vacancy

JSON
"segment_relation": "single",
"pax_relation": 1,

Fields in Request to /reservations/create

JSON
"passengers": [
  {
    "first_name": "Jane",
    "last_name": "Doe",
    "type": "PNOS",

    "ancillaries": [
      {
        "code": "SEAT",
        "price": 1000,
        "segment_index": 1
      }
    ]
  }
]

Summary of Rules

In the table below you can find all 4 cases and how to identify each in the /connections/vacancy response. Based on the value of the fields of both segment_relation and pax_relation you define the structure of the /reservations/create request.

Parameter
Rule
Application of Ancillary Array in /reservations/create Request

"segment_relation": "single"

Ancillary applies to specific segment

Should include segment_index parameter in ancillary array with value matching the segment number.

"segment_relation": "all"

Ancillary applies to all segments

The segment_index parameter is not needed in ancillary array. Exception is for booking return trips (with carriers such as DB) where the segment_index should be included to identify if the ancillary applies to the outbound and/or inbound leg.

"pax_relation": null

Ancillary applies at booking level

Should be placed at the root of the request object. This is suitable for services that apply to the entire reservation.

"pax_relation": 1

Ancillary applies at passenger level

Should be nested inside a specific object within the passengers array. This links the service directly to a passenger.

Matching Ancillaries to Segments

Trips from Distribusion can be presented as return trips, each with multiple segments. As explained above, some ancillaries could be available in specific segments of the trip such as seat reservation.

For ancillaries that have "segment_relation": "single" in the /connections/vacancy response, the request to /reservations/create should include the "segment_index" parameter with the segment value. This can be identified from the /connections/vacancy response.

For this ancillary below the segment is identified by the number in the end of the id, so ATES-USCHICHI-USMIAMIA-2025-08-16T17:55-2025-08-23T10:12-0 means the "segment_index" should be 0.

Plain text

API Workflow

  1. Perform the /connections/find request as usual.
  2. Include the parameter include=ancillary_options to your /connections/vacancy request.
  3. Get the list of ancillaries in the response and allow users to choose it.
  4. Include the selected ancillaries to the /reservations/create request.
  5. Ancillaries are added to the reservation.
  6. Continue with the Basic Integration flow.

API Examples

Sample Request to /connections/vacancy

HTTP
https://api.demo.distribusion.com/retailers/v4/connections/vacancy?currency=EUR&marketing_carrier=AMTR&departure_station=USCHICHI&arrival_station=USNYCNWO&departure_time=2024-09-08T21:30&arrival_time=2024-09-09T18:42&passengers[][pax]=1&passengers[][type]=PNOS&fare_class=FARE-15&retailer_partner_number={{rpn}}&include=ancillary_options

Sample Response from /connections/vacancy

JSON
{
    "data": {
        "id": "AMTR-USCHICHI-USNYCNWO-2024-09-08T21:30-2024-09-09T18:42",
        "type": "vacancies",
        "attributes": {
            "vacant": true,
            "total_price": 11105,
            "original_price": 11105
        },
        "relationships": {
            "applied_cards": {
                "data": []
            },
            "fees": {
                "data": []
            },
            "ancillary_options": {
                "data": [
                    {
                        "id": "AMTR-SMS-FALSE-0-EUR",
                        "type": "ancillary_options"
                    },
                    {
                        "id": "AMTR-EMAIL-FALSE-0-EUR",
                        "type": "ancillary_options"
                    },
                    {
                        "id": "AMTR-BIKE-FALSE-1806-EUR-AMTR-USCHICHI-USNYCNWO-2024-09-08T21:30-2024-09-09T18:42-0",
                        "type": "ancillary_options"
                    },
                    {
                        "id": "AMTR-CCS-FALSE-0-EUR-AMTR-USCHICHI-USNYCNWO-2024-09-08T21:30-2024-09-09T18:42-0",
                        "type": "ancillary_options"
                    }
                ]
            }
        }
    },
    "jsonapi": {
        "version": "1.0"
    },
    "meta": {
        "currency": "EUR",
        "terms_and_conditions": {
            "link": "https://www.amtrak.com/services/contentService.ibcontentpopup.terms-and-conditions.html"
        }
    },
    "included": [
        {
            "id": "AMTR-SMS-FALSE-0-EUR",
            "type": "ancillary_options",
            "attributes": {
                "code": "SMS",
                "name": "SMS Alert",
                "description": "Pre-departure notification via text message",
                "mandatory_for_admission": false,
                "segment_relation": "all",
                "pax_relation": 1,
                "flexible_price": false,
                "refundable": true,
                "refundability_offset": 3600,
                "price": 0
            },
            "relationships": {
                "custom_attributes": {
                    "data": [
                        {
                            "id": "2",
                            "type": "custom_attributes"
                        },
                        {
                            "id": "5",
                            "type": "custom_attributes"
                        }
                    ]
                }
            }
        },
        {
            "id": "AMTR-EMAIL-FALSE-0-EUR",
            "type": "ancillary_options",
            "attributes": {
                "code": "EMAIL",
                "name": "Pre-departure notification",
                "description": "Pre-departure notification via email 30 minutes before",
                "mandatory_for_admission": false,
                "segment_relation": "all",
                "pax_relation": 1,
                "flexible_price": false,
                "refundable": true,
                "refundability_offset": 3600,
                "price": 0
            },
            "relationships": {
                "custom_attributes": {
                    "data": [
                        {
                            "id": "2",
                            "type": "custom_attributes"
                        }
                    ]
                }
            }
        },
        {
            "id": "AMTR-BIKE-FALSE-1806-EUR-AMTR-USCHICHI-USNYCNWO-2024-09-08T21:30-2024-09-09T18:42-0",
            "type": "ancillary_options",
            "attributes": {
                "code": "BIKE",
                "name": "Bicycle",
                "description": "Bringing Your Bicycle\nCarry-On/Trainside: Bicycles up to 50 lbs. Standard bicycle sizes apply. Maximum tire width: 2\"\nChecked: Bicycles up to 50 lbs. and 70\" x 41\" x 8.5\"\n\nCarry-On Bicycle Service\nStandard full-size bicycles may be carried onboard and stored in within the body of the car. On short-distance routes in the Northeast, passengers must remove the front wheel before storing their bike. Fee varies by route.\n Website: https://www.amtrak.com/onboard/bring-your-bicycle-onboard",
                "mandatory_for_admission": false,
                "segment_relation": "multiple",
                "pax_relation": 1,
                "flexible_price": false,
                "refundable": true,
                "refundability_offset": 3600,
                "price": 1806
            },
            "relationships": {
                "custom_attributes": {
                    "data": [
                        {
                            "id": "7",
                            "type": "custom_attributes"
                        }
                    ]
                }
            }
        },
        {
            "id": "AMTR-CCS-FALSE-0-EUR-AMTR-USCHICHI-USNYCNWO-2024-09-08T21:30-2024-09-09T18:42-0",
            "type": "ancillary_options",
            "attributes": {
                "code": "CCS",
                "name": "Coach seat",
                "description": "Comfortable accommodation in the train",
                "mandatory_for_admission": false,
                "segment_relation": "all",
                "pax_relation": 1,
                "flexible_price": false,
                "refundable": true,
                "refundability_offset": 3600,
                "price": 0
            },
            "relationships": {
                "custom_attributes": {
                    "data": [
                        {
                            "id": "5",
                            "type": "custom_attributes"
                        }
                    ]
                }
            }
        },
        {
            "id": "2",
            "type": "custom_attributes",
            "attributes": {
                "key": "notification_time",
                "value": "30"
            }
        },
        {
            "id": "5",
            "type": "custom_attributes",
            "attributes": {
                "key": "max_weight_in_kgs",
                "value": "10"
            }
        },
        {
            "id": "7",
            "type": "custom_attributes",
            "attributes": {
                "key": "max_weight_in_kgs",
                "value": "10"
            }
        }
    ]
}

For more samples responses, check the /connections/vacancy endpoint page.

Sample Request to /reservations/create

JSON
{
  "marketing_carrier": "AMTR",
  "departure_station": "USCHICHI",
  "arrival_station": "USNYCNWO",
  "departure_time": "2024-09-08T21:30",
  "arrival_time": "2024-09-09T18:42",
  "retailer_partner_number": "222222",
  "fare_class": "FARE-15",
  "locale": "en",
  "currency": "EUR",
  "title": "mr",
  "first_name": "John",
  "last_name": "Smith",
  "email": "test@distribusion.com",
  "phone": "+4915222088994",
  "city": "Berlin",
  "zip_code": "13355",
  "street_and_number": "Wattstrasse 10",
  "passengers": [
    {
      "type": "PNOS",
      "first_name": "John",
      "last_name": "Smith",
      "birthdate": "1970-07-21",
      "nationality": "DE"
    }
  ],
  "ancillaries": [
    {
      "code": "BIKE",
      "price": 1806
    }
  ]
}

Sample Response from /reservations/create

JSON
{
    "data": {
        "id": "REQPP5HM",
        "type": "reservations",
        "attributes": {
            "total_price": 12911,
            "original_price": 12911,
            "state": "created",
            "created_at": "2024-09-06T10:08",
            "confirmed_at": null,
            "cancelled_at": null,
            "failed_at": null,
            "processing_started_at": null,
            "processing_deadline": null,
            "expires_at": "2024-09-06T10:23",
            "terms_version": null,
            "title": "mr",
            "first_name": "John",
            "last_name": "Smith",
            "email": "andre.franchini@distribusion.com",
            "phone": "+4915222088994",
            "city": "Berlin",
            "zip_code": "13355",
            "country_code": null,
            "street_and_number": "Wattstrasse 10",
            "gender": null,
            "country_of_birth": null,
            "government_id_type": null,
            "marketing_carrier_reservation_ids": [
                "7119C7"
            ],
            "agent_id": null,
            "retailer_booking_number": null
        },
        "relationships": {
            "booking": {
                "data": null
            },
            "errors": {
                "data": []
            },
            "reservation_passengers": {
                "data": [
                    {
                        "id": "R-PNOS-1-AMTR-USCHICHI-USNYCNWO-2024-09-08T21:30-2024-09-09T18:42",
                        "type": "reservation_passengers"
                    }
                ]
            },
            "applied_cards": {
                "data": []
            },
            "ancillaries": {
                "data": [
                    {
                        "id": "BIKE",
                        "type": "ancillaries"
                    }
                ]
            }
        }
    },
    "jsonapi": {
        "version": "1.0"
    },
    "meta": {
        "currency": "EUR",
        "locale": "en"
    },
    "included": [
        {
            "id": "BIKE",
            "type": "ancillaries",
            "attributes": {
                "code": "BIKE",
                "name": "name",
                "description": "description",
                "quantity": 1,
                "remote_id": null,
                "price": 1806
            },
            "relationships": {
                "custom_attributes": {
                    "data": []
                }
            }
        },
        {
            "id": "R-PNOS-1-AMTR-USCHICHI-USNYCNWO-2024-09-08T21:30-2024-09-09T18:42",
            "type": "reservation_passengers",
            "attributes": {
                "first_name": "John",
                "last_name": "Smith",
                "serial_code": null,
                "government_id_type": null,
                "nationality": "DE",
                "gender": null,
                "country_of_birth": null,
                "birthdate": "1970-07-21",
                "type": "PNOS"
            },
            "relationships": {
                "ancillaries": {
                    "data": []
                }
            }
        }
    ]
}

For more samples responses, check the /reservations/create endpoint page.

Was this section helpful?

What made this section unhelpful for you?

On this page
  • Ancillaries
View as Markdown

Ask an AI

Open in ChatGPTOpen in ClaudeOpen in Perplexity

Code with AI

Open in Copilot