MAQAMI Travel MCP Server

## 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 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](/v3.0.0/reference/get_data-countries) 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 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 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 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 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` on `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.

## 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 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 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 **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.

Search for a hotel using a semantic text query. Returns the best-matching hotel with basic details and a relevance score.

## 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 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 **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 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 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 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.

## Overview Search for places, locations, and areas using Google Places API. Returns a list of matching places that can be used to search for hotels within specific boundaries. **Pricing**: $0.01 per request ## When to Use - **Location autocomplete** - Build location search with autocomplete suggestions - **Place selection** - Let users select cities, airports, or areas - **Hotel search boundaries** - Get Place IDs to restrict hotel searches to specific regions - **Location discovery** - Find places by name or description ## What You Get - **Place list** - Multiple matching places with details - **Place IDs** - Unique identifiers for use in hotel searches - **Location information** - Names, addresses, and location types - **Formatted addresses** - Human-readable addresses for display ## Key Features - **Multiple types** - Search for cities, airports, hotels, or other place types - **Type filtering** - Specify place types (e.g., 'locality,airport,hotel') - **Smart defaults** - Automatically excludes less relevant types unless specified - **Relevance ordering** - Results sorted by relevance using Google's ranking ## Quick Start Provide a `textQuery` (e.g., "Manhattan") and optionally specify `type` to filter results. Returns matching places with Place IDs you can use in hotel searches.

## Overview Get detailed information about a specific place using its Place ID. Returns complete place details including boundaries and location information. **Pricing**: $0.01 per request ## When to Use - **Place details** - Get full information about a selected place - **Boundary information** - Retrieve place boundaries for hotel searches - **Location verification** - Verify place details before using in searches - **Display information** - Show place names and addresses to users ## What You Get - **Complete place details** - Full information about the place - **Boundary data** - Geographic boundaries for the place - **Location information** - Coordinates, address, and display name - **Place metadata** - Types, formatted address, and language ## Quick Start Provide the `placeId` in the URL path. Returns complete details for that specific place.

## 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 weather forecasts for specific locations. Response structure adapts based on the forecast time range (short-term vs. long-term). ## When to Use - **Travel planning** - Show weather forecasts for destinations - **Hotel pages** - Display weather information on hotel detail pages - **Trip preparation** - Help users plan for weather conditions - **Destination information** - Provide weather context for locations ## What You Get - **Weather forecasts** - Temperature, humidity, wind, precipitation - **Time-based structure** - Different formats for short-term (<1 week) vs. long-term forecasts - **Detailed data** - Atmospheric pressure, conditions, and summaries - **Date-specific** - Weather data for specific dates ## Key Features - **Adaptive structure** - Response format changes based on time range - **Short-term** - Detailed hourly/daily data for forecasts within one week - **Long-term** - Daily summaries for forecasts beyond one week - **Accuracy note** - Forecasts beyond one week have reduced accuracy ## Quick Start Provide location coordinates (`latitude`, `longitude`) and date range. Returns weather forecasts with appropriate detail level.

## Overview Get a ranked list of your top-performing hotels by booking volume and sales. Perfect for identifying your best-selling properties. ## When to Use - **Hotel performance dashboards** - Show top hotels by bookings - **Sales analysis** - Identify highest-revenue properties - **Inventory insights** - Understand which hotels drive business - **Partnership optimization** - Focus on high-performing hotel relationships ## What You Get - **Hotel rankings** - Hotels sorted by total bookings - **Booking counts** - Total bookings per hotel - **Sales totals** - Revenue generated per hotel - **Location data** - City and country for each hotel - **Hotel identifiers** - Hotel ID and name for reference ## Quick Start Provide a date range. Returns hotels ranked by total bookings, including booking counts, sales, and location information.

## Overview Analyze your bookings and sales by customer nationality/market. Understand which countries drive the most business. ## When to Use - **Market analysis** - Identify top-performing markets - **Geographic insights** - Understand customer distribution - **Marketing optimization** - Focus efforts on high-value markets - **Business intelligence** - Track performance by nationality ## What You Get - **Sales by nationality** - Total sales per customer country - **Booking counts** - Number of bookings per market - **Currency information** - Sales currency for each market - **Ranked results** - Markets sorted by performance ## Quick Start Provide a date range. Returns sales and booking data grouped by customer nationality (ISO country code).

## Overview Get comprehensive analytics covering sales, bookings, commissions, and revenue for your date range. This is your complete business intelligence endpoint. ## When to Use - **Executive dashboards** - Complete business overview - **Financial reporting** - Track revenue, sales, and commissions - **Booking analysis** - Monitor confirmed vs cancelled bookings - **Performance tracking** - Daily breakdowns of key metrics ## What You Get - **Sales revenue** - Daily sales totals with currency - **Booking counts** - Confirmed and cancelled bookings per day - **Commission data** - Commission earned per day - **Revenue breakdown** - Total revenue calculations - **Aggregated totals** - Summary statistics for the entire period ## Key Features - **Daily granularity** - See day-by-day performance - **Multiple currencies** - Currency information included - **Complete metrics** - Sales, bookings, commissions, and revenue in one response - **Time-series ready** - Data formatted for easy charting ## Quick Start Provide start and end dates. Returns detailed daily analytics plus aggregated totals for the period.

## Overview Get weekly aggregated sales and booking data broken down by week. Perfect for tracking week-over-week performance trends. ## When to Use - **Weekly performance dashboards** - Show sales trends by week - **Week-over-week comparisons** - Identify growth patterns - **Business reporting** - Generate weekly reports for stakeholders - **Performance monitoring** - Track weekly sales metrics ## What You Get - **Weekly sales totals** - Aggregated sales revenue per week - **Week labels** - Human-readable week identifiers (e.g., "week 12") - **Time-series data** - Ordered by week for easy charting ## Quick Start Provide a date range (`from` and `to` dates). The endpoint returns sales data grouped by week within that range.

