Authenticate by including the header Duffel-Version (current stable version string, e.g. 'v2') and Authorization: Bearer <live_or_test_token> on every request to https://api.duffel.com.
Create an offer request: POST /air/offer_requests with data.slices[] (origin, destination, departure_date), data.passengers[] (type: 'adult'|'child'|'infant_without_seat'), and data.cabin_class; set return_offers: true to get offers inline or poll GET /air/offer_requests/{id} until done.
Each offer in data.offers[] has a unique id, total_amount, total_currency, slices[], and expires_at — record expires_at; you must convert the offer to an order before that timestamp.
Optionally call GET /air/offers/{offer_id}?return_available_services=true to fetch ancillary services (seat selection, bags) before ordering.
Create the order: POST /air/orders with data.selected_offers: [offer_id], data.passengers[] (full name, date_of_birth, gender, email, phone, identity_documents[] for international), and data.payments[] specifying type 'balance' (Duffel balance) or 'arc_bsp_cash'.
On success you receive an order object with id, booking_reference (the airline PNR visible to airport staff), and documents[] if ticketing was instant; poll GET /air/orders/{id} until documents are present for carriers that ticket asynchronously.
Known gotchas
expires_at on offers is strict — Duffel will reject order creation with a 422 after that time; build in a buffer and re-search if the offer is close to expiry.
Duffel operates in live and test modes controlled by the token prefix (duffel_test_ vs duffel_live_); test mode returns real-looking data but does not issue actual tickets — never mix token types across environments.
The balance payment type draws from your Duffel account balance; ensure sufficient funds before automating bookings at scale or the order creation will fail mid-flow with an insufficient_balance error.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp