Booking API

Invoking the Booking API

The URL to use for invoking the Booking API is:
https://www.bookerville.com/API-Booking?s3cr3tK3y=1234567890ABCDEFGHIJKLMNOPQRS

You will of course replace the "s3cr3tK3y" parameter with your own Bookerville API access token. If you don't have one, you may apply for one here: Request API Token

Note: for testing purposes it is fine to pass your API access token using simple query string parameters in the URL as in the sample above. Once you have completed testing, it is far better to pass it as an HTTP POST (form) parameter instead, because that is more secure.

The bkvPropertyId parameter must be an integer and is the unique identifier for the property within Bookerville. This value is obtained from the Summary API.

The xmlPayload Field

The Booking API requires that you POST an XML document in a separate HTTP POST (form) key-value pair, called xmlPayload. The XML document you must submit in this field depends on which operation ("QUOTE", "ADD", or "DELETE") you are using.

QUOTE Operation

The QUOTE operation allows your software to request an accurate quote for a booking from Bookerville. You pass in an XML document with the Bookerville property id, the start and end dates of the request, the number of adults, and some other fields described below.

Bookerville does not block dates on the calendar for the property for QUOTE requests.

The XML document your software must post for the QUOTE operation is as follows:

<request> <operation>QUOTE</operation> <company>(Your organization name, optional)</company> <channel>(The marketing channel used, optional but STRONGLY recommended)</channel> <bkvPropertyId>19</bkvPropertyId> <beginDate>2024-07-15</beginDate> <endDate>2024-07-22</endDate> <adults>4</adults> <children>4</children> <guestData> <email>joeguest@example.com</email> <address>123 Main Street.</address> <city>San Diego</city> <state>CA</state> <country>US</country> <firstName>Joe</firstName> <lastName>Guest</lastName> <phone>555-555-5555</phone> <zip>92093</zip> </guestData> </request>

<operation>: Required: this is the specific operation of the Booking API you are requesting. For the QUOTE operation, send "QUOTE".

<bkvPropertyId>: Required: the Bookerville property id for the booking. The was returned to your software in the Property Details API.

<beginDate>: Required: in "yyyy-MM-dd" format.

<endDate>: Required: in "yyyy-MM-dd" format.

<guestData>: Optional: the guest data is optional. The <email> is strongly recommended though, as Bookerville permits things like repeat guest discounts, and other things which require identifying the guest by email address. Bookerville also supports "black-listing" by email address.

<Adults>: Required: the number of adults.

<Children>: Optional: the number of children field is optional, but not specifying it may result in less accurate quotes and/or booking amounts, as Bookerville permits pricing that can be affected by the number of children.

 

QUOTE Operation Results

The results of a successful Booking API QUOTE operation call will appear as the following example XML:

<BKV-API-Booking-Response> <warning>Cannot obtain CHILDREN. Defaulting to zero</warning> <bkvPropertyId>19</bkvPropertyId> <confirmCode>19-254168-20240718</confirmCode> <rent>750.00</rent> <overOccupancySurcharge>750.00</overOccupancySurcharge> <discount>750.00</discount> <netRent>750.00</netRent> <bookingFee>25.00</bookingFee> <cleaningFee>75.00</cleaningFee> <securityDepositWaiver>45.00</securityDepositWaiver> <taxes> <tax> <id>1</id> <label>State tax</label> <amount>98.00</amount> </tax> <tax> <id>2</id> <label>County tax</label> <amount>28.00</amount> </tax> <tax> <id>3</id> <label>City tax</label> <amount>35.00</amount> </tax> </taxes> <additionalItems> <additionalItem> <id>12345</id> <label>Damage Protection Policy</label> <price>79.00</price> <taxable>Non-Taxable</taxable> </additionalItem> <additionalItem> <id>54321</id> <label>Heated Pool</label> <price>200.00</price> <taxable>Non-Taxable</taxable> </additionalItem> </additionalItems> <total>1010.45</total> <payNowAmount>101.05</payNowAmount> <refundableSecurityDeposit>375.00</refundableSecurityDeposit> <status>success</status> </BKV-API-Booking-Response>

<status>: this field will contain either "success" or "failure". If "failure", it will return one or more <error> stanzas with explanations.

