Built by owners, for owners.

Rate Engine Bible

The rate engine is used in many places to generate charges and quote prices, including quoting on hosted websites and book now widgets, quote creation, and booking creation. It's a rules based engine, driven by seasons, rates, surcharges, discounts, add-ons and taxes. As such, it can likely handle your entire rate structure (if not, contact us and we'll see what's possible), but it's also one of the more complex things to set up.

We'll first walk through the different concepts used in the rates engine, then drill into how priority and selection for rates works, review the different methods for entering rates, and finally look at some common scenarios for rates and surcharges and how to configure them. The priority and selection section is some dry reading, so you can start with the concepts, entering some rate, jump down to the scenarios to see some common setups, and come back to priority you have more detailed questions.

Rate Concepts

Seasons define a period of time based on a date range. Recurring seasons specify a month/day to month/day period that repeats every year. Specific Dates seasons specify a month/day/year to month/day/year period that does not repeat. Recurring seasons are useful if your rates don't change on a yearly basis. Specific Dates seasons are useful if your rates do change every year, or if you want to apply rates to specific periods inside a year that have slightly different dates every year -- like holiday weeks.

Every amount (rates, surcharges, discounts, add-ons, taxes) can be configured to only apply during a specific season or apply to all seasons.

Seasons also allow control over rules that can be applied to bookings, like minimum number of nights and changeover days.

Rates control your base rent on a nightly, weekly, or monthly basis. You can configure specific criteria for number of nights, which nights of the week match a rate, and whether rates match exactly or are prorated to match shorter or longer periods of time.

Surcharges, discounts, and add-ons add or subtract an amount or percentage from your base rent, handling things like guest fees, pet fees, cleaning fees, repeat guest discounts, last minute discounts, optional upsells, pool heat, etc. They can be applied per night, per stay, or multiple times based on number of guests, adults, pets etc. via the multiplier setting. They are all configured in the same Surcharges & Discounts section. Surcharges and discounts can both be applied automatically, optionally (an Add-On), or manually -- those modes are controlled by the Applied setting on the surcharge.

Taxes configure a percentage or amount due to the taxing authorities in your area. Every other amount (rates, surcharges, discounts, add-ons) has an is taxable flag that controls whether tax will be calculated on that amount. Multiple taxes can be configured with different percentages. The percentages are accurate to 4 decimal places to accommodate all tax calculations.

Priority, Selection, and Proration

When generating a quote, everything is based on the dates and property selected for the quote. The rate engine first finds the season or seasons that match the property and dates, then uses the amounts (rates, surcharges, discounts, add-ons, taxes) that match the property and season to generate charges.

The season selection mode is controlled by the Select By configuration in Season Settings. Split Across is the default mode, which looks through each night of a booking and finds a matching season. This can match multiple seasons for a booking if it crosses seasons. You can also switch to Arrival Date or Departure Date mode, which selects a single season for the quote based on arrival date or departure date.

While multiple seasons can apply to a booking, only one season can apply to each night. If multiple seasons apply to one night, the most specific season will be selected. Specific Dates seasons take precedence over Recurring seasons and shorter seasons take precedence over longer seasons. This logic will usually pick the season you want, but you can override by setting Priority values on the seasons. Seasons with priority set take precedence over all other seasons, and higher numbered seasons take prescedence over lower numbered seasons (i.e. a priority 10 season will be picked over one with priority 5).

Once seasons have been selected, rates are selected inside them. For each season in the booking, all rates are found matching that property and season. Rates are used to calculate charges for all nights in the booking, using the longest rate with number of nights less than or equal to the nights in the booking first and using shorter rates OR proration to fill in any remaining nights. Only one rate can apply to a given night. If there are multiple rates with the same number of nights, the most specific rate is chosen based on the type of rate in this order: Custom, Month, Week, Weekend, Weekend Night, Weekday Night, Night. If there are multiple rates with the same number of nights and same type, Specific Properties and Specific Season rates are chosen. Again, this logic will usually pick the rate you want, but you can override by setting Priority values on the rates. Rates with priority set take precedence over all other rates of the same length, and higher numbered rates take prescedence over lower numbered rates (i.e. a priority 10 rate will be picked over one with priority 5).

WARNING: Both seasons and rates have property criteria. If you define a season X that matches property A, and a rate Y that matches property B and season X, it will not apply to property A at all. If you run into a situation where you think you have configured a rate for a property but are getting a "No matching rates" error, check the season properties to make sure they match as well.