## Overview **Hard Amendment** — Search for alternative rates at the same hotel and create ready-to-book 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 ready to be used with `POST /rates/rebook`. ## 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 ## Completing the Amendment Pass the chosen `prebookId` and the original `bookingId` as `existingBookingId` to `POST /rates/rebook`. On success, the new booking is created **and the original booking is automatically cancelled** — no separate cancellation call is needed. ## 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`). - **Payment type is honoured** — only rates that support the original booking's payment type are returned. A pay-at-property booking only sees `PROPERTY_PAY` alternatives; every other booking (including pay-later, succeeded, credit_line) only sees `NUITEE_PAY` alternatives. Pay-later eligibility additionally requires a refundable rate, which is enforced automatically when the original booking was refundable. - The nationality and currency of the original booking are used for the availability search. - If the cancellation of the original booking fails after the new booking is created, the error is logged but the new booking is still returned. ## Quick Start 1. Call this endpoint with the `bookingId` and new `occupancies`/dates — get back up to `maxPrebooks` `prebookId` values. 2. Call `POST /rates/rebook` with the chosen `prebookId` and `existingBookingId` — new booking confirmed, original cancelled.

## Overview Returns commission earnings on the account for the given date range. Each day in the range includes the total commission amount and the average commission percentage. ## When to Use - **Commission tracking** - Monitor daily commission earnings - **Revenue analysis** - Understand commission as a percentage of sales - **Financial reporting** - Report commission totals and averages by day - **Performance dashboards** - Chart commission trends over time ## What You Get - **Daily amounts** - Total commission earned per day - **Daily percentage** - Average commission percentage per day - **Time-series data** - One entry per day, ordered by date ## Quick Start Provide a date range (`from` and `to`) and optionally `sandbox` to filter by environment. Returns an array of daily commission amounts and percentages.

## Overview **Beta Feature** - 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. **Rate Limiting**: This endpoint is rate-limited to **10 requests per minute** per API key for both sandbox and production API keys. 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 (name, city, country, description) are resolved server-side from `hotelId`; the caller never supplies them. Generated copy is grounded in those facts. 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. **Note:** This is a beta feature and may be subject to changes.

## Overview Complete a flight reservation by confirming a prebook and processing payment. This is the final step in the booking flow. ## When to Use - **Final booking confirmation** - Convert a prebook into a confirmed booking - **Payment completion** - Confirm with Stripe (`TRANSACTION_ID`) or bill an enabled **credit line** (`CREDIT`) - **After service selection** - Book after optionally attaching seats or baggage via the services endpoint ## What You Get - **Confirmed booking** with a unique booking ID - **Payment confirmation** with transaction details - **Full itinerary** including all segments and passenger assignments - **Provider confirmation** reference number ## Key Features - **Idempotent**: Returns the existing booking if one already exists for the given `prebookId` - **Payments**: Stripe uses `transactionId` from prebook or attach-services after SDK confirmation; credit line uses `CREDIT` with server-side eligibility checks - **Provider confirmation**: Finalizes the reservation on the provider side ## Quick Start **Required fields**: `prebookId` (from `POST /flights/prebooks`), `payment` with `method` and, for Stripe, `transactionId` **Tip**: If you used `POST /flights/prebooks/{prebookId}/services` to attach ancillary services, use the new `transactionId` from that response, not the original prebook `transactionId`.

## Overview Initiate a flight booking session by reserving the offer with the provider, creating a payment intent when you use the Stripe SDK, and discovering available ancillary services — all in a single request. ## When to Use - **Start the booking flow** once a user has confirmed their flight selection - **Collect passenger details** and initiate payment processing - **Discover add-ons** like seat selection and extra baggage before final confirmation ## What You Get - **Prebook ID** required to complete the booking at `/flights/bookings` - **Payment intent** (`transactionId`, `secretKey`) when `usePaymentSdk` is true — for Stripe SDK integration - **Credit line snapshot** (`creditLine` in the response) when you set `includeCreditBalance: true` and your account has an enabled credit line with payment bypass - **Available services** (`servicesAttachable`) including seats and baggage options - **Booking confirmation** from the provider with reservation details ## Key Features - **End-to-end prebook flow**: Verifies offer → payment setup (Stripe payment intent or credit line) → books with provider → fetches services - **Payment options**: `usePaymentSdk: true` uses the Stripe SDK. `usePaymentSdk: false` is allowed when your user has **payment bypass** and an **enabled credit line** (no Stripe intent; call `/flights/bookings` with `payment.method: CREDIT`) - **Ancillary services**: Returns attachable services (seats, baggage) that can be added before final booking - **Same shape as /book**: Uses `offerId` instead of `prebookId` ## Quick Start **Required fields**: `offerId` (from search/verify), `contact` (name, email, phone), `passengers` (with birthday, document, and name details). **Payment**: Send `usePaymentSdk: true` for Stripe (typical). Send `usePaymentSdk: false` when paying on credit line (requires payment bypass); otherwise you receive a validation error. **Tip**: Use the `servicesAttachable` in the response to offer seat selection or extra baggage before calling `/flights/bookings`.

## Overview Add ancillary services such as seat selection or extra baggage to an existing prebook before confirming the final booking. ## When to Use - **Seat selection** - Allow users to choose specific seats after prebook - **Extra baggage** - Let users add additional luggage allowance - **Price update** - Required when services change the total booking cost - **Voucher discount** - Optional `voucherCode` when attaching services changes the total and you need the discount reflected on the new payment intent ## What You Get - **Updated prebook** with the selected services attached - **New payment intent** (`transactionId`, `secretKey`) reflecting the updated total price (after any voucher discount) - **Same response format** as `POST /flights/prebooks` for easy integration ## Key Features - **Seat selection**: Assign specific seats to each passenger and segment - **Extra baggage**: Add checked baggage or overweight allowances - **Updated payment**: Creates a new Stripe payment intent when the prebook used Stripe (`usePaymentSdk: true`). When the prebook used credit line only (`usePaymentSdk: false`), no new intent is returned - **Voucher recalculation**: When a voucher applies, the discount is recomputed against the updated total (journey + ancillaries); invalid or expired vouchers return `400` (same as prebook) - **Modifies in place**: Updates the existing prebook record in the database ## Quick Start Provide the `prebookId` in the URL path and `selectedServices` in the request body. Optionally pass `voucherCode` to apply a discount. Use the **new** `transactionId` from this response (not the original prebook `transactionId`) when confirming payment with Stripe and when calling `POST /flights/bookings`.

