Duffel carries 9 APIs, and what makes the surface worth studying is that the APIs aren’t organized by system — they’re organized by the flow a traveler actually moves through. It’s a modern, clean-sheet contract laid over one of the messiest legacy domains in software: airline distribution.
What’s actually in the surface
The 9 APIs trace search-to-book-to-manage, in order:
- Search —
Offer Requests API(specify the trip you want) andOffers API(the fares that come back). Two APIs, because the request and the resulting offers are genuinely different resources. - Book —
Orders API(turn a chosen offer into a booking) andSeat Maps API(pick where you sit). - Pay —
Payments API. - Manage —
Order Changes APIandOrder Cancellations API, the after-the-sale lifecycle. - Extend —
Stays API(hotels, beyond flights) andWebhooks API(async event notifications).
What’s interesting about the shape
- The surface is a state machine, made legible. Offer request → offers → order → payment → change or cancellation. You can read the customer journey straight off the list of APIs. That’s a deliberate modeling choice, and it’s the opposite of how legacy GDS systems expose the same domain.
- Offer Requests and Offers are separate on purpose. An offer request is the search you asked for; offers are the volatile, time-boxed fares that come back. Splitting them acknowledges that flight prices are ephemeral — an offer can expire — and models that instead of hiding it.
- Changes and cancellations are first-class. Two dedicated APIs for the after-sale lifecycle, because in travel the hard part isn’t booking — it’s what happens when plans change. Modeling that explicitly is what makes Duffel usable for real operators.
- Stays extends the same grammar to hotels. Rather than a separate product with a different shape, hotels slot into the same offers-and-orders model. The abstraction was built to generalize.
The takeaway
Nine APIs is what it looks like when a company models a domain by its flow instead of its backend systems. The pattern to borrow from Duffel: name your APIs after the states your customer passes through, split resources where their lifecycle genuinely differs (offer request vs. offer), and make the unhappy paths — changes, cancellations — first-class instead of footnotes. Walk the flow on the Duffel provider page.