Holding Orders and Paying Later
note
The ability to hold an order and pay for it later is not yet available for all airlines. We recommend using an offer from Duffel Airways or American Airlines to follow along with this guide.
What does it mean to hold an order?
What do you need to start?
tip
We've put together a Postman Collection that contains all of the requests you'll need to follow along with this guide.
Overview
You identify an offer that can be held and paid for later
You create an order with type
hold
You pay for your order before it expires
Identifying an offer that can be held and paid for later
payment_requirements.requires_instant_payment
set to false
.Shell
curl -X POST --compressed "https://api.duffel.com/air/offer_requests"-H "Accept-Encoding: gzip"-H "Accept: application/json"-H "Content-Type: application/json"-H "Duffel-Version: v1"-H "Authorization: Bearer$YOUR_ACCESS_TOKEN"-d '{"data": {"slices": [{"departure_date": "2021-06-21","destination": "LGW","origin": "LHR"}],"passengers": [{"type": "adult"}]}}'
JSON
"payment_requirements": {"requires_instant_payment": false,"price_guarantee_expires_at": "2021-06-01T23:59:59Z","payment_required_by": "2021-06-20T23:59:59Z"}
payment_requirements.requires_instant_payment
to determine whether the particular offer is eligible. This protects against any changes in the future and allows you to support future airlines that may have more complex rules.How does the price guarantee work?
price_guarantee_expires_at
is not null
the airline will hold the price of this offer - that is, the total_amount
- up to the specified time, providing you create a hold order to lock in the price quote.price_guarantee_expires_at
is null
the space on the flight will be reserved (until the payment_required_by
timestamp) but the price can change between booking and payment.Creating an order to hold the passenger’s seat
Set the
type
field tohold
Omit the
payments
key, as no payment takes place at the time of bookingOmit the
services
key, as it’s currently not possible to book services (for example extra bags) with hold orders
Shell
curl -X POST --compressed "https://api.duffel.com/air/orders"-H "Accept-Encoding: gzip"-H "Accept: application/json"-H "Content-Type: application/json"-H "Duffel-Version: v1"-H "Authorization: Bearer$YOUR_ACCESS_TOKEN"-d '{"data": {"type": "hold","selected_offers": ["'"$OFFER_ID"'"],"passengers": [{"phone_number": "+442080160508","email": "tony@example.com","born_on": "1980-07-24","title": "mr","gender": "m","family_name": "Stark","given_name": "Tony","id": "'"$PASSENGER_ID"'"}]}}
payment_status
field on the order:JSON
"payment_status": {"price_guarantee_expires_at": "2021-06-01T23:59:59Z","payment_required_by": "2021-06-20T23:59:59Z","awaiting_payment": true}
What happens if I don’t pay?
payment_required_by
, the space will be released by the airline and the awaiting_payment
status of the order will be set to false
. You will need to create a new order if you still wish to make a similar booking.How do I get the latest price?
Shell
curl -X GET --compressed "https://api.duffel.com/air/orders/$ORDER_ID"-H "Accept-Encoding: gzip"-H "Accept: application/json"-H "Content-Type: application/json"-H "Duffel-Version: v1"-H "Authorization: Bearer$YOUR_ACCESS_TOKEN"
price_changed
error. If you get this error you should retrieve the order to get the latest price.Paying for the order
order_id
and the latest order price.Shell
curl -X POST --compressed "https://api.duffel.com/air/payments"-H "Accept-Encoding: gzip"-H "Accept: application/json"-H "Content-Type: application/json"-H "Duffel-Version: v1"-H "Authorization: Bearer$YOUR_ACCESS_TOKEN"-d '{"data": {"order_id": "'"$ORDER_ID"'","payment": {"type": "balance","amount": "'"$ORDER_TOTAL_AMOUNT"'","currency": "'"$ORDER_TOTAL_CURRENCY"'"}}}
$ORDER_TOTAL_CURRENCY
) in ISO 4217 format — it should match the pending order's total_currency
— and the total amount ($ORDER_TOTAL_AMOUNT
) of the order, which should match the pending order's total_amount
.awaiting_payment
is now set to false
and that documents
have been issued for the order.JSON
{"payment_status": {"price_guarantee_expires_at": "2021-06-01T23:59:59Z","payment_required_by": "2021-06-20T23:59:59Z","awaiting_payment": false},"documents": [{"unique_identifier": "123-1230984567","type": "electronic_ticket"}]}
What happens if the price guarantee expires?
price_guarantee_expires_at
time may give you a new price.price_guarantee_expires_at
is always the guarantee that applies to the price at the time that the order is retrieved. This means that after we fetch a new price, the price_guarantee_expires_at
timestamp will be:updated to a new timestamp if the new price is guaranteed
updated to
null
if the new price doesn’t have a guarantee
payment_required_by
.What happens if the flight schedule changes?
schedule_changed
error when attempting to pay. This is to protect you from paying for a different itinerary than you were expecting at the time of booking.Keep Learning
Create Order Endpoint (see
type
,payments
, andservices
)Order Schema (see
payment_status
)