Duffel Flights API Integration Guide

Duffel Flights API is a useful modern reference for an explicit Offer/Order flight-supply model.

Lifecycle

Offer Request
 -> Offers
 -> selected Offer
 -> optional price/services
 -> Order
 -> payment / hold
 -> change/cancel/service

Offers are ephemeral and expose expires_at. Do not attempt to book expired offers.

Order

An Order represents a view of the airline booking. Duffel documents the airline as source of truth and exposes synced_at for the last airline synchronization time.

Ancillaries

Available services can include extras such as checked bags. Preserve selected service identity through booking.

Hold vs instant

Orders can use instant payment or hold-and-pay-later when the selected offer allows it.

Idempotency

An Order-create timeout creates UNKNOWN state. Avoid blind duplicate creation and reconcile first.

Observability

Track offer-request latency, offer expiry, order success/unknown rate, synced_at age, airline-initiated changes and service-booking errors.