Use this method to create a new booking in WebHotelier.

Table of Contents
  1. URL Endpoint
  2. Method Parameters
  3. JSON Response Schema
  4. JSON Response Example

URL Endpoint

/book/{propertycode}

Warning

This method is only available via a secure connection (https).

Note

This method is only accessible using a POST request.

Parameters must be sent in the request body (not in the URL) with Content-Type application/x-www-form-urlencoded.

To get a response in JSON make sure you are also sending the Accept: application/json header.

Warning

The API user is responsible for notifying the property and the customer of a successful booking.

If you also like our system to send confirmation e-mails make sure you pass the confirmation_email parameter. However, you should NEVER pass the confirmation_email parameter if you plan to use the /purge. If there is any post-processing involved, you should use the /reservation/confirmation_email method on success.

Method Parameters

Basic

NAME TYPE RANGE / SET REQUIRED DEFAULT EXAMPLE NOTES
checkin date (ISO 8601) from today
to (today + 3 years)
YES &checkin=2024-02-29  
checkout date (ISO 8601) from (checkin + 1)
to (checkin + 30)
YES &checkout=2024-03-07
rate integer YES &rate=448033 The rate being booked.
price decimal YES &price=1000 The final booking price shown to the user. Must match actual booking price for the booking to succeed.
rooms integer 1 – 5 NO 1 &rooms=1  
adults integer 1 – max capacity YES
(unless party param is specified)
&adults=2 The value is PER ROOM.
children integer 0 – (max capacity-1) NO 0 &children=1 The value is PER ROOM.
infants integer 0 – (max capacity-1) NO 0 &infants=1 The value is PER ROOM.
party JSON string NO** - One room: &party=[{"adults": 2}]

Two rooms with mixed occupancies: &party=[{"adults":2, "children":[2,6]},{"adults":3}]
Array of JSON objects representing number of adults and children.
"adults": (REQUIRED - integer) The number of adults staying in the room.
"children": (OPTIONAL - array of integers) The ages of any children staying in the room.

Payment

NAME TYPE RANGE / SET REQUIRED DEFAULT EXAMPLE NOTES
payment_method string CC (Credit Card)
BANK (Wire Transfer)
CHKIN (Pay on arrival)
CHKOUT (Pay on deparure)
NO &payment_method=BANK Your API account may have been configured to accept only Credit Card payment. In this case, sending any value other that CC will return error.
cardNumber numeric credit card YES
if payment_method is CC
&cardNumber=4556455645564556  
cardType string AmEx (American Express)
DIN (Diners)
Disc (Discover)
JCB
Maes (Maestro)
MC (MasterCard)
Visa
Union (UnionPay)
YES
if payment_method is CC
&cardType=AmEx  
cardName string varchar(30) YES
if payment_method is CC
&cardName=John%20Smith
cardMonth integer 1-12 YES
if payment_method is CC
&cardMonth=6
cardYear integer 2024–2124 YES
if payment_method is CC
&cardYear=2025
cardCVV numeric 000–999 YES
if payment_method is CC
&cardCVV=123
cardIssue numeric 0000–9999 NO &cardIssue=0154 Required only for Maestro

Customer information

NAME TYPE RANGE / SET REQUIRED DEFAULT EXAMPLE NOTES
firstName string varchar(30) YES 0 &firstName=John
lastName string varchar(30) YES 0 &lastName=Smith
email string email, varchar(128) YES 0 &email=jsmith%40aol.com
tel string varchar(30) NO &tel=00302101818998
country string ISO 3166-1-alpha-2 NO &country=US
region string varchar(30) NO &region=Oregon
location string varchar(30) NO &location=Portland
address string varchar(128) NO &address=128 mark avenue
postal string varchar(10) NO &postal=68100
company string varchar(64) NO &company=AcmeInc
purpose string varchar(128) NO &purpose=Business
remarks string text NO &remarks=1st%20floor%20please

Advanced

