Tips

• Required.
• klook supports a maximum of 8 rooms for a single room order. If the access party does not support multiple rooms for a single order, please inform klook of the maximum number of rooms supported per order. klook can configure the order splitting coefficient corresponding to the number of rooms in a single room order
  1. access party level
  2. hotel level
• The order placement interface will only have a retry mechanism when it times out. The access party needs to ensure the idempotence of the order placement interface, that is, for the order placement requests of the same order number, if the access party has already processed them, there is no need to reprocess them. Just return the corresponding data of the klook order

URL

The access party defines it by itself and provides it to klook

Input Parameters

Interface Request Parameters

Field	Type	Required	Description
hotelId	String	true	Supplier hotel ID. 1: For partially managed suppliers using Klook hotels as primary, use Klook hotel ID here. Refer to idType.
hotelName	String	false	Hotel name.
roomId	String	true	Supplier room ID. 1: For partially managed suppliers using Klook hotels as primary, use Klook hotel ID here. Refer to idType.
roomName	String	false	Room name.
ratePlanId	String	true	Rate plan ID. 1: For partially managed suppliers using Klook hotels as primary, use Klook hotel ID here. Refer to idType.
ratePlanName	String	false	Rate plan name.
orderCode	String	true	Klook order number, globally unique.
checkIn	String	true	Check-in date.
checkOut	String	true	Check-out date.
contact	Contact	true	Contact information.
specialRequest	String	false	Special requests.
occupancy	Occupancy	true	Room occupancy information, single room occupancy information.
rooms	List<Room>	true	Occupancy information list. list.size = room size. When placing an order for multiple rooms at a time, the number of guests' information is optional, with a minimum of one guest. If a customer only fills in the information of one guest, the check-in information for each room will be the same
price	Price	true	Price information.
payments	Payments	false	Payment method.

Room

Field	Type	Required	Description
guests	list<Guest>	true	Guest information.

Guest

Field	Type	Required	Description
firstName	String	true
lastName	String	true

Occupancy

Field	Type	Required	Description
adultCount	Integer	true
childCount	Integer	true
childrenAges	list<integer>	false	When childCount != 0

Price

Field	Type	Required	Description
totalPrice	TotalPrice	true	Total price for multiple rooms and nights.
perRoomDailyPrices	List<PerRoomDailyPrice>	true	Price details for a single room over multiple nights.
other	Other	false	Other.

TotalPrice

Field	Type	Required	Description
amountBeforeTax	String	false	Price before tax
amountAfterTax	String	true	Price after tax If there is a commission, the commission will be deducted (configurable, default deduction). If there is a discount, the discount will be deducted.
currency	String	true	Currency.

PerRoomDailyPrice

Field	Type	Required	Description
amountBeforeTax	String	false	Price before tax
amountAfterTax	String	true	Price after tax
currency	String	true	Currency.
date	String	true	Date: YYYY-MM-DD.

Other

Field	Type	Required	Description
promotion	Promotion	false	Promotion.

Promotion

Field	Type	Required	Description
discount	String	false	Discount amount.
desc	String	false	Promotion description.
currency	String	true	Currency.

Payments

Field	Type	Required	Description
payCard	PayCard	false	Pay card. It is not mandatory. Only when the merchant has enabled vcc can it be available

PayCard

Field	Type	Required	Description
cardType	String	true	Card type: only MC.
number	String	true	Card number.
securityCode	String	true	Security code.
expirationYear	String	true	Expiration year: YY (e.g., 22).
expirationMonth	String	true	Expiration month: MM (e.g., 08).
currency	String	true	Currency.
amount	String	true	Amount Up to 2 decimal places.

Contact Description

Field	Type	Required	Description
firstName	String	true
lastName	String	true
email	String	true	Email.
phone	String	true	Phone number.

Input Example

Example

