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 step is important to:
- Ensure that the price returned at the time of search is still accurate before sending the user to the checkout page.
- Retrieve ancillary options for the selected trip and fare (more information can be found in the Ancillaries guide).
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.
Important Update for Existing Partners: The /connections/vacancy endpoint has been streamlined as part of our new Offers API flow. It is now a
POSTrequest that uses theoffer_idgenerated in the search step, eliminating the need to re-send explicit trip details (like carrier, stations, and times). For information about our new flow please check the New Offers Flow Explained guide for a step-by-step walkthrough of the changes.
Making a Vacancy Request
The vacancy request must include the offer_id captured from the /connections/find response for each bound as the minimum required field, for instance "offer_id": "0d76170a-fcc3-4942-8370-499cc9f12a8f|0". This id includes all the information about the connection, fare, currency and other detais selected by the user for the further flow.
Besides that, each passenger included in the search from /connections/find should be mapped to a corresponding passenger_types supported by the carrier and include their respective passenger_ids.
For instance, a 33 years-old passenger corresponds to a PNOS passenger type with SNCF. And in the respose from the /connections/find this passenger is identified as pax-33-1. For more details on how to handle passenger mapping please check our Passenger Types guide.
{
"locale": "en",
"currency": "EUR",
"offers": [
{
"id": "cfe63acc-07eb-4463-9a88-b035c935f032|0",
"passenger_ids": [
"pax-40-1"
]
}
],
"passengers": [
{
"id": "pax-40-1",
"type": "PNOS",
"pax": 1
}
]
}
Reading Price & Vacancy Response
There are 3 possible outcomes in the response from /connections/vacancy:
- Price remains the same + vacancy (
vacant = true): In this case, the user should be moved to the next step of the flow without restrictions. - 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. - 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
In the case of a return trip, please add the offer_id 's from the offers selected for each bound. This means that the /connections/vacancy request will include two offer_id values for a return journey.
Required Fields for Creating a 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.
The following shows an example:
{
"id": "PYPO-2-1764170649",
"type": "passengers",
"relationships": {
"required_attributes": {
"data": [
{
"id": "4dabd987-f87e-422e-9187-0c6988d5b1d8",
"type": "passenger_required_attributes"
},
{
"id": "86f0b1e6-ddb9-4078-a08b-c77df8df8c53",
"type": "passenger_required_attributes"
}
]
}
}
},
{
"id": "e94d9f32-ed2b-4432-b27e-b93179d3b850",
"type": "passenger_required_attributes",
"attributes": {
"mandatory": [
"birthdate",
"first_name",
"last_name"
],
"endpoint": "reservations/create",
"internal_source": true
}
},
{
"id": "0b18608d-5371-4640-a6f3-62a1722726b3",
"type": "passenger_required_attributes",
"attributes": {
"mandatory": [
"birthdate",
"first_name",
"last_name"
],
"endpoint": "reservations/confirm",
"internal_source": true
}
},
{
"id": "4dabd987-f87e-422e-9187-0c6988d5b1d8",
"type": "passenger_required_attributes",
"attributes": {
"mandatory": [
"birthdate",
"first_name",
"last_name"
],
"endpoint": "reservations/create",
"internal_source": true
}
},
{
"id": "86f0b1e6-ddb9-4078-a08b-c77df8df8c53",
"type": "passenger_required_attributes",
"attributes": {
"mandatory": [
"birthdate",
"first_name",
"last_name"
],
"endpoint": "reservations/confirm",
"internal_source": true
}
},
{
"id": "3f38d969-3893-42c5-9b75-70e5b18655e3",
"type": "required_attributes",
"attributes": {
"mandatory": [
"email"
],
"endpoint": "reservations/create"
}
},
{
"id": "cf75d8ec-0256-451d-a1da-1bac65a8187a",
"type": "required_attributes",
"attributes": {
"mandatory": [
"email",
"first_name",
"last_name",
"terms_accepted"
],
"endpoint": "reservations/confirm"
}
}
]
}
For more details check our Dynamic Passenger Fields guide.
Best Practices
- 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 could be cached or the price may have changed while the user has selected the desired connection.
- 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 the response of the reservations/create response.
- 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. ca. 2768 USD, 2106 GBP etc. This rule applies for all carriers and all fares in the demo environment.
- 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
With the response of the vacancy request, you are also also able to present the list of ancillaries available to for booking for the user. For more information and to request activation of this functionality, please refer to the Ancillaries section.
Moreover, If any discount or loyalty 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) or 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
{
"locale": "en",
"currency": "EUR",
"offers": [
{
"id": "cfe63acc-07eb-4463-9a88-b035c935f032|0",
"passenger_ids": [
"pax-40-1"
]
}
],
"passengers": [
{
"id": "pax-40-1",
"type": "PNOS",
"pax": 1
}
]
}
Sample Response from /connections/vacancy
{
"data": {
"id": "TTES-FRPARPRG-FRMRSMBU-2026-03-16T11:11-2026-03-16T14:48",
"type": "vacancies",
"attributes": {
"vacant": true,
"total_price": 25000,
"original_price": 25000
},
"relationships": {
"agent": {
"data": null
},
"customer": {
"data": null
},
"applied_cards": {
"data": []
},
"fees": {
"data": []
},
"offer_options": {
"data": []
},
"connection_passengers": {
"data": [
{
"id": "PNOS-1-1773652361",
"type": "passengers"
}
]
},
"required_attributes": {
"data": [
{
"id": "672d1a59-7aae-4f90-8bfb-ac36cfa1c1cc",
"type": "required_attributes"
},
{
"id": "f7bfb798-4a77-4951-b0ac-20c5f9cf0e59",
"type": "required_attributes"
}
]
}
}
},
"jsonapi": {
"version": "1.0"
},
"meta": {
"currency": "EUR"
},
"included": [
{
"id": "PNOS-1-1773652361",
"type": "passengers",
"relationships": {
"required_attributes": {
"data": [
{
"id": "3299dace-c4d9-4de2-9fe4-bd207f15eab8",
"type": "passenger_required_attributes"
},
{
"id": "c285453d-c9da-41ef-b9ed-6bca88738368",
"type": "passenger_required_attributes"
}
]
}
}
},
{
"id": "3299dace-c4d9-4de2-9fe4-bd207f15eab8",
"type": "passenger_required_attributes",
"attributes": {
"mandatory": [],
"endpoint": "reservations/create"
}
},
{
"id": "c285453d-c9da-41ef-b9ed-6bca88738368",
"type": "passenger_required_attributes",
"attributes": {
"mandatory": [
"first_name",
"last_name"
],
"endpoint": "reservations/confirm",
"internal_source": true
}
},
{
"id": "672d1a59-7aae-4f90-8bfb-ac36cfa1c1cc",
"type": "required_attributes",
"attributes": {
"mandatory": [],
"endpoint": "reservations/create"
}
},
{
"id": "f7bfb798-4a77-4951-b0ac-20c5f9cf0e59",
"type": "required_attributes",
"attributes": {
"mandatory": [
"email",
"first_name",
"last_name",
"terms_accepted"
],
"endpoint": "reservations/confirm"
}
}
]
}
On this page
- Checking Price & Vacancy