<confirmCode>: this is the Bookerville "Confirmation Code" of the booking. This may be useful for your customers since they are accustomed to seeing it in Bookerville. It is communicated to the guest by Bookerville.

<rent>: this is the base rent of the booking.

<overOccupancySurcharge>: an amount that is to be added to the rent as a result of additional guests, over and above the "expected occupancy", or <freeGuests> field in the Property Details API.

<discount>: any discounts that apply, to be deducted from the rent.

<netRent>: this is the "Net Rent" of the booking - which is rent, plus any over-occupancy surcharges, less any discounts. This is the figure that any "Percent of Rent" items are based on.

<additionalItems>: there may be zero or more Additional Items. These are additional fees, with labels and whether they are taxable. Some Additional Items may contain an "id" field. If there is one present, your software should capture it and send it back with in the ADD operation.

Note: <bookingFee> and <cleaningFee> will usually appear as separate items, outside the Additional Items stanza.

<payNowAmount>: if there is an amount that must be paid by the guest immediately to secure the booking, this will be that amount. Your system may or may not be the system that facilitates that initial payment transaction with the guest.

<refundableSecurityDeposit>: if there is a refundable security deposit, this will contain the amount. Refundable security deposits are not included in the booking total, since the expectation is that the amount will be refunded.

<securityDepositWaiver>: if there is a security deposit waiver, this will contain the amount. Security deposit waivers are included in the booking total, since the waiver amount is not refunded.

Note: At most one of <refundableSecurityDeposit> or <securityDepositWaiver> will be returned; never both.

<taxes>: Zero or more tax stanzas wil be returned. These will always contain an "id" field, your software should capture this and return it in the ADD operation.

ADD Operation

The ADD operation allows your software to submit a booking to Bookerville. You pass in an XML document with the Bookerville property id, the start and end dates of the request, the number of adults, and some other fields described below.

The ADD operation causes the booking to be stored in Bookerville, and also causes the dates to be blocked on the Bookerville calendar for the property.

The ADD operation requires more fields than the QUOTE operation, mostly because Bookerville permits your software to override booking amounts. This is to help facilitate the variety of needs of various marketing channels, and also to permit your software to accommodate the idea of Net Rates.

The XML document your software must post for the ADD operation is as follows:

<request> <operation>ADD</operation> <bkvPropertyId>1234567</bkvPropertyId> <company>(Your organization name, optional but STRONGLY recommended)</company> <channel>(The marketing channel used, optional)</channel> <commission>The value of any commission your organization charged for this booking</commission> <channelCommission>The value of any commission the source channel charged for this booking</channelCommission> <bookervilleCommission>The value of any commission that Bookerville earns on this booking</bookervilleCommission> <channelBookingId>The native id of the booking in the channel's (listing site's) system</channelBookingId> <channelManagerBookingId>The native id of the booking in the channel manager's system</channelManagerBookingId> <email>joeguest@example.com</email> <firstName>Joe</firstName> <lastName>Guest</lastName> <phone>555-555-5555</phone> <address>123 Main Street</address> <city>San Diego</city> <state>CA</state> <zip>92093</zip> <country>US</country> <beginDate>2024-05-10</beginDate> <endDate>2024-05-13</endDate> <adults>4</adults> <children>4</children> <guestComments>Up to 3,000 chars, more than that will be truncated. Credit/Debit card data is prohibited (will be stripped out).</guestComments> <rent>1000.00</rent> <overOccupancySurcharge>250.00</overOccupancySurcharge> <discount>150.00</discount> <netRent>850.00</netRent> <taxes> <tax> <id>1</id> <label>State Tax</label> <amount>150.00</amount> </tax> <tax> <id>2</id> <label>County Tax</label> <amount>50.00</amount> </tax> </taxes> <additionalItems> <additionalItem> <label>Booking Fee</label> <amount>70.00</amount> <taxed>no</taxed> </additionalItem> <additionalItem> <label>Cleaning Fee</label> <amount>120.00</amount> <taxed>no</taxed> </additionalItem> <additionalItem> <label>Heated Pool</label> <amount>200.00</amount> <taxed>yes</taxed> </additionalItem> <additionalItem> <label>Damage Insurance</label> <amount>50.00</amount> <taxed>no</taxed> </additionalItem> </additionalItems> <securityDeposit> <type>Refundable|Waiver</type> <amount>350.00</amount> </securityDeposit> <total>1490.00</total> <payoutValue>1750.00</payoutValue> <prePayment>745.00</prePayment> <bookingURL>http://www.your-organization-domain.com/uri-of-this-booking-in-your-system</bookingURL> <bookingStatus>Unconfirmed | Confirmed | Completed | Maintenance | Owner-Occupied | Owner-Reserved | Checked-In | Checked-Out</bookingStatus> </request>

