> This page is for Agent Handler. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # Duffel **Authentication:** API key. See [Magic Link](/merge-agent-handler/features/magic-link) for the runtime auth flow. ## Sample use cases * Find round-trip flights from SFO to NRT next month under \$1500, with one stop or fewer. * Hold a booking for 24 hours on the cheapest morning flight to Boston tomorrow. * List Star Alliance flights between JFK and FRA on the 15th. ## Available Tools #### create\_batch\_offer\_request Create a batch flight search. Searches multiple airlines asynchronously and returns results as they come in. #### get\_batch\_offer\_request Get batch offer request status and results by ID. Poll until status is complete to get all offers. #### create\_offer\_request Search for flights by creating an offer request. Specify origin, destination, dates, passengers, and cabin class. Returns available offers. #### list\_offer\_requests List offer requests with pagination. Use cursor from page\_info for next page. #### get\_offer\_request Get offer request details by ID. Returns the original search parameters and any returned offers. #### list\_offers List offers for an offer request with pagination. Sort by total\_amount or total\_duration. Use cursor from page\_info for next page. #### get\_offer Get offer details by ID. Optionally return available services like bags and seats. #### update\_offer\_passenger Update passenger details on an offer. Set name, loyalty accounts, or identity documents before booking. #### create\_order\_cancellation Initiate cancellation of an order. Returns refund details and expiry. Must confirm with confirm\_order\_cancellation before expiry. #### list\_order\_cancellations List order cancellations with pagination. Optionally filter by order ID. Use cursor from page\_info for next page. #### get\_order\_cancellation Get order cancellation details by ID. Returns refund amount, status, and expiry time. #### confirm\_order\_cancellation Confirm an order cancellation. Must be confirmed before expiry. This action is irreversible. #### create\_order\_change\_request Request to change an order's flights. Specify slices to add and remove. Returns available change offers. #### get\_order\_change\_request Get order change request details by ID. Returns available change offers. #### list\_order\_change\_offers List change offers for an order change request. Compare prices and penalties. Use cursor from page\_info for next page. #### create\_order\_change Select an order change offer to proceed with. Must confirm with confirm\_order\_change before expiry. #### get\_order\_change Get order change details by ID. Returns change costs, new total, and confirmation status. #### confirm\_order\_change Confirm an order change. Optionally provide payment if the change costs extra. This action is irreversible. #### create\_order Book a flight by creating an order. Requires offer IDs, payment details, and passenger information. Use list\_offers to find offers first. #### list\_orders List orders with pagination. Filter by booking reference or awaiting payment status. Use cursor from page\_info for next page. #### get\_order Get order details by ID. Returns booking reference, passengers, slices, services, and payment status. #### update\_order Update order metadata. Only custom metadata can be changed after booking. #### create\_partial\_offer\_request Search for flights with partial offers. Returns offers grouped by slice, allowing mix-and-match of airlines per leg. #### get\_partial\_offer\_request Get partial offer request details by ID. Returns partial offers grouped by slice. #### create\_payment Create a payment for an order. Required for orders with awaiting\_payment status. Use get\_order to check payment status first. #### list\_payments List payments with pagination. Optionally filter by order ID. Use cursor from page\_info for next page. #### get\_payment Get payment details by ID. Returns amount, currency, type, and associated order. #### list\_airlines List airlines with pagination. Use cursor from page\_info for next page. #### get\_airline Get airline details by ID. Returns name, IATA code, logos, and conditions of carriage URL. #### list\_airports List airports with pagination. Use cursor from page\_info for next page. #### get\_airport Get airport details by ID. Returns name, IATA/ICAO codes, city, country, coordinates, and timezone. #### list\_aircraft List aircraft types with pagination. Use cursor from page\_info for next page. #### get\_aircraft Get aircraft type details by ID. Returns name and IATA code. #### list\_cities List cities with pagination. Use cursor from page\_info for next page. #### get\_city Get city details by ID. Returns name, IATA code, and country code. #### suggest\_places Search airports and cities by name. Returns matching places for use in flight searches. #### list\_loyalty\_programs List airline loyalty programmes with pagination. Use cursor from page\_info for next page. #### get\_loyalty\_program Get loyalty programme details by ID. Returns airline name and programme name. #### get\_seat\_maps Get seat maps for an offer. Returns cabin layouts with rows, seats, and availability for each flight segment.