Skip to content

HotelRates

POST {base_url}/1.0/hotels/rates

Returns availability and rates for one or more hotels in a date range.

Header Value
Authorization Bearer <access_token>
Content-Type application/json
Accept application/json
Accept-Encoding gzip
Param Required Type Notes
language No string Language of the response content. Accepted values: en-us, es-mx. Default: en-us

Your channel has a default language (English unless configured otherwise); to request a different one, use ?language= — see Languages.

{
"checkIn": "2027-05-15",
"checkOut": "2027-05-16",
"roomCriteria": [
{
"paxes": [
{ "age": 30 }
]
}
],
"hotelIds": [100652],
"hotelRateFilter": {
"nonRefundable": false
},
"market": "MX"
}
Field Required Type Notes
checkIn Yes string (YYYY-MM-DD) Cannot be a past date
checkOut Yes string (YYYY-MM-DD) Must be > checkIn
roomCriteria[] Yes array One entry per room requested
roomCriteria[].paxes[] Yes array Pax list — at least one adult (18+) required
roomCriteria[].paxes[].age Yes int Under 17 = minor
hotelIds[] Yes array of int Max 50 IDs per call
hotelRateFilter.nonRefundable No bool Rate filter. In one Integration sample, true and false returned the same 19 rates — 7 non-refundable and 12 refundable in both — so do not rely on it to narrow results, and check cancellationPolicies on every rate. Default: false
market No string ISO country code from Market catalog (e.g. MX, IN, US, ES)

If you send name and surname in roomCriteria[].paxes[], do not expect them to be returned by BookingGet — see BookingGet. To send guest names per room, use BookingHold: see Guest data in the hold.

{
"hotels": [
{
"id": 100652,
"name": "Ocean View Cancun Arenas",
"rooms": [
{
"id": 16370816,
"name": "Standard",
"rates": [
{
"rateKey": "RMDsX5...AAB=",
"clientCurrency": "USD",
"cancellationPolicies": [
{
"startDate": "2027-05-12T00:00:00Z",
"endDate": "2027-05-15T23:59:59Z",
"amount": 116.00,
"currency": "USD"
}
],
"reservationPolicies": [
{ "type": "MEAL_PLAN", "code": "I", "description": "All Inclusive" },
{ "type": "RESERVATION", "code": "PREPAID", "description": "Prepaid" }
],
"amount": 116.00,
"publicAmount": 135.98,
"taxes": { "total": 16.00, "details": [] },
"feesNotIncluded": { "total": 0, "details": [], "currency": "" }
}
]
}
]
}
],
"eventId": "93072334-e0f6-4abd-9c9c-02ffca872382"
}
Field Type Description
hotels[].id int Hotel identifier
hotels[].name string Hotel name
hotels[].rooms[].id int Room type ID
hotels[].rooms[].name string Room name
hotels[].rooms[].rates[].rateKey string Use this for CheckRates — valid 60 min
hotels[].rooms[].rates[].clientCurrency string Currency for displayed prices
hotels[].rooms[].rates[].amount decimal Net amount the agency pays
hotels[].rooms[].rates[].publicAmount decimal Recommended sale price (includes margin)
hotels[].rooms[].rates[].cancellationPolicies array Penalty by date range (UTC)
hotels[].rooms[].rates[].reservationPolicies array Meal plan + reservation type
hotels[].rooms[].rates[].taxes object Mandatory + others (informational)
hotels[].rooms[].rates[].feesNotIncluded object Fees charged at hotel check-in
eventId string Trace ID — include this when reporting issues

A rate is effectively non-refundable when:

cancellationPolicies[i].amount === rates.amount

The penalty equals the rate price → 100% penalty → no real refund window.

Code HTTP Message Cause What to do
429 429 Request rate limit exceeded Too many requests in a short period Reduce the request rate and retry with a delay
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 at PT Contact PriceTravel with the request, the response, and the eventId
3001 400 CheckIn can not be a past date checkIn is before today Send a checkIn of today or later
3002 400 CheckOut can not be earlier or equal to CheckIn checkOut is on or before checkIn Send a checkOut later than checkIn
3003 400 Can’t quote more than 28 days The requested range exceeds 28 days Split the stay into requests of 28 days or fewer
3004 400 All rooms must contain at least one adult (18+) A room in roomCriteria has no pax aged 18 or over Include at least one pax aged 18 or over in every room
4001 500 Invalid Channel Id on Rate Limiter Internal Contact PriceTravel with the request, the response, and the eventId
5001 500 Miss-match of channel Id Channel mismatch Contact PriceTravel with the request, the response, and the eventId
Symptom Likely cause
Empty hotels[] but no error No availability for those dates/criteria
Same hotel returns rates one minute and not the next Real-time inventory fluctuation from supplier
429 on every retry Channel rate limit — back off and retry with delay
Fees currency: "" Hotel does not charge fees on arrival