Overview

Search for hotel rates and availability across multiple hotels. This is your primary endpoint for finding bookable hotel rooms with real-time pricing.

When to Use

• Display hotel listings with prices on your search results page

• Show detailed rate options for specific hotels users are viewing

• Support multi-room bookings for families or groups

• Filter hotels by location, amenities, ratings, or AI-powered semantic search

What You Get

• Real-time rates with availability and pricing

• Multiple room options per hotel, sorted by price

• Complete booking details including cancellation policies, meal plans, and room types

• Hotel information (name, photos, address, ratings) when searching by filters

Key Features

• Multiple search methods: Search by hotel IDs, city/country, coordinates, Place ID, IATA code, or natural language (AI search)

• Flexible filtering: Filter by star rating, facilities, hotel chains, accessibility, and more

• Multi-room support: Book multiple rooms with different guest configurations in one request

• Performance optimized: Default limit of 200 hotels (expandable to 5,000), recommended timeout of 6-12 seconds

• Price consistency: Optional sessionId ensures rates stay consistent across listing and detail searches within a user session

Quick Start

Required fields: checkin, checkout, currency, guestNationality, occupancies, plus one location method (hotel IDs, city/country, coordinates, Place ID, or IATA code)

Tip: When searching by filters (like aiSearch or cityName), hotel data is automatically included. For direct hotel ID searches, set includeHotelData=true to include hotel names and photos.

Price consistency: Generate a unique sessionId per user search session and include it on every rates request in that session, using the same checkin, and checkout.

Overview

Get the cheapest available rate for each hotel in your list. Perfect for displaying price comparisons without loading full rate details.

When to Use

• Show price ranges on hotel listing pages

• Quick price comparisons across multiple hotels

• Optimize performance when you only need the lowest price, not all rate options

• Build price filters or sorting by price

What You Get

• Minimum rate per hotel - the cheapest available room option

• Basic rate information - price, currency, and availability

• Fast response - optimized for quick price lookups

Key Features

• Lightweight - Returns only the minimum rate, not all options

• Same parameters as the main rates endpoint for consistency

• Perfect for listings - Ideal when displaying multiple hotels where users just need to see starting prices

Quick Start

Provide a list of hotel IDs, dates, and guest occupancy. The endpoint returns the cheapest rate available for each hotel.

