Implementation Guides
Adding Extra Bags
note
The ability to book baggage with your flight is not available for all airlines yet. We recommend using British Airways offers to follow along on this guide.
What do you need to start?
This guide will go through the changes you need to make in the booking flow to be able to list and book services for any offer you want. It's important you know the basics of how to create a booking.
If you are not familiar with how to create an order please heads over to our Quick Start Guide.
This guide will start from an offer so make sure you grab an offer ID for a British Airways flight before we start.
tip
We've put together a Postman Collection that contains all of the requests you'll need to follow along with this guide.
Overview
Baggages are a type of what we call
available_services. Available services are specific to an offer but not surfaced through the API by default. The changes we'll make to work with available services are:Retrieve an offer along with its
available_servicesInclude services to order creation
See the services booked on an order
Getting services for an offer
We start by fetching the offer to make sure to get its most up to date information. The get offer endpoint gives you the ability to retrieve available services with the offer by applying the query param
return_available_services set to true. Using a valid offer id you can use:Shell
curl -X GET --compressed "https://api.duffel.com/air/offers/$OFFER_ID?return_available_services=true"-H "Accept-Encoding: gzip"-H "Accept: application/json"-H "Duffel-Version: beta"-H "Authorization: Bearer$YOUR_ACCESS_TOKEN"
This request will return an offer which now include the
available_services attribute.Available services
The only available service currently supported is baggages. Wi-fi and meals are a couple of the options we aim to support in the near future. Each available service is unique and identifiable by id. The price of the service is described by
total_currency and total_amount. And the actual service information is determined by its type and metadata.Important to notice that services are specific to segments and passengers. The relationship is described by the attributes
segment_ids and passenger_ids.Learn more
For a complete description of the available services schema checkout the API reference.
Booking with services
Once you know what offer and service a user wants to book all you have to send request to the create order endpoint with 2 small changes to the payload.
Shell
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": {"selected_offers": ["'"$OFFER_ID"'"],"payments": [{"type": "balance","currency": "'"$TOTAL_CURRENCY"'","amount": "'"$TOTAL_AMOUNT"'"}],"passengers": [{"phone_number": "+442080160508","email": "tony@example.com","born_on": "1980-07-24","title": "mr","gender": "m","family_name": "Stark","given_name": "Tony","infant_passenger_id": "'"$INFANT_PASSENGER_ID"'","id": "'"$ADULT_PASSENGER_ID_1"'"},{"phone_number": "+442080160509","email": "potts@example.com","born_on": "1983-11-02","title": "mrs","gender": "m","family_name": "Potts","given_name": "Pepper","id": "'"$ADULT_PASSENGER_ID_2"'"},{"phone_number": "+442080160506","email": "morgan@example.com","born_on": "2019-08-24","title": "mrs","gender": "f","family_name": "Stark","given_name": "Morgan","id": "'"$INFANT_PASSENGER_ID"'"}],"services": [{"quantity": 2,"id": "'"$SERVICE_ID_1"'"},{"quantity": 1,"id": "'"$SERVICE_ID_2"'"}]}}'
You must add the attribute services to your request payload. This field should contain a list of
services to be book along with the offer specified in the selected_offers field. Each service on the list here must contain the available service id ($SERVICE_ID_N) and the desired quantity.The payment amount (
$TOTAL_AMOUNT) must be increased by the amount times quantity of each service you'd like to purchase. For example, if your offer total is 50 GBP and you include service A with quantity 2 and total_amount 10 GBP, the amount of the payment should now be 70 GBP.Services on Order
Once the booking has gone through in the airline's system we will return the usual order create response payload to you. You can always retrieve your order by id:
Shell
curl -X GET --compressed "https://api.duffel.com/air/orders/$ORDER_ID"-H "Accept-Encoding: gzip"-H "Accept: application/json"-H "Duffel-Version: beta"-H "Authorization: Bearer$YOUR_ACCESS_TOKEN"
Services
The service object will look exactly the same as the available service expect for
maximum_quantity being replaced with quantity. It's worth flagging that any ancillary baggages booked as services will not be present in the slices[].segments[].passengers[].baggages[]. They are only present in the services field. If you want the full picture of a passenger's baggage you will need to combine both.Documents
Some airlines record the booking and the payment of ancillary services in a document different from the electronic ticket issued for the flight. These documents are called Electronic Miscellaneous Documents. When available we expose them in the API as a document with a
type of electronic_miscellaneous_document_associated.Learn more
For look at the services and documents schema, please visit our API reference:
Keep Learning
Now you are able to include baggages to an order! Once we support more ancillary services you'll be able to rely on the same flow but apply it to other available service types. If you'd like to get a deeper look into the API reference to learn more you can jump to:
If you still haven't learned how to cancel an order we recommend looking at that next: