Skip to main content
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.

Create Order

Convert an offer into a pending order.

Ticket Order

Issue tickets and finalize the booking.

​
Order lifecycle

Orders progress through a defined lifecycle:
StatusDescription
PENDINGOrder created, awaiting ticketing
PROCESSINGTicket issuance in progress
TICKETEDTickets successfully issued
FAILEDTicketing failed
CANCELEDOrder canceled before ticketing
REFUNDEDOrder 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

​
Create order

Creates a new order from a previously selected offer. 
POST /v1/air/orders`

​
Headers

HeaderRequiredDescription
Idempotency-KeyYesUnique key to prevent duplicate bookings
Always generate a unique idempotency key per booking attempt. This ensures safe retries during network failures.

​
Body

{
  "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

{
"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

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: 

{
"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

HeaderRequiredDescription
Idempotency-KeyYesPrevent duplicate ticket issuance

​
Response

{
  "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

ParameterRequiredDescription
limitNoNumber of orders to return (default: 25)
statusNoFilter by order status

​
Example

GET /v1/air/orders?status=TICKETED&limit=10

​
Retrieve order

Fetches an order with its offer snapshot. 
GET /v1/air/orders/:id

​
Response

{
"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.

Learn about idempotency

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

{
        "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

Search offers

Find flight offers to create orders.

Wallet

Manage your balance required for ticket issuance.