Tripklik
API docs by Redocly

B2B API: Flights & Hotels (1.0.0)

Download OpenAPI specification:

API Support: technology@infotek.ae

Everything you need to integrate with our B2B API: flights (search, availability, booking and ticketing) and hotels (search, rooms, booking and confirmation).

Getting Started

  1. API endpoint and API key. Your account manager sends you the API endpoint (the {domain} used in every path below) and your API key. Send the key on every request:
    Authorization: Bearer <your API key>
  2. Make test bookings while you integrate. Send live_booking: false in Create Order (flights) and Save Guest Details (hotels). Test bookings go through the full flow but are never booked with the airline or the hotel.
  3. Import the Postman collection. Download the Postman collection, import it into Postman, then set the domain and agency_token variables. It contains every request of these docs, grouped like the sections below.
  4. Run the certification test cases. Run the scenarios in Flight Certification Tests and Hotel Certification Tests (in the menu) with test bookings, and send us the results.
  5. Book a walkthrough. To go through the integration steps together, schedule a session.

Start with the Flights and Hotels overviews in the menu: they show each flow step by step, with the endpoints to call. Contact your account manager once you start testing or if you need anything from our side.

Authentication

All endpoints except autocomplete require your API key as a Bearer token:

Authorization: Bearer <your API key>

Some endpoints must be enabled for your account. If an endpoint returns 403, contact your account manager.

Environments

  • Test bookings: send live_booking: false when saving the order details (Create Order for flights, Save Guest Details for hotels).
  • Live bookings: send live_booking: true.
  • Not sent: your account environment decides: live for accounts enabled for live bookings, test otherwise.

Flights Overview

Our Flights API gives you a complete B2B gateway for searching, pricing, booking, and managing flight inventory with precision. It connects your system to real-time availability, rich flight content, multi-fare handling, instant confirmations, and full booking lifecycle controls.

Built for speed, stability, and clean integration, it lets your platform deliver consistent results, automate operations, and scale without friction. Whether you are powering a B2B portal, a mobile app, or a distribution engine, this API provides the structure you need to move fast, stay reliable, and serve your customers with confidence.

What this API covers

Area What it does Endpoints
Airport Autocomplete Find airports while the user types Airports Autocomplete
Booking Flow Search, price, book, hold, pay and issue tickets Search, Collect Results, Fare Families, Check Availability, Fare Rules, Create Order, Hold, Pay and Issue Ticket, Booking Details
Balance Check your agency balance before paying Get Balance
Void Ticket Cancel freshly issued tickets with a refund to your balance Booking Details, Validate Void, Void Ticket

1. Airport Autocomplete

Send what the user types (airport code, airport, city or country name) and show the matching airports. Use the selected airport's IATA_CODE as departure / arrival in Search. No token needed.

User types "cai" ──▶ Airports Autocomplete ──▶ CAI · Cairo International Airport
                                                        │
                                                        ▼  IATA_CODE
                                              Search Flights (departure: CAI)

2. Booking Flow

Search returns priced offers (itineraries), either all at once or progressively with mode: poll and Collect Results. Pick one, optionally choose a branded fare and read its fare rules, confirm the price with Check Availability (its response has the exact trip that will be booked; use it instead of the search result for baggage, fare basis and fare type), then create the order with the passengers. Creating the order only saves it; the PNR and tickets come from the next step. Hold it without payment if the itinerary allows (can_hold), or pay and issue the tickets right away. Ticketing runs in the background, so poll Booking Details until the PNR and tickets appear.

┌─────────────────┐
│  Search Flights │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Fare Families   │ (Optional - if has_fare_families=true)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│Check Availability│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Fare Rules    │ (Optional)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Create Order    │
└────────┬────────┘
         │
         ▼
┌─────────────────────────┐
│ Hold Booking (Optional) │
└────────┬────────────────┘
         │
         ▼
┌─────────────────┐
│ Pay & Issue     │
│ Ticket          │
└────────┬────────┘
         │
         ▼
┌─────────────────────────────────┐
│ Poll Booking Details            │
│ (every 10 min for 2 hours)      │
└────────┬────────────────────────┘
         │
         ▼
┌─────────────────┐
│ PNR & Tickets   │
│ Generated       │
└─────────────────┘

Booking status polling

After payment (Pay and Issue Ticket), you must poll the Booking Details endpoint to retrieve the final booking status:

┌──────────────┐     ┌─────────────────┐     ┌──────────────────┐
│ PayAndIssue  │────▶│  Poll Booking   │────▶│  Check Status    │
│ Ticket       │     │  Details        │     │                  │
└──────────────┘     └─────────────────┘     └────────┬─────────┘
                                                      │
                     ┌────────────────────────────────┼────────────────────────────────┐
                     │                                │                                │
                     ▼                                ▼                                ▼
              ┌──────────────┐               ┌──────────────┐               ┌──────────────────┐
              │ PNR & Ticket │               │  Processing  │               │ No PNR/Ticket    │
              │ Generated    │               │  (Continue   │               │ after 2 hours    │
              │ (Confirmed)  │               │   Polling)   │               │                  │
              └──────────────┘               └──────────────┘               └────────┬─────────┘
                                                                                     │
                                                                                     ▼
                                                                            ┌──────────────────┐
                                                                            │ Mark unconfirmed │
                                                                            │ Contact Supplier │
                                                                            └──────────────────┘
  • Polling Frequency: Once every 10 minutes
  • Polling Duration: Continue for 2 hours
  • Success Indicators: PNR and Tickets generated
  • Unconfirmed Status: If no PNR/Tickets after 2 hours, mark as "unconfirmed" and contact supplier

3. Balance

Bookings are paid from your agency balance (in your agency currency). Check it before Pay and Issue Ticket to avoid a payment failure.

Get Balance ──▶ balance ≥ itinerary price? ──yes──▶ Pay and Issue Ticket
                          │
                          no ──▶ top up your balance first

4. Void Ticket

A freshly issued ticket can be voided (cancelled as if never issued) within the airline's void window, usually the day of issue. The ticket amount is refunded to your balance minus the void fee and any airline penalties. Not every ticket can be voided through the API; Booking Details tells you which ones can.

Booking Details
      │
      ▼
order.available_actions has { action: "void", product_id }?
      │
      ├── no ──▶ the ticket can't be voided through the API
      │
      └── yes ─▶ Validate Void (optional, shows the void fee)
                       │
                       ▼
                 Void Ticket (product_id) ──▶ refund to your balance

API Versions

Endpoints are served by different services, so their paths carry different prefixes (/api/v1/agency/..., /api/v1/..., /api/v2/...). Use each path exactly as documented; the prefixes are not interchangeable.

Errors

Error responses are JSON with at least a message field. Validation errors (422) also include an errors object keyed by field name.

Account Enablement

Get Balance, Validate Void and Void Ticket must be enabled for your account. If they return 403, contact your account manager.

Flight Autocomplete

Airport lookup for building the search form. Use the returned IATA_CODE as departure/arrival in Search Flights.

Airports Autocomplete

Searches airports by code, name, city or country. No authentication is required.

Typical use: send what the user typed as q and show the hits. Use IATA_CODE (also returned as code) in Search Flights.

filter examples:

  • by country: country_code = "EG"
  • by airport code: IATA_CODE = "CAI"
Request Body schema: application/json
required
q
string

