> ## Documentation Index
> Fetch the complete documentation index at: https://docs.travelbase.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Orders
> Create, manage, and ticket flight orders.
Orders represent a confirmed booking created from a selected offer. Once ticketed, an order contains issued tickets and becomes immutable.
Travelbase abstracts airline supplier complexity behind a unified, stable order lifecycle.
Convert an offer into a pending order.
Issue tickets and finalize the booking.
***
## Order lifecycle
Orders progress through a defined lifecycle:
| Status | Description |
| ------------ | --------------------------------- |
| `PENDING` | Order created, awaiting ticketing |
| `PROCESSING` | Ticket issuance in progress |
| `TICKETED` | Tickets successfully issued |
| `FAILED` | Ticketing failed |
| `CANCELED` | Order canceled before ticketing |
| `REFUNDED` | Order refunded after ticketing |
Orders remain editable only while in the `PENDING` state.
Once ticketed, the order becomes immutable.
***
***
## Order state machine
Orders progress through a deterministic lifecycle managed by Travelbase. Each state represents a distinct phase in the booking and ticketing process.
Once an order reaches a terminal state, no further modifications are allowed unless explicitly supported (such as refunds).
### Lifecycle overview
* `PENDING` — Order created, awaiting ticketing
* `PROCESSING` — Ticket issuance in progress
* `TICKETED` — Tickets successfully issued (terminal)
* `FAILED` — Ticket issuance failed (terminal)
* `CANCELED` — Order canceled before ticketing (terminal)
* `REFUNDED` — Ticketed order has been refunded (terminal)
Orders are editable only in the PENDING state. Once ticketing begins, the order becomes immutable to
ensure financial and ticketing consistency.
***
### State transitions
```mermaid theme={null}
stateDiagram-v2
[*] --> PENDING : Create order
PENDING --> PROCESSING : Ticket request
PROCESSING --> TICKETED : Ticket issued successfully
PROCESSING --> FAILED : Ticket issuance failed
PENDING --> CANCELED : Cancel order
TICKETED --> REFUNDED : Refund processed
TICKETED --> [*]
FAILED --> [*]
CANCELED --> [*]
REFUNDED --> [*]
```
## Create order
Creates a new order from a previously selected offer.
```http theme={null}
POST /v1/air/orders`
```
### Headers
| Header | Required | Description |
| ----------------- | -------- | ---------------------------------------- |
| `Idempotency-Key` | Yes | Unique key to prevent duplicate bookings |
Always generate a unique idempotency key per booking attempt. This ensures safe retries during network failures.
### Body
```json theme={null}
{
"offerId": "off_...",
"passengers": [
{
"id": "psg_1",
"given_name": "Test",
"family_name": "Traveler",
"born_on": "1990-01-01",
"gender": "m",
"title": "mr",
"email": "test@example.com",
"phone_number": "+12025550123"
}
],
"services": [],
"metadata": {
"reference": "ABC-123"
}
}
```
# Response
```json theme={null}
{
"id": "ord_7f9a2c3d",
"status": "PENDING",
"totalCents": 26032,
"currency": "USD",
"createdAt": "2026-02-20T16:25:51.293Z"
}
```
# Update passengers
Updates passenger information for an existing order.
Only allowed while order status is PENDING.
# Endpoints
```http theme={null}
POST /v1/air/orders/:id/passengers
PUT /v1/air/orders/:id/passengers
```
# Body
The request body must be a JSON object with the following structure:
```json theme={null}
{
"passengers": [
{
"id": "psg_1",
"given_name": "Updated",
"family_name": "Traveler"
}
]
}
```
Passenger updates are rejected once ticketing begins.
## Ticket order
Issues airline tickets and finalizes the order.
`POST /v1/air/orders/:id/ticket`
### Headers
| Header | Required | Description |
| --------------- | -------- | --------------------------------- |
| Idempotency-Key | Yes | Prevent duplicate ticket issuance |
### Response
```json theme={null}
{
"order": {
"id": "ord_7f9a2c3d",
"status": "TICKETED",
"currency": "USD"
}
}
```
Ensure your Travelbase wallet has sufficient balance before ticketing.
## List orders
Returns recent orders.
`GET /v1/air/orders`
### Query parameters
| Parameter | Required | Description |
| --------- | -------- | ---------------------------------------- |
| limit | No | Number of orders to return (default: 25) |
| status | No | Filter by order status |
### Example
```http theme={null}
GET /v1/air/orders?status=TICKETED&limit=10
```
# Retrieve order
Fetches an order with its offer snapshot.
```http theme={null}
GET /v1/air/orders/:id
```
# Response
```json theme={null}
{
"order": {
"id": "ord_7f9a2c3d",
"status": "TICKETED",
"currency": "USD"
},
"offer": {
"id": "off_123",
"total_amount": "260.32"
}
}
```
The offer snapshot represents the exact pricing and itinerary used during booking, ensuring financial
correctness, auditability, and replay safety.
## Idempotency
Travelbase uses idempotency keys to guarantee safe retries.
If a request with the same idempotency key is retried, Travelbase returns the original response instead of creating duplicate orders or issuing duplicate tickets.
Understand how idempotency prevents duplicate bookings and ensures safe retries.
***
## Architecture abstraction
Travelbase provides a unified, supplier-agnostic order interface.
This ensures:
* consistent API behavior
* predictable order lifecycle
* simplified integration
* supplier-independent infrastructure
* forward compatibility as airline systems evolve
Travelbase manages airline communication, ticket issuance, and settlement internally. Your integration remains
stable without requiring supplier-specific handling.
***
## Error handling
Travelbase returns standard HTTP status codes.
### Example error
```json theme={null}
{
"success": false,
"statusCode": 400,
"errorCode": "TB_AUTH_101",
"message": "Insufficient balance",
"fault": "client",
"retryable": true,
"suggestedAction": "Load wallet and try again",
"reason": "wallet balance",
"environment": "sandbox",
"apiVersion": "1.0.0"
}
```
Order operations are state-dependent. Always verify the order status and ensure sufficient wallet
balance before performing ticketing operations.
Use a unique Idempotency-Key for each order creation or ticketing request to ensure safe retries and
prevent duplicate bookings.
## Next steps
Find flight offers to create orders.
Manage your balance required for ticket issuance.