API Reference

Offers

After you've searched for flights by creating an offer request, we'll send your search to a range of airlines, which may return offers.

Each offer represents flights you can buy from an airline at a particular price that meet your search criteria.

You'll see slices inside the offers. Each slice will also include a list of one or more specific flights (called segments) that the airline is offering to get the passengers where they want to go.

allowed_passenger_identity_document_types
string[]

The types of identity documents that may be provided for the passengers when creating an order based on this offer. Currently, the only supported type is passport. If this is [], then you must not provide identity documents.

Example: ["passport"]
available_services
list

The services that can be booked along with the offer but are not included by default, for example an additional checked bag. This field is only returned in the Get single offer endpoint. When there are no services available, or we don't support services for the airline, this list will be empty. If you want to know which airlines we support services for, please get in touch with the Duffel support team at help@duffel.com.

base_amount
string

The base price of the offer for all passengers, excluding taxes. It does not include the base amount of any service(s) that might be booked with the offer.

Example: "30.20"
base_currency
string

The currency of the base_amount, as an ISO 4217 currency code. It will match your organisation's billing currency unless you’re using Duffel as an accredited IATA agent, in which case it will be in the currency provided by the airline (which will usually be based on the country where your IATA agency is registered).

Example: "GBP"
created_at
datetime

The ISO 8601 datetime at which the offer was created

Example: "2020-01-17T10:12:14.545Z"
updated_at
datetime

The ISO 8601 datetime at which the offer was last updated

Example: "2020-01-17T10:12:14.545Z"
expires_at
datetime

The ISO 8601 datetime at which the offer will expire and no longer be usable to create an order

Example: "2020-01-17T10:42:14.545Z"
id
string

Duffel's unique identifier for the offer

Example: "off_00009htYpSCXrwaB9DnUm0"
live_mode
boolean

Whether the offer request was created in live mode. This field will be set to true if the offer request was created in live mode, or false if it was created in test mode.

Example: true
owner
object

The airline which provided the offer

passenger_identity_documents_required
boolean

Whether identity documents must be provided for each of the passengers when creating an order based on this offer. If this is true, you must provide an identity document for every passenger.

Example: false
passengers
list

The passengers included in the offer

slices
list

The slices that make up this offer. Each slice will include one or more segments, the specific flights that the airline is offering to take the passengers from the slice's origin to its destination.

tax_amount
string
nullable

The amount of tax payable on the offer for all passengers

Example: "40.80"
tax_currency
string
nullable

The currency of the tax_amount, as an ISO 4217 currency code. It will match your organisation's billing currency unless you’re using Duffel as an accredited IATA agent, in which case it will be in the currency provided by the airline (which will usually be based on the country where your IATA agency is registered).

Example: "GBP"
total_amount
string

The total price of the offer for all passengers, including taxes. It does not include the total price of any service(s) that might be booked with the offer.

Example: "45.00"
total_emissions_kg
string

An estimate of the total carbon dioxide (CO₂) emissions when all of the passengers fly this offer's itinerary, measured in kilograms

Example: "460"
total_currency
string

The currency of the total_amount, as an ISO 4217 currency code. It will match your organisation's billing currency unless you’re using Duffel as an accredited IATA agent, in which case it will be in the currency provided by the airline (which will usually be based on the country where your IATA agency is registered).

Example: "GBP"

Retrieves a list of offers for a given offer request specified by its ID. Unless you specify a sort parameter, the results may be returned in any order.

This endpoint does not return the complete, up-to-date information on each offer. The Get a single offer endpoint should be called for a given offer in order to get complete and up-to-date information.

Endpoint

GEThttps://api.duffel.com/air/offers

Query Parameters

after
string

A cursor pointing to the previous page of records. For more information on how to paginate through records, see the Pagination section.

Example: "g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB="
before
string

A cursor pointing to the next page of records. For more information on how to paginate through records, see the Pagination section.

Example: "g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB="
limit
integer

The maximum number of records to return per page. Defaults to 50. May be set to any integer between 1 and 200. For more information on how to paginate through records, see the Pagination section.

