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 │
│ - A recent identical search returns 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 │
│ - Bounded wait; partial results are returned for │
│ whichever airlines answered in time │
└──────────────────────┬──────────────────────────────────────┘
▼
┌──────────────────────┴──────────────────────────────────────┐
│ 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 of the marketing carrier |
| 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.0–1.0 data-completeness score; see the Quality Scores guide |
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
The search is a fan-out by design: every airline that serves the route is queried in parallel and each answer is merged as it lands, so one slow or unreachable carrier never holds up the rest. The airlines you can sell today are listed on the airlines page.
Illustration: LHR to JFK with four carriers
Result: 6 merged offers from BA + VS, sorted by price. The slow carrier didn't block the response, and the fourth was never called because it doesn't fly the route. The airlines are illustrative — the shape of the answer is the point.
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
Failure Isolation
An airline that keeps failing is paused briefly and probed before traffic resumes, so one carrier's outage never spreads to the rest of your searches.
Result Caching
An identical search repeated within a short window is served from cache. Your users get instant results, and the repeat never reaches the airline — so it does not count against your look-to-book ratio.
Search Pacing
Shopping is paced at 60 searches a minute by default, or the rate set on your account, plus any daily or monthly search ceiling agreed for it. Past one of those the answer is 429 with a Retry-After. These limits exist because airlines police the ratio of searches to bookings; there is no platform capacity limit of Norba's own.
When your account's look-to-book ratio drifts above its threshold, responses carry an X-Norba-L2B header before any throttling applies — treat it as the signal to cache more or search less.
Partial Results
If some airlines respond within the timeout and others don't, you receive the available results immediately rather than waiting for stragglers.
6. Sandbox and Going Live
Every agency starts in the sandbox. Its keys reach the airlines' test systems, searches return test inventory, and bookings don't issue real tickets or raise a booking fee. Sandbox and production keys reach different airline systems, so a sandbox key never quietly reaches a live one.
Reaching production is a request, not a toggle: the agency's legal company details, its incorporation and identity documents, and a signed production agreement are filed from the dashboard and reviewed by Norba before the account is switched to live keys and real fees. An order keeps servicing in the environment it was booked in even after the agency goes live, so a sandbox-era booking is never sent to a production system that never issued it.