For a full-order cancellation, POST /air/order_cancellations with the order_id and no passenger filter; inspect the live_mode boolean and confirm the response includes a refund_amount and refund_to field before confirming.
For partial passenger refunds (not all passengers on the booking cancel), first check whether the airline supports partial order cancellation via the order's available_actions field.
If partial cancel is unsupported by the airline, initiate an order change to remove the cancelling passenger's slices; the change_total_amount negative value represents the refund for their removed segments.
If partial cancel is supported, POST the order_cancellation with a passengers filter; parse the response to confirm that only the specified passengers' coupons are refunded.
Record the net refund_amount and reconcile it against the original per-passenger fare stored in your database — the breakdown must account for taxes (some taxes are per-person refundable, others are non-refundable service charges).
Notify only the affected passengers of the refund; do not modify itinerary records for passengers who remain on the booking.
Known gotchas
Duffel expresses refund amounts as positive numbers in the order_cancellation object even though they represent money flowing back to the customer — ensure your accounting logic does not double-sign the amount.
Taxes refundability varies by country and tax type: some government taxes (e.g., US departure tax) are refundable on cancellation; carrier-imposed fees (e.g., fuel surcharges) are typically non-refundable per the fare rules — do not assume all taxes are returned.
The order_cancellation object is created in a pending state and transitions to confirmed once the airline processes it — poll GET /air/order_cancellations/{id} until confirmed before marking the booking as cancelled in your system.
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