API reference
Orders
Create orders and follow them to a ticket.
Create an order#
Stores the order and starts booking: passenger checks, price re-check, seat hold, payment, ticketing. Returns at once; follow progress with GET /v1/orders/{id} or the timeline. Safe to retry: the same idempotencyKey returns the first order. All validation problems are returned together in issues. scenario is accepted in test mode only.
Request body application/json required
| Field | Type | Description |
|---|---|---|
offerrequired | object | |
offerId (in offer)required | string | length: 1–100 |
supplier (in offer)required | string | length: 1–50 |
searchId (in offer)required | string | length: 1–100 |
mix (in offer)required | object | |
adults (in offer.mix)required | integer | range: 1–9 |
children (in offer.mix)required | integer | range: 0–8 |
infants (in offer.mix)required | integer | range: 0–9 |
segments (in offer)required | array<object> | items: 1–8 |
from (in offer.segments)required | string | pattern: ^[A-Z]{3}$ |
to (in offer.segments)required | string | pattern: ^[A-Z]{3}$ |
departAt (in offer.segments)required | string | pattern: ^\d{4}-\d{2}-\d{2}T([01]\d|2[0-3]):[0-5]\d$ |
arriveAt (in offer.segments)required | string | pattern: ^\d{4}-\d{2}-\d{2}T([01]\d|2[0-3]):[0-5]\d$ |
carrier (in offer.segments)required | string | pattern: ^[A-Z0-9]{2,3}$ |
flightNumber (in offer.segments)required | string | pattern: ^[A-Z0-9]{2,3}\d{1,4}[A-Z]?$ |
fareBrand (in offer) | string | length: 1–40default: "Standard" |
price (in offer)required | object | |
amountMinor (in offer.price)required | integer | ≤ 1000000000000> 0 |
currency (in offer.price)required | string | one of: "UZS", "USD", "EUR" |
passengersrequired | array<object> | items: 1–9 |
type (in passengers)required | string | one of: "ADT", "CHD", "INF" |
firstName (in passengers)required | string | pattern: ^[A-Za-z]+(?:[ '-][A-Za-z]+)*$length: 1–60 |
lastName (in passengers)required | string | pattern: ^[A-Za-z]+(?:[ '-][A-Za-z]+)*$length: 1–60 |
birthDate (in passengers)required | string | pattern: ^\d{4}-\d{2}-\d{2}$ |
gender (in passengers)required | string | one of: "M", "F" |
citizenship (in passengers)required | string | pattern: ^[A-Z]{2}$ |
documentNumber (in passengers)required | string | pattern: ^[A-Z0-9]{5,20}$ |
documentExpiry (in passengers)required | string | pattern: ^\d{4}-\d{2}-\d{2}$ |
contactrequired | object | |
email (in contact)required | string (email) | pattern: ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$max length: 254 |
phone (in contact)required | string | pattern: ^\+[1-9]\d{6,14}$ |
channel | string | one of: "web", "api", "mcp", "admin", "job"default: "web" |
accountId | string | |
idempotencyKeyrequired | string | pattern: ^[A-Za-z0-9._:-]{8,100}$ |
scenario | string | one of: "happy", "flaky_supplier", "price_up", "sold_out", "payment_declined", "payment_timeout", "issue_fail", "issue_unknown", "notify_fail" |
{
"idempotencyKey": "checkout-7f3a9c2e",
"contact": {
"email": "aziz@example.uz",
"phone": "+998901234567"
},
"offer": {
"offerId": "off_9d1c",
"supplier": "hy-ndc",
"searchId": "srch_51ab",
"fareBrand": "Standard",
"mix": {
"adults": 1,
"children": 0,
"infants": 0
},
"price": {
"amountMinor": 398000000,
"currency": "UZS"
},
"segments": [
{
"from": "TAS",
"to": "IST",
"departAt": "2027-03-12T07:40",
"arriveAt": "2027-03-12T10:05",
"carrier": "HY",
"flightNumber": "HY271"
},
{
"from": "IST",
"to": "TAS",
"departAt": "2027-03-19T13:20",
"arriveAt": "2027-03-19T19:30",
"carrier": "HY",
"flightNumber": "HY272"
}
]
},
"passengers": [
{
"type": "ADT",
"firstName": "AZIZ",
"lastName": "KARIMOV",
"birthDate": "1990-04-02",
"gender": "M",
"citizenship": "UZ",
"documentNumber": "FA1234567",
"documentExpiry": "2030-01-01"
}
],
"scenario": "happy"
}Code samples
curl -X POST 'https://api.1fly.uz/v1/orders' \
-H "Authorization: Bearer $ONEFLY_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"idempotencyKey": "checkout-7f3a9c2e",
"contact": {
"email": "aziz@example.uz",
"phone": "+998901234567"
},
"offer": {
"offerId": "off_9d1c",
"supplier": "hy-ndc",
"searchId": "srch_51ab",
"fareBrand": "Standard",
"mix": {
"adults": 1,
"children": 0,
"infants": 0
},
"price": {
"amountMinor": 398000000,
"currency": "UZS"
},
"segments": [
{
"from": "TAS",
"to": "IST",
"departAt": "2027-03-12T07:40",
"arriveAt": "2027-03-12T10:05",
"carrier": "HY",
"flightNumber": "HY271"
},
{
"from": "IST",
"to": "TAS",
"departAt": "2027-03-19T13:20",
"arriveAt": "2027-03-19T19:30",
"carrier": "HY",
"flightNumber": "HY272"
}
]
},
"passengers": [
{
"type": "ADT",
"firstName": "AZIZ",
"lastName": "KARIMOV",
"birthDate": "1990-04-02",
"gender": "M",
"citizenship": "UZ",
"documentNumber": "FA1234567",
"documentExpiry": "2030-01-01"
}
],
"scenario": "happy"
}'const res = await fetch('https://api.1fly.uz/v1/orders', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.ONEFLY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"idempotencyKey": "checkout-7f3a9c2e",
"contact": {
"email": "aziz@example.uz",
"phone": "+998901234567"
},
"offer": {
"offerId": "off_9d1c",
"supplier": "hy-ndc",
"searchId": "srch_51ab",
"fareBrand": "Standard",
"mix": {
"adults": 1,
"children": 0,
"infants": 0
},
"price": {
"amountMinor": 398000000,
"currency": "UZS"
},
"segments": [
{
"from": "TAS",
"to": "IST",
"departAt": "2027-03-12T07:40",
"arriveAt": "2027-03-12T10:05",
"carrier": "HY",
"flightNumber": "HY271"
},
{
"from": "IST",
"to": "TAS",
"departAt": "2027-03-19T13:20",
"arriveAt": "2027-03-19T19:30",
"carrier": "HY",
"flightNumber": "HY272"
}
]
},
"passengers": [
{
"type": "ADT",
"firstName": "AZIZ",
"lastName": "KARIMOV",
"birthDate": "1990-04-02",
"gender": "M",
"citizenship": "UZ",
"documentNumber": "FA1234567",
"documentExpiry": "2030-01-01"
}
],
"scenario": "happy"
}),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message} (request ${data.error.requestId})`);import os
import requests
resp = requests.post(
"https://api.1fly.uz/v1/orders",
headers={"Authorization": f"Bearer {os.environ['ONEFLY_API_KEY']}"},
json={
"idempotencyKey": "checkout-7f3a9c2e",
"contact": {
"email": "aziz@example.uz",
"phone": "+998901234567",
},
"offer": {
"offerId": "off_9d1c",
"supplier": "hy-ndc",
"searchId": "srch_51ab",
"fareBrand": "Standard",
"mix": {
"adults": 1,
"children": 0,
"infants": 0,
},
"price": {
"amountMinor": 398000000,
"currency": "UZS",
},
"segments": [
{
"from": "TAS",
"to": "IST",
"departAt": "2027-03-12T07:40",
"arriveAt": "2027-03-12T10:05",
"carrier": "HY",
"flightNumber": "HY271",
},
{
"from": "IST",
"to": "TAS",
"departAt": "2027-03-19T13:20",
"arriveAt": "2027-03-19T19:30",
"carrier": "HY",
"flightNumber": "HY272",
},
],
},
"passengers": [
{
"type": "ADT",
"firstName": "AZIZ",
"lastName": "KARIMOV",
"birthDate": "1990-04-02",
"gender": "M",
"citizenship": "UZ",
"documentNumber": "FA1234567",
"documentExpiry": "2030-01-01",
},
],
"scenario": "happy",
},
timeout=30,
)
data = resp.json()
if not resp.ok:
raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")Responses
200Order created (or the existing order for this idempotency key).
{
"order": {
"id": "ord_0d6c3f8a2b9e4c1d8f7a6b5c4d3e2f10",
"reference": "K7QX2P",
"status": "draft"
},
"created": true
}400Validation failed.
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "VALIDATION_FAILED",
"message": "Some fields are missing or invalid.",
"requestId": "5b0c…",
"issues": [
{
"path": "passengers.0.lastName",
"code": "invalid_format",
"message": "Last name: use Latin letters A–Z exactly as in the passport (spaces, hyphens and apostrophes allowed, no accents or Cyrillic)."
}
]
}
}401Missing or invalid credentials.
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "string",
"message": "string",
"requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
"issues": [
{
"path": "passengers.0.lastName",
"code": "string",
"message": "string"
}
]
}
}403Account suspended, missing scope, or live mode not yet available.
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "string",
"message": "string",
"requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
"issues": [
{
"path": "passengers.0.lastName",
"code": "string",
"message": "string"
}
]
}
}429Monthly order quota or rate limit reached.
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "string",
"message": "string",
"requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
"issues": [
{
"path": "passengers.0.lastName",
"code": "string",
"message": "string"
}
]
}
}500Unexpected error on our side; quote the requestId.
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "string",
"message": "string",
"requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
"issues": [
{
"path": "passengers.0.lastName",
"code": "string",
"message": "string"
}
]
}
}List orders#
Newest first, for the authenticated account.
Parameters
Query parameters
| Name | Type | Description |
|---|---|---|
status | string | one of: "draft", "validating", "price_check", "awaiting_price_confirmation", "booking", "awaiting_payment", "paid_hold", "issuing", "issued", "expired", "failed", "cancelled" |
limit | integer | range: 1–200default: 50 |
offset | integer | range: 0–9007199254740991default: 0 |
Code samples
curl 'https://api.1fly.uz/v1/orders' \
-H "Authorization: Bearer $ONEFLY_API_KEY"const res = await fetch('https://api.1fly.uz/v1/orders', {
headers: {
Authorization: `Bearer ${process.env.ONEFLY_API_KEY}`,
},
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message} (request ${data.error.requestId})`);import os
import requests
resp = requests.get(
"https://api.1fly.uz/v1/orders",
headers={"Authorization": f"Bearer {os.environ['ONEFLY_API_KEY']}"},
timeout=30,
)
data = resp.json()
if not resp.ok:
raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")Responses
200A page of orders.
{
"rows": [
{
"id": "ord_0d6c3f8a2b9e4c1d8f7a6b5c4d3e2f10",
"reference": "K7QX2P",
"status": "awaiting_payment",
"mode": "test",
"channel": "api",
"accountId": "acc_3e1f…",
"origin": "TAS",
"destination": "IST",
"departDate": "2027-03-12",
"returnDate": "2027-03-19",
"adults": 1,
"children": 0,
"infants": 0,
"supplier": "hy-ndc",
"amountMinor": 398000000,
"currency": "UZS",
"pnr": "MVTVRK",
"failureCode": null,
"failureStep": null,
"holdExpiresAt": "2026-11-17T10:15:00.000Z",
"createdAt": "2026-11-17T10:00:00.000Z",
"updatedAt": "2026-11-17T10:00:04.000Z",
"issuedAt": null
}
],
"total": 1
}401Missing or invalid credentials.
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "string",
"message": "string",
"requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
"issues": [
{
"path": "passengers.0.lastName",
"code": "string",
"message": "string"
}
]
}
}403The key lacks a required scope, or the account is suspended.
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "string",
"message": "string",
"requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
"issues": [
{
"path": "passengers.0.lastName",
"code": "string",
"message": "string"
}
]
}
}500Unexpected error on our side; quote the requestId.
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "string",
"message": "string",
"requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
"issues": [
{
"path": "passengers.0.lastName",
"code": "string",
"message": "string"
}
]
}
}Get an order#
Order, passengers (passport numbers masked), payments, tickets and, while the booking runs, its live state (current step, hold deadline, payment link, new price awaiting confirmation).
Parameters
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Order id, e.g. ord_7c2f… (32 hex characters). pattern: ^ord_[a-f0-9]{32}$ |
Code samples
curl 'https://api.1fly.uz/v1/orders/ord_0d6c3f8a2b9e4c1d8f7a6b5c4d3e2f10' \
-H "Authorization: Bearer $ONEFLY_API_KEY"const res = await fetch('https://api.1fly.uz/v1/orders/ord_0d6c3f8a2b9e4c1d8f7a6b5c4d3e2f10', {
headers: {
Authorization: `Bearer ${process.env.ONEFLY_API_KEY}`,
},
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message} (request ${data.error.requestId})`);import os
import requests
resp = requests.get(
"https://api.1fly.uz/v1/orders/ord_0d6c3f8a2b9e4c1d8f7a6b5c4d3e2f10",
headers={"Authorization": f"Bearer {os.environ['ONEFLY_API_KEY']}"},
timeout=30,
)
data = resp.json()
if not resp.ok:
raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")Responses
200The order.
{
"order": {
"id": "ord_0d6c3f8a2b9e4c1d8f7a6b5c4d3e2f10",
"reference": "K7QX2P",
"status": "awaiting_payment",
"mode": "test",
"channel": "api",
"accountId": "acc_3e1f…",
"origin": "TAS",
"destination": "IST",
"departDate": "2027-03-12",
"returnDate": "2027-03-19",
"adults": 1,
"children": 0,
"infants": 0,
"supplier": "hy-ndc",
"amountMinor": 398000000,
"currency": "UZS",
"pnr": "MVTVRK",
"failureCode": null,
"failureStep": null,
"holdExpiresAt": "2026-11-17T10:15:00.000Z",
"createdAt": "2026-11-17T10:00:00.000Z",
"updatedAt": "2026-11-17T10:00:04.000Z",
"issuedAt": null
},
"passengers": [],
"payments": [],
"tickets": [],
"live": {
"status": "awaiting_payment",
"currentStep": "await_payment",
"pnr": "MVTVRK",
"holdExpiresAt": "2026-11-17T10:15:00.000Z",
"payUrl": "https://pay.example/…",
"newPriceMinor": null,
"failure": null,
"tickets": []
}
}401Missing or invalid credentials.
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "string",
"message": "string",
"requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
"issues": [
{
"path": "passengers.0.lastName",
"code": "string",
"message": "string"
}
]
}
}403The key lacks a required scope, or the account is suspended.
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "string",
"message": "string",
"requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
"issues": [
{
"path": "passengers.0.lastName",
"code": "string",
"message": "string"
}
]
}
}404No such order in this account.
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "string",
"message": "string",
"requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
"issues": [
{
"path": "passengers.0.lastName",
"code": "string",
"message": "string"
}
]
}
}500Unexpected error on our side; quote the requestId.
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "string",
"message": "string",
"requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
"issues": [
{
"path": "passengers.0.lastName",
"code": "string",
"message": "string"
}
]
}
}Get the order timeline#
The full chronology: every attempt of every step (started, succeeded, failed with error code, category and hint), status changes, webhooks and decisions, oldest first, plus a per-step summary.
Parameters
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Order id, e.g. ord_7c2f… (32 hex characters). pattern: ^ord_[a-f0-9]{32}$ |
Code samples
curl 'https://api.1fly.uz/v1/orders/ord_0d6c3f8a2b9e4c1d8f7a6b5c4d3e2f10/timeline' \
-H "Authorization: Bearer $ONEFLY_API_KEY"const res = await fetch('https://api.1fly.uz/v1/orders/ord_0d6c3f8a2b9e4c1d8f7a6b5c4d3e2f10/timeline', {
headers: {
Authorization: `Bearer ${process.env.ONEFLY_API_KEY}`,
},
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message} (request ${data.error.requestId})`);import os
import requests
resp = requests.get(
"https://api.1fly.uz/v1/orders/ord_0d6c3f8a2b9e4c1d8f7a6b5c4d3e2f10/timeline",
headers={"Authorization": f"Bearer {os.environ['ONEFLY_API_KEY']}"},
timeout=30,
)
data = resp.json()
if not resp.ok:
raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")Responses
200Timeline.
{
"orderId": "ord_0d6c3f8a2b9e4c1d8f7a6b5c4d3e2f10",
"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
}
}
],
"steps": [
{
"step": "book_seats",
"label": "Hold seats at the airline",
"state": "succeeded",
"attempts": 3,
"failures": 2,
"totalDurationMs": 757,
"lastError": {
"code": "SUPPLIER_TIMEOUT",
"category": "supplier",
"message": "…",
"hint": "…"
}
}
]
}401Missing or invalid credentials.
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "string",
"message": "string",
"requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
"issues": [
{
"path": "passengers.0.lastName",
"code": "string",
"message": "string"
}
]
}
}403The key lacks a required scope, or the account is suspended.
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "string",
"message": "string",
"requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
"issues": [
{
"path": "passengers.0.lastName",
"code": "string",
"message": "string"
}
]
}
}500Unexpected error on our side; quote the requestId.
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "string",
"message": "string",
"requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
"issues": [
{
"path": "passengers.0.lastName",
"code": "string",
"message": "string"
}
]
}
}Accept or decline a price change#
Only while the order is awaiting_price_confirmation. Declining cancels the order before any seats are held.
Parameters
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Order id, e.g. ord_7c2f… (32 hex characters). pattern: ^ord_[a-f0-9]{32}$ |
Request body application/json required
| Field | Type | Description |
|---|---|---|
acceptrequired | boolean |
{
"accept": true
}Code samples
curl -X POST 'https://api.1fly.uz/v1/orders/ord_0d6c3f8a2b9e4c1d8f7a6b5c4d3e2f10/price-decision' \
-H "Authorization: Bearer $ONEFLY_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"accept": true
}'const res = await fetch('https://api.1fly.uz/v1/orders/ord_0d6c3f8a2b9e4c1d8f7a6b5c4d3e2f10/price-decision', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.ONEFLY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"accept": true
}),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message} (request ${data.error.requestId})`);import os
import requests
resp = requests.post(
"https://api.1fly.uz/v1/orders/ord_0d6c3f8a2b9e4c1d8f7a6b5c4d3e2f10/price-decision",
headers={"Authorization": f"Bearer {os.environ['ONEFLY_API_KEY']}"},
json={
"accept": True,
},
timeout=30,
)
data = resp.json()
if not resp.ok:
raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")Responses
202Decision sent.
{
"accepted": true
}401Missing or invalid credentials.
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "string",
"message": "string",
"requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
"issues": [
{
"path": "passengers.0.lastName",
"code": "string",
"message": "string"
}
]
}
}403The key lacks a required scope, or the account is suspended.
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "string",
"message": "string",
"requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
"issues": [
{
"path": "passengers.0.lastName",
"code": "string",
"message": "string"
}
]
}
}409The order is not waiting for a price decision.
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "string",
"message": "string",
"requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
"issues": [
{
"path": "passengers.0.lastName",
"code": "string",
"message": "string"
}
]
}
}500Unexpected error on our side; quote the requestId.
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "string",
"message": "string",
"requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
"issues": [
{
"path": "passengers.0.lastName",
"code": "string",
"message": "string"
}
]
}
}Cancel an order#
Before payment only. Any seat hold is cancelled at the airline and any payment authorisation released.
Parameters
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Order id, e.g. ord_7c2f… (32 hex characters). pattern: ^ord_[a-f0-9]{32}$ |
Request body application/json required
| Field | Type | Description |
|---|---|---|
reason | string | max length: 300 |
{
"reason": "Traveller changed plans"
}Code samples
curl -X POST 'https://api.1fly.uz/v1/orders/ord_0d6c3f8a2b9e4c1d8f7a6b5c4d3e2f10/cancel' \
-H "Authorization: Bearer $ONEFLY_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"reason": "Traveller changed plans"
}'const res = await fetch('https://api.1fly.uz/v1/orders/ord_0d6c3f8a2b9e4c1d8f7a6b5c4d3e2f10/cancel', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.ONEFLY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"reason": "Traveller changed plans"
}),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message} (request ${data.error.requestId})`);import os
import requests
resp = requests.post(
"https://api.1fly.uz/v1/orders/ord_0d6c3f8a2b9e4c1d8f7a6b5c4d3e2f10/cancel",
headers={"Authorization": f"Bearer {os.environ['ONEFLY_API_KEY']}"},
json={
"reason": "Traveller changed plans",
},
timeout=30,
)
data = resp.json()
if not resp.ok:
raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")Responses
202Cancellation requested.
{
"accepted": true
}401Missing or invalid credentials.
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "string",
"message": "string",
"requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
"issues": [
{
"path": "passengers.0.lastName",
"code": "string",
"message": "string"
}
]
}
}403The key lacks a required scope, or the account is suspended.
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "string",
"message": "string",
"requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
"issues": [
{
"path": "passengers.0.lastName",
"code": "string",
"message": "string"
}
]
}
}409Too late to cancel (payment already held or order finished).
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "string",
"message": "string",
"requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
"issues": [
{
"path": "passengers.0.lastName",
"code": "string",
"message": "string"
}
]
}
}500Unexpected error on our side; quote the requestId.
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
code (in error)required | string | Stable machine-readable code, e.g. VALIDATION_FAILED. |
message (in error)required | string | Human-readable explanation. |
requestId (in error)required | string | Quote this to support; also in the x-request-id header and the request log. |
issues (in error) | array<object> | Present for VALIDATION_FAILED: one entry per problem. |
path (in error.issues) | string | Example: passengers.0.lastName |
code (in error.issues) | string | |
message (in error.issues) | string |
{
"error": {
"code": "string",
"message": "string",
"requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
"issues": [
{
"path": "passengers.0.lastName",
"code": "string",
"message": "string"
}
]
}
}