Text typed by the user (code, airport, city or country name)

filter
string

Filter expression, e.g. country_code = "EG" or IATA_CODE = "CAI"

sort
Array of strings

Sort rules, e.g. ["order:desc"] to rank preferred airports first

limit
integer
Default: 20
offset
integer
Default: 0

Responses

Request samples

Content type
application/json
{
  • "q": "CAI",
  • "sort": [
    ]
}

Response samples

Content type
application/json
{
  • "hits": [
    ],
  • "query": "",
  • "limit": 20,
  • "offset": 0,
  • "estimatedTotalHits": 1000,
  • "processingTimeMs": 0
}

Flights

Search, fare families, availability and fare rules.

Search Flights

Searches all airlines and suppliers enabled for your agency and returns every bookable offer for the requested route, dates and passengers. Supports one-way (O), round-trip (R) and multi-city (M) searches.

Search modes

Set mode in the request:

  • search (default): the response arrives once every supplier has answered, with the full results.
  • poll: the response arrives immediately with the search_id and no results yet. Call Collect Results with that search_id every 2-3 seconds; each call returns everything found so far (not just the new results), so replace what you show each time. Stop when status is completed (at the latest about 60 seconds after the search).
Search (mode: poll) ──▶ search_id, status: progress
        │
        ▼
Collect Results ──▶ status: progress ──▶ show results, wait 2-3 s, call again
        │
        └──────────▶ status: completed ──▶ final results, stop polling

Polling shows the first results within seconds instead of waiting for the slowest supplier.

Filters

Narrow the results with the optional filters object:

  • direct_only: true returns only non-stop itineraries (every trip is a single flight).
  • airlines: ["SV", "MS"] returns only itineraries operated entirely by those airlines.

Filters are applied to every supplier's results. Combine them as needed, e.g. direct flights on one airline.

How the response is organized

The response is split into itineraries (the offers you show and sell) and aggregations (shared reference data). To keep the payload small, an itinerary does not repeat flight or rule details. It lists their ids, and you look them up in aggregations.

Search response
├── search_id ─────────────────────► pass as {search_id} to every next call
│
├── itineraries[]                    one bookable offer each
│   ├── id ────────────────────────► pass as {itinerary_id} to every next call
│   ├── prices                       total for all passengers
│   ├── passengers[]                 price per passenger type
│   ├── trips[]                      one per direction / leg
│   │   └── flights[] ──── ids ───┐
│   ├── rules[] ────────── ids ───┼──┐
│   ├── has_fare_families         │  │  true → call Get Fare Families
│   └── can_hold                  │  │  true → Hold Booking is allowed
│                                 │  │
└── aggregations                  │  │  reference data shared by all itineraries
    ├── flights[]   ◄─────────────┘  │  segment details, find by `id`
    ├── rules{}     ◄────────────────┘  mini fare rules, keyed by id
    ├── passengers[]                    passenger types in this search
    ├── taxes[]                         tax lines (supplier dependent)
    ├── fares[]                         fare components (supplier dependent)
    └── translations                    airport and airline names

Itineraries

Each itinerary is one priced, bookable combination of flights.

  • prices is the total for all passengers. passengers[].prices is the price for one passenger of that type.
  • trips holds one entry per direction: 1 for one-way, 2 for round-trip, one per leg for multi-city. Each trip lists its flight segments in travel order, so a trip with several flight ids has connections.
  • Prices are in the requested currency and already include your agency markup.

Aggregations

  • flights: one entry per flight segment (airports, times, carriers, flight number, cabin, booking class, baggage, fare family amenities). A segment shared by several itineraries appears only once.
    • bags_per_pax is the baggage breakdown per passenger type (adult, child, infant), each with check_in and cabin allowance.
    • free_baggage and cabin_baggage are short codes for the adult (ADT) allowance only.
  • rules: mini fare rules, a short summary of refund/change conditions (type is REFUND, CHANGE, REVALIDATE, ...) for showing badges such as "Refundable" in results. Several itineraries can point to the same rule. When the airline gives no detail, the rule says to contact support. For the full conditions of one itinerary, call Get Fare Rules.
  • passengers: the passenger types of the search (ADT, CHI, INF).
  • taxes and fares: tax lines and fare components. They depend on the supplier and may be empty; don't rely on them being present.
  • translations: airport and airline names keyed by code, in the requested locale.

Next steps

  1. If has_fare_families is true, optionally call Get Fare Families to offer branded fares.
  2. Optionally call Get Fare Rules for the full conditions.
  3. Call Check Availability before booking to confirm the price.
Authorizations:
bearerAuth
Request Body schema: application/json
required
adults
required
integer >= 1

Number of adult passengers (16+ years)

children
integer >= 0

Number of child passengers (2-16 years)

infants
integer >= 0

Number of infant passengers (0-2 years)

required
Array of objects (Itinerary)
currency
required
string

Account currency code (e.g., USD)

locale
required
string
Enum: "en" "ar"

Language preference (e.g., en, ar)

direction
required
string
Enum: "R" "O" "M"

Flight type: R (Round Trip), O (One way), M (Multi destination)

cabin
required
string
Enum: "E" "PE" "B" "F"

Cabin class: E (Economy), PE (Premium Economy), B (Business), F (First)

object

Optional filters. Omit them to get all results.

mode
string
Default: "search"
Enum: "search" "poll"

search waits for all suppliers and returns the full results. poll returns immediately, then you collect results with Collect Results until status is completed.

Responses

Request samples

Content type
application/json
{
  • "adults": 1,
  • "infants": 0,
  • "children": 0,
  • "itineraries": [
    ],
  • "currency": "USD",
  • "locale": "en",
  • "direction": "R",
  • "cabin": "E",
  • "mode": "search",
  • "filters": {
    }
}

Response samples

Content type
application/json
{
  • "search_id": "2db5e697-0a85-4907-ba41-68de00ecec48",
  • "aggregations": {
    },
  • "itineraries": [
    ]
}

Collect Results

Returns the results of a search made with mode: poll. Call it every 2-3 seconds with the search_id of the search.

Each call returns all results found so far, in the same structure as the Search response, so replace what you show each time. Keep calling while status is progress; stop when it is completed.

Authorizations:
bearerAuth
path Parameters
search_id
required
string

search_id returned by Search

Responses

Response samples

Content type
application/json
{
  • "search_id": "d5826b15-4ef0-45f4-80df-3b8d5f941dd6",
  • "aggregations": {
    },
  • "itineraries": [
    ],
  • "is_cached": true,
  • "status": "progress",
  • "search_time": 0
}

Get Fare Families

This step is optional. If the itinerary has has_fare_family set to true, you can use it to fetch the branded fare offers.

Authorizations:
bearerAuth
path Parameters
itinerary_id
required
string

Unique identifier of the selected itinerary

search_id
required
string

Search session identifier from the search response

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Check Flight Availability

Confirms that the selected itinerary is still available, re-prices it, and returns the full details of the trip that will be booked. Call it before Create Order.

If you intend to book a specific branded fare (fare family), pass the corresponding fare_family_id.

Use the availability response, not the search result

The flights in order_details.data.flights are the trip that will actually be booked. Baggage (bags_per_pax, free_baggage), fare basis (fare_base), fare type, booking class and branded fare can differ from what Search returned, so replace the flight details you show with these before Create Order; don't rely on the search result.