## 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) - **Streaming** — incremental provider results over SSE ## 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 - **SSE:** send header `Accept: text/event-stream` on `POST /flights/rates`, or `POST /flights/rates/stream` with the same JSON body - Global `filters`, `sort` ## Quick Start **Required:** `legs` (at least one object with `origin`, `destination`, `date`), `adults` (≥ 1), `currency` **Round-trip:** two legs (e.g. outbound then return with `direction` `OUTBOUND` / `INBOUND`). **One-way:** one leg.

## Overview Confirm a flight offer is still available and retrieve the latest pricing before proceeding to booking. Always verify before prebooking to avoid price discrepancies. ## When to Use - **Pre-booking validation** - Confirm offer availability after user selects a flight - **Price confirmation** - Show users the guaranteed price before they enter payment details - **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 `/flights/rates` search results. Use the verified offer data to populate a booking summary page before proceeding to `/flights/prebooks`.

## Overview Convert a guest's loyalty points into a discount voucher. Points are converted at a rate of **10 points = $1 USD** (or equivalent in the specified currency). ## When to Use - **Points redemption** - Allow guests to convert points to vouchers - **Reward fulfillment** - Create discount vouchers from points - **Loyalty rewards** - Enable points-to-cash conversion ## What You Get - **Voucher code** - Unique code the guest can use for discounts - **Voucher details** - Discount type, value, validity period, and usage limits - **Fixed amount voucher** - Voucher with a specific discount value - **Shareable voucher** - Can be used by other guests ## Key Features - **Conversion rate** - 10 points = $1 USD (or equivalent) - **Currency support** - Specify the currency for the voucher value - **Shareable** - Vouchers can be shared with other guests - **Fixed amount** - Creates a fixed discount amount voucher ## Quick Start Provide the guest ID and specify `points` (amount to redeem) and `currency` (e.g., "USD"). Returns a voucher code and details.

## 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.

## 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 (accounts with price consistency enabled) ## 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 **Step 2 of 2** in the booking flow. Complete the booking by providing guest information and payment details. This confirms the reservation and creates the final booking. ## When to Use - **After prebook** - Call this after creating a prebook session - **Payment processing** - Submit payment information to confirm booking - **Booking confirmation** - Finalize the reservation ## What You Get - **Booking ID** - Unique identifier for the confirmed booking - **Hotel confirmation code** - Reference code from the hotel - **Complete booking details** - Dates, pricing, room information - **Cancellation policies** - Terms for cancelling the booking - **Guest information** - Confirmed guest details ## Payment Methods - **ACC_CREDIT_CARD** - Direct credit card payment. In sandbox mode, this can be used to simulate a booking without getting charged. - **TRANSACTION** - Use when using Payment SDK (provide `transactionId`) - **WALLET** - Wallet payment method - **CREDIT** - Use account credit balance ## Testing When testing sandbox bookings, simply use the `ACC_CREDIT_CARD` payment method. This allows you to simulate a booking without getting charged. ## Required Information - **Prebook ID** - From the prebook step - **Guest details** - First name, last name, and email - **Payment information** - Payment method and details ## Quick Start Provide the `prebookId`, guest information (firstName, lastName, email), and payment details. Returns confirmed booking with booking ID and confirmation code.

## Overview **Step 1 of 2** in the booking flow. Create a prebook session to check the availability of a rate and get final pricing before payment. This `prebookId` needed to complete the booking. ## When to Use - **Before payment** - Always call this before completing a booking - **Rate confirmation** - Verify final pricing and availability - **Session creation** - Generate a checkout session for your payment flow ## What You Get - **Prebook ID** - Required for the next step (completing the booking) - **Final pricing** - Confirmed rates with all fees and taxes - **Terms and conditions** - Cancellation policies and booking rules - **Room details** - Complete information about the selected rooms ## Key Features - **Live availability check** - Verifies the rate is available before you collect payment - **Payment SDK support** - Set `usePaymentSdk=true` to use client-side payment forms - **Reusable** - PrebookId can be used for multiple bookings if needed ## Quick Start Provide the `offerId` from your hotel rates search and set `usePaymentSdk` (true/false). Returns a `prebookId` to use in the next step. **Next Step**: Use the `prebookId` with `/rates/book` to complete the booking.

## Overview **Step 2 of 2** in the **hard amendment** flow. Use a `prebookId` produced by `POST /bookings/{bookingId}/alternative-prebooks` to create the replacement booking. On success, the new booking is created **and the original booking is automatically cancelled** — you do **not** need to call the cancel endpoint. ## When to Use - **After alternative-prebooks** — Once the guest has chosen one of the alternative prebooks returned by `POST /bookings/{bookingId}/alternative-prebooks`. - **Date or occupancy changes** — The guest needs different check-in/check-out dates or a different number of adults/children at the same hotel. - **Hard amendments only** — For simple guest-name updates use `PUT /bookings/{bookingId}/amend` instead. ## How It Works 1. The provided `prebookId` is validated against the booking referenced by `existingBookingId` (it must have been produced by an `alternative-prebooks` call for that booking). 2. The new booking is created with the supplier using the alternative rate. 3. The original booking is then automatically cancelled. If the cancellation fails after the new booking is confirmed, the error is logged but the new booking is still returned — contact support to reconcile. ## Payment - No payment is collected on this endpoint. The `payment.method` value is ignored — the request body must still include a `payment` object to satisfy the schema, but the server forces the method to `NONE` internally. Any price delta between the original and new rate is settled out of band. ## Refundable vs Non-refundable Originals - **Refundable original** — Returns `200 OK` with the new booking, and the original is cancelled immediately. - **Non-refundable original** — Returns `202 Accepted` with a booking amendment record. The request is queued for the Nuitee operations team to handle manually (the original booking may incur cancellation fees). ## Required Information - **prebookId** — A prebook session returned by `POST /bookings/{bookingId}/alternative-prebooks`. - **existingBookingId** — The `bookingId` of the original confirmed booking being replaced. Must match the `bookingId` that produced the prebook. - **holder** and **guests** — Same structure as `POST /rates/book`. If `holder` fields are empty they are copied from the original booking. ## Quick Start 1. Call `POST /bookings/{bookingId}/alternative-prebooks` and pick one of the returned `prebookId` values. 2. Call this endpoint with that `prebookId`, the original `bookingId` as `existingBookingId`, and guest information. 3. On success, the new booking is confirmed and the original is cancelled — no further calls are needed.

