2.2.2.1 Price Search

About 1540 wordsAbout 5 min

2025-11-03

Warning

Mandatory
Klook calls this interface to query the real-time rates, including price, inventory, and policy, for the specified hotels, dates, and occupancy information from the supplier.

URL

Integrator to define and provide the URL to Klook

Input Parameters

Field	Type	Mandatory	Description
`hotelList`	`List<String>`	true	Integrator Hotel ID list Multiple hotels may exist during batch price search Max List size refers to `Max number of hotels supported for price search request` in `2.2.1.5 Offline Provision and Fixed Configuration Data Description`
`checkIn`	`String`	true	Check-in Time, format: `yyyy-MM-dd`
`checkOut`	`String`	true	Check-out Time, format: `yyyy-MM-dd`
`roomCount`	`int`	true	Number of Rooms
`occupancy`	`Occupancy`	true	Room occupancy information (occupancy information of one room)
`countryCode`	`String`	true	Standard two-letter country code (e.g.: `HK`, `CN`) `User IP Country`
`language`	`String`	true	Standard Language Code (e.g.: `zh_CN`, `en_US`). Defaults to `en_US`
`currency`	`String`	true	Standard three-letter currency code (e.g.: `HKD`, `CNY`)
`platform`	`String`	true	Request source platform Enum: `website`, `mobile`

`Occupancy`

Field	Type	Mandatory	Description
`adultCount`	`Integer`	true	Number of adults per room
`childCount`	`Integer`	true	Number of children per room
`childrenAges`	`List<Integer>`	false	`childrenAges` will only exist if the number of children is not 0

`Base` Input Parameter Extension Fields

Field	Type	Mandatory	Description
`supplierAccount`	`String`	false	openApi supplier account `Integrator defines the account data` `1: The account is used for different product types for specific use cases. For example, a Member account returns rates for Members only, non-Members will not see the rate. It supports multiple accounts` `2: If the integrator does not have multiple accounts, the value passed is null` `3: Length does not exceed 128 characters`

Input Parameter Example

Example

{
  "base": {
    "requestId": "xxxx",
    "requestTime": "xxx",
    "requestAgent": "xxx",
    "openApiSign": "xx",
    "supplierAccount": "account1",
    "version": "xxx"
  },
  "requestData": {
    "hotelList": [
      "26546159",
      "123456"
    ],
    "checkIn": "2025-05-26",
    "checkOut": "2025-05-28",
    "roomCount": 1,
    "occupancy": {
      "adultCount": 2,
      "childCount": 1,
      "childrenAges": [
        8
      ]
    },
    "countryCode": "HK",
    "language": "en_US",
    "currency": "CNY",
    "platform": "website"
  }
}

Output Parameters

Field	Type	Mandatory	Description
`hotelRoomRateList`	`List<HotelRoomRate>`	true	Hotel Rate List

`HotelRoomRate`

Field	Type	Mandatory	Description
`hotelId`	`String`	true	Integrator Hotel ID
`roomId`	`String`	true	Integrator Room Type ID
`roomName`	`String`	false	Integrator Room Type Name
`ratePlanId`	`String`	true	Rate Plan ID Must be unique at the `supplierHotelId` level; otherwise, there will be price search exceptions.Try not to include special characters unless necessary
`currency`	`String`	true	Currency Must be consistent with the input parameter currency
`availableRooms`	`Integer`	false	Remaining room availability (inventory) `If not provided, Klook will use the room count from the price search input as the remaining inventory`
`roomDetailBedList`	`List<RoomDetailBed>`	false	Room detail bed list `If the price search does not return bed type information, Klook uses the bed type corresponding to the room type in the static data`
`cancelPolicyList`	`List<CancelPolicy>`	false	Cancellation Policy List `1: Must be ordered by starting time 'start' from smallest to largest` `2: Empty means non-cancellable` `3: For time periods before first 'start', Klook will treat all as free cancellation` `4：Even if the cancellation is completely free, a cancellation with a penalty must be given. You can refer to the "check in" penalty of 100% on the same day`
`maxAdultOccupancy`	`Integer`	false	Maximum adult occupancy per room `If not provided, the number of adults in the price search input will be used`
`maxChildOccupancy`	`Integer`	false	Maximum child occupancy per room `If not provided, the number of children in the price search input will be used`
`mealInfo`	`MealInfo`	false	Meal information `If no meal info is provided, it is uniformly treated as no meal`
`totalPrice`	`TotalPrice`	true	Total Room Price (multiple rooms/multiple nights)
`perRoomDailyPriceList`	`List<PerRoomDailyPrice>`	true	Daily Price List for one room (daily price may vary per room) `1：Must be sorted by date 'date' from smallest to largest. This price must be accurate; all Klook price processing is primarily based on this list` `2: Only the daily price details for one room need to be provided. By default, the total price is equal to the single room price multiplied by the number of rooms`
`perRoomArrivalFeeList`	`List<ArrivalFee>`	false	Arrival Fee (one room/multiple nights) `Must be provided if there are fees to be paid upon arrival`
`perRoomFeeAndTaxList`	`List<FeeAndTax>`	false	Tax/Fee Details - Non-Arrival (included in total price, one room/multiple nights) `Per room price before tax + perRoomFeeAndTaxList = Per room price after tax`
`benefitInfoList`	`List<BenefitInfo>`	false	Integrator Rate Amenity/Benefit List
`promotionDetailList`	`List<PromotionDetail>`	false	Promotion detail list
`configData`	`String`	false	Integrator custom data returned from price search `Length must not exceed 64. Klook will include this parameter in the price check request input`

