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 price
checkIn / checkOut — stay dates
occupancies — guest and room layout (sent as the roomOccupancies body field; see the note in the schema, the prose in the source calls this "occupancies")
Session-Id request 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

json

{
  "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.

Example response

json

{
  "code": 0,
  "msg": "string",
  "data": {
    "rooms": [
      {
        "roomTypeId": "string",
        "roomTypeName": {
          "en": "string",
          "zh": "string",
          "ar": "string"
        },
        "hotelId": "string",
        "rates": [
          {
            "ratePkgId": "string",
            "refundableMode": "full",
            "refundableUntil": "2006-01-02T15:04:05Z07:00",
            "cancelFees": [],
            "originalRoomNaming": {},
            "rate": {},
            "totalRate": {},
            "rateComment": "string",
            "includesPackaging": false,
            "checkIn": "2026-01-01",
            "checkOut": "2026-01-03",
            "board": {},
            "tax": {}
          }
        ]
      }
    ]
  }
}

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

bash

# $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

POST /api/search/hotelRates

Base URLThe published API hosts, or a localhost origin for local testing.Request body

A 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.