## Overview Create discount vouchers that customers can apply to their hotel and flight bookings. Supports percentage discounts, fixed amounts, and points redemption vouchers. ## When to Use - **Promotional campaigns** - Create discount codes for marketing - **Customer rewards** - Generate vouchers for loyal customers - **Special offers** - Create time-limited discount vouchers - **Points redemption** - Generate vouchers from loyalty points ## What You Get - **Voucher object** - Complete voucher details including code and settings - **Usage tracking** - Remaining uses count - **Validation** - Confirmation that the voucher was created successfully ## Key Features - **Multiple discount types** - Percentage, fixed amount, or points redemption - **Flexible rules** - Set minimum spend, maximum discount, and usage limits - **Validity control** - Define start and end dates - **Guest assignment** - Optionally assign to specific guests - **Applies to hotels and flights** - Pass the `voucherCode` in the `voucherCode` field of `/rates/prebook` (hotels) or `/flights/prebooks` (flights) to redeem the discount at checkout ## Quick Start Provide voucher code, discount type, value, currency, validity dates, usage limits, and status. Returns the created voucher with all details.

## Overview Cancel an existing confirmed booking. Cancellation policies determine whether a full refund, partial refund, or charges apply. ## When to Use - **Guest cancellation** - Allow guests to cancel their bookings - **Administrative cancellation** - Cancel bookings from admin panels - **Policy enforcement** - Apply cancellation policies automatically ## What You Get - **Cancellation status** - Success or failure of cancellation - **Charges information** - Any fees or charges that apply - **Refund details** - Amount refunded (if applicable) - **Updated booking status** - Booking marked as cancelled ## Cancellation Outcomes - **CANCELLED** - Fully refundable, no charges - **CANCELLED_WITH_CHARGES** - Non-refundable or past cancellation deadline, charges apply - **Cancellation policies** - Applied automatically based on booking terms ## Important Notes - **Non-refundable bookings** - Will be cancelled but still charged (status: CANCELLED_WITH_CHARGES) - **Policy enforcement** - Cancellation policies are automatically applied - **Past deadline** - Cancellations after the policy deadline may incur charges ## Quick Start Provide the `bookingId` in the URL path. Returns cancellation status and any applicable charges or refunds.

## Overview Update guest information (name and email) for an existing booking. Useful for correcting typos or updating guest details after booking. ## When to Use - **Name corrections** - Fix typos in guest names - **Email updates** - Update guest email addresses - **Guest changes** - Change guest information after booking - **Support requests** - Update booking details per customer requests ## What You Get - **Confirmation** - Success message when amendment is complete - **Updated booking** - Booking reflects the new guest information ## Editable Fields - **First name** - Guest's first name - **Last name** - Guest's last name - **Email** - Guest's email address - **Remarks** - Optional additional notes ## Limitations - **Holder only** - Only the booking holder's information can be updated - **Name and email** - Other guest details cannot be amended ## Quick Start Provide the `bookingId` and updated guest information (firstName, lastName, email). Optionally include remarks. Returns confirmation of the update.

## Overview Configure your loyalty program settings, including enabling/disabling the program and setting cashback rates. ## When to Use - **Program activation** - Enable or disable your loyalty program - **Rate adjustments** - Update cashback percentages - **Program management** - Change loyalty program configuration - **A/B testing** - Test different cashback rates ## What You Get - **Confirmation** - Updated program settings - **Status** - Current program status (enabled/disabled) - **Cashback rate** - Active cashback percentage ## Key Features - **Enable/disable** - Turn your loyalty program on or off - **Cashback control** - Set the percentage guests earn (e.g., 0.1 = 10%) - **Immediate effect** - Changes apply to new bookings right away ## Quick Start Send the new `status` ("enabled" or "disabled") and `cashbackRate` (decimal, e.g., 0.1 for 10%). Both fields are required.

## Overview Configure your supply customization preferences, including enabling or disabling advanced accessibility options for hotel searches. ## When to Use - **Enable features** - Turn on advanced accessibility filtering - **Customize supply** - Adjust how hotel results are filtered - **Accessibility control** - Control whether advanced accessibility hotels are included ## What You Get - **Updated settings** - Confirmation with your new configuration - **Current state** - Your active supply customization settings ## Key Features - **Advanced accessibility** - Enable/disable filtering for hotels with advanced accessibility features - **Search impact** - Settings affect hotel search results ## Quick Start Provide `advancedAccessibility` (boolean) to enable or disable advanced accessibility options. Returns updated settings.

## Overview Modify an existing voucher's settings, including discount values, validity periods, usage limits, and status. ## When to Use - **Extend validity** - Update voucher end dates - **Adjust discounts** - Change discount values or types - **Update limits** - Modify usage limits or minimum spend - **Status changes** - Activate or deactivate vouchers ## What You Get - **Confirmation** - Success message when voucher is updated - **Updated voucher** - Voucher reflects the new settings ## Important Notes - **Read-only if used** - Vouchers that have been used in bookings cannot be modified (returns 404) - **All fields required** - Must provide all required fields, not just the ones you want to change ## Quick Start Provide the voucher ID and updated fields. Returns confirmation of the update.

## Overview Quickly activate or deactivate a voucher without updating other fields. Perfect for temporarily disabling vouchers. ## When to Use - **Temporary disable** - Deactivate vouchers without deleting them - **Reactivate vouchers** - Turn inactive vouchers back on - **Status management** - Quickly toggle voucher availability ## What You Get - **Confirmation** - Success message confirming status change - **Updated status** - Voucher status changed to active or inactive ## Quick Start Provide the voucher ID and the new `status` ("active" or "inactive"). Returns confirmation of the status update.

## Overview Get all bookings associated with your API key, with optional filtering by date ranges. Perfect for generating reports and managing your booking inventory. ## When to Use - **Booking reports** - Generate reports of all bookings - **Date range queries** - Find bookings within specific date ranges - **Administrative overview** - View all bookings in your system - **Analytics** - Analyze booking patterns and trends ## What You Get - **Complete booking list** - All bookings linked to your API key - **Filtered results** - Optional filtering by stay dates or booking creation dates - **Booking details** - Full information for each booking - **Status information** - Current status of each booking ## Filtering Options - **Stay period** - Filter by check-in/check-out date range (`startDate`, `endDate`) - **Booking period** - Filter by when bookings were created (`bookingStartDate`, `bookingEndDate`) - **Status** - Filter by booking status (optional) ## Quick Start No parameters required for all bookings. Optionally provide date ranges to filter results. Returns all matching bookings with complete details.

