Checking Reservation Status
Once the reservation is confirmed using the /reservations/confirm endpoint, the carrier usually takes some time to process it. Most carriers will complete the process in a few seconds but this can take longer, so it is important to continuously check the reservation status using the /reservations/{reservation_id} endpoint until a response is received.
Reading Reservation Status
After sending a request to the /reservations/confirm endpoint the status of the reservation is set to processing. Then a new request must be sent to the /reservations/{reservation_id} endpoint to check the status of the reservation. In the response, the value state shows the current state of the reservation. Values can be:
created: The default value, appears right after the reservation is created.processing: Shown after /reservations/confirm is initially called.confirmed: Shown once the reservation is confirmed with the carrier.cancelled: Shown if /reservation/cancel is called (used in case the user aborts the reservation flow).failed: Shown if something goes wrong in the booking.
Processing Deadline
In the response from, the processing_deadline value will present the date and time deadline that the retailer should request /reservations/{reservation_id} to see if a booking was successfully created. Hence if you stop listening to it before that time frame, a discrepancy can happen.
The reservation status must be continually checked every 5-10 seconds until one of the following occurs:
- The reservation is
confirmedand you can proceed with the post-booking actions. - The reservation times out, in which case it will be automatically tagged as
failed. - The reservation is
failed, in which case the user must be notified that their booking was unsuccessful.
Best Practices
- Wait for for entire processing deadline: The max processing deadline supported by Distribusion is 10 mins and it is essential to continue listening (calling /reservations/{reservation_id}) until the deadline expires. If you stop listening before processing_deadline is completed and then the booking is created, there will be a discrepancy in status of the booking between you and the carrier. If this occurs, you will still be charged and incur the transaction costs. Note that in most cases the bookings are processed within 15 seconds, but it can happen that some will take longer. 10 minutes is our limit for timing out the requests. If you want to know the average processing times for selected carriers please speak to your Partnership Manager.
- Collect booking ID: The
booking_idreturned from the /reservations/{reservation_id} endpoint endpoint after a successful booking can be used for all further post-booking interaction with the Distribusion API.
Enterprise Features
Nothing applies to this step. For more details, check our guide on Ancillaries and Discount Cards.
Next Step
If the reservation is successful, check the full details of the booking and retrieve the pdf and mobile tickets.
If the reservation fails, move the user back to the search results step to initiate the flow again.
API Examples
Sample Request to /reservations/{reservation_id}
HTTP
https://api.demo.distribusion.com/retailers/v4/reservations/R7L9P7HTSample Response from /reservations/{reservation_id}
JSON
{
"data": {
"id": "R7L9P7HT",
"type": "reservations",
"attributes": {
"total_price": 5000,
"original_price": 5000,
"state": "confirmed",
"created_at": "2024-08-23T17:20",
"confirmed_at": "2024-08-23T17:20",
"cancelled_at": null,
"failed_at": null,
"processing_started_at": "2024-08-23T17:20",
"processing_deadline": null,
"expires_at": "2024-08-24T17:20",
"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": [
"R7L9P7HT"
],
"agent_id": null,
"retailer_booking_number": null
},
"relationships": {
"booking": {
"data": {
"id": "Nml-yarA4BveQ-iOVsT4BQ",
"type": "bookings"
}
},
"errors": {
"data": []
},
"reservation_passengers": {
"data": [
{
"id": "R-PNOS-1-ITAL-ITMILMAN-ITRRONGB-2024-08-29T10:15-2024-08-29T14:53",
"type": "reservation_passengers"
},
{
"id": "R-PCIL-2-ITAL-ITMILMAN-ITRRONGB-2024-08-29T10:15-2024-08-29T14:53",
"type": "reservation_passengers"
}
]
},
"applied_cards": {
"data": []
},
"ancillaries": {
"data": []
}
}
},
"jsonapi": {
"version": "1.0"
},
"meta": {
"locale": "en",
"currency": "EUR"
},
"included": [
{
"id": "R-PNOS-1-ITAL-ITMILMAN-ITRRONGB-2024-08-29T10:15-2024-08-29T14:53",
"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": {
"ancillaries": {
"data": []
}
}
},
{
"id": "R-PCIL-2-ITAL-ITMILMAN-ITRRONGB-2024-08-29T10:15-2024-08-29T14:53",
"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": "PCIL"
},
"relationships": {
"ancillaries": {
"data": []
}
}
},
{
"id": "Nml-yarA4BveQ-iOVsT4BQ",
"type": "bookings",
"attributes": {
"departure_time": "2024-08-29T10:15",
"arrival_time": "2024-08-29T14:53",
"duration": 16680,
"title": "mr",
"first_name": "John",
"last_name": "Smith",
"email": "test@distribusion.com",
"phone": "+4915222088994",
"city": "Berlin",
"zip_code": "13355",
"street_and_number": "Wattstrasse 10",
"payment_method": "demand_note",
"payment_token": null,
"payer_id": null,
"total_price": 5000,
"original_price": 5000,
"pax": 2,
"flight_number": null,
"distribusion_booking_number": "GXSK6P",
"marketing_carrier_booking_number": "R7L9P7HT",
"terms_accepted": true,
"send_customer_email": true,
"retailer_partner_number": "222222",
"connection_reference": null,
"created_at": "2024-08-23T17:20"
},
"relationships": {
"fare_class": {
"data": {
"id": "ITAL-FARE-4",
"type": "fare_classes"
}
},
"outbound_connection": {
"data": {
"id": "ITAL-ITMILMAN-ITRRONGB-2024-08-29T10:15-2024-08-29T14:53",
"type": "connections"
}
},
"inbound_connection": {
"data": null
},
"amended_by": {
"data": null
},
"result_of_amendment": {
"data": null
},
"segments": {
"data": [
{
"id": "ITAL-ITMILMAN-ITRRONGB-2024-08-29T10:15-2024-08-29T14:53-0",
"type": "segments"
}
]
},
"passengers": {
"data": [
{
"id": "PNOS-SMITH-JOHN-OUTBOUND-1",
"type": "passengers"
},
{
"id": "PCIL-SMITH-ANA-OUTBOUND-2",
"type": "passengers"
}
]
},
"fees": {
"data": []
},
"applied_cards": {
"data": []
}
}
},
{
"id": "ITAL-ITMILMAN-ITRRONGB-2024-08-29T10:15-2024-08-29T14:53-0",
"type": "segments",
"attributes": {
"departure_time": "2024-08-29T10:15",
"arrival_time": "2024-08-29T14:53",
"index": 0,
"vehicle_number": null,
"departure_platform": null,
"line": null,
"line_prefix": null
},
"relationships": {
"departure_station": {
"data": {
"id": "ITMILMAN",
"type": "stations"
}
},
"arrival_station": {
"data": {
"id": "ITRRONGB",
"type": "stations"
}
},
"operating_carrier": {
"data": {
"id": "ITAL",
"type": "operating_carriers"
}
},
"marketing_carrier": {
"data": {
"id": "ITAL",
"type": "marketing_carriers"
}
},
"vehicle": {
"data": {
"id": "TRAIN-ITAL-ITMILMAN-ITRRONGB-2024-08-29T10:15-2024-08-29T14:53-0",
"type": "vehicles"
}
},
"segment_passengers": {
"data": [
{
"id": "PNOS-SMITH-JOHN-OUTBOUND-1-0",
"type": "segment_passengers"
},
{
"id": "PCIL-SMITH-ANA-OUTBOUND-2-0",
"type": "segment_passengers"
}
]
},
"ancillaries": {
"data": []
}
}
},
{
"id": "PNOS-SMITH-JOHN-OUTBOUND-1-0",
"type": "segment_passengers",
"attributes": {
"seat_number": null,
"marketing_carrier_passenger_id": null
},
"relationships": {
"passenger": {
"data": {
"id": "PNOS-SMITH-JOHN-OUTBOUND-1",
"type": "passengers"
}
},
"ticket": {
"data": null
},
"applied_cards": {
"data": []
},
"ancillaries": {
"data": []
}
}
},
{
"id": "PCIL-SMITH-ANA-OUTBOUND-2-0",
"type": "segment_passengers",
"attributes": {
"seat_number": null,
"marketing_carrier_passenger_id": null
},
"relationships": {
"passenger": {
"data": {
"id": "PCIL-SMITH-ANA-OUTBOUND-2",
"type": "passengers"
}
},
"ticket": {
"data": null
},
"applied_cards": {
"data": []
},
"ancillaries": {
"data": []
}
}
},
{
"id": "PNOS-SMITH-JOHN-OUTBOUND-1",
"type": "passengers",
"attributes": {
"first_name": "John",
"last_name": "Smith",
"serial_code": null,
"type": "PNOS"
}
},
{
"id": "PCIL-SMITH-ANA-OUTBOUND-2",
"type": "passengers",
"attributes": {
"first_name": "Ana",
"last_name": "Smith",
"serial_code": null,
"type": "PCIL"
}
},
{
"id": "ITAL-FARE-4",
"type": "fare_classes",
"attributes": {
"code": "FARE-4",
"name": "Economy - Prima",
"iata_category": "Business Class",
"journey_type": "single"
},
"relationships": {
"post_booking_condition": {
"data": null
},
"fare_features": {
"data": [
{
"id": "ITAL-WIFI",
"type": "fare_features"
},
{
"id": "ITAL-SNAC",
"type": "fare_features"
},
{
"id": "ITAL-DRIN",
"type": "fare_features"
},
{
"id": "ITAL-ALRO",
"type": "fare_features"
},
{
"id": "ITAL-UCHA",
"type": "fare_features"
},
{
"id": "ITAL-MSYS",
"type": "fare_features"
},
{
"id": "ITAL-PREF",
"type": "fare_features"
}
]
},
"ticket_validity_rules": {
"data": [
{
"id": "ITAL-FARE-4-TICKET_VALIDITY_RULE-0",
"type": "ticket_validity_rules"
}
]
},
"passenger_group_rules": {
"data": []
}
}
},
{
"id": "ITAL-WIFI",
"type": "fare_features",
"attributes": {
"code": "WIFI",
"name": "Wifi",
"description": "Free wifi is available on board."
}
},
{
"id": "ITAL-SNAC",
"type": "fare_features",
"attributes": {
"code": "SNAC",
"name": "Snacks",
"description": "Snacks are available on board."
}
},
{
"id": "ITAL-DRIN",
"type": "fare_features",
"attributes": {
"code": "DRIN",
"name": "Drinks",
"description": "Drinks are available on board."
}
},
{
"id": "ITAL-ALRO",
"type": "fare_features",
"attributes": {
"code": "ALRO",
"name": "Additional Leg Room",
"description": "The seat has additional leg space."
}
},
{
"id": "ITAL-UCHA",
"type": "fare_features",
"attributes": {
"code": "UCHA",
"name": "USB charger",
"description": "USB plug is available at each seat."
}
},
{
"id": "ITAL-MSYS",
"type": "fare_features",
"attributes": {
"code": "MSYS",
"name": "Media System",
"description": "A media system is available on board."
}
},
{
"id": "ITAL-PREF",
"type": "fare_features",
"attributes": {
"code": "PREF",
"name": "Partially refundable",
"description": "The ticket can be cancelled and partially refunded."
}
},
{
"id": "ITAL-FARE-4-TICKET_VALIDITY_RULE-0",
"type": "ticket_validity_rules",
"attributes": {
"rule_type": "outbound",
"reference_time_type": "departure_time",
"use_type": "once",
"offset_type": "minutes",
"duration_type": "minutes",
"offset": 0,
"duration": 0
}
},
{
"id": "ITAL-ITMILMAN-ITRRONGB-2024-08-29T10:15-2024-08-29T14:53",
"type": "connections",
"attributes": {
"departure_time": "2024-08-29T10:15",
"arrival_time": "2024-08-29T14:53"
},
"relationships": {
"departure_station": {
"data": {
"id": "ITMILMAN",
"type": "stations"
}
},
"arrival_station": {
"data": {
"id": "ITRRONGB",
"type": "stations"
}
},
"marketing_carrier": {
"data": {
"id": "ITAL",
"type": "marketing_carriers"
}
},
"segments": {
"data": [
{
"id": "ITAL-ITMILMAN-ITRRONGB-2024-08-29T10:15-2024-08-29T14:53-0",
"type": "segments"
}
]
},
"fees": {
"data": []
}
}
}
]
}For more samples responses, check the /reservations/{reservation_id} endpoint page.
Was this section helpful?
What made this section unhelpful for you?
On this page
- Checking Reservation Status