`RoomDetailBed` (Room Bed Detail)

Field	Type	Mandatory	Description
`roomName`	`String`	false	Room Name
`roomDesc`	`String`	false	Room Description
`bedList`	`List<List<BedStructure>>`	true	Room Bed Type (Affects mapping) `The inner nodes of the first layer List have an "OR" relationship` `The inner nodes of the second layer List have an "AND" relationship` `(Example: (1 King Bed and 2 Single Beds) OR (2 Queen Beds and 3 Single Beds))`

`BedStructure` (Bed Structure)

Field	Type	Mandatory	Description
`bedId`	`String`	true	Integrator Bed Type ID `Klook will convert based on the supplier dictionary supplierKey (dataType = 11)`
`bedName`	`String`	false	Integrator Bed Type Name
`width`	`double`	false	Bed width, unit in meters (Affects mapping)
`length`	`double`	false	Bed length, unit in meters (Affects mapping)
`quantity`	`int`	true	Bed quantity

`BenefitInfo`

Field	Type	Mandatory	Description
`benefitCode`	`String`	true	Benefit Code `Klook will convert based on the supplier dictionary supplierKey (dataType = 10)`
`count`	`int`	false	Quantity

`CancelPolicy`

Field	Type	Mandatory	Description
`start`	`String`	true	Start Time, must include timezone, format: `yyyy-MM-dd'T'HH:mm:ss.SSSXXX`
`end`	`String`	true	End Time, must include timezone, format: `yyyy-MM-dd'T'HH:mm:ss.SSSXXX`
`amount`	`String`	true	Amount (Penalty)

`MealInfo`

Field	Type	Mandatory	Description
`mealCode`	`String`	true	Integrator's Meal Type `Klook will convert based on the dictionary (dataType = 8)`
`mealCount`	`integer`	false	Number of meals `-1: Not given` `-100: Per person` `Greater than 0: Actual number of meals` `If empty, -1, or -100, Klook will uniformly treat the number of meals = number of guests`

`TotalPrice`

Field	Type	Mandatory	Description
`amountBeforeTax`	`String`	false	Price before tax. Unit: currency unit
`amountAfterTax`	`String`	true	Price after tax. Unit: currency unit
`commission`	`String`	false	Commission `If the integrator can provide it, Klook will use the integrator's commission; otherwise, Klook calculates it based on the merchant cooperation settings`

`PerRoomDailyPrice`

Field	Type	Mandatory	Description
`date`	`String`	true	Date, format: `yyyy-MM-dd`
`amountBeforeTax`	`String`	false	Price before tax. Unit: currency unit
`amountAfterTax`	`String`	true	Price after tax. Unit: currency unit
`commission`	`String`	false	Commission `If the integrator can provide it, Klook will use the integrator's commission; otherwise, Klook calculates it based on the merchant cooperation settings`

`ArrivalFee`