## Overview Get complete details for a specific booking by its booking ID. Returns all booking information including status, guest details, pricing, and cancellation policies. ## When to Use - **Booking details page** - Display complete booking information - **Status checks** - Verify current booking status - **Confirmation lookup** - Retrieve booking confirmation details - **Support queries** - Look up booking information for customer service ## What You Get - **Complete booking details** - All information about the booking - **Booking status** - Current status (confirmed, cancelled, etc.) - **Guest information** - Name, email, and contact details - **Stay information** - Check-in/check-out dates, hotel details - **Pricing breakdown** - Total cost, taxes, fees, and payment status - **Cancellation policies** - Terms and conditions for cancellation - **Hotel confirmation** - Hotel confirmation code and reference ## Quick Start Provide the `bookingId` in the URL path. Returns complete booking details including status and all associated information.

## Overview Returns analytics on the source markets (guest nationality) of bookings. Compares the current period to the previous period of equal length, with per-nationality booking counts, sales in USD, average booking value, and period-over-period change. ## When to Use - **Source market analysis** - See which nationalities drive the most bookings and sales - **Period comparison** - Compare current vs previous period totals and per-nationality growth - **Geographic dashboards** - Track performance by guest country (ISO code) - **Marketing and sales planning** - Identify growing or declining markets ## What You Get - **Period definition** - Date ranges for current and previous periods - **Summary** - Total sales (USD), change percent/amount, and count of nationalities - **Per-nationality data** - For each guest nationality: booking count, total sales USD, avg booking value; current and previous period; and change (sales percent/amount, booking count change) - **New markets** - Nationalities with no previous-period data have `previous_period: null` and change expressed as 100% growth ## Quick Start Pass query parameters `from`, `to`, and `sandbox`. The API derives the previous period (same length, immediately before). Returns period metadata, summary totals, and an array of nationality-level metrics.

## Overview Returns analytics on **properties** (hotels): per-hotel sales, buying price, profit, and profit margin. Compares the current period to the previous period of equal length. Results are ordered by current-period sales (highest first) and limited by the `limit` parameter. ## When to Use - **Property performance** - See which hotels drive the most sales and profit - **Period comparison** - Compare current vs previous period sales, profit, and bookings per hotel - **Profit analysis** - Track total_buying_price_usd, total_profit_usd, and profit_margin_percent by property - **Top properties dashboards** - Rank hotels by sales or profit ## What You Get - **Period definition** - Date ranges for current and previous periods - **Summary** - Totals for sales (USD), profit (USD), bookings, count of hotels in the result, and average profit margin percent; all with period-over-period change - **Per-hotel data** - For each property: hotel_id, hotel_name, city, country; current and previous period (booking_count, total_sales_usd, avg_booking_value_usd, total_buying_price_usd, total_profit_usd, profit_margin_percent); and change (sales/profit percent and amount, booking_count_change) - **New properties** - Hotels with no previous-period data have `previous_period: null` ## Quick Start Pass query parameters `from`, `to`, `sandbox`, and optionally `limit` (default controls how many top hotels are returned). The API derives the previous period (same length, immediately before). Returns period metadata, summary totals, and an array of hotel-level metrics.

## Overview Returns analytics on **destinations** (the country where the hotel is located). Compares the current period to the previous period of equal length, with per-destination booking count, hotel count, sales in USD, average booking value, and period-over-period change. ## When to Use - **Destination performance** - See which countries (hotel locations) drive the most bookings and sales - **Period comparison** - Compare current vs previous period totals and per-destination growth - **Geographic dashboards** - Track performance by destination country (ISO code) - **Inventory and commercial planning** - Identify growing or declining destinations ## What You Get - **Period definition** - Date ranges for current and previous periods - **Summary** - Total sales (USD), change percent/amount, and count of destination countries - **Per-destination data** - For each country: booking count, hotel count, total sales USD, avg booking value; current and previous period; and change (sales percent/amount, booking count change) - **New or inactive destinations** - Countries with no previous-period data have `previous_period: null`; destinations with no current-period activity may have zeros and negative change ## Quick Start Pass query parameters `from`, `to`, and `sandbox`. The API derives the previous period (same length, immediately before). Returns period metadata, summary totals, and an array of destination-level metrics.

## Overview Retrieve a complete list of all guests enrolled in your loyalty program with their points balance and booking history. ## When to Use - **Guest management** - View all loyalty program members - **Points administration** - Check points balances across all guests - **Customer support** - Look up guest information quickly - **Reporting** - Generate lists of loyalty program participants ## What You Get - **Guest profiles** - Name, email, phone number for each guest - **Points balance** - Current points and upcoming points (pending from bookings) - **Booking history** - List of booking IDs associated with each guest - **Account metadata** - Creation and update timestamps ## Quick Start No parameters required. Returns all guests with their loyalty program details.

## Overview Get detailed information about a specific guest by their ID, including loyalty points and booking history. ## When to Use - **Customer profiles** - Display guest information on their account page - **Points lookup** - Check a specific guest's points balance - **Booking history** - Show a guest's past bookings - **Support tickets** - Quickly access guest details during support ## What You Get - **Complete guest profile** - Personal information (name, email, phone) - **Points summary** - Current available points and upcoming points - **Booking list** - All booking IDs associated with this guest - **Account status** - Account creation and update information ## Quick Start Provide the guest ID in the URL path. Returns complete guest information including points and bookings.

## Overview Get all loyalty transactions for a specific guest, showing points earned and cashback rates used for each booking. ## When to Use - **Points history** - Show guests their points earning history - **Transaction details** - Display detailed booking transactions - **Cashback tracking** - Show cashback rates applied to bookings - **Account statements** - Generate points activity reports ## What You Get - **Transaction list** - All loyalty transactions for the guest - **Points per booking** - Points earned (or deducted) for each booking - **Cashback rates** - Cashback percentage used for each transaction - **Booking references** - Booking IDs linked to each transaction - **Timestamps** - When each transaction occurred ## Quick Start Provide the guest ID in the URL path. Returns all loyalty transactions with points and cashback details.

