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:
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#
{
"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#
| type | Written by | Meaning |
|---|---|---|
order.created | API | The order was stored. data: offerId, supplier, scenario, requestId. |
order.status_changed | Workflow | The order moved to a new status. |
step.started | Step recorder | An attempt of a step began. attempt = 1, 2, … |
step.succeeded | Step recorder | That attempt finished. durationMs is set. |
step.failed | Step recorder | That attempt failed. error has code, category, retryable and hint; data.willRetry says whether another attempt follows. |
price.confirmation_requested | Workflow | The price went up; the order waits for a decision. data has the new amount. |
price.decision | Workflow | The traveller accepted or declined. data.accept. |
signal.price_decision | API | Your POST /price-decision request was received. |
signal.cancel | API | Your POST /cancel request was received. |
signal.issue | API | Your POST /issue request was received (manual-issue orders). |
issue.awaiting_instruction | Workflow | A manual-issue order is paid and waits for POST /issue. |
issue.requested | Workflow | The issue instruction arrived; ticketing starts. |
signal.void | API | Your POST /void request was received; the void runs in its own workflow. |
void.started | Void workflow | Voiding the tickets. data: tickets, reason. |
payment.webhook_received | API (webhook) | The payment provider reported held or declined. Event id is mockpay:<providerEventId>. |
order.attention_needed | Workflow | Something needs a person, e.g. the e-ticket e-mail failed after retries. The order stays issued. |
Steps#
| Step | Label | Kind |
|---|---|---|
validate_passengers | Check passenger details | Purchase funnel |
recheck_price | Re-check price and seats | Purchase funnel |
book_seats | Hold seats at the airline | Purchase funnel |
create_payment | Create payment | Purchase funnel |
await_payment | Wait for payment | Purchase funnel |
issue_ticket | Issue ticket | Purchase funnel |
check_issue_status | Check issue status | Status check or compensation (only when it runs) |
capture_payment | Capture payment | Purchase funnel |
send_ticket | Send e-ticket | Purchase funnel |
release_payment | Release payment hold | Status check or compensation (only when it runs) |
cancel_booking | Cancel booking | Status check or compensation (only when it runs) |
void_ticket | Void ticket | Status check or compensation (only when it runs) |
refund_payment | Refund payment | Status 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.
| Category | Who must act | What it means |
|---|---|---|
customer | The traveller | Entered something wrong, declined a price, did not pay in time or cancelled. Show the hint and let them fix it. |
supplier | The airline or supplier | Seats, price or ticketing failed on the supplier side. Offer another flight or retry later. |
payment | The payment provider or bank | The card or wallet was declined. The traveller can try another method before the hold expires. |
system | 1fly | Our 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
requestIdfromdata.
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.