Use this method to create a new booking in WebHotelier.
/book/{propertycode}
This method is only available via a secure connection (https).
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.
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.
NAME | TYPE | RANGE / SET | REQUIRED | DEFAULT | EXAMPLE | NOTES |
---|---|---|---|---|---|---|
checkin | date (ISO 8601) | from today to (today + 3 years) |
YES | &checkin=2024-09-27 | ||
checkout | date (ISO 8601) |
from (checkin + 1) to (checkin + 30) |
YES | &checkout=2024-10-04 | ||
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. |
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 |
NAME | TYPE | RANGE / SET | REQUIRED | DEFAULT | EXAMPLE | NOTES |
---|---|---|---|---|---|---|
firstName | string | varchar(30) | YES | 0 | &firstName=John | |
lastName | string | varchar(30) | YES | 0 | &lastName=Smith | |
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 | ®ion=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 |
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.
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.
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. |
NAME | TYPE | RANGE / SET | REQUIRED | DEFAULT | EXAMPLE | NOTES |
---|---|---|---|---|---|---|
extra_[extra_id] | integer | quantity | NO | &extra_3=1 | Book an extra service using its id. |
{ "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. } }
{ "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": [] }
{ "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": [] }
{ "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": [] }