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.

1. Fetch available services for an offer

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.

2. Book offer with services

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.

3. Check what services you booked

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):