Also check price_changed / price_change: if the price changed, show the new price to the customer before continuing.

Authorizations:
bearerAuth
path Parameters
itinerary_id
required
string

Unique identifier of the selected itinerary

search_id
required
string

Search session identifier from the search response

query Parameters
fare_family_id
string

Optional fare family ID to book a specific branded fare

Responses

Response samples

Content type
application/json
{
  • "available": true,
  • "price_changed": false,
  • "price_change": 0,
  • "formatted_price_change": "SAR 0.00",
  • "price": "SAR 854.49",
  • "session_id": "46a7beae-b13b-4f36-811c-faaa5f919a59",
  • "order_session_id": "8500000-46a7beae-b13b-4f36-811c-faaa5f919a59",
  • "order_details": {
    }
}

Get Fare Rules

Returns the fare rules (cancellation, change and no-show conditions) for a selected itinerary.

This step is optional and informational — it does not affect pricing or booking. It can be called any time after search, within the same search session.

If the customer selected a branded fare (fare family), pass the same fare_family_id you use for Check Availability, so the returned rules match that fare.

If no rules are available for the itinerary, rules is an empty object and text is null.

Authorizations:
bearerAuth
path Parameters
itinerary_id
required
string

Unique identifier of the selected itinerary

search_id
required
string

Search session identifier from the search response

query Parameters
fare_family_id
string

Optional fare family ID, to get the rules of a specific branded fare

Responses

Response samples

Content type
application/json
{
  • "rule_level": "ITINERARY",
  • "rules": {
    },
  • "text": "CAI -> JED:\n\nAFTER_DEP: INR 3360.00\nNO_SHOW: INR 17760.00 (before 2026-11-26 07:25 UTC)\nPRIOR_TO_DEP: INR 3360.00\n\nJED -> CAI:\n\nAFTER_DEP: INR 3360.00\nNO_SHOW: INR 17760.00 (before 2026-11-28 03:15 UTC)\nPRIOR_TO_DEP: INR 3360.00\n\nCAI -> JED:\n\nAFTER_DEP: INR 6720.00\nNO_SHOW: Not permitted (before 2026-11-26 07:25 UTC)\nPRIOR_TO_DEP: INR 6720.00\n\nJED -> CAI:\n\nAFTER_DEP: INR 6720.00\nNO_SHOW: Not permitted (before 2026-11-28 03:15 UTC)\nPRIOR_TO_DEP: INR 6720.00"
}

Bookings

Create, hold, pay for and track a booking.

Create Order

Creates the order for the selected itinerary and saves the passengers and contact details.

This endpoint does not book with the airline. It doesn't create a PNR, take payment or issue tickets; it only saves the order so you can continue with one of the next steps:

  • Hold Booking: creates the PNR without payment (only when the itinerary allows hold), then pay later with Pay and Issue Ticket.
  • Pay and Issue Ticket: pays from your agency balance, creates the PNR and issues the tickets.

Call Check Availability before this endpoint to confirm the price.

Authorizations:
bearerAuth
path Parameters
itinerary_id
required
string
search_id
required
string

Search session identifier from the search response

Request Body schema: application/json
required
required
Array of objects (BookingPassenger)

One entry per passenger. The count must match the adults + children + infants of the search.

mobile
required
string <= 20 characters

Contact mobile number with country code, digits only with optional leading +

phone
string or null <= 20 characters

Alternative contact number

email
required
string <email>

Contact email for booking confirmation

live_booking
boolean or null

false makes this a test booking (never sent to the airline). true makes a live booking. When omitted, your account environment decides: live for accounts enabled for live bookings, test otherwise. Accounts not enabled for live bookings always make test bookings.

Responses

Request samples

Content type
application/json
{
  • "passengers": [
    ],
  • "mobile": "+966565565655",
  • "phone": "",
  • "email": "John.Doe@example.com",
  • "live_booking": false
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "passenger information stored successfully"
}

Retrieve Booking Details

This endpoint retrieves comprehensive details of a specific flight booking, including:

  • Passenger information.
  • PNR (Passenger Name Record).
  • Tickets.
  • Booking status.

Usage Instructions:

  • Call this endpoint every 10 minutes for up to 2 hours after the booking is created.
  • Check for the generation of PNR and tickets during this time-frame.

Timeout Behavior:

  • If neither the PNR nor tickets are generated within 2 hours, the booking is considered unconfirmed.
  • In such cases, contact the supplier directly to verify the final booking status.

Example Workflow:

  1. Create a flight booking.
  2. Poll this endpoint every 10 minutes for updates.
  3. If the booking remains unconfirmed after 2 hours, escalate to the supplier for resolution.

This ensures timely and accurate updates to the booking status while minimizing manual intervention.

Baggage

Baggage breakdown per passenger type (adult, child, infant), each with check_in and cabin allowance. Use this for the exact allowance of every passenger. free_baggage and cabin_baggage on the flight are short codes for the adult (ADT) allowance only.

Available actions

order.available_actions lists what you can do on the booking now. Currently only void, and only when the ticket can be voided through the API; see Void Ticket.

Authorizations:
bearerAuth
path Parameters
itinerary_id
required
string

The unique identifier of the itinerary

search_id
required
string

Search session identifier from the search response

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "order": {
    }
}

Hold Booking

This endpoint allows placing a hold on a booking.

  • Applicable only for itineraries where can_hold = true. (Needs to be activated on the account)
  • Creates a PNR without deducting credit from the user.
  • Booking must be confirmed later using the Pay and Issue Ticket endpoint
Authorizations:
bearerAuth
path Parameters
itinerary_id
required
string

The unique identifier of the itinerary

search_id
required
string

Search session identifier from the search response

Responses

Response samples

Content type
application/json
{
  • "order": {
    },
  • "data": {
    }
}

Pay and Issue Ticket

Pays for the booking from your agency balance and issues the tickets.

Previously named payWallet. The old path /api/v2/orders/payWallet/{itinerary_id}-{search_id} still works, but is deprecated; use this one.

  • Can confirm both held bookings and direct bookings.
  • Deducts credit from the agency account, creates a PNR, and initiates ticket issuance.
  • Once this endpoint is called, the booking enters a processing state.

Important Notes:

  • After payment, the system begins processing the PNR and ticket issuance.
  • Polling is required after payment to monitor the booking status.
  • Use the Booking Details endpoint every 10 minutes for up to 2 hours to track the generation of the PNR and tickets.
  • If neither the PNR nor tickets are available after 2 hours, the booking is considered unconfirmed, and you must contact the supplier directly for resolution.

This polling mechanism ensures accurate tracking of the booking lifecycle after payment.

Authorizations:
bearerAuth
path Parameters
itinerary_id
required
string

The unique identifier of the itinerary

search_id
required
string

Search session identifier from the search response

Responses

Response samples

Content type
application/json
{
  • "order": {
    },
  • "data": {
    }
}

Void Ticket

Cancel freshly issued tickets within the airline's void window; the ticket amount is refunded to your agency balance minus the void fee and any airline penalties.

Flow

  1. Call Booking Details and look for an entry with action: void in order.available_actions. If it isn't there, the ticket can't be voided through the API.
  2. Optional: call Validate Void with its product_id to see the void fee.
  3. Call Void Ticket with the same product_id.

