MAQAMI Travel

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

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

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

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

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 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 in post_flights_rates

• City and country details for display purposes

• Geographic coordinates for map-based interfaces

Quick Start

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

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.

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.

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

Overview

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

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.

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

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

Overview

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

When to Use

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

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

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

What You Get

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

• isRefundable / isVoidable — Quick eligibility flags

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

• penalties[] — Itemised penalty breakdown when available

• tickets[] — Per-ticket detail when available

• destination — Where the refund goes

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

Concurrent cancellation

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

Refund amount caveat

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

Key Features

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

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

• Booking currency — Every amount, including tickets[] and penalties[] lines, is returned in the booking currency. Amounts the airline quotes in another currency are converted at the rate implied by the quote itself, or at the current exchange rate when the quote does not price them in the booking currency

Quick Start

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

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

Overview

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

When to Use

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

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

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

What You Get

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

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

• expiresAt - Validity window of the bookable catalog

Key Features

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

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

Quick Start

Provide the bookingId from the flight booking confirmation.

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

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

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

Overview

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

When to Use

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

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

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

How It Works

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

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

3. A prebook session is created for each rate.

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

What You Get

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

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

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

Key Notes

• The booking must be in CONFIRMED status.

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

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

Quick Start

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

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

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

Flight bookings are cancelled on MAQAMI's website, not in this chat. When a customer wants to cancel a flight, give them https://book.maqami.co/manage-bookings and tell them to continue from there: choose "Flight reservations", enter the last name and the booking ID, then follow the steps to see the refund and cancel. Calling this tool returns the same link and steps.

Overview

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

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

When to Use

• Listings — live prices for search results UI

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

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

What You Get

• Offers from multiple providers

• Itineraries with segments, layovers, and durations

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

Key Features

• Multi-provider aggregation in one request

• Global filters, sort

Quick Start

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

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

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

Booking

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

Overview

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

When to Use

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

• Price confirmation - Show users the guaranteed price

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

What You Get

• Verified pricing with up-to-date fare breakdown

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

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

• Fare family details including name and included amenities

• Baggage policy for each passenger type and segment

• Booking terms including cancellation and change fee rules

Key Features

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

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

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

Quick Start

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

Booking

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

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

• Core search parameters shared with the main rates endpoint: hotel IDs, dates, occupancies, currency and guest nationality

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

Consistency with /hotels/rates: this endpoint takes no sessionId, does not use room mapping and is not covered by price consistency. Its price can differ from /hotels/rates with roomMapping: true, and the offer may not appear in a later /hotels/rates response.

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 holds the lowest-priced room-mapped offer of each hotel for the hotel page within a user session (accounts with price consistency enabled; see Multi-hotel and single-hotel consistency)

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.

Multi-hotel and single-hotel consistency

A multi-hotel search and a search for one of those hotels are independent searches. Unless an offer is held through price consistency, as described below, the same hotel can return different rates in each, even with identical parameters, so an offer from a multi-hotel response may not appear in a later single-hotel response. Common reasons:

• Rates considered per hotel: when a request covers 50 or more hotels (listed in hotelIds or resolved from a location search), a high maxRatesPerHotel is currently reduced (see that field). A single-hotel request keeps your value, so it can consider more rates.

• Room mapping: when room mapping is on, each mapped room keeps only its best offers by price, board type and refundability, and most offers that cannot be mapped to a room are removed. A different set of input rates can therefore produce a different result.

• Response timing: suppliers and other rate sources can respond differently, or at different times, from one call to the next.

• Caching: a repeated identical multi-hotel request, including the same sessionId, can be answered from a short-lived cache. Single-hotel responses are not stored in that cache.

Keeping a listing price on the hotel page requires price consistency to be enabled on your account. Send the same sessionId, checkin and checkout on the multi-hotel search and on the single-hotel request. The multi-hotel search then holds, for each hotel, its lowest-priced room-mapped offer, and the single-hotel request returns that offer, while it can still be served, and no cheaper one. If the lowest offer in the listing is not room-mapped, the held offer can be a higher-priced one. A later multi-hotel search in the same session replaces the held offer of each hotel it can hold again; other hotels keep theirs until the hold ends. A multi-hotel response served from the short-lived cache does not create or renew a hold.

The hold applies to single-room searches only. It lasts for a limited time set for your account, starts with the first search of the session and is not extended by later searches in that session; a live search made after the hold has ended starts a new one. When no offer is held for a hotel, the single-hotel request returns live rates, and its lowest-priced room-mapped offer, if it has one, becomes the held offer for that session. Availability can still change, so treat prebook as the final confirmation of price.

Party, nationality and currency. The hold covers one room only, and the held offer is also returned when the single-hotel request asks for other adults or children in the room, another guestNationality or another currency than the search that created the hold. Its price stays the held one, converted to the requested currency. Prebook then re-checks that room for the request's own party and nationality, and fails if it is no longer offered for them; search again in that case.

Without sessionId. On accounts with session-less price consistency enabled, a single-hotel request without sessionId returns the offer held for that hotel, checkin and checkout by the latest multi-hotel search of your account, whichever session it belonged to. That hold has its own expiry: the time set for your account, counted from the search that held that hotel's offer, not from the first search of its session. A hotel first held late in a session can therefore stay held after that session's hold has ended. The party, nationality and currency rules above apply. On other accounts, a request without sessionId returns live rates.

For listing prices that need to be held, use this endpoint with multiple hotel IDs rather than /hotels/min-rates, which is not covered by price consistency.

Overview

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

When to Use

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

Quick Start

Pass the offerId from post_hotels_rates exactly as it was returned.

What You Get

• prebookId - The locked rate

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

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

Payment

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

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

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

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

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