Official MCP RegistryListed
MAQAMI Travel
Official MCP server for MAQAMI, a hotel and flight booking platform with 3M+ hotels.
First seen 2 Oct 2026. Evidence as of 6 Oct 2026.
63
Tools
From an anonymous probe
1
Source listings
Each with its own history
3
Recorded changes
Since first seen
Tools
| Tool | Description | Behaviour |
|---|---|---|
| cancelExperienceBooking | Cancel a confirmed experience/tour booking. For traveler security, you must provide the bookingId along with the guest email address or last name. | Changes data |
| chargeFlightExtraCharges | ## Overview Confirms a pending extra-charge batch created by `/extra-charges/precharges`. Captures the Stripe PaymentIntent or bills the credit line, then appends the lines to the booking. ## Access Requires Flights API access. Post-booking extra charges are not enabled by default — contact the MAQAMI support team to request access. ## Idempotency Idempotent on `chargesId`, mirroring `POST /flights/bookings` prebookId replay: - **Already confirmed** — HTTP 200 with `data.message` and the persisted extras (no re-capture / no duplicate credit-line billing) - **Concurrent confirm** — HTTP 409 / `45035` while another confirm for the same `chargesId` holds the Redis lock; retry after the first completes ## When to Use - After the customer confirmed the Stripe PaymentIntent (status `requires_capture` / `succeeded`), or immediately for `CREDIT` bookings ## Constraints - Body only needs `chargesId` + `payment` (charge lines are encoded in `chargesId`) - `payment.method` must match the booking's original payment (`TRANSACTION_ID` or `CREDIT`) - For Stripe, `payment.transactionId` must be the id returned by precharges | Changes data |
| createExperienceBooking | 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. Public booking responses expose partner **sell** in `price` and partner earn in `commission` / `clientCommission`. Provider retail / invoice (`providerPayment`) is omitted. | Changes data |
| get_bookings_bookingid | Retrieve details for a confirmed hotel booking. For traveler privacy, you must provide the bookingId along with the guest email address or last name used during booking. | Read-only |
| get_data_chains | ## 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. | Read-only |
| get_data_cities | ## 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. | Read-only |
| get_data_countries | ## 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. | Read-only |
| get_data_currencies | ## 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. | Read-only |
| get_data_facilities | ## 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. | Read-only |
| get_data_flights_airlines | ## 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. | Read-only |
| get_data_flights_airlines_iatas | ## 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. | Read-only |
| get_data_flights_airlines_iatas_iatacode | ## 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. | Read-only |
| get_data_flights_airports | ## 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. | Read-only |
| get_data_flights_airports_iatas | ## 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. | Read-only |
| get_data_flights_airports_iatas_iatacode | ## 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. | Read-only |
| get_data_hotel | ## 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. | Read-only |
| get_data_hotel_ask | ## 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. | Read-only |
| get_data_hotel_search | Search for a hotel using a semantic text query. Returns the best-matching hotel with basic details and a relevance score. | Read-only |
| get_data_hotels | ## 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. | Read-only |
| get_data_hotels_room_search | ## 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. | Read-only |
| get_data_hotels_semantic_search | ## 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. | Read-only |
| get_data_hoteltypes | ## 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. | Read-only |
| get_data_iatacodes | ## 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. | Read-only |
| get_data_languages | ## 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. | Read-only |
| get_data_places | ## 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. | Read-only |
| get_data_places_placeid | ## 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. | Read-only |
| get_data_reviews | ## 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. | Read-only |
| get_data_weather | ## 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. | Read-only |
| get_flights_bookings_bookingid | Retrieve complete details of a confirmed flight booking. For traveler privacy, you must provide the bookingId along with the passenger email address or last name. | Read-only |
| get_flights_bookings_bookingid_cancellations | ## Overview Returns refund eligibility, estimated refund amounts, and penalty details for a booking **without actually cancelling it**. Use this before calling `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 refunded money goes (`original_payment`, `agency_deposit`, `voucher`, etc.) - **`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 `POST /flights/bookings` in the URL path. Every call hits the upstream provider — do not place this on a hot polling loop. | Read-only |
| get_flights_bookings_bookingid_services | ## 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 `serviceId`s - **`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` (returned from `POST /flights/bookings`) in the URL path. > **Note:** Booking additional services on an existing booking is not available yet; this endpoint currently only reports availability. | Read-only |
| get_prebooks_prebookid | ## 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. | Read-only |
| getExperienceBooking | Poll booking status while pending confirmation or retrieve voucher after webhook confirms. Public response omits `providerPayment` (provider retail/invoice). | Read-only |
| getExperienceBookingCancelPreview | ## 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 GET this endpoint with the dispatcher `bookingId` from `POST /experiences/bookings`. This does not cancel the booking - call `POST /experiences/bookings/{bookingId}/cancel` to actually cancel. | Read-only |
| getExperienceTour | ## Overview Retrieve full details for a specific tour, including description, media, inclusions, pricing context, and structured itineraries when available. ## 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 - **Structured itineraries** - Ordered days/items (`itineraries`) when the provider supplies them. `locations` are importance-ordered tags, not itinerary order. - **Localized pricing** - Prices in the requested currency ## Quick Start Provide the tour `id` in the URL path plus required `language` and `currency` query parameters. | Read-only |
| getExperienceTourAvailability | ## 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. | Read-only |
| getExperienceTourBookingOptions | ## 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 sell totals (`pricing.totals.net` / `priceSummary.netPrice`) - **Checkout forms** - Collect `bookingQuestionSchema` before proceeding to payment ## What You Get - **Booking options** - `optionId`, title, and `bookingQuestionSchema` - **Time slots** - `dateTime`, `isAvailable`, and slot-level pricing (`unitNet` / `totalNet` / `totals.net` / `priceSummary.netPrice`, plus `totals.commission` when markup applies) - **Participant mapping** - Uses `ticketCategory` keys from availability (e.g. `adult`, `child`) ## Money semantics Field names keep `*Net` from experiences-api; dispatcher marks commercial net up **in place** to partner sell. Use `slots[].pricing.totals.net` as `selection.price.amount` on prebook. ## Quick Start POST a body with `language`, `currency`, `date` (`YYYY-MM-DD`), and `participants` to `/experiences/tours/{id}/booking-options`. Use slot `pricing.totals.net` for display and checkout handoff. ## Option-level `price` `options[].price.amount` is overwritten from the lowest available slot `pricing.totals.net` for the requested mix (after markup). It is not the GYG catalog from-price. Checkout still uses the chosen slot `pricing.totals.net`. | Changes data |
| getExperienceTourReviews | ## 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. | Read-only |
| getFlightPrebook | ## Overview Retrieve an existing flight checkout session (prebook) by ID, including any ancillary services already attached and a live catalog of remaining attachable services. ## When to Use - **Resume checkout** — Reload prebook state after the user navigates away - **Confirm attached ancillaries** — Show selected seats/bags before final book - **Reuse payment intent** — Returns the stored Stripe `transactionId` / `secretKey` as-is (GET does not create or refresh a PaymentIntent) - **Credit balance** — Optionally include a live credit-line snapshot with `includeCreditBalance=true` ## What You Get - Same core `FlightPrebookData` shape as `POST /flights/prebooks` / attach-services (journey, pricing, payment intent fields, `servicesAttachable`) - `booking.selectedServices` / `booking.bookedServices` when services were attached - Live `servicesAttachable` from the provider (not persisted) - Existing payment fields conserved from create/attach - Optional `creditLine` when `includeCreditBalance=true` (live remaining credit when the account can cover the prebook price) ## Quick Start Provide the `prebookId` returned from `POST /flights/prebooks` in the URL path. Optionally pass `includeCreditBalance=true` to include credit-line availability. | Read-only |
| getHotelTaxSchema | ## 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 | Read-only |
| getPriceIndexCity | ## 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.02 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. | Read-only |
| getPriceIndexHotels | ## 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.02 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. | Read-only |
| getPublicPrice | ## Overview Retrieve cached public price data for a specific hotel and occupancy. This endpoint returns pricing information sourced from public booking platforms (e.g., Booking.com, Expedia) that has been pre-fetched and cached. It applies occupancy canonicalization automatically, so callers don't need to replicate that logic. **⚠️ Beta Feature**: This endpoint is currently in beta. The API structure and behavior may change in future versions. **Pricing**: $0.02 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 comparison** - Compare your negotiated rates against publicly available prices - **Rate validation** - Verify that your offered rates are competitive before displaying to end users - **Market intelligence** - Understand public pricing trends for specific hotels and dates ## What You Get - **amount** - The best (lowest) cached public price for the stay in the specified currency - **nightlyAmount** - The best (lowest) nightly public price - **currency** - Currency code (USD) - **provider** - Normalized provider identifier for the best offer (e.g., `cheaptickets`) - **rawObservedText** - Raw observed price text from the source - **offers** - Public price offers from multiple booking providers - **fetchedAt** - When the price was last retrieved from the source - **expiresAt** - When this cached price expires and should no longer be used ## Key Features - **Occupancy-specific** - Prices are stored per occupancy configuration; query params must match write-time occupancy - **Negative cache aware** - Returns 404 for both cache misses and negative cache entries (hotels with no public price found) - **Low latency** - Direct cache lookup, no upstream API calls ## Parameters - `hotelId` (required): The MAQAMI hotel ID (e.g., `lpec902`) - `checkin` (required): Check-in date in YYYY-MM-DD format - `checkout` (required): Check-out date in YYYY-MM-DD format - `adults` (required): Number of adult guests - `childrenAges` (optional): Comma-separated ages of children (e.g., `5,8`) - `currency` (optional): Currency code; if present, must be `USD` | Read-only |
| listBookings | ## 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. | Read-only |
| post_bookings_bookingid_alternative_prebooks | ## 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 `MAQAMI_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. | Changes data |
| post_data_hotel_highlights | ## 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 are resolved server-side from `hotelId`; the caller never supplies them. The model sees the name, city, country, and description, plus a sample of facilities, rooms, and policies, guest sentiment when one is stored, and classification (star rating, hotel type, chain). 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. | Changes data |
| post_flights_bookings | ## 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`), bill an enabled **credit line** (`CREDIT`), pay with a **credit card** (`CREDIT_CARD` via the secure endpoint), or charge the **card stored on your account** (`ACC_CREDIT_CARD`) - **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 (HTTP 200 + `data[0].message`) if one already exists for the given `prebookId`. Transient book failures are retried in place without exposing a terminal failure status. Concurrent duplicate requests while a book is in progress return HTTP 409 (`45035`). - **Payments**: Stripe uses `transactionId` from prebook or attach-services after SDK confirmation; credit line uses `CREDIT` with server-side eligibility checks; `CREDIT_CARD` charges the provided card immediately — send card details in `billingInfo` via `https://pci-book.MAQAMI.travel` (contact the team to enable this on your API key); `ACC_CREDIT_CARD` charges the card saved on your account immediately, with no card details in the request (in sandbox it simulates the booking without a charge) - **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`. | Changes data |
| post_flights_bookings_bookingid_cancellations | Cancel an existing confirmed flight booking. For passenger security, you must provide the bookingId along with the passenger email address or last name. | Changes data |
| post_flights_prebooks | ## 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** (sandbox or whitelabel) and either an **enabled credit line** or a **whitelabel/CMI** checkout (no Stripe intent; complete payment via WL and call `/flights/bookings` with `payment.method: THIRD_PARTY` and `payment.token`) - **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 or via whitelabel/CMI (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`. | Changes data |
| post_flights_prebooks_prebookid_services | ## 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`). For whitelabel/CMI prebooks (`used_custom_payment_keys`), no new intent is returned — re-charge via WL and submit a fresh JWT at `POST /flights/bookings` - **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`. | Changes data |
| post_flights_rates | ## 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. | Read-only |
| post_flights_verify | ## 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`. | Read-only |
| post_hotels_min_rates | ## 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. | Read-only |
| post_hotels_rates | ## 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`. | Read-only |
| post_rates_book | ## 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 - **CREDIT_CARD** - Credit card payment via secure endpoint. Accepts any credit or debit card, including virtual credit cards. Send card details via `https://pci-book.MAQAMI.travel` using the `billingInfo` object. Contact the team to enable this on your API key. ## 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. | Changes data |
| post_rates_prebook | ## 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. | Changes data |
| post_rates_rebook | ## 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 - **Pay-at-property bookings are not supported.** Bookings paid at the property (`PROPERTY_PAY`) cannot be rebooked through this endpoint. - 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 MAQAMI 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. | Changes data |
| prebookExperienceTour | ## Overview Create a temporary hold on the selected tour slot and a Stripe PaymentIntent for checkout. ## When to Use - **Checkout start** — After the user picks option, slot, and participants from booking-options - **Payment setup** — Obtain `transactionId` and `secretKey` for Stripe SDK confirmation - **Hold window** — Reserve inventory for ~10 minutes before book ## What You Get - **Checkout context** — `tourId`, `optionId`, `dateTime`, `language`, `participants`, and pricing echoed back - **Provider refs** — `cartId`, `experienceBookingId`, `providerBookingId`, `status`, `reservationExpiresAt` - **Stripe fields** — `transactionId`, `secretKey`, `paymentTypes: ["TRANSACTION_ID"]` ## Quick Start POST the same `selection` used for display pricing from booking-options with `usePaymentSdk: true`. Confirm payment with Stripe, then call `POST /experiences/bookings`. | Changes data |
| prechargeFlightExtraCharges | ## Overview Creates a pending post-booking extra-charge batch for an existing flight booking and returns an opaque `chargesId`. For Stripe-paid bookings, also creates a PaymentIntent (`transactionId` + `secretKey`) when `usePaymentSdk` is true. ## Access Requires Flights API access. Post-booking extra charges are not enabled by default — contact the MAQAMI support team to request access. ## When to Use - Attach fees after confirmation (seat change, baggage, admin adjustment) - Obtain a Stripe client secret so the customer can confirm payment before `POST .../extra-charges/charges` ## What You Get - **`chargesId`** — Opaque token required by `/extra-charges/charges` (do not re-send charge lines) - **`paymentTypes`** — Locked to the booking's original payment (`TRANSACTION_ID` or `CREDIT`) - **`transactionId` / `secretKey`** — Present for Stripe bookings when `usePaymentSdk` is true - Existing extras totals plus pending batch totals ## Constraints - Booking status must be `CONFIRMED` or `PENDING_CONFIRMATION` - All lines in one request must share the same currency - Payment method on `/charges` must match the original booking payment | Changes data |
| put_bookings_bookingid | Cancel an existing confirmed hotel reservation. For traveler security and to prevent unauthorized cancellations, you must provide the bookingId along with the guest email address or last name used during booking. | Destructive |
| put_bookings_bookingid_amend | Amend an existing confirmed booking (dates, rooms, or guests). For traveler security, you must provide the bookingId along with the guest email address or last name used during booking. | Changes data |
| searchExperienceTours | ## 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. | Read-only |
| searchFlightsMatrix | ## 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 MAQAMI 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. | Changes data |
Change history
- Website changed from "https://maqami.co" to "https://mcp.maqami.co/" (registry)
- Repository changed (registry)
- Description changed (registry)
| Source | Listing | First seen | Last seen | Versions |
|---|---|---|---|---|
| Official MCP Registry | io.github.negm17111995/maqami-travel | 2 Oct 2026 | 6 Oct 2026 | 2 |