Validate Void

Returns the void fee for the product's tickets, in your agency currency, before voiding.

Only call it for a product listed with action: void in order.available_actions of Booking Details. This endpoint must be enabled for your account. If it returns 403, contact your account manager.

Authorizations:
bearerAuth
path Parameters
session_id
required
string
Example: 10400003-9db3b1de-7be1-4028-9b61-23f3624a1dcf

Order session, {itinerary_id}-{search_id} (the order session_id)

Request Body schema: application/json
required
product_id
required
integer

product_id of the void entry in order.available_actions (Booking Details)

Responses

Request samples

Content type
application/json
{
  • "product_id": 12001
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "Void Validation Result",
  • "status": true
}

Void Ticket

Voids the product's tickets. The tickets are cancelled as if never issued, and the ticket amount minus the void fee and any airline penalties is returned to your agency balance.

Only products listed with action: void in order.available_actions of Booking Details can be voided; any other product is rejected. This endpoint must be enabled for your account. If it returns 403, contact your account manager.

Authorizations:
bearerAuth
path Parameters
session_id
required
string
Example: 10400003-9db3b1de-7be1-4028-9b61-23f3624a1dcf

Order session, {itinerary_id}-{search_id} (the order session_id)

Request Body schema: application/json
required
product_id
required
integer

product_id of the void entry in order.available_actions (Booking Details)

Responses

Request samples

Content type
application/json
{
  • "product_id": 12001
}

Response samples

Content type
application/json
{
  • "data": [ ],
  • "message": "Ticket Voided Successfully",
  • "status": true
}

Flight Certification Tests

Run these flight scenarios with test bookings (live_booking: false in Create Order) and send us the session ID, PNR and ticket number of each. Download the flight test cases (CSV).

# Test case Session ID PNR Ticket
1 1 ADT, 1 CHD, 1 INF, One Way
2 1 ADT, 1 CHD, 1 INF, One Way with Fare Family
3 1 ADT, 1 CHD, 1 INF, Round Trip
4 1 ADT, 1 CHD, 1 INF, Round Trip with Fare Family
5 4 ADT, 2 CHD, 2 INF, One Way - Connecting Point
6 4 ADT, 2 CHD, 2 INF, Round Trip - Connecting Point (Hold)
7 4 ADT, 2 CHD, 2 INF, One Way - Connecting Point with Fare Family (Hold)
8 4 ADT, 2 CHD, 2 INF, Round Trip - Connecting Point with Fare Family

Hotels Overview

Our Hotels API gives you a complete B2B gateway for searching, pricing, booking, and managing hotel inventory with precision. It connects your system to real-time availability, rich hotel content, multi-rate handling, instant confirmations, and full booking lifecycle controls.

Built for speed, stability, and clean integration, it lets your platform deliver consistent results, automate operations, and scale without friction. Whether you are powering a B2B portal, a mobile app, or a distribution engine, this API provides the structure you need to move fast, stay reliable, and serve your customers with confidence.

What this API covers

Area What it does Endpoints
Autocomplete Find cities, hotels and nationalities while the user types Location Autocomplete, Nationality Autocomplete
Booking Flow Search hotels, pick rooms, book, hold, pay and confirm Search Hotels, Collect Results, Get Hotel Details, Get Available Rooms, Check Availability, Save Guest Details, Hold Booking, Pay and Confirm Booking, Retrieve Order Details
Hold Reserve free-cancellation rooms now and pay later Hold Booking, then Pay and Confirm Booking
Cancel Booking Cancel a free-cancellation booking before its deadline Retrieve Order Details, Cancel Booking
Balance Check your agency balance before paying Get Balance
Hotels Dump Download all our hotels once, then only what changed Hotels Dump

1. Autocomplete

Build the search form from two lookups (no token needed):

  • Location Autocomplete searches cities and hotels in one call.
  • Nationality Autocomplete searches countries for the guest nationality.
User types "cairo" ──▶ Location Autocomplete
                         ├── city hit:  code CAI, country.code EG ──▶ Search: city + country_code
                         └── hotel hit: id 2135352 ──────────────▶ Search: hotels_ids  (only this hotel)
                                                                      or requested_hotel_ids + city
User types "eg" ────▶ Nationality Autocomplete ──▶ code EG ──────▶ Search: nationality

2. Booking Flow

Search returns hotels with their cheapest price, either all at once or progressively with mode: poll and Collect Results. Get the rooms of the chosen hotel, then call Check Availability with the selected room combination: it confirms the rooms and price and creates the order. Save the guests on the order, then either hold it (when can_hold is true) or pay and confirm right away. Confirmation with the supplier runs in the background, so poll Retrieve Order Details until booking_status is final.

Search Hotels ──(mode: poll)──▶ Collect Results until status: completed
     │
     ▼
Get Hotel Details (optional)
     │
     ▼
Get Available Rooms ──────────▶ room_combinations[].can_hold / deadline
     │
     ▼
Check Availability ───────────▶ creates the order, returns can_hold / deadline
     │
     ▼
Save Guest Details
     │
     ├── can_hold = true ──▶ Hold Booking ──▶ (pay before deadline) ──┐
     │                                                                │
     ▼                                                                ▼
Pay and Confirm Booking ◀─────────────────────────────────────────────┘
     │
     ▼
Poll Retrieve Order Details (every 10 min, up to 3 hours)
     │
     ▼
booking_status: book_success or book_failed

3. Hold

can_hold tells you whether the booking can be held without payment, and deadline until when (pay before it, or the hold is released). They are returned by Get Available Rooms (per room combination), Check Availability and Retrieve Order Details; always use the latest one. A hold is offered only for fully free-cancellation rooms from suppliers that support it, and must be enabled for your account.

can_hold = true ──▶ Hold Booking ──▶ order status: hold
                                         │
                       before `deadline` ▼
                              Pay and Confirm Booking ──▶ booking confirmed
                                         │
                        after `deadline` ▼
                              hold released, book again

Hold can still be refused (403 with the reason) when your account's hold limits are reached, e.g. the number or total amount of active holds, or a check-in date that is too close.

4. Cancel Booking

Cancel a booking free of charge before its free-cancellation deadline. The amount is refunded to your agency balance.

Before cancelling

  1. Check the cancellation policy of the rooms (cancellation_policy in Get Available Rooms): free cancellation ends at last_cancellation_deadline, after which policies show the charges.
  2. Call Retrieve Order Details and look for an entry with action: cancel in order.available_actions. It is listed only while the booking can be cancelled through the API (free-cancellation booking, before its deadline data.deadline). If it isn't there, the booking can't be cancelled through the API; contact your account manager.
  3. Call Cancel Booking with its product_id.
Retrieve Order Details
      │
      ▼
order.available_actions has { action: "cancel", product_id }?
      │
      ├── no ──▶ can't be cancelled through the API (non-refundable, or past the deadline)
      │
      └── yes ─▶ Cancel Booking (product_id) ──▶ booking cancelled, refund to your balance

5. Balance

Bookings are paid from your agency balance (in your agency currency). Check it before Pay and Confirm Booking to avoid a payment failure.

Get Balance ──▶ balance ≥ booking price? ──yes──▶ Pay and Confirm Booking
                          │
                          no ──▶ top up your balance first

6. Hotels Dump

Keep your own copy of our hotels, to map them to your inventory or build your own search pages.

