Concepts

Chronology (order timeline)

The complete, append-only history of an order. Read it to see what happened, how often a step was retried, and who must act.

Every order has a timeline: an append-only list of events written while it is booked. Nothing is ever updated or deleted, so it is the full story of the purchase, including every failed attempt. Fetch it with:

Shell
curl -s http://localhost:4000/v1/orders/$ORDER_ID/timeline -H "Authorization: Bearer $ONEFLY_API_KEY"

The response has two parts: events, oldest first, and steps, one summary row per step.

Events#

JSON
{
  "seq": 41,
  "occurredAt": "2026-11-17T10:00:01.245Z",
  "type": "step.failed",
  "step": "book_seats",
  "status": "failed",
  "attempt": 1,
  "durationMs": 252,
  "actorType": "system",
  "channel": "api",
  "message": "Hold seats at the airline failed: Supplier did not answer within 30 s",
  "errorCode": "SUPPLIER_TIMEOUT",
  "errorCategory": "supplier",
  "errorRetryable": true,
  "errorHint": "The supplier did not answer in time; retried automatically.",
  "data": { "willRetry": true }
}
Field Meaning
type What happened (table below).
step The booking step it belongs to, or null for order-level events.
status started, succeeded, failed or info.
attempt 1 for the first try of a step, 2 for the first retry, and so on.
durationMs How long the attempt took (on succeeded and failed).
actorType Who caused it: system, provider (payment provider), traveller, api_key, agent (MCP), agency_member, support.
channel Where the order came from: api, mcp, web, admin, job.
errorCode, errorCategory, errorRetryable, errorHint Set on failures. The code is from the error catalogue.
data Extra details: amounts, the payment id, the requestId of the API call that caused the event, willRetry.

Event types#

typeWritten byMeaning
order.createdAPIThe order was stored. data: offerId, supplier, scenario, requestId.
order.status_changedWorkflowThe order moved to a new status.
step.startedStep recorderAn attempt of a step began. attempt = 1, 2, …
step.succeededStep recorderThat attempt finished. durationMs is set.
step.failedStep recorderThat attempt failed. error has code, category, retryable and hint; data.willRetry says whether another attempt follows.
price.confirmation_requestedWorkflowThe price went up; the order waits for a decision. data has the new amount.
price.decisionWorkflowThe traveller accepted or declined. data.accept.
signal.price_decisionAPIYour POST /price-decision request was received.
signal.cancelAPIYour POST /cancel request was received.
signal.issueAPIYour POST /issue request was received (manual-issue orders).
issue.awaiting_instructionWorkflowA manual-issue order is paid and waits for POST /issue.
issue.requestedWorkflowThe issue instruction arrived; ticketing starts.
signal.voidAPIYour POST /void request was received; the void runs in its own workflow.
void.startedVoid workflowVoiding the tickets. data: tickets, reason.
payment.webhook_receivedAPI (webhook)The payment provider reported held or declined. Event id is mockpay:<providerEventId>.
order.attention_neededWorkflowSomething needs a person, e.g. the e-ticket e-mail failed after retries. The order stays issued.

Steps#

StepLabelKind
validate_passengersCheck passenger detailsPurchase funnel
recheck_priceRe-check price and seatsPurchase funnel
book_seatsHold seats at the airlinePurchase funnel
create_paymentCreate paymentPurchase funnel
await_paymentWait for paymentPurchase funnel
issue_ticketIssue ticketPurchase funnel
check_issue_statusCheck issue statusStatus check or compensation (only when it runs)
capture_paymentCapture paymentPurchase funnel
send_ticketSend e-ticketPurchase funnel
release_paymentRelease payment holdStatus check or compensation (only when it runs)
cancel_bookingCancel bookingStatus check or compensation (only when it runs)
void_ticketVoid ticketStatus check or compensation (only when it runs)
refund_paymentRefund paymentStatus check or compensation (only when it runs)

Each row in steps folds the events of one step into: state (succeeded, failed, running, not_reached, skipped), attempts, failures, first start and last finish, total duration and lastError. Funnel steps always appear, so you can see where an order stopped (not_reached after that point). check_issue_status, release_payment and cancel_booking appear only when they ran.

Reading retries#

A step that failed and then worked looks like this in events:

attempt type errorCode
1 step.started
1 step.failed SUPPLIER_TIMEOUT (data.willRetry: true)
2 step.started
2 step.failed SUPPLIER_TIMEOUT (data.willRetry: true)
3 step.started
3 step.succeeded

and as one row in steps: state: "succeeded", attempts: 3, failures: 2. Retries of retryable errors are automatic; you do nothing. A failure without a later success, and with a non-retryable code, is what stopped the order: it matches order.failureCode.

A declined payment is the one failure that waits for the traveller rather than retrying on its own: await_payment gets a step.failed with PAYMENT_DECLINED and willRetry: true, and the step stays running until another payment arrives or the hold expires.

Who must act: error categories#

Every error carries a category that tells you who has to do something about it. Group by it in your support tools.

CategoryWho must actWhat it means
customerThe travellerEntered something wrong, declined a price, did not pay in time or cancelled. Show the hint and let them fix it.
supplierThe airline or supplierSeats, price or ticketing failed on the supplier side. Offer another flight or retry later.
paymentThe payment provider or bankThe card or wallet was declined. The traveller can try another method before the hold expires.
system1flyOur bug or infrastructure. Retryable automatically; contact support with the request id if it persists.

Typical handling:

  • customer: show the hint to the traveller and let them fix the data, answer, or pay. Passenger data errors need a new order with corrected data.
  • supplier: offer another flight (SOLD_OUT) or try again later (ISSUE_REJECTED). Timeouts are retried for you.
  • payment: let the traveller try another card before holdExpiresAt.
  • system: our side. Contact support with the order id and the requestId from data.

Note

Event ids are deterministic for retried writers, and repeated provider callbacks share one id, so the timeline never contains duplicates even when we retry internally or a provider sends the same webhook twice.

API version v0.0.1 · Spec generated from source on 2026-11-22Changelog · Prices in so‘m (UZS)