Field	Type	Mandatory	Description
`typeCode`	`String`	true	Supplier Tax/Fee Type `Klook will convert based on the dictionary (dataType = 17)` Klook Enum: `mandatory_fee`, `mandatory_tax`, `resort_fee`, `amenities_fee`
`currency`	`String`	false	Currency `If not returned, it is treated as the price currency (requested merchant currency)`
`amount`	`String`	true	Tax/Fee Amount
`frequencyUnit`	`String`	false	Supplier Tax/Fee Unit `Klook will convert based on the supplier dictionary supplierKey (dataType = 19)` Klook Enum `per_person` `per_room` `per_accommodation` `per_house` `per_apartment` `per_adult` `others` `unknown`
`scopeUnit`	`String`	false	Supplier Tax/Fee Scope `Klook will convert based on the supplier dictionary supplierKey (dataType = 18)` Klook Enum `per_night` `per_day` `per_stay` `per_week` `round_trip` `one_way` `unknown`

`FeeAndTax`

Field	Type	Mandatory	Description
`typeCode`	`String`	true	Supplier Tax/Fee Type `Klook will convert based on the supplier dictionary supplierKey (dataType = 12)` Klook Enum `sales_tax` `surcharge_or_adjustment` `total_recovery_charges` `tax_and_service_fee` `extra_guest_fee` `property_fee` `compensation` `hotel_accommodation_tax`
`amount`	`String`	true	Tax/Fee Amount

`PromotionDetail`

Field	Type	Mandatory	Description
`description`	`String`	false	Promotion Description If the integrator's promotion code is fixed, the promotion code can be returned here instead of the description; a promotion description dictionary must be implemented

Output Parameter Example

Example

{
  "success": true,
  "error": {
    "code": "",
    "message": ""
  },
  "result": {
    "hotelRoomRateList": [
      {
        "hotelId": "26546159",
        "roomId": "104841831",
        "roomName": "Sea View Twin Bed Room",
        "ratePlanId": "1432185081",
        "currency": "CNY",
        "availableRooms": 5,
        "roomDetailBedList": [
          {
            "roomName": "King Bed Room",
            "roomDesc": "King Bed Room multiple beds",
            "bedList": [
              [
                {
                  "bedId": "0",
                  "bedName": "big bed name",
                  "width": 1.2,
                  "length": 2.2,
                  "quantity": 2
                }
              ]
            ]
          },
          {
            "roomName": "Twin Bed Room",
            "roomDesc": "Twin Bed Room multiple beds",
            "bedList": [
              [
                {
                  "bedId": "0",
                  "bedName": "double bed name",
                  "width": 1.2,
                  "length": 2.1,
                  "quantity": 3
                }
              ]
            ]
          }
        ],
        "cancelPolicyList": [
          {
            "amount": "449.10",
            "start": "2022-11-25T12:00:00.000+08:00",
            "end": "2025-08-20T00:00:00.000+08:00"
          }
        ],
        "maxAdultOccupancy": 6,
        "maxChildOccupancy": 2,
        "mealInfo": {
          "mealCode": "breakfast",
          "mealCount": 1
        },
        "totalPrice": {
          "amountBeforeTax": "45",
          "amountAfterTax": "50",
          "commission": "0.55"
        },
        "perRoomDailyPriceList": [
          {
            "date": "2025-10-01",
            "amountBeforeTax": "21.22",
            "amountAfterTax": "25",
            "commission": "0.55"
          }
        ],
        "perRoomArrivalFeeList": [
          {
            "typeCode": "mandatory_fee",
            "currency": "HKD",
            "amount": "8",
            "frequencyUnit": "per_night",
            "scopeUnit": "per_person"
          }
        ],
        "perRoomFeeAndTaxList": [
          {
            "typeCode": "sales_tax",
            "amount": "20.26"
          }
        ],
        "benefitInfoList": [
          {
            "benefitCode": "Free gift",
            "count": 1
          }
        ],
        "promotionDetailList": [
          {
            "description": "Summer Promotion"
          }
        ],
        "configData": "AAAABBBBCCCCCBDDDDBBDDDD"
      }
    ]
  }
}

1. Getting Started

2. Interface Documentation

2.1 Basic Structure

2.2 Standard Interfaces

2.2.1 Static Data Processing

2.2.2 Standard Booking Flow

3. Information Hub

4. FAQ

2.2.2.1 Price Search

URL

Input Parameters

`Occupancy`

`Base` Input Parameter Extension Fields

Input Parameter Example

Output Parameters

`HotelRoomRate`

`RoomDetailBed` (Room Bed Detail)

`BedStructure` (Bed Structure)

`BenefitInfo`

`CancelPolicy`

`MealInfo`

`TotalPrice`

`PerRoomDailyPrice`

`ArrivalFee`

`FeeAndTax`

`PromotionDetail`

Output Parameter Example