Retrieve a hotel prebook by its prebookId: final price, cancellation terms, room details and the checkoutUrl (https://book.maqami.co/booking?prebookId=...). Bookings are paid and confirmed only on MAQAMI's website, through the checkoutUrl.

Overview

Locks the chosen hotel rate and returns the final price, cancellation terms and a checkout link on MAQAMI's website.

When to Use

When the customer has chosen a hotel, room, dates and guests and reviewed the price and cancellation terms.

Quick Start

Pass the offerId from post_hotels_rates exactly as it was returned.

What You Get

• prebookId - The locked rate

• Final price and cancellation terms - For the customer to review

• checkoutUrl - https://book.maqami.co/booking?prebookId=...

Payment

Bookings are paid and confirmed only on MAQAMI's website. The checkoutUrl opens checkout for this exact rate, where the customer enters guest details, pays securely and receives the confirmation. This tool takes no payment details and does not confirm the booking.

Find a customer's hotel bookings by the email address and last name used to book.

Both must match the booking holder; nothing is returned otherwise. Returns each booking with its bookingId, status, hotel, dates, guests, price and cancellation policy.

To look up, change or cancel one booking, use its bookingId with the same email in the booking tools.

Look up a confirmed hotel booking: status, hotel, dates, rooms, guests, price and cancellation policy.

Requires the bookingId and the email used to book: the server only returns or changes a booking when they match.

Cancel a confirmed hotel booking. First check the cancellation policy with get_bookings_bookingid and confirm with the customer: a non-refundable booking, or one past its free-cancellation deadline, can be charged in full.

Requires the bookingId and the email used to book: the server only returns or changes a booking when they match.

Correct the booking holder's name, email or phone on a confirmed hotel booking, for example to fix a typo.

It does not change dates, rooms or guests. To show the customer prices for other dates or guests, use post_bookings_bookingid_alternative_prebooks.

Pass the bookingId, the email currently on the booking and the corrected holder (firstName, lastName, email, optional phone). Confirm the new details with the customer before calling.

Requires the bookingId and the email used to book: the server only returns or changes a booking when they match.

Overview

Hard Amendment — Search for alternative rates at the same hotel and create prebook sessions for a confirmed booking. Used when the guest needs to change their check-in/check-out dates or room occupancy.

When to Use

• Date changes — Guest needs different check-in or check-out dates

• Occupancy changes — Guest needs a different number of adults or children

• Hard amendments — Situations where the booking must be cancelled and re-booked with new parameters

How It Works

1. The system searches for live availability at the same hotel with the new parameters.

2. Up to maxPrebooks alternative rates are selected (sorted by price ascending). Defaults to 3 when omitted; capped at 10 (any larger value is silently clamped to 10).

3. A prebook session is created for each rate.

4. The caller receives a list of prebookId values with prices to show the guest.

What You Get

• Up to maxPrebooks prebook sessions — Each with a prebookId, final pricing, cancellation policies, and room details

• Price comparison — priceDifferencePercent shows how each alternative compares to the original booking's selling price (negative = cheaper than what the guest paid, positive = more expensive)

• Policy change flags — cancellationChanged and boardChanged highlight any policy differences

Key Notes

• The booking must be in CONFIRMED status.

• If the original booking is non-refundable, only non-refundable alternatives are returned (unless overridden with refundableRatesOnly).

• The nationality and currency of the original booking are used for the availability search.

Quick Start

1. Call this endpoint with the bookingId and new occupancies/dates — get back up to maxPrebooks prebookId values.

On this server: rebooking is not available, so use this only to show the guest alternative prices. To change a booking, cancel it if its policy allows and make a new booking, or contact MAQAMI support.

Requires the bookingId and the email used to book: the server only returns or changes a booking when they match.

Overview

Returns the tax schema of a hotel as normalized static data, independent of the supply provider the rules were learned from. Each entry describes one tax or fee: whether it is already included in the room rate, whether it is a percentage of the rate or a fixed amount, and how fixed amounts scale (per adult and/or per night).

When to Use

• Price transparency - Show guests which taxes and fees apply at a property

• Amount-due-at-property estimates - Excluded taxes are typically collected at the hotel

• Tax auditing - Compare supplier-declared taxes against the reference schema

Notes

• Fixed amounts are expressed in USD

• Percentage rates apply to the room rate (e.g. 13.5 means 13.5%)

• The schema is learned by an offline pipeline; hotels without learned data return 404

• When the direct (hotel-declared) source is enabled, taxes declared by the hotel in MAQAMI Cloud take precedence over learned rules and each entry carries source, chargeType, appliedPer, appliedOn, payAtProperty and validity dates

Overview

Search and retrieve hotel listings based on various criteria. Get hotel metadata including names, addresses, ratings, amenities, and images for display in your application.

When to Use

• Hotel listings - Display hotel search results

• Location-based search - Find hotels by city, coordinates, or Place ID

• Hotel discovery - Browse hotels in specific areas

• Metadata retrieval - Get hotel information for display

What You Get

• Hotel list - Matching hotels with complete metadata

• Basic information - Names, addresses, ratings, and locations

• Amenities - Available facilities and features

• Images - Hotel photos for display

• Identifiers - Hotel IDs for use in rate searches

Search Options

• By city - Search hotels in a specific city

• By coordinates - Find hotels near latitude/longitude with radius

• By Place ID - Get hotels within a specific place boundary

• By hotel IDs - Retrieve specific hotels by their IDs

Quick Start

Provide search criteria (city, coordinates+radius, placeId, or hotelIds). Returns matching hotels with complete metadata.

Overview

Beta Feature - Search hotels using natural language queries. Uses AI to understand search intent and find hotels that match the meaning, not just keywords.

When to Use

• Natural language search - Let users search with phrases like "romantic getaway in London"

• Intent-based matching - Find hotels matching the vibe or style, not just location

• Conversational search - Support natural language hotel discovery

• Semantic matching - Get hotels that semantically match the query

What You Get

• Matching hotels - Hotels that semantically match your query

• Semantic attributes - Tags, persona, style, location_type, and story for each hotel

• Relevance scores - How well each hotel matches the query

• Hotel metadata - ID, name, photos, address, city, country

Example Queries

• "Romantic getaway in London with Italian vibes"

• "Hotels near Paris"

• "Family-friendly beachfront hotels"

Quick Start

Provide a natural language query parameter. Returns hotels with semantic matching scores and attributes.

Note: This is a beta feature and may be subject to changes.

Overview

Beta Feature - Ask natural language questions about a specific hotel and get AI-powered answers based on the hotel's information.

When to Use

• Hotel Q&A - Answer customer questions about hotels

• Information lookup - Get specific details about amenities, services, or features

• Conversational interfaces - Build chat interfaces for hotel information

• Detailed inquiries - Ask about specific aspects like restaurants, parking, or amenities

What You Get

• AI-generated answers - Relevant responses to your questions

• Hotel-specific information - Answers based on the hotel's actual data

• Natural language responses - Human-readable answers

Example Questions

• "What amenities does this hotel have?"

• "Is there parking available?"

• "What does a meal at the restaurant look like?"

Key Features

• Web search option - Enable allowWebSearch to get additional information from the web

• Hotel context - Answers are specific to the hotel you're asking about

• Natural language - Ask questions conversationally

Quick Start

Provide the hotelId and your question. Optionally enable allowWebSearch for web-enhanced answers.

Note: This is a beta feature and may be subject to changes.

Overview

Generate short, AI-written "Smart Highlight" cards for a hotel. Each highlight is a title plus a one or two sentence description, generated directly in the requested language.

Pricing: $0.02 per request

Rate Limiting: This endpoint is rate-limited to 10 requests per minute. Exceeding this limit will result in a 429 Too Many Requests response.

When to Use

• Hotel detail pages - Show a few compelling reasons to consider a property

• Partner-specific tone - Adjust voice and emphasis per surface via tone, style and per-highlight context

What You Get

• Exactly count highlights, always, in the requested order

• type echoed back from the request so you can map each card to your own UI

• generated indicating whether the copy is AI-generated or template fallback

Behaviour

Hotel facts are resolved server-side from hotelId; the caller never supplies them. The model sees the name, city, country, street address, parking, and description, plus a sample of facilities, rooms, policies, and nearby places (with a server-computed distance phrase: on the property, short walk, short drive, or longer drive; farther places are omitted), guest sentiment strengths when stored (not drawbacks), and classification (star rating, hotel type, chain). Generated copy is grounded in those facts. Straight apostrophes in titles and descriptions are normalized to typographic apostrophes. Enterprise API keys also omit wifi and the phrase modern amenities from the facts and from the copy, and they omit review-style wording such as guests say. Other API keys still return wifi and connectivity copy when the request asks for it. When tone or style specify length or format, those rules override the default title and description lengths.

If AI generation fails, the endpoint still returns 200 with the requested number of neutral template highlights and generated: false. It never returns an empty array for a valid hotel.

Results are cached, so repeated calls with an identical request body return identical copy.

tone and style are truncated to 200 characters (5,000 for enterprise accounts). Each highlight context is truncated to 300 characters (10,000 for enterprise accounts).

Overview

Beta Feature - Search hotel rooms using visual and text-based queries. Uses image search technology to match your query against room images and find hotels with rooms that match your visual preferences, amenities, or style.

When to Use

• Visual room search - Find rooms based on visual characteristics like "luxury modernist comfort" or "blue accessible bathroom"

• Style-based search - Search for rooms by design style like "art deco hotel room" or "brutalist room"

• Amenity-focused search - Find rooms with specific features like "twin room with a city view" or "room with a skylight"

• Geographic filtering - Limit results to hotels near a specific location using coordinates or Place ID

• City and country filtering - Filter results by city and/or country

What You Get

• Matching hotels - Hotels grouped by hotel ID with rooms that match your query

• Room details - Room name, image URL, and similarity score (rounded to 3 decimals) for each matching room

• Hotel metadata - ID, name, address, city, country, and rating for each hotel

• Geographic filtering - Optionally limit results to a specific area using coordinates or Place ID

• City and country filters - Filter results by city and/or country code

Example Queries

• "luxury modernist comfort"

• "an extremely fun room or art deco hotel room"

• "luxurious accessible bathroom or blue accessible bathroom with walk in shower"

• "twin room with a city view"

• "a room filled with paintings"

• "a hotel room with a skylight"

Geographic Filtering

You can optionally limit search results to a specific geographic area:

• Using coordinates: Provide latitude, longitude, and optionally radius (in kilometers, default: 12km)

• Using Place ID: Provide placeId - the place's location will be automatically fetched and the search will use the place's viewport boundaries (or the provided radius if viewport is unavailable)

• Using city/country: Provide city and/or country to filter results by location

Quick Start

Provide a query parameter describing the room you're looking for. Optionally add geographic filtering with latitude/longitude or placeId to limit results to a specific area.

Note: This is a beta feature and may be subject to changes.

Overview

Get comprehensive details about a specific hotel including descriptions, amenities, images, location, and ratings. Perfect for displaying hotel detail pages.

When to Use

• Hotel detail pages - Show complete hotel information

• Booking pages - Display hotel details before booking

• Hotel profiles - Build rich hotel information pages

• Content display - Show descriptions, amenities, and images

What You Get

• Complete hotel information - Name, address, description, and ratings

• Amenities list - All available facilities and services

• Image gallery - Hotel photos and images

• Location details - Address, coordinates, and location information

• Hotel metadata - Star rating, chain information, and classifications

Quick Start

Provide the hotelId as a query parameter. Returns complete hotel details including all metadata, amenities, and images.

Overview

Retrieve guest reviews and ratings for a specific hotel. Display authentic feedback from previous guests to help users make informed booking decisions.

When to Use

• Review display - Show guest reviews on hotel detail pages

• Rating aggregation - Display average ratings and review counts

• Trust building - Show authentic guest feedback

• Decision support - Help users evaluate hotels before booking

What You Get

• Guest reviews - Individual review text and ratings

• Review dates - When each review was written

• Ratings - Numerical and textual ratings

• Guest feedback - Detailed comments from previous guests

Quick Start

Provide the hotelId as a query parameter. Returns all reviews for that hotel with ratings and comments.

Overview

Get a list of all cities within a specific country. Perfect for building location dropdowns and city selection interfaces.

When to Use

• City dropdowns - Populate city selection lists

• Location filters - Filter hotels by city

• Geographic data - Get city lists for specific countries

• Form autocomplete - Build city autocomplete features

What You Get

• City list - All cities in the specified country

• City names - Formatted city names ready for display

Quick Start

Provide the countryCode in ISO-2 format (e.g., "US", "GB"). Returns all cities in that country. Use the Get Country List endpoint to get country codes.

Overview

Get a complete list of all countries available in the system with their ISO-2 country codes. Essential for building country selection interfaces.

When to Use

• Country dropdowns - Populate country selection lists

• Location filters - Filter hotels or searches by country

• Form inputs - Build country selection forms

• Reference data - Get country codes for use in other endpoints

What You Get

• Country list - All available countries

• ISO-2 codes - Standard country codes (e.g., "US", "GB", "FR")

• Country names - Full country names

Quick Start

No parameters required. Returns all countries with their ISO-2 codes.

Overview

Get all available currencies with their codes, names, and the countries where each currency is used. Perfect for building currency selection interfaces.

When to Use

• Currency dropdowns - Populate currency selection lists

• Price display - Show prices in different currencies

• Currency conversion - Get currency information for conversion

• Reference data - Get currency codes for use in booking endpoints

What You Get

• Currency list - All available currencies

• Currency codes - ISO currency codes (e.g., "USD", "EUR", "GBP")

• Currency names - Full currency names

• Country mapping - Countries where each currency is used

Quick Start

No parameters required. Returns all currencies with codes, names, and country mappings.

Overview

Get IATA (International Air Transport Association) airport codes with airport names, coordinates, and country information. Useful for airport-based hotel searches.

When to Use

• Airport searches - Find hotels near airports

• Location selection - Let users search by airport codes

• Geographic data - Get airport locations and coordinates

• Reference data - Get IATA codes for use in hotel searches

What You Get

• Airport list - All available airports with IATA codes

• Airport names - Full airport names

• Coordinates - Latitude and longitude for each airport

• Country codes - ISO-2 country codes for each airport

Quick Start

No parameters required. Returns all airports with IATA codes, names, coordinates, and country information.

Overview

Get all available hotel facilities (amenities) with multi-language translations. Use these facility IDs to filter hotel searches by amenities.

When to Use

• Facility filters - Build amenity filtering in hotel searches

• Facility display - Show available facilities with translated names

• Multi-language support - Display facilities in user's language

• Reference data - Get facility IDs for use in search filters

What You Get

• Facility list - All available hotel facilities

• Facility IDs - Numeric IDs for use in search filters

• Multi-language names - Facility names in multiple languages

• Translations - Localized facility names

Quick Start

No parameters required. Returns all facilities with IDs and multi-language translations. Use facility IDs in hotel search filters.

Overview

Get all available hotel type classifications (e.g., resort, boutique, business hotel). Use type IDs to filter hotel searches.

When to Use

• Type filters - Filter hotels by type in search

• Type display - Show hotel type classifications

• Reference data - Get hotel type IDs for filtering

What You Get

• Hotel type list - All available hotel types

• Type IDs - Numeric IDs for use in search filters

• Type names - Hotel type classifications

Quick Start

No parameters required. Returns all hotel types with IDs. Use type IDs in hotel search filters.

Overview

Get all available hotel chains (e.g., Marriott, Hilton, IHG). Use chain IDs to filter hotel searches by brand.

When to Use

• Chain filters - Filter hotels by chain/brand

• Brand selection - Let users search for specific hotel chains

• Reference data - Get chain IDs for use in search filters

What You Get

• Chain list - All available hotel chains

• Chain IDs - Numeric IDs for use in search filters

• Chain names - Hotel chain/brand names

Quick Start

No parameters required. Returns all hotel chains with IDs. Use chain IDs in hotel search filters.

Overview

Get all supported languages for hotel translations and content localization. Use language codes to request hotel data in specific languages.

When to Use

• Language selection - Display available languages to users

• Content localization - Get language codes for API requests

• Multi-language support - Build language switchers in your application

• Reference data - Validate language codes before making requests

What You Get

• Language list - All supported and enabled languages

• Language codes - ISO 639-1 codes (e.g., 'en', 'es', 'fr')

• Language names - Human-readable language names in English

Quick Start

No parameters required. Returns all supported languages with codes and names. Use language codes in hotel search and detail requests.

Find hotels by name or place with a semantic text search. Returns up to 5 matches (set limit for more) with name, address, city, country and a relevance score. Check the name and city before using an id. For an exact hotel name, get_data_hotels with hotelName and cityName or countryCode is more precise.

Overview

Retrieve full details for a specific airline using its 2-letter IATA code.

When to Use

• Airline display - Show airline name, logo, and alliance for a given IATA code

• Flight result enrichment - Fetch airline details to display alongside search results

• Data validation - Verify an airline code and retrieve its metadata

What You Get

• Airline details including name, IATA/ICAO codes, and country

• Alliance membership (Star Alliance, oneworld, SkyTeam, or Vanilla Alliance)

• Logo URL for displaying the airline's logo in your UI

• Active status indicating whether the airline is currently operating

Quick Start

Provide the 2-letter IATA code (e.g., AA for American Airlines) in the URL path.

Overview

Retrieve detailed information for a specific airport using its 3-letter IATA code.

When to Use

• Airport display - Show airport name, city, and country for a given IATA code

• Flight result enrichment - Fetch airport details to display alongside origin/destination in search results

• Autocomplete validation - Verify an airport code and retrieve its full details

What You Get

• Airport details including name, city, country, and timezone

• IATA and ICAO codes for the airport

• Geographic coordinates (latitude and longitude)

• Country and city information for display purposes

Quick Start

Provide the 3-letter IATA code (e.g., JFK for John F. Kennedy International) in the URL path.

Overview

Retrieve a lightweight list of airport IATA codes with names for autocomplete and lookup purposes.

When to Use

• Autocomplete dropdowns - Populate airport search inputs with a full list of codes and names

• Client-side filtering - Download the full list once and filter locally

• Code validation - Build a lookup table of valid airport codes

What You Get

• IATA codes for all airports in the database

• Airport names paired with each code

• Filtered results when the q query parameter is provided

Quick Start

Call with no parameters to get all airport codes and names. Use the q parameter to filter by name or code.

Overview

Search for available flights with real-time pricing from multiple providers. The itinerary must be sent as a non-empty legs array. Each leg follows the provider SearchLeg shape: required origin, destination, and date (YYYY-MM-DD); optional direction (OUTBOUND or INBOUND); optional per-leg filters that override global filters for that leg only.

Not supported: top-level origin, destination, departureDate, or returnDate — use legs only.

When to Use

• Listings — live prices for search results UI

• One-way, round-trip, or multi-city — one leg per segment, in order

• Filtering — cabin class, stops, price, refundability, times (globally or per leg)

What You Get

• Offers from multiple providers

• Itineraries with segments, layovers, and durations

• Price breakdown (fares, taxes, fees) and baggage hints

Key Features

• Multi-provider aggregation in one request

• Global filters, sort

Quick Start

Required: legs (at least one object with origin, destination, date), adults (≥ 1), currency

Date limit: each leg date must not be more than 11 months from today.

Round-trip: two legs (e.g. outbound then return with direction OUTBOUND / INBOUND). One-way: one leg.

Booking

The response includes searchUrl, the same search on book.maqami.co. Flights are booked and paid only on MAQAMI's website: post_flights_verify re-prices the chosen offer and returns its checkoutUrl.

Overview

Confirm a flight offer is still available and retrieve the latest pricing before proceeding to booking. Returns the checkout link for the verified offer.

When to Use

• Pre-booking validation - Confirm offer availability after user selects a flight

• Price confirmation - Show users the guaranteed price

• Fare rule retrieval - Get the latest cancellation and change policies

What You Get

• Verified pricing with up-to-date fare breakdown

• changes (when present) — cabin/fare flags, human-readable messages, and pricing (old / new full OfferPricing) instead of deprecated scalar currency/prices

• Journey pricing — original (provider/PCC) and display (customer) price breakdown per provider FlattenedJourney

• Fare family details including name and included amenities

• Baggage policy for each passenger type and segment

• Booking terms including cancellation and change fee rules

Key Features

• Real-time price check: Confirms current availability and price with the provider

• Updated baggage info: Returns the latest baggage allowances at time of verification

• Fare rules: Includes cancellation and change fee policies before commitment

Quick Start

Provide the offerId from post_flights_rates search results. The verified offer data gives the customer a booking summary.

Booking

The response includes checkoutUrl (https://book.maqami.co/flights/booking?offerId=...). Flights are booked and paid only on MAQAMI's website: the checkoutUrl opens checkout for this fare, where the customer enters passenger details, pays securely and receives the confirmation. This tool takes no card or passport details.

Look up a confirmed flight booking: status, passengers, flights, booking references, fare rules and price.

Requires the bookingId and the email used to book: the server only returns or changes a booking when they match.

Overview

Retrieve the ancillary services (seats, baggage) for an existing flight booking: services that are already booked together with the live catalog of services that can still be booked.

When to Use

• Post-booking upsell - Show the passenger which seats and bags they can still add after the booking was created

• Booking management - Display the services already attached to the booking with the prices that were charged

• Availability refresh - The bookable catalog is fetched live from the provider on every call

What You Get

• groups - Bookable services grouped by category (seat, baggage) with post-margin prices and encoded serviceIds

• bookedServices - Services already attached to the booking; entries booked through the API carry the exact price that was charged at attach time

• expiresAt - Validity window of the bookable catalog

Key Features

• Read-only: Safe to call at any time; the catalog reflects live availability

• Consistent pricing: Booked services echo the post-margin amounts the user actually paid

Quick Start

Provide the bookingId from the flight booking confirmation.

On a ticketed booking (status CONFIRMED) groups lists only what can be sold after ticketing (provider-dependent, usually baggage) and only when canAddServicesAfterTicketing is true; buy them with POST /flights/bookings/{bookingId}/services and /services/confirm.

Requires the bookingId and the email used to book: the server only returns or changes a booking when they match.

Overview

Returns refund eligibility, estimated refund amounts, and penalty details for a booking without actually cancelling it. Useful before post_flights_bookings_bookingid_cancellations to understand the financial impact of cancellation.

When to Use

• Pre-cancellation review — Show the customer the potential maximum refund (not guaranteed) before they confirm cancellation

• Refund estimation — Display potential maximum refund and penalty amounts in the booking management UI (refund is not granted until cancel completes)

• Eligibility check — Determine whether the booking is within the void window (isVoidable) or eligible for a partial refund (isRefundable)

What You Get

• confidence — How reliable the quote is (confirmed, estimated, heuristic, unknown)

• isRefundable / isVoidable — Quick eligibility flags

• refund / penalty — Aggregate amounts with margin applied. refund is the potential maximum the airline may refund — not a granted/guaranteed amount

• penalties[] — Itemised penalty breakdown when available

• tickets[] — Per-ticket detail when available

• destination — Where the refund goes

• vouchers[] — Airline travel vouchers / credit-shells when destination is voucher; omitted when absent. Distinct from MAQAMI discount voucherCode on prebook

Concurrent cancellation

If a cancellation was already submitted and is still awaiting provider confirmation, this endpoint returns HTTP 409 with code 49007 (CONCURRENT_OPERATION). A new quote is not available until that cancellation completes or fails.

Refund amount caveat

The refund amount on a cancellation quote is the potential maximum the airline may refund if cancellation proceeds under the quoted conditions. It is an estimate for decision-making only and is not granted — the final refund (if any) is determined when cancellation completes and may be lower or zero. The refund may arrive asynchronously once the airline determines the final amount.

Key Features

• Non-destructive — Does not cancel the booking; safe to call before user confirmation

• Margin-applied pricing — All amounts (including voucher pricing.display) reflect the same margin applied at booking time

Quick Start

Provide the bookingId from the flight booking confirmation. Each call checks the airline live.

Requires the bookingId and the email used to book: the server only returns or changes a booking when they match.

Cancel a confirmed flight booking. First show the customer the refund estimate from get_flights_bookings_bookingid_cancellations and wait for a clear yes.

Requires the bookingId and the email used to book: the server only returns or changes a booking when they match.

Overview

Retrieve a list of airlines with optional filtering by name, alliance, and active status.

When to Use

• Airline directory - Build a searchable list of airlines for display or filtering

• Alliance filtering - Filter airlines by alliance membership (Star Alliance, oneworld, SkyTeam)

• Active airlines - Retrieve only currently operating airlines

What You Get

• Full airline records including name, IATA/ICAO codes, country, alliance, and logo URL

• Alliance membership for each airline

• Active status to identify currently operating carriers

• Filtered results based on query, alliance, and active status parameters

Quick Start

Call with no parameters to get all airlines. Use q to search by name, alliance to filter by alliance, and activeOnly=true to exclude inactive carriers.

Overview

Retrieve a lightweight list of airline IATA codes with names for autocomplete and lookup purposes.

When to Use

• Autocomplete dropdowns - Populate airline search inputs with a minimal list

• Client-side filtering - Download the full list once and filter locally

• Code validation - Build a lookup table of valid airline codes

What You Get

• IATA codes for all airlines in the database

• Airline names paired with each code

• Active filtering available via the activeOnly parameter

Quick Start

Call with no parameters to get all airline IATA codes and names. Use activeOnly=true to filter out inactive airlines.

Overview

Search for airports by name, city, or IATA code using a text query. Returns matching airports for use in autocomplete and search inputs.

When to Use

• Airport autocomplete - Power origin/destination search inputs with type-ahead suggestions

• Airport discovery - Find airports in a city or region by name

• Search validation - Look up airports before constructing a flight search request

What You Get

• Matching airports ranked by relevance to the query

• IATA codes for legs[].origin and legs[].destination in post_flights_rates

• City and country details for display purposes

• Geographic coordinates for map-based interfaces

Quick Start

Provide a q query string (minimum 2 characters) to search by airport name, city, or code. Returns matching airports ordered by relevance.

Look up a tour or activity booking: status, booking details and the voucher once it is confirmed.

Requires the bookingId and the email used to book: the server only returns or changes a booking when they match.

Overview

Preview the refund amount and cancellation fee for a booking before committing to cancel it.

When to Use

• Cancellation confirmation screens - Show the guest exactly what they'll be refunded

• Support tooling - Check whether a booking is still cancellable before offering a refund

What You Get

• cancellable - Whether the booking can currently be cancelled

• policy - cancellationFee, refundAmount, refundType, estimateConfidence, currency, sellingPrice

Quick Start

Use this with the bookingId from POST /experiences/bookings. This does not cancel the booking - cancelExperienceBooking cancels it.

Requires the bookingId and the email used to book: the server only returns or changes a booking when they match.

Cancel a confirmed tour or activity booking. First show the customer the refund from getExperienceBookingCancelPreview and wait for a clear yes.

Requires the bookingId and the email used to book: the server only returns or changes a booking when they match.