Adds a Booking for a given property and date range

Use this function to add a booking where by you (the 3rd Party) are responsable for calculating quotes/cost of bookings. Validation of rules for placing bookings into a property via this function are exclusively your responsability (the 3rd Party reservation supplier).

• APIUsername (String) *Required
• APIPassword (String) *Required
• xmlMsg (String) *Required
  -Pass blank string unless otherwise discussed with your CiiRUS technical point of contact.
• jSonMsg (String) *Required
  -Pass blank string unless otherwise discussed with your CiiRUS technical point of contact.
• BookingParameters Class Object *Required
  • PropertyID (Integer) *Required
  • FirstName (String) *Required
  • LastName (String) *Required
  • EmailAddress (String) *Required
  • Address (String) *Required
  • Telephone (String) *Required
  • ArrivalDate (String, dd MMM yyyy) *Required
  • DepartureDate (String, dd MMM yyyy) *Required
  • AddAsTentative (Boolean) *Required
    -If True, this will block off availability for the period of the reservation up until the tentative booking is confirmed by the MC or via Payment or until the current date is greater than "TentativeExpiryDate". If not converted into a confirmed booking before either of these two cases, the reservation is automatically cancelled.
    -If False, this booking will be added as a confirmed reservation.
  • TentativeExpiryDate (String, dd MMM yyyy) *Required
    If "AddAsTentative" is True the date value in this field will be set as the automatic expirey date for this reservation if it is not converted into a confirmed reservation.
    -If "AddAsTentative" is False, this parameter is still required, but the value will be ignored (any date will do).
  • PoolHeat (Boolean) *Required
    -This denotes if the guests have or have not requested and are or are not going to pay for PoolHeat.
    -If True, you will need to get the rules on how to charge PoolHeat from the function "GetPoolHeatSettings".
  • BaseRentalAmountToMCExTax (decimal) *Required
    -This is the amount of the Base Rental Rate Only that the MC should expect to recieve for this booking Exclusive of tax.
    -If the merchant of record is the Agent, the Agent commission should be the "BaseRentalAmountToAgentExTax" minus the "BaseRentalAmountToMCExTax"
    -If the merchant of record is the MC, the Agent commission should be the "BaseRentalAmountToMCExTax" minus the "BaseRentalAmountToAgentExTax"
  • BaseRentalAmountToAgentExTax (decimal) *Required
    -This is the amount of the Base Rental Rate Only that the Agent should expect to recieve for this booking.
    -If the merchant of record is the Agent, the Agent commission should be the "BaseRentalAmountToAgentExTax" minus the "BaseRentalAmountToMCExTax"
    -If the merchant of record is the MC, the Agent commission should be the "BaseRentalAmountToMCExTax" minus the "BaseRentalAmountToAgentExTax"
  • BasePoolHeatAmountExTax (decimal) *Required
    -This is the cost of pool heat to be paid by the Guest exclusive of tax.
    -If "PoolHeat" is True, you will need to get the rules on how to charge PoolHeat from the function "GetPoolHeatSettings"
    -If "PoolHeat" is False, this value should be 0.
  • BaseBookingFeeAmountExTax (decimal) *Required
    -This is a fee to be collected by the MC for placing the booking. This could be a administration fee or a fee to cover the cost of processing payment via a merchant processor.
    -You will need to use the function "GetBookingFee" to get the rules for this charge and calculate the value to pass as this parameter. This value is exclusive of any tax that may apply to this amount.
  • BaseCleaningFeeAmountExTax (decimal) *Required
    -This is a fee to be collected by the MC to cover the cost of cleaning the property. This fee may or may not apply.
    -You will need to use the function "GetCleaningFee" to get the rules for this charge and calculate the value to pass as this parameter. This value is exclusive of any tax that may apply to this amount.
  • Tax1Percent (decimal) *Required
    -Three different tax rates can apply to a booking. Each sub-section of the booking is subject to taxation seperately. These tax settings are defined by the MC/inventory provider based on te taxes that they must pay on any reservation.
    -You will need to use the function "GetTaxRates" to get the values of each of the 3 tax bands for this property.
    -You will need to apply the respective tax band in any calculation warranting it. In this case "Tax1Percent"
  • Tax2Percent (decimal) *Required
    -Three different tax rates can apply to a booking. Each sub-section of the booking is subject to taxation seperately. These tax settings are defined by the MC/inventory provider based on te taxes that they must pay on any reservation.
    -You will need to use the function "GetTaxRates" to get the values of each of the 3 tax bands for this property.
    -You will need to apply the respective tax band in any calculation warranting it. In this case "Tax2Percent"
  • Tax3Percent (decimal) *Required
    -Three different tax rates can apply to a booking. Each sub-section of the booking is subject to taxation seperately. These tax settings are defined by the MC/inventory provider based on te taxes that they must pay on any reservation.
    -You will need to use the function "GetTaxRates" to get the values of each of the 3 tax bands for this property.
    -You will need to apply the respective tax band in any calculation warranting it. In this case "Tax3Percent"
  • ChargeTax1OnRental (Boolean) *Required
    -Reservations will always be taxable. You would always pass this value as True, unless otherwise specified/discussed with your CiiRUS technical point of contact.
  • ChargeTax2OnRental (Boolean) *Required
    -Reservations will always be taxable. You would always pass this value as True, unless otherwise specified/discussed with your CiiRUS technical point of contact.
  • ChargeTax3OnRental (Boolean) *Required
    -Reservations will always be taxable. You would always pass this value as True, unless otherwise specified/discussed with your CiiRUS technical point of contact.
  • ChargeTax1OnPoolHeat (Boolean) *Required
    -User the setting "ChargeTax1OnPoolHeat" returned by the function "GetPoolHeatSettings" for this value.
  • ChargeTax2OnPoolHeat (Boolean) *Required
    -User the setting "ChargeTax2OnPoolHeat" returned by the function "GetPoolHeatSettings" for this value.
  • ChargeTax3OnPoolHeat (Boolean) *Required
    -User the setting "ChargeTax3OnPoolHeat" returned by the function "GetPoolHeatSettings" for this value.
  • ChargeTax1OnBookingFee (Boolean) *Required
    -User the setting "ChargeTax1" returned by the function "GetBookingFee" for this value.
  • ChargeTax2OnBookingFee (Boolean) *Required
    -User the setting "ChargeTax2" returned by the function "GetBookingFee" for this value.
  • ChargeTax3OnBookingFee (Boolean) *Required
    -User the setting "ChargeTax3" returned by the function "GetBookingFee" for this value.
  • ChargeTax1OnCleaningFee (Boolean) *Required
    -User the setting "ChargeTax1" returned by the function "GetCleaningFee" for this value.
  • ChargeTax2OnCleaningFee (Boolean) *Required
    -User the setting "ChargeTax2" returned by the function "GetCleaningFee" for this value.
  • ChargeTax3OnCleaningFee (Boolean) *Required
    -User the setting "ChargeTax3" returned by the function "GetCleaningFee" for this value.
  • TaxExemptBooking (Boolean) *Required
    -This should always be false unless otherwise specified/discussed with your CiiRUS technical point of contact.
  • Comments (String) *Required
    -Pass any comments from the guest or from (you) the Agent that the MC should be notified of and is not otherwise catered for in the API.
  • PaymentTakenBy (Enum = MC (0) or Agent (1)) *Required Value(Restricted - This value will be inherited from the CiiRUS Admin Panel unless otherwise agreed with the CiiRUS Business Development Department and your CiiRUS technical point of contact)
    -This is integral to ensuring correct booking values. Who is the merchant of record?
    -If this or the CiiRUS Admin setting for this is not set correctly and validated before moving into production, the merchant of record in this relationship risks owing more money to the non-merchant of record than the Merchant of record will have collected for the reservation.