GET /api/agency/api-out/hotels/dump                     first time: all hotels
GET /api/agency/api-out/hotels/dump?since=<version>     every day: only what changed
  • First time: call it without since. You get type: full with a link to a file of all hotels (gzip-compressed JSON Lines, one hotel per line). Download it, import it, and keep its version.
  • Every day: call it with since set to your version. You get type: delta with the files of what changed, to apply in order, or type: up_to_date when nothing changed. Keep the new version. If you get type: full, replace all your hotels with it.

Links are valid for 1 hour; call the endpoint again for fresh links. A new version is published every day.

first time ──▶ Hotels Dump ─────────────▶ type: full ──▶ download, check sha256, import all, keep version
                                                                                                │
every day ───▶ Hotels Dump?since=<version> ◀─────────────────────────────────────────────────────┘
                 ├── type: up_to_date ──▶ nothing to do
                 ├── type: delta ───────▶ apply each file of `deltas` in order, keep its version
                 └── type: full ────────▶ replace all your hotels, keep version

Hotel IDs:

  • Use a hotel's id in hotels_ids or requested_hotel_ids of Search Hotels. These are the same IDs as Location Autocomplete and Sample Hotels.
  • Search results may show a hotel under one of its linked_hotel_ids. Map those to the hotel id.
  • A delete line with replaced_by means the hotel now has another ID. Move your mapping to replaced_by.

Account Enablement

Get Balance, Hold Booking, Cancel Booking, Sample Hotels and Hotels Dump must be enabled for your account. If they return 403, contact your account manager.

Test Bookings

Send live_booking: false in Save Guest Details to make the order a test booking, or true for a live booking. When not sent, your account environment decides: live for accounts enabled for live bookings, test otherwise. Accounts not enabled for live bookings always make test bookings.

Test bookings go through the full flow (hold, pay, order details) but are never sent to the supplier. Their supplier reference and hcn start with TEST-.

Need known hotels to test with? Sample Hotels returns up to 100 4- and 5-star hotels for each test city (IST, CAI, DXB, PAR, JED); use their id in hotels_ids or requested_hotel_ids.

To test the pending flow, use a check-in date on the 17th of any month:

check-in on the 17th ──▶ Pay and Confirm ──▶ booking_status: book_pending (reference set, no HCN)
                                                   │  next confirmation run (within ~5 minutes)
                                                   ▼
                                             booking_status: book_success, hcn: TEST-HCN-...
any other check-in ────▶ Pay and Confirm ──▶ booking_status: book_success, hcn: TEST-HCN-...

Status Fields

The order has two status fields:

  • status: payment/order status (payment_pending, hold, payment_success)
  • booking_status: booking status with the supplier:
    • book_success: confirmed by the supplier.
    • book_pending: the supplier accepted the booking but hasn't confirmed it yet. Keep polling; it moves to book_success or book_failed.
    • book_failed: the supplier refused the booking.

Supplier Reference and HCN

  • reference: the supplier's booking reference, available as soon as the supplier accepts the booking.
  • hcn (hotel confirmation number): the hotel's own confirmation number, to give the guest at check-in. It depends on the supplier:
    • some return it immediately with book_success;
    • some reach book_pending first and set the HCN later, when the hotel confirms;
    • some never return it; the booking is still valid with the supplier reference.

Keep polling Retrieve Order Details while booking_status is book_pending, or until hcn is set if you need it.

Booking Status Polling

After Pay and Confirm Booking, you must poll the Order Details endpoint to retrieve the final booking status:

┌──────────────┐     ┌─────────────────┐     ┌──────────────────┐
│ PayAndConfirm│────▶│  Poll Order     │────▶│  Check Status    │
│ Booking      │     │  Details        │     │                  │
└──────────────┘     └─────────────────┘     └────────┬─────────┘
                                                      │
                     ┌────────────────────────────────┼────────────────────────────────┐
                     │                                │                                │
                     ▼                                ▼                                ▼
              ┌──────────────┐               ┌──────────────┐               ┌──────────────────┐
              │ book_success │               │ book_failed  │               │ No final status  │
              │ (Confirmed)  │               │  (Failed)    │               │ after 3 hours    │
              └──────────────┘               └──────────────┘               └────────┬─────────┘
                                                                                     │
                                                                                     ▼
                                                                            ┌──────────────────┐
                                                                            │ Mark unconfirmed │
                                                                            │ Contact Account  │
                                                                            │ Manager          │
                                                                            └──────────────────┘
  • Polling Frequency: Once every 10 minutes
  • Polling Duration: Continue for 3 hours
  • Final Statuses: book_success or book_failed. book_pending is not final: keep polling.
  • HCN: may arrive after book_success; see Supplier Reference and HCN
  • Unconfirmed Status: If no final status is received after 3 hours, mark the booking as "unconfirmed" (not failed) and contact your account manager

Hotel Autocomplete

Destination, hotel and nationality lookup for building the search form. No authentication needed.

Location Autocomplete

Searches cities and hotels in one call while the user types. No authentication is required.

Send one query per index in queries, usually both with the same q:

  • cities: use the hit's code as city and country.code as country_code in Search Hotels.
  • hotels: use the hit's id in hotels_ids (search only this hotel) or in requested_hotel_ids together with a city (show this hotel first among the city's hotels).

Results come back in results, one entry per query, in the same order.

Optional per query: limit, filter (e.g. country_code = "EG") and sort (e.g. ["combined_score:desc"] for cities, to rank popular destinations first).

Request Body schema: application/json
required
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "queries": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Nationality Autocomplete

Searches countries by name or code while the user types, for the guest nationality. No authentication is required.

Use the hit's code as nationality in Search Hotels.

Request Body schema: application/json
required
q
required
string

Text typed by the user

limit
integer
Default: 20

Responses

Request samples

Content type
application/json
{
  • "q": "eg"
}

Response samples

Content type
application/json
{
  • "hits": [],
  • "query": "eg",
  • "limit": 20,
  • "offset": 0,
  • "estimatedTotalHits": 1,
  • "processingTimeMs": 0
}

Search Hotels

Search for available hotels with comprehensive filtering options. Supports searching by city or by specific hotel IDs. Multiple rooms with different guest configurations can be searched.

Search modes

Set mode in the request:

  • search (default): the response arrives once every supplier has answered, with the full results.
  • poll: the response arrives immediately with the search_id, status: progress and up to 100 skeleton hotels (skeleton: true): hotel content (name, stars, photos, location) without price, so you can render the list right away. Call Collect Results with that search_id every 2-3 seconds. Each call returns everything found so far, with skeletons replaced by priced hotels as suppliers answer, so replace what you show each time. Stop when status is completed (at the latest about 60 seconds after the search).
Search (mode: poll) ──▶ search_id, status: progress, skeleton hotels (no price)
        │
        ▼
Collect Results ──▶ status: progress ──▶ priced hotels replace skeletons, call again in 2-3 s
        │
        └──────────▶ status: completed ──▶ final results, stop polling

Show skeleton hotels as "loading" and don't let users select them; only hotels with skeleton: false have rooms and prices.

Search by city, specific hotels, or both

Field Searches Limit
city + country_code All hotels of the city
hotels_ids Only the listed hotels up to 1000
city + country_code + requested_hotel_ids The city and the listed hotels; the listed hotels come first (is_requested_hotel: true) and are always returned, with is_available: false when no supplier has them up to 10

