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.
/api/v1/hotels/get_ratesTake 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.
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": []
}
]
}'{
"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
}{
"environment": "sandbox",
"success": true,
"data": {
"hotelId": null,
"hid": null,
"rates": []
},
"processingTime": 0.16
}Request
Body
Required, JSON.
hotel_idstringrequiredThe 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.
checkinstringrequiredCheck-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.
checkoutstringrequiredCheck-out date, YYYY-MM-DD, after checkin. A stay is 1 to 30 nights. A midnight time is read as in checkin.
guestsarray of objectrequiredThe rooms: one {adults, children} object per room, 1 to 9 rooms. Rates are for exactly this occupancy.
ShowHide 2 attributes
adultsintegerrequiredNumber 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.
childrenarray of integerOne entry per child of the room: the age at check-in. [] or omitted when there is none. At most 4 children per room.
residencystringResidency 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.
languagestringLanguage 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.
idstringdeprecatedLegacy name, still accepted. Use hotel_id instead.
The hotel id, in its older spelling. Use hotel_id.
hotelIdstringdeprecatedLegacy name, still accepted. Use hotel_id instead.
The hotel id, in its older spelling. Use hotel_id.
checkinDatestringdeprecatedLegacy name, still accepted. Use checkin instead.
The check-in date, in an older spelling. Use checkin.
checkin_datestringdeprecatedLegacy name, still accepted. Use checkin instead.
The check-in date, in an older spelling. Use checkin.
check_instringdeprecatedLegacy name, still accepted. Use checkin instead.
The check-in date, in an older spelling. Use checkin.
checkoutDatestringdeprecatedLegacy name, still accepted. Use checkout instead.
The check-out date, in an older spelling. Use checkout.
checkout_datestringdeprecatedLegacy name, still accepted. Use checkout instead.
The check-out date, in an older spelling. Use checkout.
check_outstringdeprecatedLegacy name, still accepted. Use checkout instead.
The check-out date, in an older spelling. Use checkout.
Response
200The rates of the hotel. rates is empty when there is none.
environmentstringThe 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_idstringThe id of the request, also in the X-Request-Id header.
warningsarray of objectPresent only when the request used a previous spelling of a field or something the endpoint ignored.
ShowHide 5 attributes
codestringWhat the warning is about.
One of deprecated_field, ignored_field, coerced_value, deprecated_value, deprecated_endpoint.
fieldstringThe request field the warning is about.
replacementstringThe name to use instead, for deprecated_* warnings.
messagestringA sentence that says what happened and what to do.
documentation_urlstringWhere the naming rules are explained.
successbooleantrue when the call worked, also when the hotel has no rates.
dataobjectThe rates of one hotel.
ShowHide 4 attributes
hotelIdstringnullabledeprecatedLegacy name, still accepted. Use hotel_id instead.
The id of the hotel; null when the hotel is unknown or has no availability for the request.
hotel_idstringnullableThe 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.
hidintegernullableThe supplier's numeric hotel id; null with hotelId.
ratesarray of objectEvery rate of the hotel for the stay and occupancy, not sorted by price. Empty when there is none.
ShowHide 17 attributes
bookHashstringdeprecatedLegacy name, still accepted. Use book_hash instead.
The token of this rate. Send it as book_hash to pre_book. It stays valid for 30 minutes.
book_hashstringThe 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.
matchHashstringdeprecatedLegacy name, still accepted. Use match_hash instead.
A second identifier of the rate. You do not need it to book: send bookHash.
match_hashstringA 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.
roomobjectThe 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.
ShowHide 16 attributes
namestringName of the room as the supplier sells it, in the language of the request.
beddingTypestringnullableThe bedding as a phrase: single bed, full double bed, twin beds ...
miscRoomTypestringnullableAnother description of the bed or room, when the supplier gives one (king size bed).
capacityintegernullableNumber of guests the room is made for; null when unknown.
bathroomstringnullableprivate-bathroom or shared-bathroom.
hasPrivateBathroombooleantrue when the bathroom is private.
balconybooleantrue when the room has a balcony.
roomClassstringnullableClass of the room: room, suite, junior-suite, apartment, studio, cottage, dorm ...
qualitystringnullableQuality of the room: economy, standard, classic, superior, deluxe, executive, business ...
viewstringnullableView of the room (city-view, garden-view ...); null when there is none.
floorstringnullableFloor of the room, when it is special (attic).
bedroomsintegernullableNumber of bedrooms; null when unknown.
isFamilybooleantrue for a family room.
isClubbooleantrue for a club room.
genderRestrictionstringnullableGender the room is reserved for (hostel dorms); null when there is no restriction.
nonSmokingbooleantrue when the room is non-smoking.
mealobjectThe meal plan of a rate.
ShowHide 3 attributes
typestringThe 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.
includedbooleantrue when a meal is included (type is not nomeal).
childMealIncludedbooleantrue when the meal of the children is included too.
dailyPricesarray of numberdeprecatedLegacy name, still accepted. Use daily_prices instead.
The supplier's price of each night of the stay (first room), in supplierCurrency.
daily_pricesarray of numberThe 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.
allotmentintegerHow many rooms of this type are left at this rate.
isPackagebooleantrue when the rate is part of a package.
anyResidencybooleanfalse when the rate is reserved for some residencies: it exists for the residency of your request only.
depositobjectnullableReserved for deposit terms of the rate. null today.
noShowobjectnullableReserved for no-show terms of the rate. null today.
cancellationPolicyobjectWhen 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.
ShowHide 3 attributes
freeCancellationBeforestringnullabledeprecatedLegacy name, still accepted. Use free_cancellation_before instead.
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_beforestringnullableUTC 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.
policiesarray of objectThe schedule of penalties from now to check-in: the free window first, then the windows with a penalty.
ShowHide 5 attributes
fromstringnullableStart of the window, a UTC date and time without zone suffix; null for the first window (from now).
untilstringnullableEnd of the window, a UTC date and time without zone suffix; null for the last window (to check-in and after).
originalAmountnumberThe penalty charged by the supplier in this window, in originalCurrency. 0 in the free window.
originalCurrencystringCurrency of originalAmount, the supplier's: EUR.
currencystringYour agency currency, as a label. originalAmount is NOT in this currency.
pricingobjectThe 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).
ShowHide 10 attributes
supplierCurrencystringdeprecatedLegacy name, still accepted. Use supplier_currency instead.
Currency the supplier prices in: EUR.
supplier_currencystringCurrency the supplier prices in: EUR. The snake_case twin of supplierCurrency, with the same value: use this name.
agencyCurrencystringdeprecatedLegacy name, still accepted. Use agency_currency instead.
The currency of your agency. Every amount below except originalPrice and taxes is in it.
agency_currencystringThe 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.
originalPricenumberThe supplier's price for the whole stay and all rooms, in supplierCurrency. For information: it is not the base of what you pay.
agencyCommissionnumberdeprecatedLegacy name, still accepted. Use agency_commission instead.
Your commission, in agencyCurrency. The agency price is totalPrice minus this amount.
agency_commissionnumberYour commission, in agencyCurrency. The agency price is totalPrice minus this amount. The snake_case twin of agencyCommission, with the same value: use this name.
totalPricenumberdeprecatedLegacy name, still accepted. Use total_price instead.
What the traveler pays: the whole stay, all rooms, in agencyCurrency. You are debited totalPrice - agencyCommission.
total_pricenumberWhat 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.
taxesobjectTaxes and fees by name (cityTax, cleaningFee, electricityFee, occupancyTax, resortFee, serviceFee, vat ...), only the ones the rate has.
exchangeRatenumberdeprecatedLegacy name, still accepted. Use exchange_rate instead.
The rate of exchange from supplierCurrency to agencyCurrency that was used (285.0 in the sandbox).
exchange_ratenumberThe 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.
processingTimenumberdeprecatedLegacy name, still accepted. Use processing_time instead.
Seconds the call took, as a number.
processing_timenumberSeconds the call took, as a number. The snake_case twin of processingTime, with the same value: use this name.
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. |
The shape of the error body depends on the endpoint. See Errors for every shape and code.