• AddBooking: Validation Error 1
• AddBooking: Error 2 - This API User does not have permissions to use this function. Please contact your CiiRUS technical point of contact for more information.
• AddBooking: Error 3 - This API User does not have permissions to use this function. Please contact your CiiRUS technical point of contact for more information.
• AddBooking: Error - Property not enabled for online booking. Please contact the supplier to enable this property.
• AddBooking: Error - Arrival Date must be before Departure Date
• AddBooking: Error - Could not resolve the User's relationship to this Property.
• AddBooking: Error - It could not be determined if the property was deleted (2724368). Please contact CiiRUS.
• AddBooking: Error - It could not be determined if the property was deleted (277724368). Please contact CiiRUS.
• AddBooking: Error - Owners are not directly supported via the API. Please contact CiiRUS to configure a SuperSite Agent.
• AddBooking: Error - User has no Relation/permissions to this property.
• AddBooking: Error - User has unkonwn Relations/permissions to this property.
• AddBooking: Error - This property has been deleted by the MC.
• AddBooking: Error - Could not resolve Owner.
• AddBooking: Error - Could not resolve MC.
• AddBooking: Error - One or more bookings clash with this booking
• AddBooking: Error - Unable to get the new Booking ID
• AddBooking: Error - Clean Not added to Booking: (BookingID)
  Note: (BookingID) = The BookingID stored in CiiRUS for this function call.