Use requested_hotel_ids when the user picked a specific hotel but should still see alternatives in the same city.

Filters

Optional: min_price, max_price (total for the stay), stars, boarding (meal plans) and free_cancellation. They narrow the city results; requested hotels are never filtered out.

How the response is organized

Search response
├── search_id ──────────────────────▶ use as `session` in every next call
├── search                            the destination and number of nights
├── fact_groups ◀────────────────┐  facilities and services, grouped by category
│   └── <group>.facts.<code>.id   │
└── hotels[]                      │  one entry per available hotel
    ├── index ────────────────────┼─▶ use as `hotel` in Hotel Details, Rooms and Check Availability
    ├── name, stars, address, location, zone, thumbnail, reviews
    ├── amenities[] ── fact ids ──┘
    ├── price                         cheapest price for all rooms and the whole stay
    ├── free_cancellation             at least one room option can be cancelled for free
    └── boarding_type[]               meal plans available (room only, breakfast, ...)
  • Show hotels[] as your results list. The price is a starting price ("from"); the exact options and prices come from Get Available Rooms.
  • index is the hotel identifier for the next calls.
  • amenities holds fact IDs: find each one in fact_groups (the facts are keyed by code; match on their id) to show the hotel's facilities and to build facility filters.
  • Sort and filter on your side using price.display_price, stars, reviews, free_cancellation, boarding_type and amenities.
Authorizations:
bearerAuth
Request Body schema: application/json
required
required
Array of objects (RoomSearch) non-empty

Array of room objects with guest configurations

nationality
required
string = 2 characters

Guest nationality code (ISO 3166-1 alpha-2)

country_code
string = 2 characters

Country code for a city search (required with city)

city
string

City code for a city search (required with country_code)

hotels_ids
Array of integers <= 1000 items

Search only these hotels (up to 1000). When provided, city and country_code are optional.

check_in
required
string <date>

Check-in date (YYYY-MM-DD)

check_out
required
string <date>

Check-out date (YYYY-MM-DD)

currency
required
string = 3 characters

Currency code (ISO 4217)

language
required
string = 2 characters

Language preference (ISO 639-1)

requested_hotel_ids
Array of integers <= 10 items

Hotels to highlight in a normal city search (up to 10). The search still returns the city's hotels, and these hotels are searched as well and listed first, flagged with is_requested_hotel. They are always returned, even when they don't match the filters or have no availability (is_available: false).

mode
string
Default: "search"
Enum: "search" "poll"

search waits for all suppliers and returns the full results. poll returns immediately with placeholder (skeleton) hotels, then you collect results with Collect Results until status is completed.

min_price
number or null

Minimum total price for the stay (price.display_price)

max_price
number or null

Maximum total price for the stay (price.display_price)

stars
Array of integers or null[ items [ 0 .. 5 ] ]

Only hotels with one of these star ratings

boarding
Array of strings or null

Only hotels offering at least one of these meal plans (values of boarding_type)

free_cancellation
boolean or null

true: only hotels with a free-cancellation option. false: only hotels without one.

Responses

Request samples

Content type
application/json
Example
{
  • "rooms": [
    ],
  • "nationality": "EG",
  • "country_code": "AE",
  • "city": "DXB",
  • "check_in": "2025-12-14",
  • "check_out": "2025-12-16",
  • "currency": "USD",
  • "language": "en"
}

Response samples

Content type
application/json
{
  • "search_id": "575f395a-e8c9-4cc4-a85b-a12551678eeb",
  • "search": {
    },
  • "hotels": [
    ],
  • "status": "progress",
  • "requested_hotel": true,
  • "is_available": true,
  • "fact_groups": {
    },
  • "fact_sheet": [
    ]
}

Collect Results

Returns the results of a search made with mode: poll. Call it every 2-3 seconds with the search_id of the search.

Each call returns all hotels found so far, in the same structure as the Search response; skeleton hotels are replaced by priced hotels as suppliers answer, so replace what you show each time. Keep calling while status is progress; stop when it is completed.

Authorizations:
bearerAuth
path Parameters
search_id
required
string

search_id returned by Search Hotels

Responses

Response samples

Content type
application/json
{
  • "search_id": "575f395a-e8c9-4cc4-a85b-a12551678eeb",
  • "search": {
    },
  • "hotels": [
    ],
  • "status": "progress",
  • "requested_hotel": true,
  • "is_available": true,
  • "fact_groups": {
    },
  • "fact_sheet": [
    ]
}

Hotel Details

Retrieve comprehensive hotel information including descriptions, amenities, images, and location data to enrich your user experience.

Get Hotel Details

Retrieves comprehensive details about a specific hotel including full description, amenities, gallery images, and location information.

Authorizations:
bearerAuth
Request Body schema: application/json
required
session
required
string <uuid>

Search session ID from search response

hotel
required
string

Hotel index from search results

currency
required
string

Currency code

language
required
string

Language preference

Responses

Request samples

Content type
application/json
{
  • "session": "575f395a-e8c9-4cc4-a85b-a12551678eeb",
  • "hotel": "0",
  • "currency": "USD",
  • "language": "en"
}

Response samples

Content type
application/json
{
  • "id": 989573,
  • "name": "Movenpick Grand Al Bustan Hotel",
  • "type": "HOTEL",
  • "description": "This hotel is located on Casablanca Road in the Al Garhoud district, just 5 minutes from Dubai International Airport...",
  • "gallery": [],
  • "stars": 5,
  • "address": "Casablanca Street, Po Box 30880 Dubai Airport",
  • "city": {
    },
  • "country": {
    },
  • "postal_code": "",
  • "phones": [
    ],
  • "provider": "hotel_beds",
  • "coordinates": {
    },
  • "emails": [
    ],
  • "website": "",
  • "thumbnail": "https://via.placeholder.com/800x600/CCCCCC/333333?text=Hotel+Image",
  • "featured": false,
  • "check_in_time": "None",
  • "check_out_time": "None",
  • "check_in_out_policy": "string",
  • "zone": {
    },
  • "amenities": [
    ],
  • "fact_details": { },
  • "facts_groups": {
    }
}

Rooms

Access detailed room availability, pricing options, meal plans, and cancellation policies for selected hotels to help customers make informed booking decisions.

Get Available Rooms

Retrieves all available room options for a selected hotel, including room types, pricing, meal plans, and cancellation policies.

How the response is organized

Each room combination is one complete, bookable option: one room for each room you searched for, with a single total price for all rooms and the whole stay. Similar options are grouped in accommodations.

Rooms response
├── lowest_price                     the cheapest room combination (same shape as below)
├── free_cancellation                at least one combination can be cancelled for free
└── accommodations[]                 groups of similar options
    └── room_combinations[]          one bookable option each
        ├── room_ids[] ─────────────▶ send as `rooms[]` to Check Availability
        ├── rooms[]                   one room per room searched for (name, meal, amenities, gallery)
        ├── total_price               price for all rooms and the whole stay
        ├── meal                      meal plan of the option
        ├── refundable                false when any room can't be cancelled
        ├── cancellation_policy       when cancellation becomes chargeable
        ├── can_hold                  the option can be held without payment
        └── deadline                  hold deadline, when known at this step
  • Show each room combination as one option, with total_price.display_price as its price.
  • To book an option, send its room_ids to Check Availability. When saving guests, room_index is the position of the room in rooms[] (0 for the first room).
  • Cancellation policy: when use_combination_policy is true, use the combination's cancellation_policy; when false, ignore it and use the cancellation_policy of each room in rooms.
  • can_hold / deadline here are a first indication: confirm them with Check Availability.