<operation>: Required: this is the specific operation of the Booking API you are requesting. For the ADD operation, send "ADD".

<channel>: Optional: if this booking is being provided by a channel (listing site, agency, etc.) place the name of that channel here (i.e., AirBnB, Booking.com, FlipKey, HomeAway/VRBO, etc.)

<commission>: Optional: if your organization charged any commission for this booking, put the value charged here (not the percent). Applies only to ADD operation. Bookerville will create an expense record for this amount if supplied.

<channelCommission>: Optional: if the source channel charged any commission for this booking, put the value charged here (not the percent). Applies only to ADD operation. Bookerville will create an expense record for this amount if supplied.

<bookervilleCommission>: Optional: if Bookerville receives any commission (or rev-share) from this booking, put that value here (not the percent). Applies only to ADD operation.

<bkvPropertyId>: Required: the Bookerville property id for the booking. This was returned to your software in the Property Details API.

<beginDate>: Required: in "yyyy-MM-dd" format.

<endDate>: Required: in "yyyy-MM-dd" format.

<guestData>: Optional: the guest data is optional. The <email> field is strongly recommended though, as property managers use Bookerville's powerful email system to send vital correspondence to the guest throughout the booking lifecycle.

<Adults>: Required: the number of adults.

<Children>: Optional: the number of children.

<rent>: Optional: the base rent for the booking. Your software must specify either the <rent> field, or the <netRent> field.

<overOccupancySurcharge>: Optional: the over-occupancy surcharge for the booking.

<discount>: Optional: the discount for the booking.

<netRent>: Optional: the net rent for the booking. Net rent is rent, plus over-occupancy surcharge, minus discount. If your software specifies this netRent field, Bookerville will use this and ignore the rent, overOccupancySurcharge, and discount fields. If this netRent field is empty (or zero), then the rent field is mandatory.

<additionalItems>: Optional: your software may specify one or more additional item stanzas. If you are returning any of the additional items that were returned to you during the QUOTE operation, you must send the <id> field back to Bookerville in the ADD operation so that we can map it back for proper accounting, etc.

<total>: Optional: If your software specifies this total field, Bookerville will use it for the booking total. Otherwise, Bookerville will calculate the total based on the other amount fields sent.

<payoutValue>: Optional: Convey the "payout value", or in the case of channels like Booking.com, the amount to charge the guest, here.

<prePayment>: Optional: If your software specifies this prePayment field, Bookerville will use it as the required pre-payment for the booking, and will modify the payment schedule accordingly.

<bookingURL>: Optional: this is optional but strongly recommended. This is the URL to the specific page of this booking in your software. Bookerville will render this as a link in the Bookerville Booking Details page, so that managers can simply click to view your software's page for the booking. Bookerville will treat this URL with discretion - it will not be shared with any other parties, and the manager must be signed in to Bookerville in order to see it.

<bookingStatus>: Optional: this is the Bookerville internal status of the booking. The default is "Confirmed", but you may override with any of the values shown above.

 

ADD Operation Results

The results of a successful Booking API ADD operation call will appear as the following example XML. Most of these fields will simply be the same values your software received from the QUOTE operation, unless you overwrote them with custom values in the ADD operation:

