3. API Reference
HotelRates
POST /api/search/hotelRates
Returns room-level rates and availability for one specific hotel, across all connected suppliers.
Where HotelList covers many hotels with summary rate data, this call is scoped to a single hotel and returns the full rate detail needed to drive a booking. Every supplier supports detailed rate queries on this endpoint.
Required inputs:
hotelId— identifier of the hotel to pricecheckIn/checkOut— stay dates- occupancies — guest and room layout (sent as the
roomOccupanciesbody field; see the note in the schema, the prose in the source calls this "occupancies") Session-Idrequest header — carries the session used to track the booking process
What comes back:
- Full room-package detail including rates
- Standardized/mapped room types alongside the supplier's own room naming
- Session context so the result can be carried into the booking flow
Typical uses: rendering rates on a hotel detail page, comparing and selecting a room, and starting a detailed booking flow.
Integration guidance: use HotelList for multi-hotel searches with basic rate data, use HotelRates for single-hotel detail, and keep the session identifier consistent so the transition into booking is seamless.
Request headers
| Header | Required | Description |
|---|---|---|
Client-Request-Timestamp |
No | client request time(start to send request); unix timestamp |
Currency |
No | Requested currency for the rates, in https://en.wikipedia.org/wiki/ISO_4217 format |
IP |
No | client IP address, compatible with both IPv4 and IPv6 |
Language |
No | https://masonreview.com/posts/ietf-bcp-47-language-tags/, eg: "en", "en-US"; default "en-US" |
Market |
No | Point-of-sale market for this call, as an ISO 3166-1 alpha-2 country code. Required only when your account carries a market restriction: an allow-list cannot admit a market you have not stated, so such an account refuses calls that omit it. |
Request-Id |
No | for identifying the current request, it can't be duplicate |
Session-Id |
Yes | Suggested provided in request by client. It's required in booking flow. |
Test |
No | Test flags. support key-value pairs, eg, "hotel=HC1&scenario=priceChange".If it's not recognized by server, the call will behave as if the "Test" header was not provided. |
Timeout-Milliseconds |
No | timeout specified by client, and server will try its best to return data before this timeout |
Trace-Id |
No | for tracing a group of requests |
User-Ref |
No | Your own identifier for the person on whose behalf this call is made. Required only once named users have been authorised on your account, after which every call must identify one and is authorised against that user's scopes as well as the key's. |
Authorization |
Yes | starts with "Bearer ". got from Ticket response. Ticket doesn't need it |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
hotelId |
string | Yes | |
checkIn |
string | Yes | CheckIn is the check-in date, defaults to current date |
checkOut |
string | Yes | CheckOut is the check-out date, defaults to 7 days from now |
countryCode |
string | No | CountryCode is the country code of the booker's point of sale in ISO 3166-1 alpha-2 format (e.g., "US") |
residencyCode |
string | No | ResidencyCode is the residency code of the booker in ISO 3166-1 alpha-2 format (e.g., "US") |
nationalityCode |
string | No | NationalityCode is the nationality code of the booker in ISO 3166-1 alpha-2 format (e.g., "US") |
roomOccupancies[] |
array<hotel.supplier.domain.GuestPerRoom> | Yes | |
roomOccupancies[].adultCount |
integer | Yes | AdultCount is the number of adults |
roomOccupancies[].childrenAges[] |
array |
No | ChildrenAges contains ages of children |
Example request
{
"hotelId": "461850557",
"checkIn": "2026-01-01",
"checkOut": "2026-01-03",
"countryCode": "US",
"residencyCode": "US",
"nationalityCode": "US",
"roomOccupancies": [
{
"adultCount": 2,
"childrenAges": [
2
]
}
]
}Response
Successful calls return the standard envelope. code is 0 on success — check it rather than the HTTP status alone, because some business failures are delivered with HTTP 200.
| Field | Type | Required | Description |
|---|---|---|---|
code |
integer | No | |
msg |
string | No | |
data |
hotel.search.protocol.HotelRatesResp | No | |
data.rooms[] |
array |
No | rooms contains room packages |
data.rooms[].roomTypeId |
string | Yes | Standardized room type ID, e.g. "R001". |
data.rooms[].roomTypeName |
I18N | Yes | Standardized room type name. When the supplier's type cannot be recognised, a fallback such as "Standard Room" is returned. |
data.rooms[].roomTypeName.en |
string | No | English; the default system language. |
data.rooms[].roomTypeName.zh |
string | No | Chinese (中文). |
data.rooms[].roomTypeName.ar |
string | No | Arabic (اللغة العربية). |
data.rooms[].hotelId |
string | Yes | Hotel ID. Repeats the parent hotel's ID so the room can be identified on its own. |
data.rooms[].rates[] |
array<hotel.supplier.domain.RoomRatePkg> | No | The core structure — the room offers available for this room. |
data.rooms[].rates[].ratePkgId |
string | Yes | used as key input for checkAvail & book APIs |
data.rooms[].rates[].refundableMode |
RefundableMode | Yes | Refundability of the rate package: full = RefundableModeFully - free cancellation partial = RefundableModePartially - partial cancellation no = RefundableModeNo - not refundable Allowed: full, partial, no. |
data.rooms[].rates[].refundableUntil |
string | No | RefundableMode is valid until RefundableUntil |
data.rooms[].rates[].cancelFees[] |
array<hotel.supplier.domain.ComputedCancelPolicyItem> | No | |
data.rooms[].rates[].originalRoomNaming |
OriginalRoomNaming | No | origin room naming fields from supplier |
data.rooms[].rates[].rate |
Rate | Yes | single room price for multiple nights |
data.rooms[].rates[].totalRate |
Rate | Yes | total price for multiple rooms (and multiple nights) |
data.rooms[].rates[].rateComment |
string | No | |
data.rooms[].rates[].includesPackaging |
boolean | No | Whether this is a packaged product (e.g., flight+hotel combo) |
data.rooms[].rates[].checkIn |
string | Yes | CheckIn is the check-in date, defaults to current date |
data.rooms[].rates[].checkOut |
string | Yes | CheckOut is the check-out date, defaults to 7 days from now |
data.rooms[].rates[].board |
Board | No | Board info - Standard meal plan following liteapi standard |
data.rooms[].rates[].tax |
Tax | No | Taxes and fees, generally collected by hotels on behalf of the government, are fixed costs and do not participate in the price increase during the distribution process. Therefore, they are listed separately. |
Failure responses
| HTTP | Meaning |
|---|---|
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 429 | Too Many Requests |
Every failure uses the { code, msg } envelope. See Error handling for the full business-code table.
Code samples
# $SESSION_ID is the sessionId returned by hotelList (data.basic.sessionId).
curl -X POST https://api-test.ttdbooking.com/api/search/hotelRates \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TICKET" \
-H "Session-Id: $SESSION_ID" \
-H "Request-Id: $(uuidgen)" \
-d '{
"hotelId": "461850557",
"checkIn": "2026-01-01",
"checkOut": "2026-01-03",
"countryCode": "US",
"residencyCode": "US",
"nationalityCode": "US",
"roomOccupancies": [
{
"adultCount": 2,
"childrenAges": [
2
]
}
]
}'Try it
Try it
POST /api/search/hotelRatesA ticket will be fetched with ttdbooking_api_demo.
Session-IdRequired here. One will be opened with a hotelList search on the first request, then reused across these pages.