Example: 1
offer_request_id
string
required

Duffel's unique identifier for the offer request, returned when it was created

Example: "orq_00009htyDGjIfajdNBZRlw"
sort
enum

By default, the offers will be returned sorted by id in ascending order. This parameter allows you to sort the list of offers by total_amount or total_duration. By default the sorting order will be ascending, if you wish to sort in descending order a - will need to be prepended to the sorting attribute (i.e: -total_amount).

Possible values: "total_amount" or "total_duration"
max_connections
integer

Allows to filter the offers list by the maximum number of connections in a given offer. e.g. a return flight with three flights outbound and a direct inbound flight would be filtered out if max_connections=1 was passed.

Example: 2

Request example

curl -X GET --compressed "https://api.duffel.com/air/offers" \
-H "Accept-Encoding: gzip" \
-H "Accept: application/json" \
-H "Duffel-Version: beta" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Response example

{
"meta": {
"limit": 50,
"after": "g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB="
},
"data": [
{
"total_currency": "GBP",
"total_emissions_kg": "460",
"total_amount": "45.00",
"tax_currency": "GBP",
"tax_amount": "40.80",
"slices": [
{
"segments": {
"passengers": [
{
"passenger_id": "passenger_0",
"cabin_class_marketing_name": "Economy Basic",
"cabin_class": "economy",
"baggages": [
{
"quantity": 1,
"type": "checked"
}
]
}
],
"operating_carrier_flight_number": "4321",
"operating_carrier": {
"name": "British Airways",
"id": "aln_00001876aqC8c5umZmrRds",
"iata_code": "BA"
},
"origin": {
"city": {
"iata_country_code": "GB",
"name": "London",
"id": "cit_lon_gb",
"iata_code": "LON"
},
"city_name": "London",
"time_zone": "Europe/London",
"icao_code": "EGLL",
"longitude": -141.951519,
"latitude": 64.068865,
"iata_country_code": "GB",
"name": "Heathrow",
"id": "arp_lhr_gb",
"iata_code": "LHR"
},
"marketing_carrier_flight_number": "1234",
"marketing_carrier": {
"name": "British Airways",
"id": "aln_00001876aqC8c5umZmrRds",
"iata_code": "BA"
},
"id": "seg_00009htYpSCXrwaB9Dn456",
"duration": "PT02H26M",
"distance": 424,
"destination": {
"city": {
"iata_country_code": "GB",
"name": "London",
"id": "cit_lon_gb",
"iata_code": "LON"
},
"city_name": "London",
"time_zone": "Europe/London",
"icao_code": "EGLL",
"longitude": -141.951519,
"latitude": 64.068865,
"iata_country_code": "GB",
"name": "Heathrow",
"id": "arp_lhr_gb",
"iata_code": "LHR"
},
"origin_terminal": "B",
"departing_at": "2020-06-13T16:38:02",
"destination_terminal": "5",
"arriving_at": "2020-06-13T16:38:02",
"aircraft": {
"name": "Airbus Industries A380",
"id": "arc_00009UhD4ongolulWd91Ky",
"iata_code": "380"
}
},
"id": "sli_00009htYpSCXrwaB9Dn123",
"fare_brand_name": "Basic",
"duration": "PT02H26M",
"origin": {
"airports": [
{
"city": {
"iata_country_code": "GB",
"name": "London",
"id": "cit_lon_gb",
"iata_code": "LON"
},
"city_name": "London",
"time_zone": "Europe/London",
"icao_code": "EGLL",
"longitude": -141.951519,
"latitude": 64.068865,
"iata_country_code": "GB",
"name": "Heathrow",
"id": "arp_lhr_gb",
"iata_code": "LHR"
}
],
"city": {
"iata_country_code": "GB",
"name": "London",
"id": "cit_lon_gb",
"iata_code": "LON"
},
"city_name": "London",
"time_zone": "Europe/London",
"icao_code": "EGLL",
"longitude": -141.951519,
"latitude": 64.068865,
"iata_country_code": "GB",
"type": "airport",
"name": "Heathrow",
"id": "arp_lhr_gb",
"iata_code": "LHR",
"iata_city_code": "LON"
},
"origin_type": "airport",
"destination": {
"airports": [
{
"city": {
"iata_country_code": "GB",
"name": "London",
"id": "cit_lon_gb",
"iata_code": "LON"
},
"city_name": "London",
"time_zone": "Europe/London",
"icao_code": "EGLL",
"longitude": -141.951519,
"latitude": 64.068865,
"iata_country_code": "GB",
"name": "Heathrow",
"id": "arp_lhr_gb",
"iata_code": "LHR"
}
],
"city": {
"iata_country_code": "GB",
"name": "London",
"id": "cit_lon_gb",
"iata_code": "LON"
},
"city_name": "London",
"time_zone": "Europe/London",
"icao_code": "EGLL",
"longitude": -141.951519,
"latitude": 64.068865,
"iata_country_code": "GB",
"type": "airport",
"name": "Heathrow",
"id": "arp_lhr_gb",
"iata_code": "LHR",
"iata_city_code": "LON"
},
"destination_type": "airport"
}
],
"passengers": [
{
"id": "pas_00009hj8USM7Ncg31cBCL",
"type": "adult",
"age": 14
}
],
"owner": {
"name": "British Airways",
"id": "aln_00001876aqC8c5umZmrRds",
"iata_code": "BA"
},
"live_mode": true,
"id": "off_00009htYpSCXrwaB9DnUm0",
"expires_at": "2020-01-17T10:42:14.545Z",
"created_at": "2020-01-17T10:12:14.545Z",
"base_currency": "GBP",
"base_amount": "30.20",
"allowed_passenger_identity_document_types": [
"passport"
]
}
]
}