Authorizations:
bearerAuth
Request Body schema: application/json
required
session
required
string <uuid>

Search session ID from search response

hotel
required
string

Hotel index from search results

currency
required
string

Currency code

language
required
string

Language preference

Responses

Request samples

Content type
application/json
{
  • "session": "575f395a-e8c9-4cc4-a85b-a12551678eeb",
  • "hotel": "0",
  • "currency": "USD",
  • "language": "en"
}

Response samples

Content type
application/json
{
  • "accommodations": [
    ],
  • "lowest_price": {
    },
  • "free_cancellation": true
}

Hotel Booking

Confirm the rooms, save the guests, then hold or pay and confirm.

can_hold tells you whether the booking can be held without payment, and deadline until when (pay before it, or the hold is released). They are returned by Get Available Rooms (per room combination), Check Availability and Retrieve Order Details; always use the latest one. A hold is offered only for fully free-cancellation rooms from suppliers that support it, and must be enabled for your account.

Check Availability

Confirms that the selected room combination is still available at the same price, and creates the order for it.

Authorizations:
bearerAuth
query Parameters
product_type
required
string
Value: "hotel"
search_id
required
string

Session ID from the search

hotel
required
string

Hotel code

rooms[]
required
Array of strings

Room IDs of the selected room combination (room_ids from Get Available Rooms), one parameter per room

currency
required
string
Example: currency=USD
language
required
string
Example: language=en

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Product availability checked successfully",
  • "available": true,
  • "price_changed": false,
  • "price_change": 0,
  • "price": null,
  • "session_id": "575f395a-e8c9-4cc4-a85b-a12551678eeb",
  • "order_id": 9120,
  • "can_hold": true,
  • "deadline": "2026-11-20 23:59:00"
}

Save Guest Details

Saves the contact details and guests on the order created by Check Availability.

This does not book the hotel. Continue with Hold Booking (when can_hold is true) or Pay and Confirm Booking.

Authorizations:
bearerAuth
path Parameters
session
required
string <uuid>
Example: 575f395a-e8c9-4cc4-a85b-a12551678eeb

Session ID returned by Check Availability (session_id)

Request Body schema: application/json
required
required
object
required
Array of objects non-empty

One entry per guest. The first guest is the lead guest.

live_booking
boolean or null

false makes this a test booking (never sent to the supplier). true makes a live booking. When omitted, your account environment decides: live for accounts enabled for live bookings, test otherwise. Accounts not enabled for live bookings always make test bookings.

Responses

Request samples

Content type
application/json
{
  • "contact": {
    },
  • "passengers": [
    ],
  • "live_booking": false
}

Response samples

Content type
application/json
{
  • "message": "order stored successfully"
}

Hold Booking

Reserves the booking without payment. Available only when can_hold is true (see Hold in the overview). Pay with Pay and Confirm Booking before deadline, or the hold is released.

This must be enabled for your account. If it is refused, the response is 403 with the reason (for example, your account's hold limits were reached).

Authorizations:
bearerAuth
path Parameters
session
required
string <uuid>
Example: 575f395a-e8c9-4cc4-a85b-a12551678eeb

Session ID returned by Check Availability (session_id)

Responses

Response samples

Content type
application/json
{
  • "message": "Order held successfully",
  • "data": [ ],
  • "order": {
    }
}

Pay and Confirm Booking

Pays for the booking from your agency balance and confirms it with the supplier. Works for new and held bookings.

Important: After payment, you must poll the Order Details endpoint every 10 minutes for up to 3 hours to receive the final booking status (book_success or book_failed). If no final status is received, mark the booking as "unconfirmed" and contact your account manager.

Authorizations:
bearerAuth
path Parameters
session
required
string <uuid>
Example: 575f395a-e8c9-4cc4-a85b-a12551678eeb

Search session ID used in booking creation

Responses

Response samples

Content type
application/json
{
  • "message": "Order confirmed successfully",
  • "data": [
    ],
  • "order": {
    }
}

Hotel Orders

Retrieve order details and monitor booking status. After payment, poll order details every 10 minutes for up to 3 hours to receive final booking status (book_success or book_failed).

Retrieve Order Details

Retrieves comprehensive details of a specific hotel booking, including guest information, room details, pricing, and booking status.

Polling Instructions:

  • After Pay and Confirm Booking, poll this endpoint every 10 minutes
  • Continue polling for up to 3 hours
  • Monitor booking_status for the final status: book_success or book_failed (book_pending means keep polling)
  • order.hcn is set when the hotel confirms; it can arrive later than book_success, and some suppliers never return it
  • If no final status after 3 hours, mark as "unconfirmed" and contact your account manager

Hold: data.can_hold and data.deadline show whether the booking can be held and until when a held booking must be paid.

Cancel: order.available_actions lists cancel (with its product_id) while the booking can be cancelled through the API; see Cancel Booking.

Authorizations:
bearerAuth
path Parameters
session
required
string <uuid>
Example: 575f395a-e8c9-4cc4-a85b-a12551678eeb

Search session ID from booking

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "order": {
    }
}

Hotel Cancel Booking

Cancel a booking free of charge before its free-cancellation deadline. The amount is refunded to your agency balance.

Before cancelling

  1. Check the cancellation policy of the rooms (cancellation_policy in Get Available Rooms): free cancellation ends at last_cancellation_deadline, after which policies show the charges.
  2. Call Retrieve Order Details and look for an entry with action: cancel in order.available_actions. It is listed only while the booking can be cancelled through the API (free-cancellation booking, before its deadline data.deadline). If it isn't there, the booking can't be cancelled through the API; contact your account manager.
  3. Call Cancel Booking with its product_id.
Retrieve Order Details
      │
      ▼
order.available_actions has { action: "cancel", product_id }?
      │
      ├── no ──▶ can't be cancelled through the API (non-refundable, or past the deadline)
      │
      └── yes ─▶ Cancel Booking (product_id) ──▶ booking cancelled, refund to your balance

Cancel Booking

Cancels the booking with the supplier and refunds it to your agency balance. Retrieve Order Details then shows booking_status: cancel_success.

Only call it for a product listed with action: cancel in order.available_actions of Retrieve Order Details; any other booking is rejected. Check the rooms' cancellation policy before cancelling.

This endpoint must be enabled for your account. If it returns 403, contact your account manager.

Authorizations:
bearerAuth
path Parameters
session
required
string <uuid>
Example: 575f395a-e8c9-4cc4-a85b-a12551678eeb

Session ID returned by Check Availability (session_id)

Request Body schema: application/json
required
product_id
required
integer

product_id of the cancel entry in order.available_actions

Responses

Request samples

Content type
application/json
{
  • "product_id": 12001
}

Response samples

Content type
application/json
{
  • "data": [ ],
  • "message": "Hotel Booking Cancelled Successfully",
  • "status": true
}

Static Content

All our hotels, to keep in your own system and keep up to date. See Hotels Dump for the download flow.