• AddBooking: Error - Could not add booking action to booking:
  Note: (BookingID) = The BookingID stored in CiiRUS for this function call.
• AddBooking: Error - Unable to get the new Booking ID
• Error at AddBooking (Phase (i))
  Note: (i) = integer representing phase in Booking function that an unknown exception occured

AddBooking Prerequisites

If you use this function, you will need to calculate the quote, and utilize all the following function as to obtain the settings and base values for which to base a quote upon:

• IsPropertyAvailable
• GetPropertyRatesAndRestrictions
• GetTaxRates
• GetCleaningFee
• GetBookingFee
• GetPoolHeatSettings
• GetExtras

After a confirmed booking, you will need to make the following additional calls to finalize the guestlist, credit card details, and extras (optional/manditory):

• AddGuests
• AddExtra
• If the MC is taking payment and you are passing Credit Card Details:
  • getDownPayment
  • GetCardTypes
  • addCCPayment
    Note: addCCPayment uses payments.ciirus.com, and not secure.ciirus.com
• If the Agent is taking payment and you are showing how much has been collected from the guest toward the reservation total:
  • AddGuestPayment

How to Calculate Booking Totals

Please see the formula for calculating a quote:
Sub-Totals:
BaseRental = (DailyRate(s) * (number of nights in each respective rate band))
CleaningFee = (cleaning fee if applicable)
BookingFee = (booking fee amount if applicable)
ManditoryExtras = sum of all mandatory extras that apply
OptionalExtras = sum of all optional extras that apply

Sub-Total (ex tax) = BaseRental + CleaningFee + BookingFee + ManditoryExtras + OptionalExtras

Taxes:
BaseRental Tax = ((BaseRental)*(taxpercent1 if applicable for this item)) + ((BaseRental)*(taxpercent2 if applicable for this item)) + ((BaseRental)*(taxpercent3 if applicable for this item))
CleaningFee Tax = ((CleaningFee)*(taxpercent1 if applicable for this item)) + ((CleaningFee)*(taxpercent2 if applicable for this item)) + ((CleaningFee)*(taxpercent3 if applicable for this item))
BookingFee Tax = ((BookingFee)*(taxpercent1 if applicable for this item)) + ((BookingFee)*(taxpercent2 if applicable for this item)) + ((BookingFee)*(taxpercent3 if applicable for this item))
ManditoryExtras Tax (Sum of the following for each extra individually) = ((ManditoryExtra)*(taxpercent1 if applicable for this item)) + ((ManditoryExtra)*(taxpercent2 if applicable for this item)) + ((ManditoryExtra)*(taxpercent3 if applicable for this item))
OptionalExtras Tax (Sum of the following for each extra individually) = ((OptionalExtra)*(taxpercent1 if applicable for this item)) + ((OptionalExtra)*(taxpercent2 if applicable for this item)) + ((OptionalExtra)*(taxpercent3 if applicable for this item))

