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#

Order lifecycleNormal path: draft, validating, price_check, booking, awaiting_payment, paid_hold, issuing, issued. If the price went up, price_check moves to awaiting_price_confirmation: accept continues to booking, decline ends as cancelled, no answer within 10 minutes ends as expired. From awaiting_payment, no payment before the hold expires ends as expired. A cancel request before payment ends as cancelled. An error in any step ends as failed. issued, expired, failed and cancelled are final.draftvalidatingprice_checkbookingawaiting_paymentpaid_holdissuingissuedawaiting_price_confirmationprice went upacceptexpiredno answerhold expired,no paymentcancelleddeclineor POST /cancel before paymentfailederror in any step(seats, holds released)
Dashed boxes wait for someone outside 1fly: you (price decision) or the payment provider. Red and green boxes are final.
  1. 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.
  2. Re-check price and seats with the supplier. If the price went up, the order waits in awaiting_price_confirmation.
  3. Hold seats at the airline. Supplier timeouts are retried automatically.
  4. Create the payment and wait for the provider until the hold expires. A declined card can be retried until then.
  5. Issue the ticket, exactly once. If the airline does not answer, 1fly asks the supplier for the status instead of issuing again.
  6. Capture the money, only after the ticket exists.
  7. 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#

StatusMeaningFinal
draftStored; the booking has not started yet.
validatingChecking passengers against the airline rules.
price_checkRe-checking price and seat availability with the supplier.
awaiting_price_confirmationThe price went up. Waiting for your accept or decline (10 minutes).
bookingHolding seats at the airline.
awaiting_paymentSeats held; waiting for the payment provider until the hold expires.
paid_holdPayment authorised (held, not yet captured).
issuingIssuing the ticket at the airline.
issuedTicket issued and payment captured. Final.Final
expiredNobody paid or answered the price change in time. Final.Final
failedStopped by a supplier, payment or system error. Final; see failureCode.Final
cancelledCancelled by you or because the new price was declined. Final.Final
voidedNot documented yetFinal

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:

Shell
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_SUSPENDED otherwise).
  • Live keys get 403 LIVE_MODE_UNAVAILABLE until real suppliers are connected.
  • scenario is accepted in test mode only.
  • Each plan has a monthly order quota (429 QUOTA_EXCEEDED). See Rate limits & plans.
API version v0.0.1 · Spec generated from source on 2026-11-22Changelog · Prices in so‘m (UZS)