NAME TYPE RANGE / SET REQUIRED DEFAULT EXAMPLE NOTES
remote_country string ISO 3166-1-alpha-2 NO &remote_country=US Specifies remote user's country.
Required for Markets
remote_ip string Dot-decimal notation NO &remote_ip=94.71.170.105 Specifies remote user's ip address. This is an alternative to remote_country using IP address geolocation.
Required for Markets.
Only IPv4 supported.
device string MOBILE
DESKTOP
NO* &device=MOBILE Specified user device.
Used to unlock special pricing policies.
referer string domain, varchar(255) NO &referer=www.domain.com
bk_code string varchar(255) NO &bk_code=SPECIALRATES Required for Private Rates
voucher string varchar(255) NO &voucher=VCH123 Unlocks special offers
attach flag NO &attach Include the new booking in the response.
confirmation_email flag NO &confirmation_email Send confirmation e-mail to the customer and hotelier.
The default is to NOT send any automated e-mails.
NEVER use this param if you plan to rollback with /purge.
external_id string varchar(64) NO &external_id=EXT-123456 Pass an additional booking identifier of your own. You can later look up the booking by using this id with /reservation search method
origin_profile_id string varchar(255) NO &origin_profile_id=TA-123456 Pass an additional booker profile identifier of your own. This identifier can later be accessed in the Booking Retrieval API, in the "additional_fields" array. You can not look up bookings by using this identifier with the /reservation search API.
partner_data JSON string varchar(4000) NO &partner_data={"source_code":"EMAIL", "operator_name": "John Smith"} Pass a JSON serialized object, which will be echoed to the Booking Retrieval API and be accessible as a JSON serialized string, in the "additional_fields" array with the code "PARTNER_DATA"
price_override string Comma delimited list of {day}^{price} pairs NO &price_override=1^87.00,2^87.00,3^80.00 Override rate price by passing alternative daily rates. Number of day-price pairs must match the total number of nights. If this is a multi room booking, daily price is the total price for all rooms.
price_detax boolean NO false &price_detax=1 Only used in conjunction with price_override. When true, the price_override daily rates are considered to be the final prices with tax included. Otherwise the price is considered net without tax. It is strongly recommended to always pass price_detax=1 when using price_override since it is extremely complex to precisely calculate net and final prices in order to pass the price check validation.

You can use remote_country or remote_ip. If you use both, remote_country takes precedence and remote_ip is ignored.

Language / Locale

To specify remote user's language preference please send Accept-Language header as described in the Internationaliation section of our Getting Started guide.

Specifying the language may be required for Markets.



Booking Amend

You can amend a booking by passing its confirmation number, additionally to all the above parameters.

In this case, instead of creating a new booking with a new auto-generated confirmation number, the existing booking with the specified confirmation number will be modified.

NAME TYPE RANGE / SET REQUIRED DEFAULT EXAMPLE NOTES
res_id integer - NO &res_id=123456789 Confirmation number of the booking that will be amended.


Extra Supplements

NAME TYPE RANGE / SET REQUIRED DEFAULT EXAMPLE NOTES
extra_[extra_id] integer quantity NO &extra_3=1 Book an extra service using its id.


JSON Response Schema

{
	"method": "https://rest.reserve-online.net/book/DEMO",
	"http_method": "POST",
	"http_code": 200,
	"error_code": "OK",
	"error_msg": "",
	"params": [],
	"data": {
		"summaryUrl":URL, // Reservation summary URL. Can be used to modify or change the booking at a later point.
		"res_id":INTEGER, // Reservation unique id
		"email":STRING, // Comma delimited list of email addresses that can be used to notify the property of a successful booking
		"result":STRING, // Reservation status result. Enumerated value: CONFIRMED for successful booking.
		"reservation":Booking Retrieval Data, // Optional. If the "attach" flag is present, then the new booking's data are also included.
	}
}
	

JSON Response Examples


Successful booking


  

Generic invalid parameter error

{
  "method": "http://rest.webhotelier.localhost/book/demo",
  "http_method": "POST",
  "http_code": 400,
  "error_code": "INVALID_PARAM",
  "error_msg": "Parameter [email] can not be empty",
  "params": []
}

Availability depleted error

{
  "method": "https://rest.reserve-online.net/book/demo",
  "http_method": "POST",
  "http_code": 400,
  "error_code": "ALLOT_DEPLETED",
  "error_msg": "Availability depleted. Booking cannot continue.",
  "params": []
}

Invalid price error

{
  "method": "https://rest.reserve-online.net/book/demo",
  "http_method": "POST",
  "http_code": 400,
  "error_code": "INVALID_PRICE",
  "error_msg": "Pricing passed does not match actual booked price. Pricing may have changed during booking.",
  "params": []
}