Tax-Total (Tax only) = BaseRental Tax + CleaningFee Tax + BookingFee Tax + ManditoryExtras Tax + OptionalExtras Tax

Reservation Total = Sub-Total + Tax-Total

The Agent commission is the difference between the BaseRental rate to the MC/PM vs the BaseRental to the Agent. The formula above applies in both cases, but the input values differ for the Base Rental amount.

Testing & Validation

1. The dates are not nothing.
2. The dates are in the future.
3. The departure date is at least 1 day after the arrival date.
4. A booking is NOT added if the arrival date overlaps a period of non-availability.
5. A booking is NOT added if the departure date overlaps a period of non-availability.
6. A booking is NOT added if the entire booking range overlaps a period of non-availability.
7. A booking is NOT added if no rates are defined for the specified date range.
8. A booking is NOT added if the arrival day lands on a day of the week not allowed as an arrival day.
9. A booking is NOT added if the departure day lands on a day of the week not allowed as an departure day.
10. A booking is NOT added if the arrival and departure day lands on both a disallowed arrival and departure day.
11. A booking is NOT added if the booking agent does not have permissions to the specified property.
12. A booking is NOT added if the duration of the booking is less than the specified minimum night stay for the date range as specified by the arrival day date band in the RateSet for the respective property.
13. A booking is NOT added if all required fields are not provided in the request.
14. A booking is added only if the dates are available and rates are defined for the specified date range and all required fields have been supplied.
15. The total value of the reservation matches in the Total Booking Summary (TBS) with the value you expect to pay to the inventory supplier for the respective reservation test.
16. The tax sub-total values for each of the tax bands are of the correct calculated percentage for the respective bands specified by the inventory supplier.
17. The Base Rental amount is the price expected based on the rates specified by the inventory supplier.
18. The Cleaning Fee amount is the price expected based on the rates specified by the inventory supplier.
19. The Booking Fee amount is the price expected based on the rates specified by the inventory supplier.
20. When applied (and only when applied to the reservation as specified in the request) the pool heat amount is the price expected based on the rates specified by the inventory supplier.
21. The Base Rental Tax amount is the price expected based on the rates specified by the inventory supplier.
22. The Cleaning Fee Tax amount is the price expected based on the rates specified by the inventory supplier.
23. The Booking Fee Tax amount is the price expected based on the rates specified by the inventory supplier.
24. When applied (and only when applied to the reservation as specified in the request) the pool heat Tax amount is the price expected based on the rates specified by the inventory supplier.
25. All mandatory extras are applied to the reservation with the correct pricing amount is the price expected based on the rates specified by the inventory supplier.
26. All optional extras which selected by the guest are applied to the reservation with the correct pricing amount is the price expected based on the extras specified by the inventory supplier.
27. All extras amounts (optional and mandatory) prices are applied to the reservation with the correct pricing amount is the price expected based on the extras specified by the inventory supplier.
28. All extras tax amounts (optional and mandatory) prices are applied to the reservation with the correct pricing amount is the price expected based on the extras specified by the inventory supplier.
29. All lead guest contact details are listed correctly against the booking’s guest contact record.
30. All guests intended to be disclosed as part of the guest list are listed correctly against the reservation with ages of persons under 18 included (mandatory by law before guests can stay in the property in central florida).
31. A second booking CANNOT be added overlapping the dates in any configuration of a booking that you have just placed.
32. The Agent commission accurately reflects the amount intended to be disclosed/tracked as taken by the Agent against the booking. If not disclosed, value should be 0.

Additional Error Messages may be returned. If you recieve an alternate response, and are unsure why, or what it means, please contact your CiiRUS technical point of contact for more information.