You should use this API to get the complete, up-to-date information about an offer. This endpoint does not guarantee that the offer will be available at the time of booking.

Due to limitations in airlines' systems, you may see changes to the offer (e.g a changed total_amount). Additionally, you may receive information that may have not been included in the original offer such as baggage allowances.

Optionally, you can request information about additional available_services that you can book with this offer by specifying the return_available_services query parameter.

Endpoint

GEThttps://api.duffel.com/air/offers/{id}

URL parameters

id
string
required

Duffel's unique identifier for the offer

Example: "off_00009htYpSCXrwaB9DnUm0"

Query Parameters

return_available_services
boolean

When set to true, the offer resource returned will include all the available_services returned by the airline. If set to false, the offer resource won't include any available_services.

Example: true

Request example

curl -X GET --compressed "https://api.duffel.com/air/offers/{id}" \
-H "Accept-Encoding: gzip" \
-H "Accept: application/json" \
-H "Duffel-Version: beta" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Response example

{
"data": {
"total_currency": "GBP",
"total_emissions_kg": "460",
"total_amount": "45.00",
"tax_currency": "GBP",
"tax_amount": "40.80",
"slices": [
{
"segments": {
"passengers": [
{
"passenger_id": "passenger_0",
"cabin_class_marketing_name": "Economy Basic",
"cabin_class": "economy",
"baggages": [
{
"quantity": 1,
"type": "checked"
}
]
}
],
"operating_carrier_flight_number": "4321",
"operating_carrier": {
"name": "British Airways",
"id": "aln_00001876aqC8c5umZmrRds",
"iata_code": "BA"
},
"origin": {
"city": {
"iata_country_code": "GB",
"name": "London",
"id": "cit_lon_gb",
"iata_code": "LON"
},
"city_name": "London",
"time_zone": "Europe/London",
"icao_code": "EGLL",
"longitude": -141.951519,
"latitude": 64.068865,
"iata_country_code": "GB",
"name": "Heathrow",
"id": "arp_lhr_gb",
"iata_code": "LHR"
},
"marketing_carrier_flight_number": "1234",
"marketing_carrier": {
"name": "British Airways",
"id": "aln_00001876aqC8c5umZmrRds",
"iata_code": "BA"
},
"id": "seg_00009htYpSCXrwaB9Dn456",
"duration": "PT02H26M",
"distance": 424,
"destination": {
"city": {
"iata_country_code": "GB",
"name": "London",
"id": "cit_lon_gb",
"iata_code": "LON"
},
"city_name": "London",
"time_zone": "Europe/London",
"icao_code": "EGLL",
"longitude": -141.951519,
"latitude": 64.068865,
"iata_country_code": "GB",
"name": "Heathrow",
"id": "arp_lhr_gb",
"iata_code": "LHR"
},
"origin_terminal": "B",
"departing_at": "2020-06-13T16:38:02",
"destination_terminal": "5",
"arriving_at": "2020-06-13T16:38:02",
"aircraft": {
"name": "Airbus Industries A380",
"id": "arc_00009UhD4ongolulWd91Ky",
"iata_code": "380"
}
},
"id": "sli_00009htYpSCXrwaB9Dn123",
"fare_brand_name": "Basic",
"duration": "PT02H26M",
"origin": {
"airports": [
{
"city": {
"iata_country_code": "GB",
"name": "London",
"id": "cit_lon_gb",
"iata_code": "LON"
},
"city_name": "London",
"time_zone": "Europe/London",
"icao_code": "EGLL",
"longitude": -141.951519,
"latitude": 64.068865,
"iata_country_code": "GB",
"name": "Heathrow",
"id": "arp_lhr_gb",
"iata_code": "LHR"
}
],
"city": {
"iata_country_code": "GB",
"name": "London",
"id": "cit_lon_gb",
"iata_code": "LON"
},
"city_name": "London",
"time_zone": "Europe/London",
"icao_code": "EGLL",
"longitude": -141.951519,
"latitude": 64.068865,
"iata_country_code": "GB",
"type": "airport",
"name": "Heathrow",
"id": "arp_lhr_gb",
"iata_code": "LHR",
"iata_city_code": "LON"
},
"origin_type": "airport",
"destination": {
"airports": [
{
"city": {
"iata_country_code": "GB",
"name": "London",
"id": "cit_lon_gb",
"iata_code": "LON"
},
"city_name": "London",
"time_zone": "Europe/London",
"icao_code": "EGLL",
"longitude": -141.951519,
"latitude": 64.068865,
"iata_country_code": "GB",
"name": "Heathrow",
"id": "arp_lhr_gb",
"iata_code": "LHR"
}
],
"city": {
"iata_country_code": "GB",
"name": "London",
"id": "cit_lon_gb",
"iata_code": "LON"
},
"city_name": "London",
"time_zone": "Europe/London",
"icao_code": "EGLL",
"longitude": -141.951519,
"latitude": 64.068865,
"iata_country_code": "GB",
"type": "airport",
"name": "Heathrow",
"id": "arp_lhr_gb",
"iata_code": "LHR",
"iata_city_code": "LON"
},
"destination_type": "airport"
}
],
"passengers": [
{
"id": "pas_00009hj8USM7Ncg31cBCL",
"type": "adult",
"age": 14
}
],
"owner": {
"name": "British Airways",
"id": "aln_00001876aqC8c5umZmrRds",
"iata_code": "BA"
},
"live_mode": true,
"id": "off_00009htYpSCXrwaB9DnUm0",
"expires_at": "2020-01-17T10:42:14.545Z",
"updated_at": "2020-01-17T10:12:14.545Z",
"created_at": "2020-01-17T10:12:14.545Z",
"base_currency": "GBP",
"base_amount": "30.20",
"available_services": [
{
"type": "baggage",
"total_currency": "GBP",
"total_amount": "15.00",
"segment_ids": [
"seg_00009hj8USM7Ncg31cB456"
],
"passenger_ids": [
"pas_00009hj8USM7Ncg31cBCLL"
],
"maximum_quantity": 1,
"id": "ase_00009UhD4ongolulWd9123"
}
],
"allowed_passenger_identity_document_types": [
"passport"
]
}
}