Rates longer than a night have the option to be prorated. Proration has 4 modes:

  • None, which will never prorate
  • Up, which will only prorate for more nights than the rate is configured for
  • Down, which will only prorate for less nights than the rate is configured for
  • Both, which prorates for more nights or less nights than the rate is configured for

If proration is triggered, the amount of the rate will be divided by the number of nights of the rate and that value will be used for the additional days. Proration Up is self explanatory -- a 7 night week rate can be used for 10 nights, for example, applying 1/7 of the amount to each of the additional 3 nights. Proration Down is more special case, allowing a 7 night week rate to apply to a 5 night booking and be calculated as 1/7 of the amount for the 5 nights in the booking. Proration Down will only occur if there are no shorter rates to match -- for example if there was 5 night booking matching a 7 night week rate with proration down and a 1 night rate, the 1 night rate would be used because it is shorter. But if there was no 1 night rate, the week rate would be prorated. Proration Both will apply Up or Down as it applies to the booking length.

If a booking crosses seasons, the longest rate matching the number of nights in the booking is used for both seasons regardless of the proration setting. Because the full length of the rate is used, it's not considered a proration. Number of nights in each season is ignored. For example, take a 7 night booking with 3 nights in season A and 4 nights in season B, where each season has a week rate. In that case, charges would be generated for 3 nights of the week rate in season A and 4 nights of the week rate in season B.

After charges for rates are generated, all matching surcharges, discounts, and taxes are selected and applied. There's no concept of priority as there is with seasons and rates because any number of surcharges, discounts, and taxes can match a booking. All items where the properties and seasons configured match the property and at least one season of the booking will be added.

Surcharges and discounts have two additional forms of criteria: Multipliers and Booking criteria.

Multiplier criteria allows you to configure surcharges that apply based on the number of Guests, Adults, Children, Pets, or Holidays. If a Per Multiplier or Per Night & Multiplier setting is used, the item will only be added if the number matches the criteria you set. You can set an interval that will be used (for example: per 1 guest, 2 guests etc.) as well as minimum that will be checked (for example: after the first 2 guests). If the criteria matches, the Amount of the item will be multiplied by the multiplier you've chosen, and number of nights (if you choose Per Night & Multiplier).

For example, you could create a pet fee surcharge of $50 per multiplier, calculated per 1 after the first 0 pets. That would apply $50 per pet per stay.

Or you could create a guest fee surcharge of $25 per night and multiplier, calculated per 1 after the first 2 guests. That would apply $25 per guest per night, to guests over 2.

Booking criteria allows you to select criteria (days in future of the booking, number of nights, number of guests) and a formula (equal to 5, greater than 7, etc). If you add multiple critera, they all must match the booking for the item to be applied.

For example, you could create a last minute discount with an amount of -10% and a booking criteria of Arrival Date is Less Than 7 days away.

Or you could create a one night stay surcharge with an amount of $100 and a booking criteria of Number of Nights is Equal To 1.

Add-Ons (optionally selected surcharges) won't show in the quote. They are available to be selected by the guest at checkout. You can also configure a detailed information section for each add-on that guests can view during checkout.

WARNING: Again, both seasons and surcharges/discounts/taxes have property criteria. If you define a season X that matches property A, and a surcharge/discount/tax Y that matches property B and season X, it will not apply to property A at all. If you run into a situation where you think you have configured a surcharge/discount/tax for a property but aren't seeing it show up in a quote, check the season properties to make sure they match as well.

To control the position of items in a quote, you can assign their position value. This is important because percentage based items only apply to charges above them. Rent items are always added first, then surcharges/discounts, then taxes. These items have position which controls which order that charges will appear in the quote. Lower positions (or blank positions) appear earlier in the quote, while higher positions appear later. For example, a position 5 would appear after a blank position, but a position 10 would apply after the position 5.

If you have a percentage based surcharge or discount that should apply to other surcharges/discounts, give it a high priority. For example, if you have a per guest fee and a last minute discount, leave the priority blank on the guest fee but give the last minute discount a priority of 10 so it shows after the guest fee and applies to it as well as rent.

Taxes are added at the end and apply to all items above them with the Is Taxable flag set. If you have a surcharge or discount that's not taxable, you can optionally place it after the tax items by using the "Place this below tax line items" option.