DumpHotel

One line of the full dump file, and the hotel of a delta upsert line.

id
integer

Hotel ID. Use in hotels_ids or requested_hotel_ids of Search Hotels.

linked_hotel_ids
Array of integers

Other IDs of the same hotel. Search results may show the hotel under one of them.

object (LocalizedName)

Text per language

stars
integer or null
type
string or null
object (LocalizedName)

Text per language

postal_code
string or null
phone
string or null
object
object or null
object
object (LocalizedName)

Text per language

thumbnail
string or null <uri>
images
Array of strings <uri> [ items <uri > ]
check_in_time
string or null
check_out_time
string or null
{
  • "id": 2135352,
  • "linked_hotel_ids": [
    ],
  • "name": {
    },
  • "stars": 5,
  • "type": "hotel",
  • "address": {
    },
  • "postal_code": "11511",
  • "phone": "+20227957171",
  • "geo": {
    },
  • "city": {
    },
  • "country": {
    },
  • "description": {
    },
  • "thumbnail": "https://images.example.com/img/AUo-hSG0n72Gwj7_yTdra1MV.jpg",
  • "images": [],
  • "check_in_time": "15:00:00",
  • "check_out_time": "12:00:00"
}

DumpDeltaLine

One line of a delta file.

One of
op
required
string
Value: "upsert"
required
object (DumpHotel)

One line of the full dump (and the hotel of a delta upsert). Empty translations are "".

Example
{
  • "op": "upsert",
  • "hotel": {
    }
}

Hotels Dump

Links to download all our hotels, or only what changed since the version you last applied.

GET /api/agency/api-out/hotels/dump                     first time: all hotels
GET /api/agency/api-out/hotels/dump?since=<version>     every day: only what changed
type When What to do
full First call (no since), or when your copy needs a full reload Download url, check sha256, replace all your hotels, keep version
delta Daily call with since Download each file of deltas in order, apply its lines, keep its version
up_to_date Nothing changed since your version Nothing to do

A new version is published every day. Links are valid until expires_at (1 hour); call this endpoint again for fresh links.

Full dump (hotels.jsonl.gz): gzip-compressed JSON Lines, one DumpHotel per line. Decompress and read it line by line; the file is large (tens of MB compressed).

Delta (delta.jsonl.gz): one DumpDeltaLine per line:

  • {"op": "upsert", "hotel": {…}}: add the hotel, or replace the hotel with the same id.
  • {"op": "delete", "id": 3011456, "replaced_by": 2135352}: remove the hotel. When replaced_by is set, the hotel now has that ID; move your mapping to it.

Use id in hotels_ids or requested_hotel_ids of Search Hotels; linked_hotel_ids are other IDs of the same hotel that search results may show.

The full dump response has an ETag (its version). Send it back in If-None-Match to get 304 Not Modified while it is still the latest.

This endpoint must be enabled for your account. If it returns 403, contact your account manager.

Authorizations:
bearerAuth
query Parameters
since
string^\d{8}T\d{6}Z$
Example: since=20261011T040000Z

The version you last applied. Omit it on your first call to get all hotels.

header Parameters
If-None-Match
string
Example: "20261012T040000Z"

The ETag of your last full dump. Returns 304 when it is still the latest.

Responses

Response samples

Content type
application/json
Example
{}

Test Data

Known hotels to try the API with.

Sample Hotels

Returns up to 100 hotels rated 4 or 5 stars for each test city: Istanbul (IST), Cairo (CAI), Dubai (DXB), Paris (PAR) and Jeddah (JED). Hotels are in the same format as the hotel hits of Location Autocomplete, with the same IDs as Hotels Dump.

Use a hotel's id in hotels_ids or requested_hotel_ids of Search Hotels, with city_code and country_code for a city search. The list is refreshed daily.

This endpoint must be enabled for your account. If it returns 403, contact your account manager.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "Sample hotels retrieved successfully",
  • "status": true
}

Hotel Certification Tests

Run these hotel scenarios with test bookings (live_booking: false in Save Guest Details) and send us the session ID, supplier reference, HCN and cancellation result of each. Download the hotel test cases (CSV).

# Test case Session ID Supplier reference HCN Cancellation
1 2 adults
2 2 adults + 1 child (11 years old)
3 2 adults + 2 children (8 and 9 years old)
4 2 rooms: 1 single + 1 double
5 1 single room, cancelled before the cancellation deadline (free)
6 2 rooms (1 single + 1 triple), within the cancellation penalty period

How to run the hotel test cases. Each one is a full test booking: Search Hotels, Get Available Rooms, Check Availability, Save Guest Details (live_booking: false), then Pay and Confirm Booking, and Retrieve Order Details until booking_status is final. Record the session ID, the supplier reference and the hcn. Use different hotels and suppliers across the cases.

  1. 2 adults. Search with "rooms": [{"adults": "2", "children": []}]. Send both adults in Save Guest Details with room_index: 0. Expected: booking_status: book_success (possibly after book_pending), with reference and hcn set.
  2. 2 adults + 1 child (11). Search with "rooms": [{"adults": "2", "children": ["11"]}]. Send the 2 adults (type: ADT) and the child (type: CHI, birth matching 11 years), all with room_index: 0.
  3. 2 adults + 2 children (8, 9). Search with "rooms": [{"adults": "2", "children": ["8", "9"]}]. Send the children as type: CHI with their birth dates. room_index starts at 0: the first room is 0.
  4. 2 rooms: 1 single + 1 double. Search with "rooms": [{"adults": "1", "children": []}, {"adults": "2", "children": []}] and pick a room combination with 2 rooms. Send the single-room guest with room_index: 0 and the double-room guests with room_index: 1 (their position in the combination's rooms).
  5. Single room, cancelled before the deadline. Pick a combination with refundable: true and a future last_cancellation_deadline, and book it. Retrieve Order Details must list cancel in order.available_actions; call Cancel Booking with its product_id. Expected: booking_status: cancel_success, no penalty, and the amount refunded to your balance.
  6. 2 rooms (1 single + 1 triple), within the penalty period. Search with "rooms": [{"adults": "1", "children": []}, {"adults": "3", "children": []}] and book a combination whose cancellation policy already charges a penalty (non-refundable, or past last_cancellation_deadline). Expected: Retrieve Order Details does not list cancel, Cancel Booking is refused (417), and the penalty you show matches cancellation_policy.policies. Such bookings are cancelled through your account manager.

Validations (all cases).

  • Cancellation policy: show the policy exactly as returned: free cancellation until last_cancellation_deadline, then the charges in policies (from_date, to_date, charge, type, currency). Use the combination's policy when use_combination_policy is true, otherwise each room's own policy. If your application adds its own buffer to our deadlines, tell us how much.
  • Taxes: when total_price returns included_taxes_list / excluded_taxes_list, show them. Excluded taxes are paid at the hotel and must be shown to the guest before booking.
  • Policy norms: show cancellation_policy.norms (the supplier's remarks) with the room and on the booking confirmation.
  • Guest names: first and last names of 2 to 25 characters, letters only (no spaces, numbers or special characters). Send every guest, including all adults, in Save Guest Details.

Account

Agency account information.

Get Balance

Returns the available balance of your agency as a plain number, in the agency currency.

This endpoint must be enabled for your account. If it returns 403, contact your account manager.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
85104.87