Skip to content

CheckRates

POST {base_url}/1.0/hotels/checkrates

Validates a previously-obtained rateKey and returns the current rate. Always required before BookingHold.

Header Value
Authorization Bearer <access_token>
Content-Type application/json
Accept application/json
{
"rateKey": "<rateKey from /hotels/rates>"
}
{
"hotel": {
"rooms": [
{
"id": 5438585,
"name": "Standard",
"rates": [
{
"rateKey": "<NEW rateKey, valid 20 min>",
"clientCurrency": "USD",
"cancellationPolicies": [...],
"reservationPolicies": [...],
"amount": 116.00,
"publicAmount": 135.98,
"taxes": {...},
"feesNotIncluded": {...},
"roomOccupancies": [
{ "adults": 2, "amount": 740.29 },
{ "adults": 1, "minorsAges": "6,6", "amount": 740.29 }
]
}
]
}
],
"id": 100652,
"name": "Ocean View Cancun Arenas",
"remarks": "Hotel notes, mandatory taxes payable at hotel, etc."
},
"eventId": "30456e90-4525-4d3f-a2b4-aca715da3bcf"
}

Important: it is hotel (singular) here, not hotels (plural)

Section titled “Important: it is hotel (singular) here, not hotels (plural)”

/hotels/rates returns hotels[]. /hotels/checkrates returns a single hotel object since you queried for one specific rate.

Tells you how the room can be occupied. Useful when the rate supports both adult-only and adult+children configurations at the same price.

Field Description
adults Number of adults
minorsAges Comma-separated ages of minors
amount Total amount in hotel currency (not client currency)

Free text from the hotel. Often contains:

  • Mandatory taxes payable at hotel (e.g. “$67.42 MXN per room per night”)
  • Visa / entry requirements
  • Hotel-specific notes
  • Always before BookingHold.
  • After getting a rateKey from Rates, within 60 minutes.
  • The price/availability may have changed since Rates — use the new rateKey returned.
From To Limit
Rates rateKey Used in CheckRates 60 minutes
CheckRates rateKey Used in BookingHold 20 minutes

If you exceed 60 minutes, error 4004 is returned.

Code HTTP Message Cause What to do
1002 401 agency configuration not Found Channel/agency not provisioned Contact PriceTravel with the request, the response, and the eventId
1003 400 Invalid agency templateId Agency setup issue Contact PriceTravel with the request, the response, and the eventId
4001 400 The RateKey must be valid rateKey corrupted, expired, or empty (e.g. {{ _.rateKey }} not substituted) Send the rateKey from HotelRates complete and unmodified; if it expired, re-search via /hotels/rates
4002 400 More hotels than expected rateKey contains multiple hotels — invalid for CheckRates Send a rateKey for a single hotel
4003 400 You don’t have enough credit Channel credit / line balance exhausted Contact PriceTravel to review your credit balance
4004 400 RateKey older than 60 min The rateKey from HotelRates is older than 60 min Re-search via /hotels/rates
4005 200 No results The rate is no longer available at all Re-search via /hotels/rates
4006 200 <provider message> (e.g. “not allotment for the rate”) Supplier-specific availability error Re-search via /hotels/rates
5001 500 Miss-match of channel Id Channel mismatch Contact PriceTravel with the request, the response, and the eventId
5007 401 Mismatch of channel id. Channel id from previous step: <X> The rateKey was generated with another channel’s credentials Run the whole flow, from HotelRates on, with the same credentials

Special case: 4006 “not allotment for the rate ”

Section titled “Special case: 4006 “not allotment for the rate ””

The supplier no longer has inventory for that specific rate. The rateKey was valid at search time but the supplier sold out between Rates and CheckRates. Solution: re-search via /hotels/rates and get a fresh rateKey.

Special case: 4005 “Your search did not yield any results”

Section titled “Special case: 4005 “Your search did not yield any results””

Returned with HTTP 200 (not an error in HTTP terms). The rate is gone but the API responded successfully. Treat as “sold out — re-search.”

If the price differs between Rates and CheckRates, the new rate must be presented to the user before continuing. The amount returned by CheckRates is the binding rate going into BookingHold.