{
  "base": {
    "requestAgent": "KLOOK",
    "openApiSign": "301e4cfefbc376c4f4c4dac8b096efcdee47810c2a3627b29b2d3a66b8ae04af27f4ff38c4a8d40dff48f6729fe0d7959fdd90f1848f25c595b574872b8ec69a",
    "requestId": "xxxxx111bbbbbcccc",
    "requestTime": "2025-11-28T12:06:15.890+08:00"
  },
  "requestData": {
    "hotelId": " ",
    "hotelName": "",
    "roomId": " ",
    "roomName": "",
    "ratePlanId": " ",
    "ratePlanName": "",
    "orderCode": " ",
    "checkIn": " ",
    "checkOut": " ",
    "contact": {
      "firstName": " ",
      "lastName": " ",
      "email": " ",
      "phone": " "
    },
    "specialRequest": " ",
    "occupancy": {
      "adultCount": 0,
      "childCount": 0,
      "childrenAges": [
        0
      ]
    },
    "rooms": [
      {
        "guests": [
          {
            "firstName": " ",
            "lastName": " "
          }
        ]
      },
      {
        "guests": [
          {
            "firstName": " ",
            "lastName": " "
          }
        ]
      }
    ],
    "price": {
      "totalPrice": {
        "amountBeforeTax": "1",
        "amountAfterTax": "106",
        "currency": ""
      },
      "perRoomDailyPrices": [
        {
          "date": "2025-10-01",
          "amountBeforeTax": "21.22",
          "amountAfterTax": "25",
          "currency": ""
        },
        {
          "date": "2025-10-02",
          "amountBeforeTax": "23.22",
          "amountAfterTax": "28",
          "currency": ""
        }
      ],
      "other": {
        "promotion": {
          "discount": "25.28",
          "currency": "",
          "desc": "促销描述"
        }
      }
    },
    "payments": {
      "payCard": {
        "cardType": "",
        "number": "",
        "securityCode": "",
        "expirationYear": "",
        "expirationMonth": "",
        "currency": "",
        "amount": ""
      }
    }
  }
}

Curl Example illustration

curl --location 'https://www.test.dddd/test/booking' \
--header 'Content-Type: application/json' \
--data-raw '{
    "base": {
        "requestAgent": "KLOOK",
        "openApiSign": "301e4cfefbc376c4f4c4dac8b096efcdee47810c2a3627b29b2d3a66b8ae04af27f4ff38c4a8d40dff48f67",
        "requestId": "747BAA04B9B642C08E1C2FAD352A0A42",
        "requestTime": "2025-05-13T19:46:18.849+08:00"
    },
    "requestData": {
        "checkIn": "2025-05-26",
        "checkOut": "2025-05-28",
        "contact": {
            "email": "operator@klook.com",
            "firstName": "test",
            "lastName": "li",
            "phone": "852 800931187"
        },
        "hotelId": "3969",
        "hotelName": "HoteliersGuru Test hotel 1",
        "occupancy": {
            "adultCount": 2,
            "childCount": 1,
            "childrenAges": [
                8
            ]
        },
        "orderCode": "FRN448811",
        "payments": {
            "payCard": {
                "amount": "MC",
                "cardType": "MC",
                "currency": "USD",
                "expirationMonth": "05",
                "expirationYear": "27",
                "number": "5329594705169154",
                "securityCode": "225"
            }
        },
        "price": {
            "perRoomDailyPrices": [
                {
                    "amountAfterTax": "180.000000",
                    "amountBeforeTax": "165.5000000",
                    "currency": "USD",
                    "date": "2025-05-26"
                },
                {
                    "amountAfterTax": "200.00",
                    "amountBeforeTax": "105.50",
                    "currency": "USD",
                    "date": "2025-05-27"
                }
            ],
            "totalPrice": {
                "amountAfterTax": "1140.000000",
                "amountBeforeTax": "813.0000000",
                "currency": "USD"
            }
        },
        "ratePlanId": "10483045",
        "ratePlanName": "meal + free cancel",
        "roomId": "5120",
        "roomName": "Standard room（Mezzanine, Street view, Balcony）",
        "rooms": [
            {
                "guests": [
                    {
                        "firstName": "test",
                        "lastName": "li"
                    }
                ]
            },
            {
                "guests": [
                    {
                        "firstName": "test",
                        "lastName": "li"
                    }
                ]
            },
            {
                "guests": [
                    {
                        "firstName": "test",
                        "lastName": "li"
                    }
                ]
            }
        ],
        "specialRequest": ""
    }
}'

Output Parameters

Field	Type	Required	Description
success	boolean	true	Whether successful, true: success, false: failure. When false, error needs to return error information.
error	String	false	Error information.
result	String	false	Result.

error

Field	Type	Required	Description
code	String	true	Error code.
message	String	false	Error message.

result

Field	Type	Required	Description
supplierOrderCode	String	true	Supplier order number.
supplierConfirmCode	String	false	Supplier confirmation number.
hotelConfirmCode	String	false	Hotel confirmation number, comma-separated if multiple.
status	String	true	Order status, see dictionary orderStatus.

Output Example

{
    "success": true, // When false, error needs to return error information.
    "error": {
        "code": "",
        "message": ""
    },
    "result": {
        "supplierOrderCode": "",
        "supplierConfirmCode": "",
        "hotelConfirmCode": "",
        "status": ""
    }
}

Contributors: Rich

Previous page2.3.1 Price Check

Next page2.3.3: Booking Info Query