How Booking Works
Understand the end-to-end journey of a flight search and booking: from the moment you submit a search request to receiving a confirmed ticket. This guide explains how Norba orchestrates multiple airlines behind a single, unified API.
1. The Search Flow
When you send a search request with an origin, destination, and travel dates, Norba performs several steps before returning results:
┌─────────────────────────────────────────────────────────────┐
│ 1. VALIDATE INPUT │
│ - Verify origin & destination are valid IATA codes │
│ - Parse departure and return dates │
│ - Normalize passenger counts (adults, children, infants)│
└──────────────────────┬──────────────────────────────────────┘
▼
┌──────────────────────┴──────────────────────────────────────┐
│ 2. CHECK CACHE │
│ - Identical searches within 3 minutes return instantly │
│ - Cached results include the full offer list │
└──────────────────────┬──────────────────────────────────────┘
▼
┌──────────────────────┴──────────────────────────────────────┐
│ 3. ROUTE FILTERING │
│ - Non-stop search: only airlines with a direct route │
│ - Connection search: airlines serving both endpoints │
│ - Airlines that don't serve the route are skipped │
└──────────────────────┬──────────────────────────────────────┘
▼
┌──────────────────────┴──────────────────────────────────────┐
│ 4. PARALLEL FAN-OUT │
│ - Query all matching airlines simultaneously │
│ - Each airline gets the same search parameters │
│ - 4-second global timeout; partial results are returned │
└──────────────────────┬──────────────────────────────────────┘
▼
┌──────────────────────┴──────────────────────────────────────┐
│ 5. MERGE & RANK │
│ - Combine offers from all airlines that responded │
│ - Deduplicate by OfferID │
│ - Sort by total price (cheapest first) │
│ - Enrich with airport names, airline logos, aircraft │
└──────────────────────┬──────────────────────────────────────┘
▼
┌───────────────┐
│ JSON RESPONSE │
│ (200 OK) │
└───────────────┘
The response includes a search_id that you can use to track the search, and each offer has a unique offer_id you'll need when creating an order.
2. Understanding Offers
An offer represents a priced itinerary from a specific airline. Each offer contains:
| Field | Description |
|---|---|
| offer_id | Unique identifier; required for booking |
| airline | IATA code (e.g., BA, VY, IB) |
| total_price | Amount + currency (per passenger or total) |
| slices | Directional legs (outbound + optional return) |
| segments | Individual flights within a slice (flight number, times, aircraft) |
| cabin_class | economy, premium_economy, business, or first |
| quality_score | 0–100 completeness score; higher means more data fields populated |
Tip
Use OfferPrice to lock in a price before booking. Offers have a limited validity window (typically 15–30 minutes). Confirming the price ensures the fare doesn't change before you create the order.
3. The Order Lifecycle
Once you've selected an offer, creating an order takes it through a defined lifecycle:
POST /v1/orders POST /v1/orders/{id}/commit
┌───────────┐ ┌──────────────┐ ┌─────────┐
│ PENDING │───▶│ CONFIRMED │───▶│TICKETED │
└───────────┘ └──────────────┘ └─────────┘
│ │ │
│ │ │
▼ ▼ ▼
┌───────────┐ ┌──────────────┐ ┌──────────┐
│ FAILED │ │ CANCELLED │ │REFUNDED │
└───────────┘ └──────────────┘ └──────────┘
Other possible states: partially_cancelled, disrupted
| State | Meaning |
|---|---|
| pending | Order created but not yet confirmed by the airline |
| confirmed | Reservation confirmed; PNR assigned |
| ticketed | Payment processed and e-tickets issued |
| cancelled | Booking cancelled by traveler or agency |
| refunded | Cancellation processed and payment returned |
| disrupted | Schedule change or flight cancellation by airline |
| failed | Order creation or payment processing failed |
4. Multi-Airline Aggregation
Norba queries multiple airlines in parallel, so you get results from all carriers in a single response. Here's how this works in practice:
Example: LHR to JFK Search
Result: 6 merged offers from BA + VS, sorted by price. Delta's timeout didn't block the response, and United was never called because it doesn't fly that route.
This architecture means you always get the fastest results available. If one airline is slow or unavailable, it doesn't prevent you from seeing offers from the others.
5. Reliability & Resilience
Circuit Breakers
If an airline fails 5 times consecutively, it is temporarily paused for 30 seconds. A single test request then checks if it has recovered. This prevents cascading failures.
Result Caching
Identical search parameters are cached for 3 minutes. Your users get instant results while reducing load on airline systems.
Rate Limiting
Each agency is limited to 60 searches per minute per endpoint to protect against accidental overuse and comply with airline look-to-book ratio requirements.
Partial Results
If some airlines respond within the timeout and others don't, you receive the available results immediately rather than waiting for stragglers.