Understanding Midterm Pricing

Assumptions

The length of stay of 31 days is considered by BookingSync as a threshold between short-term and midterm stay. Since the midterm stay is no longer the subject of short-term rates rules, the price is calculated differently.

Here is a comparison of what's supported and what's not:

Price factors	Short-term	Midterm
Rates rules (availability, price, occupancy)	Supported	Not supported
Seasonality	Supported (via Seasons + Periods or Nightly Rate Map)	Supported (via Midterm Rate Map)
Price increase per application	Supported	Supported

Of course user can still opt out from midterm pricing (by changing Rental's mid_term_pricing_active attribute to false)

What happens when midterm pricing is disabled?

Even though consulted with our users, we acknowledge the fact that for some reason this approach may not work for all of them, therefore they can opt-out of midterm pricing.

If this is the case, there are still ways to allow midterm bookings:

• Live quote (via rentals_search endpoint) - includes all rates rules, yet cannot be cached and may affect integration performance and overall user experience
• Rates - it's a nightly price, independent of the length of stay. Therefore, they do not include all available rates rules which may lead to inaccurate pricing.

What will not work:

• LOS record - Pricing is limited to 30 days only, therefore it's not possible to use it for longer stays.

How to use midterm rate map?

A midterm rate map is a simple object that consists of two main attributes:

• start_date The date of the first price from the map. It's refreshed every day at 00:25.
• map Contains 1096 (~ 3 years) prices for consecutive days since start_date. Values are comma-separated, decimal values are supported with dot as decimal separator. If a value is 0, it means that midterm pricing is not defined for that date, and therefore no 31+ days long stay covering this date is not possible.

To calculate a midterm price for a given stay of X days, find price corresponding to booking start date, and sum X consecutive values, making sure none of them is zero.

Example

Let's consider the midterm rate map with the following attributes:

{
  "start_date": "2020-05-02",
  "map": "0,0,0,0,0,100,100,100,100,100,100,100,100,100,100,50,50,50,50,50,50,50,50,50,50,300,300,100,100,100,100,100,100,100,100,100,100,0,100,100,100,100,100,100,100,100,100,100,50,50,50,50,50,50,50,50,50,50,300,300,100,100,100,100,100,100,100,100,100,100",
  ...
}

It could be converted to:

{
  * <2020-05-02, 2020-05-07) - Booking not possible (5 nights)
  * <2020-05-07, 2020-05-17) - Nightly price is 100 (10 nights)
  * <2020-05-17, 2020-05-27) - Nightly price is 50 (10 nights)
  * <2020-05-27, 2020-05-29) - Nightly price is 300 (2 nights)
  * <2020-05-29, 2020-06-08) - Nightly price is 100 (10 nights)
  * <2020-06-08, 2020-06-09) - Booking not possible (1 night)
  * <2020-06-09, 2020-06-19) - Nightly price is 100 (10 nights)
  * <2020-06-19, 2020-06-29) - Nightly price is 50 (10 nights)
  * <2020-06-29, 2020-07-01) - Nightly price is 300 (2 nights)
  * <2020-07-01, 2020-07-11) - Nightly price is 100 (10 nights)
  * <2020-07-11, 2023-05-03) - Booking not possible (1026 nights)
}

Below there are few examples of expected results:

{

1. **Booking <2020-05-17, 2020-05-18>**

    Stay too short, midterm pricing shouldn't be applied.

2. **Booking <2020-05-07, 2020-06-08>**

    `10 * 100 + 10 * 50 + 2 * 300 + 10 * 100 = 3100`

3. **Booking <2020-05-07, 2020-06-09>**

    Impossible to book since there is no midterm price defined for 2020-06-08
}

map vs map_with_price_variation

A Mid Term Rate Map exposes its rates as two parallel views of the same 1096 days:

• map — the raw nightly rates as configured by the property manager. Comma-separated string. This is what the PM sees and edits.
• map_with_price_variation — the same rates after applying the calling Application's price increase, per day. Array of decimals.

Both arrays are aligned to the same start_date and have the same length, so map[i] and map_with_price_variation[i] refer to the same calendar day.

How the per-day modifier is resolved

For each day in the map, the price modifier is determined as follows:

1. If an Applications Periods Rental record for the calling Application and the Rental covers that date, its price_increase is used.
2. Otherwise, the Application's default_price_increase (configured per account) is used.
3. If neither is set, the modifier is 0%.

The modifier is then applied as:

modifier = 1 + price_increase / 100
map_with_price_variation[i] = map[i] * modifier

0 values in map stay 0 in map_with_price_variation — days the PM marked as unbookable remain unbookable regardless of the markup.

Example

Say map starts as:

100, 100, 100, 0, 100, 100, 100, ...

And the calling Application has default_price_increase: 10 (10%), with one Applications Periods Rental record covering days [2, 3] (zero-indexed) that sets price_increase: 25.

Then map_with_price_variation is:

110.0, 110.0, 125.0, 0, 110.0, 110.0, 110.0, ...

Day 2 uses the period override (100 * 1.25 = 125.0), day 3 stays 0 (unbookable; the override does not turn it into a bookable day), and the rest fall back to the default 10% (100 * 1.10 = 110.0).

Which one to use?

• To calculate what to charge a guest booking through your Application, use map_with_price_variation. The values already include your Application's markup, so summing the days of the stay gives the price the guest should pay.
• To display the PM's own rates (e.g., in a property-manager-facing UI), use map.

If the calling Application has no price increase configured (no default_price_increase and no covering Applications Periods Rental records), the two views agree numerically day by day. They still differ in shape: map is a single comma-separated string you split client-side, while map_with_price_variation is a JSON array whose elements are Decimal values (each one rendered as its own JSON string, e.g. "100.0").