# Get the rooms and rates of one hotel > Returns every room and rate of one hotel for a stay and an occupancy, each with its meal plan, cancellation schedule and price. Endpoint: `POST /hotels/get_rates` Source: https://fx-port.com/docs/api/get-hotel-rates `POST /api/v1/hotels/get_rates` Requires an API key with **Read** permission; a **Read+Write** key works too. Take the `bookHash` of the rate the user chose and send it to `pre_book`. Only prepaid (deposit) rates are returned, in no particular order: sort by `pricing.totalPrice` yourself. Prices are for the whole stay and all rooms, in the currency of your agency. The hashes are valid for 30 minutes. A hotel that is unknown, closed, not available for the dates or not available for the residency answers `200` with `data.hotelId` `null` and an empty `rates`, not an error: check `rates.length`. The call takes 0.5 to 5 seconds. Identical calls of your agency that arrive at the same moment are merged into one supplier call; each caller still gets its own `request_id` and headers. Do not send `currency`. A value written in another well-defined way is read and reported in `warnings` (`coerced_value`), as in `search_advanced`; what cannot be read keeps its error code. In the sandbox the rates of any hotel are real; only the test hotels can be booked, and `test_hotel` has rates for the residencies `dz`, `ru` and `us` only. ## Request ### Body Required, JSON. - `hotel_id` (string, required): The FX-Port id of the hotel (1 to 128 characters: letters, digits and `_ . : -`; spaces around it are trimmed): `hotels_details[].id` of a search, a hit of the name search. A JSON integer is read as its text, but it is not looked up as the supplier's numeric `hid` here: send the FX-Port id. - `checkin` (string, required): Check-in date, `YYYY-MM-DD`: from yesterday (for time zones) to 400 days ahead. A date written with a midnight time (`2026-12-01T00:00:00Z`) is read as that day, with a `coerced_value` warning; any other time of day is `invalid_date`. - `checkout` (string, required): Check-out date, `YYYY-MM-DD`, after `checkin`. A stay is 1 to 30 nights. A midnight time is read as in `checkin`. - `guests` (array of object, required): The rooms: one `{adults, children}` object per room, 1 to 9 rooms. Rates are for exactly this occupancy. - `adults` (integer, required): Number of adults in the room, 1 to 6. A number written as text (`"2"`) is read as the number, with a `coerced_value` warning. Between 1 and 6. - `children` (array of integer, optional): One entry per child of the room: the age at check-in. `[]` or omitted when there is none. At most 4 children per room. - `residency` (string, optional): Residency of the guests, a two-letter ISO 3166-1 country code. A sub-territory code of the website's nationality list (`GB-SCT`, `USPR`, `PT-MA` ...) is read as its country, with a `coerced_value` warning: send the 2-letter country. Some rates exist for some residencies only. Default `gb`. - `language` (string, optional): Language of the room names, such as `en`, `fr` or `zh_CN`. A longer tag (`zh-Hans-CN`, `es-419`) is read as the supplier's code, with a `coerced_value` warning. Default `en`. - `id` (string, deprecated, optional): Legacy name: use `hotel_id`. The hotel id, in its older spelling. Use `hotel_id`. - `hotelId` (string, deprecated, optional): Legacy name: use `hotel_id`. The hotel id, in its older spelling. Use `hotel_id`. - `checkinDate` (string, deprecated, optional): Legacy name: use `checkin`. The check-in date, in an older spelling. Use `checkin`. - `checkin_date` (string, deprecated, optional): Legacy name: use `checkin`. The check-in date, in an older spelling. Use `checkin`. - `check_in` (string, deprecated, optional): Legacy name: use `checkin`. The check-in date, in an older spelling. Use `checkin`. - `checkoutDate` (string, deprecated, optional): Legacy name: use `checkout`. The check-out date, in an older spelling. Use `checkout`. - `checkout_date` (string, deprecated, optional): Legacy name: use `checkout`. The check-out date, in an older spelling. Use `checkout`. - `check_out` (string, deprecated, optional): Legacy name: use `checkout`. The check-out date, in an older spelling. Use `checkout`. ### Example request ```bash curl https://api.fx-port.com/api/v1/hotels/get_rates \ -H "Authorization: Bearer fxp_test_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "hotel_id": "test_hotel_do_not_book", "checkin": "2026-12-01", "checkout": "2026-12-04", "residency": "gb", "language": "en", "guests": [ { "adults": 2, "children": [] } ] }' ``` ## Response ### 200: The rates of the hotel. `rates` is empty when there is none. - `environment` (string): The environment of the key that made the call: `sandbox` for fxp_test_ keys, `live` for fxp_live_ keys. Present in every JSON body. One of `sandbox`, `live`. - `request_id` (string): The id of the request, also in the `X-Request-Id` header. - `warnings` (array of object): Present only when the request used a previous spelling of a field or something the endpoint ignored. - `code` (string): What the warning is about. One of `deprecated_field`, `ignored_field`, `coerced_value`, `deprecated_value`, `deprecated_endpoint`. - `field` (string): The request field the warning is about. - `replacement` (string): The name to use instead, for `deprecated_*` warnings. - `message` (string): A sentence that says what happened and what to do. - `documentation_url` (string): Where the naming rules are explained. - `success` (boolean): `true` when the call worked, also when the hotel has no rates. - `data` (object): The rates of one hotel. - `hotelId` (string, nullable, deprecated): Legacy name: use `hotel_id`. The id of the hotel; `null` when the hotel is unknown or has no availability for the request. - `hotel_id` (string, nullable): The id of the hotel; `null` when the hotel is unknown or has no availability for the request. The snake_case twin of `hotelId`, with the same value: use this name. - `hid` (integer, nullable): The supplier's numeric hotel id; `null` with `hotelId`. - `rates` (array of object): Every rate of the hotel for the stay and occupancy, not sorted by price. Empty when there is none. - `bookHash` (string, deprecated): Legacy name: use `book_hash`. The token of this rate. Send it as `book_hash` to `pre_book`. It stays valid for 30 minutes. - `book_hash` (string): The token of this rate. Send it as `book_hash` to `pre_book`. It stays valid for 30 minutes. The snake_case twin of `bookHash`, with the same value: use this name. - `matchHash` (string, deprecated): Legacy name: use `match_hash`. A second identifier of the rate. You do not need it to book: send `bookHash`. - `match_hash` (string): A second identifier of the rate. You do not need it to book: send `bookHash`. The snake_case twin of `matchHash`, with the same value: use this name. - `room` (object): The room of a rate. Match it with the hotel content by room name; the document of `get_hotel_info` lists every room type with photos and amenities. - `name` (string): Name of the room as the supplier sells it, in the `language` of the request. - `beddingType` (string, nullable): The bedding as a phrase: `single bed`, `full double bed`, `twin beds` ... - `miscRoomType` (string, nullable): Another description of the bed or room, when the supplier gives one (`king size bed`). - `capacity` (integer, nullable): Number of guests the room is made for; `null` when unknown. - `bathroom` (string, nullable): `private-bathroom` or `shared-bathroom`. - `hasPrivateBathroom` (boolean): `true` when the bathroom is private. - `balcony` (boolean): `true` when the room has a balcony. - `roomClass` (string, nullable): Class of the room: `room`, `suite`, `junior-suite`, `apartment`, `studio`, `cottage`, `dorm` ... - `quality` (string, nullable): Quality of the room: `economy`, `standard`, `classic`, `superior`, `deluxe`, `executive`, `business` ... - `view` (string, nullable): View of the room (`city-view`, `garden-view` ...); `null` when there is none. - `floor` (string, nullable): Floor of the room, when it is special (`attic`). - `bedrooms` (integer, nullable): Number of bedrooms; `null` when unknown. - `isFamily` (boolean): `true` for a family room. - `isClub` (boolean): `true` for a club room. - `genderRestriction` (string, nullable): Gender the room is reserved for (hostel dorms); `null` when there is no restriction. - `nonSmoking` (boolean): `true` when the room is non-smoking. - `meal` (object): The meal plan of a rate. - `type` (string): The meal included in the rate. `nomeal` is room only. One of `nomeal`, `breakfast`, `lunch`, `dinner`, `half-board`, `half-board-lunch`, `half-board-dinner`, `full-board`, `all-inclusive`, `ultra-all-inclusive`. - `included` (boolean): `true` when a meal is included (`type` is not `nomeal`). - `childMealIncluded` (boolean): `true` when the meal of the children is included too. - `dailyPrices` (array of number, deprecated): Legacy name: use `daily_prices`. The supplier's price of each night of the stay (first room), in `supplierCurrency`. - `daily_prices` (array of number): The supplier's price of each night of the stay (first room), in `supplierCurrency`. The snake_case twin of `dailyPrices`, with the same value: use this name. - `allotment` (integer): How many rooms of this type are left at this rate. - `isPackage` (boolean): `true` when the rate is part of a package. - `anyResidency` (boolean): `false` when the rate is reserved for some residencies: it exists for the `residency` of your request only. - `deposit` (object, nullable): Reserved for deposit terms of the rate. `null` today. - `noShow` (object, nullable): Reserved for no-show terms of the rate. `null` today. - `cancellationPolicy` (object): When and at what price a booking of the rate can be cancelled. The amounts are the supplier's (`originalAmount`, in `originalCurrency`); what is refunded to your agency is in the answer of `cancel_hotel`. - `freeCancellationBefore` (string, nullable, deprecated): Legacy name: use `free_cancellation_before`. UTC date and time (no zone suffix) until which the booking can be cancelled for free. `null` means the rate is non-refundable. - `free_cancellation_before` (string, nullable): UTC date and time (no zone suffix) until which the booking can be cancelled for free. `null` means the rate is non-refundable. The snake_case twin of `freeCancellationBefore`, with the same value: use this name. - `policies` (array of object): The schedule of penalties from now to check-in: the free window first, then the windows with a penalty. - `from` (string, nullable): Start of the window, a UTC date and time without zone suffix; `null` for the first window (from now). - `until` (string, nullable): End of the window, a UTC date and time without zone suffix; `null` for the last window (to check-in and after). - `originalAmount` (number): The penalty charged by the supplier in this window, in `originalCurrency`. `0` in the free window. - `originalCurrency` (string): Currency of `originalAmount`, the supplier's: `EUR`. - `currency` (string): Your agency currency, as a label. `originalAmount` is NOT in this currency. - `pricing` (object): The prices of a rate or of an offer. There is no `b2bPrice` in this block: the amount debited from your agency is `totalPrice - agencyCommission` (see Hotel pricing). - `supplierCurrency` (string, deprecated): Legacy name: use `supplier_currency`. Currency the supplier prices in: `EUR`. - `supplier_currency` (string): Currency the supplier prices in: `EUR`. The snake_case twin of `supplierCurrency`, with the same value: use this name. - `agencyCurrency` (string, deprecated): Legacy name: use `agency_currency`. The currency of your agency. Every amount below except `originalPrice` and `taxes` is in it. - `agency_currency` (string): The currency of your agency. Every amount below except `originalPrice` and `taxes` is in it. The snake_case twin of `agencyCurrency`, with the same value: use this name. - `originalPrice` (number): The supplier's price for the whole stay and all rooms, in `supplierCurrency`. For information: it is not the base of what you pay. - `agencyCommission` (number, deprecated): Legacy name: use `agency_commission`. Your commission, in `agencyCurrency`. The agency price is `totalPrice` minus this amount. - `agency_commission` (number): Your commission, in `agencyCurrency`. The agency price is `totalPrice` minus this amount. The snake_case twin of `agencyCommission`, with the same value: use this name. - `totalPrice` (number, deprecated): Legacy name: use `total_price`. What the traveler pays: the whole stay, all rooms, in `agencyCurrency`. You are debited `totalPrice - agencyCommission`. - `total_price` (number): What the traveler pays: the whole stay, all rooms, in `agencyCurrency`. You are debited `totalPrice - agencyCommission`. The snake_case twin of `totalPrice`, with the same value: use this name. - `taxes` (object): Taxes and fees by name (`cityTax`, `cleaningFee`, `electricityFee`, `occupancyTax`, `resortFee`, `serviceFee`, `vat` ...), only the ones the rate has. - `exchangeRate` (number, deprecated): Legacy name: use `exchange_rate`. The rate of exchange from `supplierCurrency` to `agencyCurrency` that was used (`285.0` in the sandbox). - `exchange_rate` (number): The rate of exchange from `supplierCurrency` to `agencyCurrency` that was used (`285.0` in the sandbox). The snake_case twin of `exchangeRate`, with the same value: use this name. - `processingTime` (number, deprecated): Legacy name: use `processing_time`. Seconds the call took, as a number. - `processing_time` (number): Seconds the call took, as a number. The snake_case twin of `processingTime`, with the same value: use this name. ```json { "environment": "sandbox", "success": true, "data": { "hotelId": "test_hotel_do_not_book", "hid": 8473727, "rates": [ { "bookHash": "h-14574656-7ce9-5a21-b673-8654c5ebd416", "matchHash": "m-a1f40b22-c086-57c9-b2b5-70c8e59cb27c", "room": { "name": "Standard room", "beddingType": "single bed", "miscRoomType": null, "capacity": null, "bathroom": "private-bathroom", "hasPrivateBathroom": true, "balcony": false, "roomClass": "room", "quality": "standard", "view": null, "floor": null, "bedrooms": null, "isFamily": false, "isClub": false, "genderRestriction": null, "nonSmoking": true }, "meal": { "type": "nomeal", "included": false, "childMealIncluded": false }, "dailyPrices": [ 1, 1, 1 ], "allotment": 77, "isPackage": false, "anyResidency": true, "deposit": null, "noShow": null, "cancellationPolicy": { "freeCancellationBefore": "2026-12-01T21:00:00", "policies": [ { "from": null, "until": "2026-12-01T21:00:00", "originalAmount": 0, "originalCurrency": "EUR", "currency": "DZD" }, { "from": "2026-12-01T21:00:00", "until": null, "originalAmount": 3, "originalCurrency": "EUR", "currency": "DZD" } ] }, "pricing": { "supplierCurrency": "EUR", "agencyCurrency": "DZD", "originalPrice": 3, "agencyCommission": 2.97, "totalPrice": 1484.97, "taxes": { "cityTax": { "includedInPrice": false, "amount": 23.1, "currency": "HNL" }, "electricityFee": { "includedInPrice": true, "amount": 0.6, "currency": "EUR" }, "resortFee": { "includedInPrice": true, "amount": 0.68, "currency": "EUR" } } }, "exchangeRate": 285 } ] }, "processingTime": 0.335 } ``` ## Errors | Status | Code | Example message | | --- | --- | --- | | 400 | `stay_too_long` | A stay can be at most 30 nights ('checkout' is 35 nights after 'checkin'). | | 400 | `missing_field` | Missing required fields: ['guests'] | | 400 | `missing_field` | Missing required fields: ['checkin', 'guests'] | | 400 | `bad_request` | Do not pass 'currency'. Currency is resolved automatically from the authenticated agency. | | 502 | `supplier_invalid_response` | The hotel supplier returned an answer that could not be used. Retry in a few minutes. | | 503 | `supplier_unavailable` | The hotel supplier could not be reached. Retry in a few minutes. | | 503 | `supplier_timeout` | The hotel supplier did not answer in time, so the request may or may not have been processed: read the booking's status before you retry. | | 503 | `supplier_busy` | The supplier is temporarily at capacity; retry after the time given in the Retry-After header. | See [Errors](https://fx-port.com/docs/errors.md) for every code and how to react. ## Related guides - [Get hotel rates](https://fx-port.com/docs/hotels/rates.md) - [Hotel pricing](https://fx-port.com/docs/hotels/pricing.md)