--- title: "Retrieve rates for hotels" method: POST path: "/hotels/rates" tags: ["Hotel rates"] --- # Retrieve rates for hotels `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`. ## Request body - object - `hotelIds` string[] — An array of hotel IDs to search for availability and pricing. These are usually pulled from https://docs.liteapi.travel/reference/get_data-hotels. - `occupancies` object[], required — An array of objects specifying the number of guests per room. Required. - `adults` integer, required — Number of adults in each selected room - `children` integer[] — The ages of children of each selected room - `currency` string, required — The currency in which the prices will be displayed. - `guestNationality` string, required — The guest's nationality in ISO 2-letter country code format. - `checkin` string, required — The check-in date in YYYY-MM-DD format (ISO 8601). - `checkout` string, required — The check-out date in YYYY-MM-DD format (ISO 8601). - `timeout` integer — The maximum time in seconds before the request times out. This is when the live request for rates will cut off responses; it will take a few more ms to return the value. - `maxRatesPerHotel` integer — The number of room rates to return per hotel, sorted by price (cheapest first). Set to 1 to just get the cheapest rate for each hotel, this is helpful for listing pages. - `boardType` string — Filter results by board type(s). Can be a single value (e.g., 'BB') or comma-separated values (e.g., 'BB,BB1,BB2') for OR logic. Example values: RO (Room Only), BB (Bed & Breakfast), HB (Half Board), BB1, BB2, BB3, etc. - `refundableRatesOnly` boolean — If true, only refundable rates (RFN) will be included in the response. - `roomAmenities` number[] — Legacy room-level amenity filter. Only rates from rooms that match the specified amenities will be returned. Use amenityFilterLogic to control flat AND/OR behavior. If roomAmenitiesFilter is provided, it takes precedence over this field. - `roomAmenitiesFilter` string — Grouped room-level amenity filter. Use '-' for OR within a group and ',' for AND across groups. Example: '1-2,3-4' means (1 OR 2) AND (3 OR 4). If provided, this field takes precedence over roomAmenities and amenityFilterLogic. - `amenityFilterLogic` 'AND' | 'OR' — Legacy logic applied to roomAmenities. 'AND': room must have all specified amenities. 'OR': room must have at least one specified amenity. Ignored when roomAmenitiesFilter is provided. - `bedTypes` string[] — Filter results by bed types extracted from room names. Only rates from rooms matching the specified bed types will be returned. Example values: 'double', 'twin', 'king', 'queen', 'single'. - `sort` object[] — Sorting criteria for the results. Multiple criteria can be provided, processed in order. The default sorting is by top picks (weighted by search popularity, review quality, and content completeness). Use 'revenue' to sort by historical booking value and monetary performance. - `field` 'top_picks' | 'price' | 'revenue', required — Criteria to sort by. 'top_picks' (default) ranks by search popularity, review quality, and content completeness. 'price' sorts by room rate. 'revenue' ranks by historical booking value and monetary performance. - `direction` 'ascending' | 'descending' — Sort direction (e.g. ascending would sort prices by cheapest first when using 'price'). - `roomMapping` boolean — Enable room mapping to retrieve the mappedRoomId for each room. This allows you to link a rate to its specific room by combining it with hotel details, providing access to room images and additional information - `hotelName` string — A case-insensitive search for a hotel's name (e.g., 'Hilton'). - `countryCode` string — The country code in ISO 2-letter format (e.g., 'SG' for Singapore). Instead of using hotel IDs, you can search by country/city. This is a valid main query. - `cityName` string — The name of the city to search for hotels in. Pairs with countryCode to do a country/city search. - `latitude` number — The latitude coordinate for location-based hotel searches. Instead of using hotel IDs, you can search by lat/long and a radius around that spot. This is a valid main query. - `longitude` number — The longitude coordinate for location-based hotel searches. Pairs with latitude to do a lat/long search. - `radius` integer — The search radius in meters for location-based searches. Pairs with latitude to do a lat/long search. - `iataCode` string — The IATA code of the search location, typically an airport code. Instead of using hotel IDs, you can search by IATA code. This is a valid main query. - `limit` integer — The maximum number of results to return. Defaults to 200, max allowed is 5000. - `offset` integer — The number of results to skip for pagination. This paginates the passed hotels not the results returned so the actual returned results will vary. - `aiSearch` string — AI-powered hotel search based on a natural language query. Uses semantic search to find hotels matching the query intent. Examples: 'Romantic getaway with Italian vibes in London near the London Eye', 'hotels near Paris'. This is a valid main query. - `minReviewsCount` integer — The minimum number of reviews a hotel must have to be included in results. This is a filter on top of the main query. - `minRating` number — The minimum rating (on a scale of 0-5) required for hotels in search results. This is a filter on top of the main query. - `zip` string — The zip code of the search location. This is a filter on top of the main query. - `placeId` string — The unique Place ID of the search location. Instead of using hotel IDs, pass a Place ID to get all the hotels in the specified region. This is a valid main query. - `starRating` number[] — An array of hotel star ratings to include. Ratings are rounded to the nearest half-star (e.g., [3.5, 4.0, 4.5, 5.0]). This is a filter on top of the main query. - `hotelTypeIds` number[] — An array of hotel type IDs to filter the search results. This is a filter on top of the main query. - `chainIds` number[] — An array of hotel chain IDs to filter the search results. This is a filter on top of the main query. - `facilities` number[] — An array of facility IDs. Results will include hotels with at least one of these facilities by default. This is a filter on top of the main query. - `strictFacilityFiltering` boolean — If enabled, only hotels with all specified facilities will be returned. - `stream` boolean — If true, enables streaming mode where response data is sent incrementally instead of as a single payload. - `advancedAccessibilityOnly` boolean — If true, only hotels with advanced accessibility features will be returned. - `feed` string — Which feed to use when searching for rates. This applies only to accounts with multiple feeds enabled - `includeHotelData` boolean — If `true`, includes hotel data (name, main photo, address, rating) in the response even when searching by direct hotel IDs. By default, hotel data is only included when searching by filters (e.g., using `aiSearch`, `countryCode`, `cityName`, etc.). Setting this to `true` enables hotel data inclusion for all search types. - `margin` number — Override the markup percentage for this specific request. When provided, this value takes precedence over your account-level margin setting, allowing you to dynamically adjust pricing based on your business logic, customer segments, or other factors. Specified as a percentage number (e.g., `10` for 10% commission). - `sessionId` string — Optional client-generated session identifier that ensures price consistency for the user's search session. When your account has price consistency enabled, pass the same `sessionId` with the same `checkin` and `checkout` across related requests in that session. Has no effect when price consistency is not enabled for your account. - `loyaltyProgram` string — Loyalty program identifier used to request loyalty-eligible rates from supported suppliers. When set, rates that support the program may return member pricing and benefits. - `loyaltyProgramDetails` object[] — Loyalty membership details forwarded to supported suppliers to unlock member rates and benefits. Provide one entry per loyalty program membership. - `membershipId` string, required — The guest's membership ID for the loyalty program. - `programId` string, required — The loyalty program identifier (e.g., 'HH' for Hilton Honors). ## Response `200` OK - object - `data` object[] - `hotelId` string, required — The unique identifier for the hotel related to this pre-booking. Used along with the hotel content endpoint. - `roomTypes` object[], required — An array of objects containing all the requested rooms/rates. This is not the type of room being booked. - `roomTypeId` string — Unique identifier for the room type - `name` string — The name of the room type booked, including key attributes. - `offerId` string — The offer ID passed during the prebook call, provided again here for reference. - `supplier` string — The supplier providing the inventory for this booking. By default this will always be Nuitee. - `supplierId` integer — The numerical identifier of the supplier. By default Nuitee's ID is always 2. - `rates` object[] — An array of objects detailing the pricing and availability of the selected room rates. There will be a number of rates equal to the occupancies request. - `rateId` string — The unique identifier for a specific rate within the offer. - `occupancyNumber` integer — The number identifying which guest is associated with each room in a multi-room booking. - `name` string — The name of the room type booked, including key attributes. - `maxOccupancy` integer — The maximum number of guests allowed in this room. - `adultCount` integer — The number of adults included in this booking. - `childCount` integer — The number of children included in this booking. - `childrenAges` integer[] — The ages of children included in this booking for this rate. Empty if no children are booked. - `boardType` string — A short code representing the meal plan included with the booking. - `boardName` string — The full name of the meal plan included in the booking. - `remarks` string — Any special remarks related to the booking or room type. - `priceType` string — The pricing model applied to this rate (e.g., commission) - `commission` object[] — Defines how pricing is structured. Only commission currently used. It can be set to 0 for net rates. The markup is not going to be applied in case of paymentTypes PROPERTY_PAY. - `amount` number — The amount of commission included in the total price. - `currency` string — The currency the commission is in. - `retailRate` object - `total` object[] — An array containing the total price due for this room. - `amount` number — The total cost amount due to book this room. This is what the end user will pay. - `currency` string — The currency the total is in. - `suggestedSellingPrice` object[] — The minimum public selling price for all the rooms combined. This is used for pricing control. - `amount` number — The minmum amount the room can be sold for publicly. - `currency` string — The currency the SSP is in. - `source` string — The source of the SSP if we have it. - `initialPrice` object[] — This object represents the hotel’s standard listed price for the room. It is always equal to or higher than the total price. If higher, it indicates a hotel discount is applied. - `amount` number — The base monetary value of the booking rate, inclusive of taxes and commission fees. - `currency` string — Currency of the initial price - `taxesAndFees` object[] — Breakdown of applicable taxes and additional charges - `included` boolean — Indicates whether the tax is included in the total price - `description` string — Description of the tax or fee - `amount` number — Cost of the tax or fee - `currency` string — Currency of the tax or fee - `promotions` object[] — An array of promotions or special offers associated with this rate. Promotions can include early booking deals, seasonal discounts, and other special offers. - `name` string — The name or title of the promotion. - `from` string — The start date of the promotion in YYYY-MM-DD format (ISO 8601). - `to` string — The end date of the promotion in YYYY-MM-DD format (ISO 8601). - `discount` number — The discount value applied by this promotion. - `discountType` string — The type of discount. Common values include 'percentage' for percentage-based discounts. - `promotionCode` string — An optional promotion code that can be used to apply this promotion. May be empty if no code is required. - `currency` string — The currency associated with the promotion discount. - `cancellationPolicies` object — An object containing the cancellation rules and conditions for the booking. - `cancelPolicyInfos` object[] — An array of objects detailing specific cancellation penalties and deadlines. - `cancelTime` string — The deadline to cancel before incurring a fee (ISO datetime format). - `amount` number — The monetary penalty applied if the booking is canceled after the deadline. Can be 0 which means its fully refundable. - `currency` string — The currency of the cancellation fee. - `type` string — The type of cancellation penalty (e.g., 'amount' for a fixed fee). - `timezone` string — The timezone in which the cancellation policy applies. Always GMT, even if not listed. - `hotelRemarks` unknown[] — An array of additional remarks from the hotel regarding cancellations. - unknown - `refundableTag` string — Indicates whether the booking is refundable, Either 'NRFN' for non-refundable or RFN for refundable. - `paymentTypes` string[] — An array of payment types supported for this booking request. - `perks` object[] — An array of perks or benefits associated with this rate. Perks can include amenities like breakfast, room upgrades, property credits, early check-in, late check-out, and other value-added services. - `perkId` integer — Unique identifier for the perk. - `name` string — The name or description of the perk. - `amount` number — The monetary value of the perk. - `currency` string — The currency of the perk amount. - `level` string — The level or tier of the perk. Possible values: 'HOTEL' for hotel-level perks, 'RATE' for rate-level perks, or 'ROOM' for room-level perks. - `offerRetailRate` object[] — Total offer price derived from summing the final prices (including base rate, taxes, fees, and adjustments) of each rate in the offer. - `amount` number — Final price at the offer level - `currency` string — Currency of the offer price - `suggestedSellingPrice` object[] — The minimum public selling price for all the rooms combined. This is used for pricing control. - `amount` number — The minmum amount the room can be sold for publicly. - `currency` string — The currency the SSP is in. - `source` string — The source of the SSP if we have it. - `offerInitialPrice` object[] — Combined original price for the offer, calculated by adding the initial prices (inclusive of taxes and commission) of each rate before any discounts or modifications. - `amount` number — Initial price - `currency` string — Currency of the initial price - `priceType` string — The pricing model applied to this offer (e.g., commission) - `rateType` string — The rate type, either 'standard' or 'package' - `loyaltyMembershipIdRequired` boolean — Indicates whether a valid loyalty membership ID must be supplied (via `loyaltyProgramDetails` on the rates request) to book this rate. - `guestLevel` integer — Used with loyalty programs to determine the guests level of cost reduction. - `sandbox` boolean — Indicates if the request was made in a sandbox (test) environment - `hotels` object[] — Hotel details included when searching by filters or when `includeHotelData` is set to `true`. Contains basic hotel information for each hotel in the results. - `id` string, required — The liteAPI hotel ID - `name` string, required — The hotel name - `main_photo` string — URL of the hotel's main photo - `thumbnail` string — URL of a smaller thumbnail version of the hotel's main photo, suitable for list views and previews - `address` string — The hotel's address - `country_code` string — The hotel's country code - `city_name` string — The name of the city the hotel is located in - `latitude` number — The hotel's latitude coordinate - `longitude` number — The hotel's longitude coordinate - `rating` number — The hotel's guest rating score - `stars` number — The hotel's star rating - `review_count` integer — The number of guest reviews for the hotel - `tags` string[] — Descriptive tags associated with the hotel - `persona` string — The hotel's persona classification - `style` string — The hotel's style classification - `location_type` string — The type of location the hotel is in - `story` string — A short narrative description of the hotel ## Other responses - `204` — No Content - `400` — Bad Request --- [API](https://skmtc.net/liteapi/apis/api-search.md) · [All operations](https://skmtc.net/liteapi/apis/api-search/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/liteapi/api-search/versions/315ba2a4dcf4/schema)