This is a small guide to booking an offer with services, such as baggages, with the Duffel API.
The guide assumes that you already have an integration built with the Duffel API to search and book flights.
The first step to book extra services is to fetch them. This is performed using the endpoint to fetch a single offer. To fetch available_services
, call this endpoint setting the return_available_services
query param to true
.
Request
curl -X GET --compressed "<https://api.duffel.com/air/offers/off_123?return_available_services=true>" \\
-H "Accept-Encoding: gzip" \\
-H "Accept: application/json" \\
-H "Duffel-Version: beta" \\
-H "Authorization: Bearer example_token"
Response
{
"data": {
"id": "off_00009htYpSCXrwaB9DnUm0",
// ...
**"available_services": [
{
"type": "baggage",
"total_currency": "GBP",
"total_amount": "15.00",
"segment_ids": [
"seg_00009hj8USM7Ncg31cB456",
"seg_00009hj8USM7Ncg31cB123",
],
"passenger_ids": [
"passenger_0"
],
"metadata": {
"type": "checked",
"maximum_depth_cm": 75,
"maximum_length_cm": 90,
"maximum_height_cm": 90,
"maximum_weight_kg": 23
},
"maximum_quantity": 1,
"id": "ser_00009UhD4ongolulWd9123"
},
{
"type": "baggage",
"total_currency": "GBP",
"total_amount": "15.00",
"segment_ids": [
"seg_00009hj8USM7Ncg31cB456",
"seg_00009hj8USM7Ncg31cB123",
],
"passenger_ids": [
"passenger_1"
],
"metadata": {
"type": "checked",
"maximum_depth_cm": 75,
"maximum_length_cm": 90,
"maximum_height_cm": 90,
"maximum_weight_kg": 23
},
"maximum_quantity": 1,
"id": "ser_00009UhD4ongolulWd9123"
}
]**
}
}
As we can see in the example above the offer has two very similar available services, both represent a 23kg checked bag service that can be used on the seg_00009hj8USM7Ncg31cB456
segment and the seg_00009hj8USM7Ncg31cB123
segment, and they both cost £15.
{
"type": "baggage",
"total_currency": "GBP",
"total_amount": "15.00",
"segment_ids": [
"seg_00009hj8USM7Ncg31cB456",
"seg_00009hj8USM7Ncg31cB123"
],
"passenger_ids": [
"passenger_1"
],
"metadata": {
"type": "checked",
"maximum_depth_cm": 75,
"maximum_length_cm": 90,
"maximum_height_cm": 90,
"maximum_weight_kg": 23
},
"maximum_quantity": 1,
"id": "ser_00009UhD4ongolulWd9123"
}
The difference between the two is to which passenger they apply to, the first one applies to passenger_0
and the second to passenger_1
. The metadata
field includes metadata about the service itself, in the example above it includes the maximum weight and dimensions of the bag. Please note that this information maybe null if the airline does not expose it.
The example above only includes services of type baggage
, but you should build your integration in a way that can handle more type of services in the future because we won't consider adding new types of services to be a breaking change.
Once you know what offer and service a user wants to book all you have to do call the "Order create" endpoint as you normally would, but with two small changes (the differences are highlighted in the example below):
curl -X POST --compressed "<https://api.duffel.com/air/orders>" \\
-H "Accept-Encoding: gzip" \\
-H "Accept: application/json" \\
-H "Content-Type: application/json" \\
-H "Duffel-Version: beta" \\
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \\
-d '{
"data": {
**"payments": [
{
"currency": "GBP",
"amount": "50.20",
"type": "balance"
}
],**
"passengers": [
// ...
],
**"services": [
{
"quantity": 1,
"id": "ser_00009hj8USM7Ncg31cB123"
}
],**
"selected_offers": [
"off_00009htyDGjIfajdNBZRlw"
]
}
}'
The first change is the addition of a new request field called services
. This field should contain a list of services to book along with the offer specified in the selected_offers
field. As you can see from the example, the service id is all you need to book the service. Duffel automatically figures out the service details for you.
The second change is in the payments
field. You will need to provide a payment amount that includes the offer total amount plus the total amount of all the services
.
Once the booking has gone through in the airline's system we will return the usual order create response payload to you, but with a few changes as well (these changes are highlighted in the example below):