Checking Price & Vacancy

Once the user has selected a specific trip and proceeds to the checkout page on your platform, the next step is to call the /connections/vacancy endpoint. This is important to confirm the availability and price for the requested combination of passengers on the selected trip as the content from the /connections/find response is cached.

We recommend that this request to /connections/vacancy is placed right after the user selects a specific departure from the search results page and before the user lands on the checkout page to enter their customer details. If you implemented the Seat Selection step and the Ancillaries step, the /connections/vacancy request should be placed before these steps as well.

Reading Price & Vacancy Response

There are 3 possible outcomes in the response from /connections/vacancy:

1. Price remains the same + vacancy (vacant = true): In this case, the user should be moved to the next step of the flow without restrictions.
2. Price changes + vacancy (vacant = true): In this case, we recommend to alert the user that the price has changed and allow them to continue the flow.
3. No vacancy (vacant = false): In this case, inform the user that the departure selected is not available and move them to the search results page to select another departure.

Return Trips

For return trips, we recommend to include both the inbound and outbound segments into the same request. This can be done by adding the return_departure_time and return_arrival_time parameters as retrieved from the Searching for Trips step. For more details, check our guide on Journey Types.

When you book both outbound and inbound legs in the same trip, both legs have to be booked with the same fare class.

Required Fields for Creating Reservation

The response from the /connections/vacancy endpoint outlines which passenger fields are required or optional for the /reservations/create and /reservations/confirm request. You should store this data to dynamically show the required fields when creating a reservation. For more details check our Dynamic Passenger Fields guide.

Best Practices

1. Implement the /connections/vacancy endpoint: It might seem redundant to call the /connections/vacancy endpoint mentioned in this step, but note that the content from the /connections/find endpoint is cached. We built the logic of our caching in a way that the content is as fresh as possible, but some carriers change their price dynamically with high frequencies which can cause the prices in our cache to be outdated once in a while.
2. Map pax ages to pax types: In the /connections/find endpoint you can define the exact age of each passenger. However, for the /connections/vacancy endpoint you must match the ages to the pax types supported by the carrier, which can be found in the /connections/find and /marketing_carriers/{marketing_carrier_id} endpoints. Read our Passenger Types guide for more details about it.
3. Read the price from the response: It is important to read the price from the /connections/vacancy response and display the value to the user in the the following steps, to ensure the user is presented with the most updated price for the trip. After the reservation is created, the price should be taken from that response.
4. Include the fare class in the request: Even though the fare_class parameter is not mandatory in the /connections/vacancy request, it is recommended to always include it to ensure the price returned matches the fare selected by the user. In case the fare_class parameter is not included the response will show the price for FARE-1 by default.
5. Take note of dummy prices in demo environment: When you use EUR as your currency for the request the price returned from /connections/vacancy will always show the value of 2500. This price is in cents, so when decimals are added the final price equals to €25.00. For other currencies it will be the equivalent amount e.g. 2768 USD, 2106 GBP etc. This rule applies for all carriers and all fares in the demo environment.
6. Remove trips with no vacancy from the search results: In case the response from the /connections/vacancy request shows vacant = false , when you move the user back to the search results page we recommend that you remove the departure from the list to prevent them from choosing it again.

Enterprise Features

As part of this step you may also want to present the list of ancillaries available to booked by the user. When enabled, the list of ancillaries available are presented in the response from /connections/vacancy. For more details, check our guide on Ancillaries.

If any discount cards are applied as part of the flow, they can be added to /connections/vacancy request and will affect the price that appears in the response. The details of the cards applied also appear at the bottom of the response. For more details, check our guide on Discount Cards.

Next Step

After confirming price and vacancy, move the user to select a seat (in case you implement this step).

If seat selection is not implemented, right at the time of sending the user to the checkout page create a reservation with the specified trip and passenger details.

API Examples

Sample Request to /connections/vacancy

 
https://api.demo.distribusion.com/retailers/v4/connections/vacancy?currency=GBP&departure_station=ESBCNBSB&arrival_station=ESMADMAT&departure_time=2025-05-19T07%3A05&arrival_time=2025-05-19T09%3A42&passengers[][pax]=1&passengers[][type]=PNOS&fare_class=FARE-1&retailer_partner_number=222222

Sample Response from /connections/vacancy

 
{
    "data": {
        "id": "ITES-ESBCNBSB-ESMADMAT-2025-05-19T07:05-2025-05-19T09:42",
        "type": "vacancies",
        "attributes": {
            "vacant": true,
            "total_price": 2211,
            "original_price": 2211
        },
        "relationships": {
            "applied_cards": {
                "data": []
            },
            "fees": {
                "data": []
            },
            "ancillary_options": {
                "data": []
            },
            "connection_passengers": {
                "data": [
                    {
                        "id": "PNOS-1-1746802563",
                        "type": "passengers"
                    }
                ]
            },
            "required_attributes": {
                "data": [
                    {
                        "id": "d71399d1-c46b-4601-8c1d-232bdd958119",
                        "type": "required_attributes"
                    },
                    {
                        "id": "4087d6fc-5576-4783-8cb2-4efe9f88bf95",
                        "type": "required_attributes"
                    }
                ]
            }
        }
    },
    "jsonapi": {
        "version": "1.0"
    },
    "meta": {
        "currency": "GBP"
    },
    "included": [
        {
            "id": "PNOS-1-1746802563",
            "type": "passengers",
            "relationships": {
                "required_attributes": {
                    "data": [
                        {
                            "id": "bd02ac60-f72d-4b8d-a49c-72d522aa2685",
                            "type": "passenger_required_attributes"
                        },
                        {
                            "id": "e82e46ea-ad04-4acf-94ab-b7c79eff7bce",
                            "type": "passenger_required_attributes"
                        }
                    ]
                }
            }
        },
        {
            "id": "bd02ac60-f72d-4b8d-a49c-72d522aa2685",
            "type": "passenger_required_attributes",
            "attributes": {
                "mandatory": [],
                "endpoint": "reservations/create"
            }
        },
        {
            "id": "e82e46ea-ad04-4acf-94ab-b7c79eff7bce",
            "type": "passenger_required_attributes",
            "attributes": {
                "mandatory": [
                    "birthdate",
                    "government_id",
                    "government_id_type",
                    "first_name",
                    "last_name"
                ],
                "endpoint": "reservations/confirm"
            }
        },
        {
            "id": "d71399d1-c46b-4601-8c1d-232bdd958119",
            "type": "required_attributes",
            "attributes": {
                "mandatory": [],
                "endpoint": "reservations/create"
            }
        },
        {
            "id": "4087d6fc-5576-4783-8cb2-4efe9f88bf95",
            "type": "required_attributes",
            "attributes": {
                "mandatory": [
                    "city",
                    "email",
                    "first_name",
                    "last_name",
                    "street_and_number",
                    "title",
                    "zip_code",
                    "terms_accepted"
                ],
                "endpoint": "reservations/confirm"
            }
        }
    ]
}

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