Module: hotel

Hotel Booking

Methods


<static> book(header, body)

POST Book

Parameters:
Name Type Argument Default Description
header YHeader

HTTP request header

params.mode string <optional>
async

Mode. Since booking can be time-consuming, an asynchronous mechanism is available to generate orders and retrieve booking confirmation numbers in steps for better user experience.

  • sync Synchronously responds with all data.
  • async Recommended. Synchronously responds with order data, order status is confirming. Subsequently, use webhook or order/search to asynchronously retrieve the confirmation number; order status will be upcoming.
body object

HTTP request body

Properties
Name Type Argument Description
user User <optional>

Booker

booking HotelBooking

Hotel booking information

payment Payment <optional>

Payment information

merchant object <optional>

Merchant order information

Properties:
Name Type Description
body.merchant.uid string

Order identifier

Since:
  • 1.0.0
Returns:
Type
bookResponse

<static> rateCalendar(header, body)

POST Get one-night hotel rates by check-in date. dateRange.end is exclusive. The maximum range is 90 days, or 270 days for hotelux and hoteluxjp channels.

Parameters:
Name Type Description
header YHeader

HTTP request header

body object

HTTP request body

Properties
Name Type Argument Description
preferred Preferred <optional>

Preferences; currency is used for approximate price conversion

hotel Hotel

Hotel, identified by _id

dateRange object

Date range to query

Properties
Name Type Description
start string

First check-in date, YYYY-MM-DD

end string

Exclusive end date, YYYY-MM-DD

Since:
  • 1.0.0
Returns:
Type
HotelRateCalendarResponse

<static> rateRule(header, body)

POST Get rate plan and rules. To obtain more accurate price details, ensure this is displayed to the user before they place an order.

  • E.g. For a "Stay 3, Pay for 2" offer (Day 1 1200, Day 2 1200, Day 3 Free), the rates API might return price details of 800, 800, 800, whereas the rateRule API returns the accurate 1200, 1200, 0.
Parameters:
Name Type Description
header YHeader

HTTP request header

body object

HTTP request body

Properties
Name Type Argument Description
preferred Preferred <optional>

Preferences

stay Stay

Stay information

hotel Hotel

Hotel

rate HotelRate

Rate plan

Since:
  • 1.0.0
Returns:
Type
rateRuleResponse

<static> rates(header [, params], body)

POST Get detailed hotel room types and rate plans

Parameters:
Name Type Argument Description
header YHeader

HTTP request header

params object <optional>

HTTP request query string parameters

Properties
Name Type Argument Default Description
mode string <optional>
sync

Mode. Since retrieving all rates can be time-consuming, an asynchronous mechanism is available to fetch first-page rates and all rates in batches for better user experience.

  • sync Synchronously responds with all data.
  • async Recommended. Asynchronously retrieves all rates. Synchronously responds with first-page rates and asyncJobId. Use asyncJobId to retrieve all rates asynchronously.
  • asyncPaging Recommended. Asynchronously retrieves all rates. Synchronously responds with first-page rates and asyncJobId. Use asyncJobId to retrieve subsequent pages of rates, fetching page by page until asyncJobId is null.
body object

HTTP request body

Properties
Name Type Argument Description
preferred Preferred <optional>

Preferences

stay Stay

Stay information

hotel Hotel

Hotel

Since:
  • 1.0.0
Returns:
Type
ratesResponse

<static> search(header [, params], body)

POST Search for hotels and prices

Parameters:
Name Type Argument Description
header YHeader

HTTP request header

params object <optional>

HTTP request query string parameters

Properties
Name Type Argument Default Description
mode string <optional>
sync

Mode. Since retrieving prices can be time-consuming, an asynchronous mechanism is available to fetch basic data and prices in batches for better user experience.

  • sync Synchronously responds with all data.
  • async Recommended. Asynchronously retrieves prices. Synchronously responds with basic data (excluding minBasePrice and minPrice) and asyncJobId. Use asyncJobId to retrieve prices asynchronously.
body object

HTTP request body

Properties
Name Type Argument Default Description
preferred Preferred <optional>

Preferences

user User <optional>

Booker

stay Stay

Stay information

filter HotelFilter

Filter criteria

  • Set filter.highCommission=true to return only hotels whose high commission sample matches the requested stay.
sort string <optional>
byRecommendation

Sorting method

  • byRecommendation Sort by system recommendation.
  • byUserRecommendation Sort by user history and system recommendation. Valid only when user has a value.
  • byMinBasePrice Sort by lowest single-night price (ascending). Since prices are queried from suppliers in real-time, this sorting method significantly reduces query performance.
  • byMinBasePriceDescending Sort by lowest single-night price (descending). Since prices are queried from suppliers in real-time, this sorting method significantly reduces query performance.
  • byDistance Sort by distance. Valid only when filter.geospatial is provided.
  • byHotelFilterOrder Preserve the hotel order in filter.hotels. Only _id-based hotel filters are supported.
  • bySearch Sort by search keyword relevance. Valid when filter.search is provided.
paging Paging <optional>

Pagination info

Since:
  • 1.0.0
See:
Returns:
Type
searchResponse

Type Definitions


bookResponse

Type:
  • object
Properties:
Name Type Argument Description
err Error <optional>

Error message, possible messageKeys:

  • invalidTraveler Traveler information is incorrect, usually because the name contains non-English characters.
  • invalidCreditCard Credit card information is incorrect, usually due to invalid expiry date format (YYMM) or incorrect card number.
  • invalidPriceDetail Price is incorrect, usually due to incorrect booking.rate.priceDetail. (Validation is disabled by default; contact support to enable and set booking.rateRule.key in the book request).
  • invalidRate Rate plan is incorrect, usually because the price has changed and needs to be re-fetched. (Validation is disabled by default; contact support to enable and set booking.rateRule.key in the book request).
order Order

Order

Since:
  • 1.0.0

HotelRateCalendarDay

Type:
  • object
Properties:
Name Type Argument Description
checkIn string

Check-in date in YYYY-MM-DD format; each entry is for a one-night stay

lowest HotelRate <optional>

Lowest rate for the day, containing only code, name, nameEn, price, and priceDetail; absent when no rate is available

Since:
  • 1.0.0

HotelRateCalendarResponse

Type:
  • object
Properties:
Name Type Argument Description
err Error <optional>

Error message

results Array.<HotelRateCalendarDay>

Daily rates in date order; dates without available rates still include checkIn

Since:
  • 1.0.0

rateRuleResponse

Type:
  • object
Properties:
Name Type Argument Description
err Error <optional>

Error message

rate HotelRate

Rate plan, containing only price and priceDetail nodes. Data here is more accurate than that returned by the rates API.

rateRule HotelRateRule

Rate plan rules

Since:
  • 1.0.0

ratesResponse

Type:
  • object
Properties:
Name Type Argument Description
err Error <optional>

Error message

rooms Array.<HotelRoom>

Room types

asyncJobId string <optional>

Asynchronous job ID. Null indicates no more rates need to be retrieved asynchronously.

Since:
  • 1.0.0

searchResponse

Type:
  • object
Properties:
Name Type Argument Description
err Error <optional>

Error message

paging Paging

Pagination info

hotels Array.<Hotel>

List of hotels

asyncJobId string <optional>

Asynchronous job ID

Since:
  • 1.0.0