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 would 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=2025-11-11 | ||
| checkout | date (ISO 8601) |
from (checkin + 1) to (checkin + 30) |
YES | &checkout=2025-11-18 | ||
| 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 | 2025–2125 | YES if payment_method is CC |
&cardYear=2026 | ||
| 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 |
Note: All invoice fields are optional. However, if you wish to send invoice information, both
inv_cmp_name and inv_tax_id must be provided at minimum.
| NAME | TYPE | RANGE / SET | REQUIRED | DEFAULT | EXAMPLE | NOTES |
|---|---|---|---|---|---|---|
| inv_cmp_name | string | varchar(255) | YES* | &inv_cmp_name=Acme%20Corp | Invoice company name Required if any invoice info is sent |
|
| inv_tax_id | string | varchar(50) | YES* | &inv_tax_id=123456789 | Invoice tax identification number Required if any invoice info is sent |
|
| inv_country | string | ISO 3166-1-alpha-2 | NO | &inv_country=US | Invoice country (2-letter ISO code) | |
| inv_tel | string | varchar(50) | NO | &inv_tel=00302101818998 | Invoice telephone number | |
| inv_address | string | varchar(255) | NO | &inv_address=123%20Main%20Street | Invoice address | |
| inv_location | string | varchar(255) | NO | &inv_location=New%20York | Invoice city/location | |
| inv_region | string | varchar(255) | NO | &inv_region=New%20York%20State | Invoice state/region | |
| inv_postal | string | varchar(10) | NO | &inv_postal=10001 | Invoice postal/ZIP code |
* Required only if any invoice information is sent.
| 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, in addition 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": []
}
