Creating Reservation
Once the price and vacancy of the trip selected by the user is confirmed the next step is to call the /reservations/create endpoint to create a reservation.
A reservation is a temporary block of a place on the ride that ensures seat availability at the moment of purchase (confirmation). Reservations hold for 10 minutes in general, and, if not confirmed will be automatically cancelled.
Reservations are a helpful tool to ensure that the customer retains their booking and seat throughout the checkout process. Without reservations, it is possible that while the user is buying their ticket their bus or seat could be booked out, resulting in the user losing their trip.
It is important to note that even if you have implemented reservations, your integration will still work with carriers who do not support reservations yet. The flow will work as it normally does and the reservation will be simulated.
Reading Expiration Time
Some carriers in Distribusion were integrated using the full reservation flow. In this case, when a reservation is created they hold the reservation for a set amount of time. This is usually set at 10 minutes but some carriers can hold it for a few hours or even days (such as SNCF).
When the carrier selected doesn't support it, the reservation still works as expected but the response shows the value expires_at = null . In this case we recommend to set the value to 10 minutes to match the default of most carriers to keep the flow consistent to the user. However, the reservation is not truly on hold and there is a chance the request to confirm the reservation at /reservations/confirm will fail.
Defining Passenger Type
When searching for trips you can include the exact age of each passenger. However, in the request to create a reservation you must match the age of the passenger to the passenger type as defined by the carrier. To understand more about it check our Passenger Type guide.
Return Trips
For return trips, we recommend to include both the inbound and outbound segments into the same reservation 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.
Adding Seats
Seats selected in the previous step can be included at the time of creating the reservation. In case the journey is multi-segment, a seat code per segment must be specified.
Required Fields for Creating Reservation
Note that most carriers require passenger details only in the /reservations/confirm request, but there are a few that require some details to be included as part of the /reservations/create request. This information is available from the /connections/vacancy endpoint. For more details check our Dynamic Passenger Fields guide.
Best Practices
- Cancel the reservation when the user aborts the flow: If the checkout is aborted by the user by clicking on a cancel button or by moving back to the search results page, it is recommended to cancel the reservation to avoid blocking seats. This can be done from the /reservation/cancel endpoint.
- Read the price from the response: It is important to read the price from the /reservations/create 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.
- Read the list of required booking fields from /connections/find: Read the info in the /connections/vacancy response and check our Dynamic Passenger Fields guide. We recommend that you store this data to dynamically show the required fields when creating a reservation.
Enterprise Features
Before a reservation is created you can allow users to book additional ancillaries. For more details, check our guide on Ancillaries.
If any discount cards are applied as part of the flow, they can be added to the /reservations/create request and will affect the price that appears in the response. The details of the cards applied also appear in the response. For more details, check our guide on Discount Cards.
Next Step
If the reservation is created successfully, the user can proceed to the checkout page to complete their details and payment, where the reservation can be confirmed.
API Examples
Sample Request to /reservations/create
{
"marketing_carrier": "UTIL",
"departure_station": "BRBHZBHB",
"arrival_station": "BRLZSRDJ",
"departure_time": "2025-05-19T08:00",
"arrival_time": "2025-05-19T15:55",
"retailer_partner_number": "222222",
"fare_class": "FARE-2",
"locale": "en",
"currency": "EUR",
"passengers": [
{
"type": "PNOS",
"seats": [
{
"seat_code": "10",
"segment_index": 1
}
]
},
{
"type": "PNOS",
"seats": [
{
"seat_code": "12",
"segment_index": 1
}
]
}
]
}Sample Response from /reservations/create
{
"data": {
"id": "RK8B1T7Z",
"type": "reservations",
"attributes": {
"total_price": 3070,
"original_price": 3070,
"state": "created",
"created_at": "2025-05-09T16:53",
"confirmed_at": null,
"cancelled_at": null,
"failed_at": null,
"processing_started_at": null,
"processing_deadline": null,
"expires_at": "2025-05-09T17:04",
"terms_version": null,
"title": null,
"first_name": null,
"last_name": null,
"email": null,
"phone": null,
"city": null,
"zip_code": null,
"country_code": null,
"street_and_number": null,
"gender": null,
"country_of_birth": null,
"government_id_type": null,
"marketing_carrier_reservation_ids": [
"RK8B1T7Z"
],
"agent_id": null,
"retailer_booking_number": null,
"customer_id": null
},
"relationships": {
"booking": {
"data": null
},
"utm_params": {
"data": null
},
"errors": {
"data": []
},
"segments": {
"data": [
{
"id": "UTIL-BRBHZBHB-BRLZSRDJ-2025-05-19T08:00-2025-05-19T15:55-0",
"type": "segments"
}
]
},
"reservation_passengers": {
"data": [
{
"id": "R-PNOS-1-UTIL-BRBHZBHB-BRLZSRDJ-2025-05-19T08:00-2025-05-19T15:55",
"type": "reservation_passengers"
},
{
"id": "R-PNOS-2-UTIL-BRBHZBHB-BRLZSRDJ-2025-05-19T08:00-2025-05-19T15:55",
"type": "reservation_passengers"
}
]
},
"applied_cards": {
"data": []
},
"ancillaries": {
"data": []
},
"required_attributes": {
"data": [
{
"id": "RK8B1T7Z-7650115c-df50-45bb-a0bc-d3ff2d203ff3",
"type": "required_attributes"
}
]
},
"custom_fields": {
"data": []
}
}
},
"jsonapi": {
"version": "1.0"
},
"meta": {
"currency": "EUR",
"locale": "en"
},
"included": [
{
"id": "UTIL-BRBHZBHB-BRLZSRDJ-2025-05-19T08:00-2025-05-19T15:55-0",
"type": "segments",
"relationships": {
"segment_passengers": {
"data": [
{
"id": "PNOS-1-UTIL-BRBHZBHB-BRLZSRDJ-2025-05-19T08:00-2025-05-19T15:55-0",
"type": "segment_passengers"
},
{
"id": "PNOS-2-UTIL-BRBHZBHB-BRLZSRDJ-2025-05-19T08:00-2025-05-19T15:55-0",
"type": "segment_passengers"
}
]
}
}
},
{
"id": "PNOS-1-UTIL-BRBHZBHB-BRLZSRDJ-2025-05-19T08:00-2025-05-19T15:55-0",
"type": "segment_passengers",
"attributes": {
"seat_number": "10"
},
"relationships": {
"ancillaries": {
"data": []
}
}
},
{
"id": "PNOS-2-UTIL-BRBHZBHB-BRLZSRDJ-2025-05-19T08:00-2025-05-19T15:55-0",
"type": "segment_passengers",
"attributes": {
"seat_number": "12"
},
"relationships": {
"ancillaries": {
"data": []
}
}
},
{
"id": "R-PNOS-1-UTIL-BRBHZBHB-BRLZSRDJ-2025-05-19T08:00-2025-05-19T15:55",
"type": "reservation_passengers",
"attributes": {
"first_name": null,
"last_name": null,
"serial_code": null,
"government_id_type": null,
"nationality": null,
"gender": null,
"country_of_birth": null,
"birthdate": null,
"type": "PNOS"
},
"relationships": {
"required_attributes": {
"data": [
{
"id": "R-PNOS-1-UTIL-BRBHZBHB-BRLZSRDJ-2025-05-19T08:00-2025-05-19T15:55-329bbc2e-fb42-45f1-a1ae-9ee1cfe2843d",
"type": "reservation_passenger_required_attributes"
}
]
}
}
},
{
"id": "R-PNOS-2-UTIL-BRBHZBHB-BRLZSRDJ-2025-05-19T08:00-2025-05-19T15:55",
"type": "reservation_passengers",
"attributes": {
"first_name": null,
"last_name": null,
"serial_code": null,
"government_id_type": null,
"nationality": null,
"gender": null,
"country_of_birth": null,
"birthdate": null,
"type": "PNOS"
},
"relationships": {
"required_attributes": {
"data": [
{
"id": "R-PNOS-2-UTIL-BRBHZBHB-BRLZSRDJ-2025-05-19T08:00-2025-05-19T15:55-bf85c093-9513-4597-a2ff-732743db8067",
"type": "reservation_passenger_required_attributes"
}
]
}
}
},
{
"id": "R-PNOS-1-UTIL-BRBHZBHB-BRLZSRDJ-2025-05-19T08:00-2025-05-19T15:55-329bbc2e-fb42-45f1-a1ae-9ee1cfe2843d",
"type": "reservation_passenger_required_attributes",
"attributes": {
"mandatory": [
"government_id",
"government_id_type",
"first_name",
"last_name"
],
"endpoint": "reservations/confirm"
}
},
{
"id": "R-PNOS-2-UTIL-BRBHZBHB-BRLZSRDJ-2025-05-19T08:00-2025-05-19T15:55-bf85c093-9513-4597-a2ff-732743db8067",
"type": "reservation_passenger_required_attributes",
"attributes": {
"mandatory": [
"government_id",
"government_id_type",
"first_name",
"last_name"
],
"endpoint": "reservations/confirm"
}
},
{
"id": "RK8B1T7Z-a3f5003f-8136-4a5c-b912-dec95913feca",
"type": "required_attributes",
"attributes": {
"mandatory": [
"city",
"email",
"first_name",
"last_name",
"street_and_number",
"title",
"terms_accepted"
],
"endpoint": "reservations/confirm"
}
}
]}
}For more samples responses, check the /reservations/create endpoint page.
What made this section unhelpful for you?
On this page
- Creating Reservation