Concepts
Orders & booking lifecycle
How an order moves from creation to a ticket, where you need to act, and how to retry safely.
An order is one purchase: one flight offer, its passengers and a contact. POST /v1/orders stores it and starts the booking right away. Booking runs on our side as a durable workflow; your integration follows the status and acts at the two points that need a person: a price change and payment.
The flow#
- Check passengers against the airline rules: the passenger mix matches the offer, names are in Latin letters, ages fit the passenger type on the date of the last flight, each infant has an adult, passports are valid until the trip ends.
- Re-check price and seats with the supplier. If the price went up, the order waits in
awaiting_price_confirmation. - Hold seats at the airline. Supplier timeouts are retried automatically.
- Create the payment and wait for the provider until the hold expires. A declined card can be retried until then.
- Issue the ticket, exactly once. If the airline does not answer, 1fly asks the supplier for the status instead of issuing again.
- Capture the money, only after the ticket exists.
- E-mail the e-ticket. A delivery failure is recorded but does not fail the order.
If anything fails after seats are held, the payment hold is released and the booking cancelled at the airline, so money is never taken without a ticket.
Statuses#
| Status | Meaning | Final |
|---|---|---|
draft | Stored; the booking has not started yet. | |
validating | Checking passengers against the airline rules. | |
price_check | Re-checking price and seat availability with the supplier. | |
awaiting_price_confirmation | The price went up. Waiting for your accept or decline (10 minutes). | |
booking | Holding seats at the airline. | |
awaiting_payment | Seats held; waiting for the payment provider until the hold expires. | |
paid_hold | Payment authorised (held, not yet captured). | |
issuing | Issuing the ticket at the airline. | |
issued | Ticket issued and payment captured. Final. | Final |
expired | Nobody paid or answered the price change in time. Final. | Final |
failed | Stopped by a supplier, payment or system error. Final; see failureCode. | Final |
cancelled | Cancelled by you or because the new price was declined. Final. | Final |
voided | Not documented yet | Final |
GET /v1/orders/{id} returns the stored order plus, while it is still running, a live object from the workflow: currentStep, holdExpiresAt, payUrl, and newPriceMinor when a price change is waiting. Once an order is final, order.failureCode and order.failureStep say why it did not end as issued.
Following an order#
There are no outbound notifications to you yet. Poll GET /v1/orders/{id} every 2–3 seconds while the order is running and stop at a final status. Most test orders reach awaiting_payment within seconds.
Price changes#
When the re-check returns a higher price, the order enters awaiting_price_confirmation and live.newPriceMinor holds the new total in minor units. Show the traveller the old and new amount, then send their answer:
curl -X POST http://localhost:4000/v1/orders/$ORDER_ID/price-decision \
-H "Authorization: Bearer $ONEFLY_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"accept": true}'The response is 202 {"accepted": true}: the decision was delivered; the order continues to booking. accept: false cancels the order (PRICE_REJECTED). With no answer within 10 minutes the order ends as expired (PRICE_CONFIRMATION_TIMEOUT). Sending a decision in any other status returns 409 INVALID_STATE.
Warning
A price decision spends the traveller’s money. Only send accept: true after the traveller agreed to the new amount. Agents must ask a person.
Payment and the hold window#
When seats are held, the order enters awaiting_payment with holdExpiresAt: the earlier of 15 minutes after the hold and the airline’s own time limit. Send the traveller to live.payUrl. The payment provider reports the result through a webhook; a declined card leaves the order waiting, so the traveller can try another card. If nothing is paid by holdExpiresAt, the seats are released and the order ends as expired (PAYMENT_TIMEOUT).
Cancelling#
POST /v1/orders/{id}/cancel with an optional {"reason": "…"} works before payment: in validating, price_check, awaiting_price_confirmation, booking and awaiting_payment. Any seat hold is cancelled and any payment authorisation released; the order ends as cancelled. After payment it returns 409 INVALID_STATE.
Idempotency keys#
Every POST /v1/orders carries an idempotencyKey (8–100 characters: letters, digits and ._:-). Keys are unique per account:
- The first request with a key creates the order:
"created": true. - Any later request with the same key returns that same order with
"created": false, and starts nothing new.
So when a request times out or you are not sure it arrived, retry it with the same key. Use a new key for each purchase, for example your own checkout or cart id.
Note
The second request is not compared with the first. If you change the passengers and reuse the key, you still get the original order. Generate a new key when the traveller changes anything.
Limits on creating orders#
- The account must be active (
403 ACCOUNT_SUSPENDEDotherwise). - Live keys get
403 LIVE_MODE_UNAVAILABLEuntil real suppliers are connected. scenariois accepted in test mode only.- Each plan has a monthly order quota (
429 QUOTA_EXCEEDED). See Rate limits & plans.