## Overview Get a guest's current available points and upcoming points (points pending from confirmed bookings). ## When to Use - **Points display** - Show points balance on guest account pages - **Points checking** - Quick lookup of available points - **Pending points** - Display points that will be awarded after stays - **Balance verification** - Verify points before redemption ## What You Get - **Current points** - Points available for immediate redemption - **Upcoming points** - Points that will be awarded from confirmed bookings ## Quick Start Provide the guest ID in the URL path. Returns both current and upcoming points balances.

## Overview Retrieve all vouchers available to a specific guest, including discount codes, validity periods, and usage limits. ## When to Use - **Voucher display** - Show available vouchers on a guest's account page - **Discount management** - Check which vouchers a guest can use - **Validity checking** - Verify if vouchers are still active - **Usage tracking** - Monitor voucher usage counts ## What You Get - **Voucher list** - All vouchers assigned to the guest - **Discount details** - Type (percentage/fixed), value, and currency - **Validity period** - Start and end dates for each voucher - **Usage information** - Current usage count and usage limits - **Status** - Active/inactive status of each voucher ## Quick Start Provide the guest ID in the URL path. Returns all vouchers available to that guest.

## Overview Get a paginated list of all vouchers in your system, including active and inactive vouchers with their current status. ## When to Use - **Voucher management** - View all vouchers in your admin panel - **Inventory overview** - See all available discount codes - **Status monitoring** - Check which vouchers are active - **Reporting** - Generate lists of all vouchers for analysis ## What You Get - **Complete voucher list** - All vouchers with full details - **Discount information** - Type, value, and currency for each voucher - **Validity status** - Start/end dates and current status - **Usage tracking** - Remaining uses for each voucher ## Pagination Results are paginated. Use the `page` and `limit` query parameters to navigate through the list, e.g. `/vouchers?page=5&limit=10`. ## Quick Start Optionally provide `page` and `limit` query parameters. Returns a paginated list of vouchers with complete details including codes, discounts, validity, and usage counts.

## Overview Get a complete history of all voucher redemptions across your system, showing which vouchers were used, when, and for which bookings. ## When to Use - **Usage analytics** - Track voucher redemption patterns - **Performance reporting** - See which vouchers are most popular - **Audit trail** - Maintain records of voucher usage - **Marketing insights** - Understand voucher effectiveness ## What You Get - **Usage records** - Each voucher redemption with full details - **Booking information** - Booking IDs and hotel or flight names where vouchers were used - **Guest details** - Email addresses of guests who used vouchers - **Discount amounts** - Total discount applied per usage - **Timestamps** - When each voucher was redeemed ## Quick Start No parameters required. Returns complete usage history for all vouchers across hotel and flight bookings, including booking details and discount amounts.

## Overview Get complete details for a specific voucher by its ID, including discount rules, validity, and usage information. ## When to Use - **Voucher lookup** - Find details for a specific voucher code - **Validation** - Verify voucher details before applying to bookings - **Details display** - Show voucher information to customers - **Support** - Look up voucher information during customer service ## What You Get - **Complete voucher details** - All information about the voucher - **Discount rules** - Type, value, minimum spend, maximum discount - **Validity information** - Start/end dates and current status - **Usage data** - Current usage count and remaining uses ## Quick Start Provide the voucher ID in the URL path. Returns complete voucher information.

## Overview List confirmed flight bookings owned by the authenticated user. Supports an optional PNR + last-name lookup for retrieving a single booking, and optional `customTags` filtering. ## When to Use - **"My bookings" page** - Display the authenticated user's confirmed flight bookings - **PNR lookup** - Retrieve a single booking by `airlinePnr` and a passenger's `lastName` - **Tag filtering** - Narrow results with `customTags=KEY:VALUE` labels set at book time - **Booking management** - Build dashboards or list views of past and upcoming reservations ## What You Get - **Confirmed bookings only** - Returns records persisted from the booking flow; - **Full booking objects** with status, journey, passengers, order reference, pricing, and optional `customTags` - **Sandbox isolation** - Sandbox and live bookings are scoped by the API key used ## Key Features - **Owner-scoped**: Only returns bookings belonging to the authenticated user - **PNR + last-name lookup**: When both `airlinePnr` and `lastName` are supplied, returns a single matching booking; both are required together - **Custom tags filter**: Optional `customTags` query AND-filters on labels attached at `POST /flights/bookings` - **Stable response shape**: `data` is always an array containing exactly one element with a `bookings` array ## Quick Start Call with no query parameters to list all bookings for the authenticated user. To look up a specific booking, pass both `airlinePnr` and `lastName`. Filter with `customTags=SOURCE:GOOGLE`.

## Overview Retrieve complete details of a confirmed flight booking using its unique booking ID. ## When to Use - **Booking confirmation page** - Display full itinerary after booking completes - **Booking management** - Retrieve details for an existing reservation - **Itinerary display** - Show passengers, segments, and confirmation numbers - **Status checks** - Verify booking status for a given booking ID ## What You Get - **Complete itinerary** with all flight segments and connection details - **Passenger manifest** with names, documents, and seat assignments - **Booking status** and provider confirmation reference - **Pricing breakdown** including taxes and fees paid ## Key Features - **Full booking record**: Returns all data associated with the confirmed booking - **Provider reference**: Includes the provider-side booking confirmation number - **Passenger details**: Complete passenger information for all travelers ## Quick Start Provide the `bookingId` (returned from `POST /flights/bookings`) in the URL path. Returns the complete booking record.

Capture Stripe payment then confirm cart with experiences-api. Cart status `completed` maps to dispatcher `PENDING_CONFIRMATION`; final `CONFIRMED` arrives via webhook. Cart status `ERROR` returns 502.

Poll booking status while pending confirmation or retrieve voucher after webhook confirms.

## Overview Retrieve full details for a specific tour, including description, media, inclusions, and pricing context. ## When to Use - **Product pages** - Display a tour detail view before the user selects dates - **Comparison** - Show full metadata when comparing activities - **Content enrichment** - Fetch descriptions and images for marketing surfaces ## What You Get - **Complete tour profile** - Title, description, duration, and highlights - **Media** - Images and cover assets - **Practical info** - Meeting points, cancellation policy, and inclusions - **Localized pricing** - Prices in the requested currency ## Quick Start Provide the tour `id` in the URL path plus required `language` and `currency` query parameters.

