HotelRates
Endpoint
Section titled “Endpoint”POST {base_url}/1.0/hotels/ratesReturns availability and rates for one or more hotels in a date range.
Headers
Section titled “Headers”| Header | Value |
|---|---|
Authorization |
Bearer <access_token> |
Content-Type |
application/json |
Accept |
application/json |
Accept-Encoding |
gzip |
Query params
Section titled “Query params”| 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.
Request body
Section titled “Request body”{ "checkIn": "2027-05-15", "checkOut": "2027-05-16", "roomCriteria": [ { "paxes": [ { "age": 30 } ] } ], "hotelIds": [100652], "hotelRateFilter": { "nonRefundable": false }, "market": "MX"}Body fields
Section titled “Body fields”| 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.
Response (success)
Section titled “Response (success)”{ "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"}Response fields
Section titled “Response fields”| 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 |
Identifying non-refundable rates
Section titled “Identifying non-refundable rates”A rate is effectively non-refundable when:
cancellationPolicies[i].amount === rates.amountThe penalty equals the rate price → 100% penalty → no real refund window.
Errors specific to this endpoint
Section titled “Errors specific to this endpoint”| 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 |
Diagnostic patterns
Section titled “Diagnostic patterns”| 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 |