<BKV-API-Booking-Response> <warning>Cannot obtain CHILDREN. Defaulting to zero</warning> <bkvPropertyId>19</bkvPropertyId> <bkvBookingId>1234567</bkvBookingId> <bkvBookingURL>http://www.bookerville.com/BookingDetails?confirmCode=19-254168-20240718</bkvBookingURL> <bkvContractURL>http://www.bookerville.com/ContractAgree?bid=somenumber</bkvContractURL> <confirmCode>19-254168-20240718</confirmCode> <rent>750.00</rent> <overOccupancySurcharge>750.00</overOccupancySurcharge> <discount>750.00</discount> <netRent>750.00</netRent> <bookingFee>25.00</bookingFee> <cleaningFee>75.00</cleaningFee> <securityDepositWaiver>45.00</securityDepositWaiver> <taxes> <tax> <label>State tax</label> <amount>98.00</amount> </tax> <tax> <label>County tax</label> <amount>28.00</amount> </tax> <tax> <label>City tax</label> <amount>35.00</amount> </tax> </taxes> <additionalItems> <additionalItem> <id>12345</id> <label>Damage Protection Policy</label> <price>79.00</price> <taxable>Non-Taxable</taxable> </additionalItem> <additionalItem> <id>54321</id> <label>Heated Pool</label> <price>200.00</price> <taxable>Non-Taxable</taxable> </additionalItem> </additionalItems> <total>1010.45</total> <payNowAmount>101.05</payNowAmount> <refundableSecurityDeposit>375.00</refundableSecurityDeposit> <status>success</status> </BKV-API-Booking-Response>

<status>: this field will contain either "success" or "failure", along with <error> stanzas for explanations.

<bkvBookingId>: this is the Bookerville id of the booking. You will want your software to store this number and associate it with the booking in your system, as it will be needed for a potential "DELETE" operation.

<confirmCode>: this is the Bookerville "Confirmation Code" of the booking. This may be useful for your customers since they are accustomed to seeing it in Bookerville. It is communicated to the guest by Bookerville.

<bkvBookingURL>: this will contain the URL to the Bookerville Booking Details page for this new booking. It is recommended that you render this as a link in your software's booking page so that the manager can simply click a button to view it in Bookerville.

<bkvContractURL>: this will contain the URL to the Bookerville Contract Agreement page for this new booking. This may be useful for those wishing to implement electronic/digital contract signing; the link will take the guest to a page where they can digitally sign the contract.

DELETE Operation

The DELETE operation permits your software to delete (cancel) a booking. This will un-block the dates of the booking from the calendar in Bookerville, but the rest of the booking data will be retained, in the form of a Booking Request (Canceled Booking). Your software must pass in the bkvBookingId, which was sent back to your software during the "ADD" operation. Your software can of course only delete bookings that it created through the "ADD" operation.

The XML document your software must post for the DELETE operation is as follows:

<request> <operation>DELETE</operation> <bkvBookingId>543210</bkvBookingId> <bkvPropertyId>19</bkvPropertyId> <beginDate>2024-05-10</beginDate> <endDate>2024-05-13</endDate> </request>

<operation>: Required: this is the specific operation of the Booking API you are requesting. For the DELETE operation, send "DELETE".

<bkvBookingId>: Required: the Bookerville id for the booking. The was returned to your software in the ADD operation.

<bkvPropertyId>: Optional: the Bookerville property id for the booking. The was returned to your software in the Property Details API.

<beginDate>: Optional: in "yyyy-MM-dd" format.

<endDate>: Optional: in "yyyy-MM-dd" format.

Note: you may optionally omit the <bkvBookingId>, and instead pass in the <bkvPropertyId>, <beginDate>, and <endDate> fields.

 

DELETE Operation Results

The results of a successful Booking API ADD operation call will appear as the following example XML:

<BKV-API-Booking-Response> <status>success</status> </BKV-API-Booking-Response>

<status>: This field will either contain "success" or "failure". If "failure", look for <error> stanzas for help in resolving the issue.

Booking API Exceptions

The results of the Booking API may contain <error> stanzas or <warning> stanzas which are designed to help you debug issues. <error> stanzas are fatal, and a <status> of "failure" will be returned. <warning> stanzas are not fatal.

Examples:
<error>Booking 19-123456-654321-20240517, bkvBookingId: 761943, was not created by (your organization name). Cannot delete.</error> <warning>Cannot obtain CHILDREN. Defaulting to zero</warning>

Note that <error> and <warning> stanzas may appear in-line with other XML content. Explanations will be given inside each stanza.