## Overview Retrieve available dates and time slots for a specific tour so users can pick when to attend. ## When to Use - **Date pickers** - Populate a calendar or slot selector on the tour page - **Availability checks** - Confirm a tour runs on the user's travel dates - **Booking flow** - Gate the checkout path until a valid slot is selected ## What You Get - **Available dates** - Days the tour can be booked - **Time slots** - Start times per date where applicable - **Capacity hints** - Whether slots are still bookable ## Quick Start Provide the tour `id` in the URL path and the required `language` query parameter.

## Overview Resolve priced booking options, time slots, and required guest inputs for a selected tour date and participant mix. ## When to Use - **Option/slot pickers** - Show available variants and start times for a date - **Live pricing** - Display authoritative slot `retailPrice` values - **Checkout forms** - Collect `requiredInputs` before proceeding to payment (future checkout slice) ## What You Get - **Booking options** - `optionId`, title, and `requiredInputs` - **Time slots** - `dateTime`, `isAvailable`, and slot-level `pricing.priceSummary.retailPrice` - **Participant mapping** - Uses `ticketCategory` keys from availability (e.g. `adult`, `child`) ## Quick Start POST a body with `language`, `currency`, `date` (`YYYY-MM-DD`), and `participants` to `/experiences/tours/{id}/booking-options`. Use slot `retailPrice` for display and checkout handoff.

## Overview Retrieve normalized guest reviews and ratings for a specific tour. ## When to Use - **Review sections** - Display guest feedback on tour detail pages - **Trust building** - Show authentic ratings before booking - **Decision support** - Help users evaluate tours before selecting dates ## What You Get - **Guest reviews** - Review text, ratings, and dates - **Pagination** - `limit` and `offset` query parameters - **Localized content** - Reviews in the requested language where available ## Quick Start Provide the tour `id` in the URL path plus required `language` and `currency` query parameters.

## Overview Retrieve aggregated historical price index data for all hotels in a specific city. Returns average per-night prices aggregated by calendar day across all hotels in the city, providing city-level pricing trends. **⚠️ Beta Feature**: This endpoint is currently in beta. The API structure and behavior may change in future versions. **Pricing**: $0.05 per request **Rate Limiting**: This endpoint is rate-limited to **10 requests per minute** for both sandbox and production API keys. Exceeding this limit will result in a `429 Too Many Requests` response. ## When to Use - **City-level price analysis** - Analyze average pricing trends for an entire city - **Market research** - Compare pricing across different cities - **Destination pricing** - Get aggregated pricing data for a destination - **City pricing dashboards** - Build visualizations of city-level price trends ## What You Get - **City-level aggregation** - Average prices aggregated across all hotels in the city (up to 1,000 hotels) - **Per-night prices** - Average price per night for each calendar day - **Daily aggregation** - One entry per day with aggregated pricing data - **Future dates only** - Only returns data for future check-in dates (defaults to today onwards) ## Key Features - **Automatic hotel discovery** - Automatically finds hotels in the specified city (up to 1,000) - **City-level aggregation** - Prices are averaged across all hotels in the city, not per hotel - **Per-night pricing** - Prices are normalized to per-night rates - **Future-focused** - Only queries check-in dates in the future by default - **Flexible date ranges** - Optional date filtering with sensible defaults ## Parameters - `countryCode` (required): ISO-2 country code (e.g., 'US', 'GB', 'FR') - `cityName` (required): City name (case-insensitive) - `fromDate` (optional): Start date in YYYY-MM-DD format. Defaults to today. - `toDate` (optional): End date in YYYY-MM-DD format. Defaults to 1 year from today.

## Overview Retrieve historical price index data for a list of hotels. Returns average per-night prices aggregated by calendar day, allowing you to analyze pricing trends and patterns. **⚠️ Beta Feature**: This endpoint is currently in beta. The API structure and behavior may change in future versions. **Pricing**: $0.05 per request **Rate Limiting**: This endpoint is rate-limited to **10 requests per minute** for both sandbox and production API keys. Exceeding this limit will result in a `429 Too Many Requests` response. ## When to Use - **Price trend analysis** - Analyze how hotel prices change over time - **Price forecasting** - Use historical data to predict future pricing - **Market research** - Compare pricing across multiple hotels - **Pricing dashboards** - Build visualizations of hotel price trends ## What You Get - **Per-night prices** - Average price per night for each calendar day - **Daily aggregation** - One entry per day with aggregated pricing data - **Multiple hotels** - Query up to 50 hotels in a single request - **Future dates only** - Only returns data for future check-in dates (defaults to today onwards) ## Key Features - **Per-night pricing** - Prices are normalized to per-night rates regardless of stay duration - **Daily aggregation** - Each day has a single entry with the average per-night price across all stays that include that day - **Future-focused** - Only queries check-in dates in the future by default - **Flexible date ranges** - Optional date filtering with sensible defaults - **Hotel limit** - Maximum 50 hotel IDs per request ## Parameters - `hotelIds` (required): Comma-separated list of hotel IDs. Maximum 50 hotel IDs allowed. - `fromDate` (optional): Start date in YYYY-MM-DD format. Defaults to today. - `toDate` (optional): End date in YYYY-MM-DD format. Defaults to 1 year from today.

## Overview Search for bookings by guest ID or client reference. Perfect for displaying a guest's booking history or finding bookings by your internal reference codes. ## When to Use - **Guest booking history** - Show all bookings for a specific guest - **Reference lookup** - Find bookings by your internal reference codes - **Booking management** - List bookings for administrative purposes - **Customer support** - Quickly find bookings for support tickets ## What You Get - **Booking list** - All matching bookings with complete details - **Guest information** - Name, email, and contact details - **Stay details** - Check-in/check-out dates and hotel information - **Payment status** - Current payment and booking status - **Booking references** - Booking IDs and confirmation codes ## Search Options - **By guest ID** - Find all bookings for a specific guest - **By client reference** - Find bookings using your internal reference codes - **By customTags** - Narrow results by booking labels using `customTags=KEY:VALUE,KEY2:VALUE2` (AND across keys) - **Optional timeout** - Set request timeout (default 4 seconds) ## Quick Start Provide either `guestId` or `clientReference` (or both). Returns matching bookings with full details.