Rate Population Methods and Tools

There are several different ways to add or update rates and seasons in the system:

  • The rates section in Settings has sections for each type: Seasons, Rates, Surcharges, Discounts and Addons, and Taxes. This is the most flexible configuration method, but you can only work with one item at a time.
  • The setup interview pages for Seasons and Rates. These allow you to do a simple batch addition, but don't support updates or detailed criteria.
  • Rate/season import and Rate/season export. The import and export use an Excel spreadsheet in the same format, so you can do a large batch dump of rates and seasons, add or edit them, and re-import to overwrite or add to your seasons and rates.

We have a couple of tools to help you review and validate your rates and seasons:

  • The rate tester is available under the Tools menu. That will take a property, dates, and occupancy and run it through the rates engine, displaying any charges, rules violations, and show you which seasons and rates were used.
  • Each property has a rates table on the Info tab that shows all applicable seasons and rates

Common Scenarios

Holiday fees

You can configure holidays in the Holidays section in settings. They'll show up on your calendars and you can apply surcharges to bookings that include a holiday.

To do that, create a surcharge and pick either Per Multiplier (to apply the fee once per holiday) or Per Night & Multiplier (to apply the fee for every night for bookings with holidays).

If you want to use a totally different rate for holiday periods instead of just adding a surcharge, see the next section.

Holiday or upsell periods

To increase your rates for holiday or upsell periods, shoulder seasons, etc., the easiest thing to do is to create overlapping seasons with increased rates inside your normal seasons.

For example, say you have an Off Season of 1 September to 31 March with a $100/night rate and you want to up the rates for Christmas and New Years. You could create a Christmas Holiday season from 20 December to 10 January and add a $150/night rate to it. Because that season is shorter than Off Season, it'd take priority and those rates would be used for bookings during those dates. See the [season priority section] above for more information and how to override this behavior.

If you want to apply a holiday surcharge to normal rates instead of creating separate rates, see the previous section.

Monthly rates (29-31 days)

If you create a single 30 day Monthly rate, that would apply only to 30 day bookings. You could turn on prorate to handle less or additional days, but that would change the amount according to the prorated number of nights.

Sometimes you want the same amount to apply whether it is 29, 30, or 31 days. To do that, create 3 Monthly type rates, all with the same amount and prorate None, and set the number of nights to 29 on one, 30 on another, and 31 on the last. That way the rate with the exact number of nights will be chosen and the amount will be the same for all 3 lengths.

Cleaning fee

A once per stay cleaning surcharge is simple. Create a surcharge with the amount you want, and select Applies Per Stay.

If you want to have multiple cleaning surcharges per stay, you can create multiple surcharges and use a booking criteria based on Number Of Nights to apply them.

For example, you could have a $50 normal cleaning fee with booking criteria Number of Nights is Less Than or Equal To 7. And a $150 long term cleaning fee with booking criteria Number of Nights is Greater Than 7.

Pet fee

For a pet fee applied once per stay, pick Per Multiplier and select Pet per 1 after the first 0. That will apply once per stay if any pets are included.

Guest/Adult/Child fee

Guests, Adults, and Children are all different multipliers. These examples use Guests, but Adults and Children work the same way.

For a guest fee applied per guest per night for all guests, pick Per Night & Multiplier and select Guest per 1 after the first 0.

For a guest fee applied per guest per night for more than 4 guests, pick Per Night & Multiplier and select Guest per 1 after the first 4.

Credit card surcharge

To add a surcharge to offset credit card fees, create a percentage based surcharge.

Last minute discount

To add a last minute discount, for example if the booking is less than 14 days away, create a percentage based discount and select a booking criteria of Number of Nights is Less Than 14.

Military discount, Repeat guest discount

There isn't any automated criteria for these, but you can add a manual surcharge that you can apply to a quote after it has been generated.

To do this, create a discount and select Specific bookings under critera, but don't add any booking criteria. That way it will be available for you to add, but the criteria will exclude it from being automatically added to quotes.

You could also make an optional add-on discount that the guest can select at checkout, and then require proof of ID after booking. If they can't provide it, remove the add-on so they are charged full price.

Taxes

Add one tax for each jurisdiction you need to remit to, with the correct percentage. Each tax applicable to a booking will be shown as a separate charge.