## Overview Retrieve your current loyalty program configuration, including whether it's active and what cashback rate is set. ## When to Use - **Settings display** - Show current program configuration in admin panels - **Status checks** - Verify if the loyalty program is enabled - **Rate verification** - Check current cashback rates - **Configuration review** - Review program settings before making changes ## What You Get - **Program status** - Whether the program is enabled or disabled - **Cashback rate** - Current percentage guests earn - **Currency** - Cashback currency setting ## Quick Start No parameters required. Returns current loyalty program settings.

Temp hold via experiences-api validate and Stripe PaymentIntent creation. Phase 1 requires `usePaymentSdk: true`.

## Overview Retrieve details of an existing prebook session by its ID. Use this to fetch prebook information without creating a new session. ## When to Use - **Session recovery** - Retrieve prebook details if you've stored the prebookId - **Status checks** - Verify prebook session details before completing booking - **Payment integration** - Get prebook data needed for payment processing - **Credit balance** - Optionally include updated credit balance information ## What You Get - **Complete prebook data** - All information from the prebook session - **Rate details** - Pricing, room types, and availability - **Terms and conditions** - Cancellation policies and booking terms - **Credit balance** - Optional updated credit balance (if requested) ## Quick Start Provide the `prebookId` in the URL path. Optionally include `includeCreditBalance` query parameter to get updated credit information.

## Overview Search for bookings by free-text query. Matches guest names, booking IDs, hotel names, and other booking-related fields. Results are paginated. ## When to Use - **Admin or support lookup** - Find bookings by guest name, hotel name, or partial ID - **Text search** - Search across multiple fields with a single query string - **Paginated results** - Control page size and page index via request body ## What You Get - **Matching bookings** - List of bookings matching the query with key fields - **Pagination** - `page`, `rowsPerPage`, and the search `query` echoed back - **Credit line billing** - When applicable, billing info (credit line ID, billed amount USD, billed at date, payment ID) ## Request Body - **query** (required) - Text to search for (e.g. guest name, hotel name, booking ID) - **page** - Zero-based page index (default 0) - **rowsPerPage** - Number of results per page (e.g. 5) - **sand_box** - Filter by environment (e.g. "false" for production) ## Quick Start POST a JSON body with `query`, `page`, and `rowsPerPage`. Response includes `data` array, `success`, and pagination fields.

## Overview Search available tours and activities with localized content and prices in your chosen currency. ## When to Use - **Search results** - Populate a tours listing or map view - **Destination pages** - Show activities available in a city or region - **Category browsing** - Filter tours by type, duration, or rating ## What You Get - **Tour listings** - Titles, descriptions, images, and ratings - **Localized content** - Names and descriptions in the requested language - **Prices** - Amounts in the requested currency ## Quick Start Provide required `language` and `currency` query parameters. Returns a paginated list of matching tours.

## Overview Search the cheapest fare for each departure (and, on round-trips, return) date combination across a grid of nearby dates — `±flexDays` around the dates in your request. Accepts the same `legs`-based body as `POST /flights/rates` plus optional `flexDays` (1–3, default 3). **Supported:** one-way (1 leg) or round-trip (2 legs) only. Multi-city (3+ legs) is not supported. **Not supported:** top-level `origin`, `destination`, `departureDate`, or `returnDate` — use `legs` only. ## Access Requires Flights API access and matrix enablement on your account. Matrix search is not enabled by default — contact the LiteAPI support team to request access. ## When to Use - **Flexible-date calendars** — price heatmap when the traveller can shift dates - **Cheap-date discovery** — find the lowest fare in a ±N day window before a full `/flights/rates` search - **Round-trip date pairing** — compare outbound × return combinations on one grid - **Progressive UI** — stream cells over SSE as each underlying search completes ## What You Get - **`cells`** — one entry per valid date combination, sorted by `(outboundOffset, returnOffset)` - **`cheapest`** — globally lowest-priced cell (null when nothing was priced) - **`currency`** — currency of the global cheapest cell - **`baseOutboundDate`** / **`baseReturnDate`** — the originally requested dates - **`flexDays`**, **`roundTrip`** — grid metadata - Per-cell **`price`**, **`currency`**, date offsets, and whether the underlying search was **`cached`** or **`success`** - **Margined prices** — cell `price`, `cheapest`, and `currency` include the authenticated user's rate-search margin (same as `/flights/rates`) ## Key Features - Probes `±flexDays` (1–3) around requested departure and return dates - Each underlying date pair uses normal provider caching — a later `POST /flights/rates` for a matrix date is served from warm cache - **SSE:** send header `Accept: text/event-stream` for incremental events: `matrix-start` (grid skeleton), `matrix-chunk` (one priced cell), `matrix-complete` (full sorted grid + cheapest) - Same global `filters`, `sort`, and `options` as `/flights/rates` where applicable ## Quick Start **Required:** `legs` (1 leg for one-way or 2 for round-trip, each with `origin`, `destination`, `date`), `adults` (≥ 1), `currency` **Optional:** `flexDays` (1–3, default 3), `country`, passenger counts, `filters`, `sort` **Round-trip:** two legs — outbound then return with optional `direction` `OUTBOUND` / `INBOUND`. **One-way:** one leg. After choosing a date pair from the matrix, call `POST /flights/rates` with `legs` set to those dates for full offer details.

## Overview Get your current supply customization preferences, including advanced accessibility options for hotel searches. ## When to Use - **Settings display** - Show current customization settings in admin panels - **Configuration checks** - Verify your current preferences - **Feature verification** - Check if advanced accessibility is enabled ## What You Get - **Current settings** - Your active supply customization configuration - **Advanced accessibility flag** - Whether advanced accessibility options are enabled ## Quick Start No parameters required. Returns your current supply customization settings.

## Overview Permanently remove a voucher from your system. Use with caution - deleted vouchers cannot be recovered. ## When to Use - **Cleanup** - Remove expired or unused vouchers - **Error correction** - Delete vouchers created by mistake - **Inventory management** - Remove vouchers no longer needed ## What You Get - **Confirmation** - Success message when voucher is deleted ## Important Notes - **Permanent action** - Deleted vouchers cannot be restored - **Usage check** - Ensure vouchers aren't needed before deleting ## Quick Start Provide the voucher ID in the URL path. Returns confirmation of deletion.