Preferences Rules

Calendar rules are scoped overrides stored on preference settings such as minimum stay, min/max price, and discount configurations. When the pricing engine evaluates a date, it finds the highest-priority rule whose conditions match that date and applies its value. Rules that do not match that date are skipped; if no rule matches, the engine falls back to a default or applies no constraint.

Rule types and default priority

Each rule has a type that determines its default priority. Higher priority overrides lower priority when multiple rules match the same date. The priority field is assigned automatically by the server — any value submitted in a request body is ignored.

Priority	Rule type(s)	Scope
1	global	Whole calendar — at most one per rule set, applies to every date
2	day_of_week, monthly	Weekday pattern or specific calendar month(s)
3	time_based	Booking window relative to today (days_before / days_after)
4	seasonal	Named seasonal date range (references custom_date_ranges)
5	event	Named event date range (references custom_date_ranges)
6	adjacency / one_sided_gap	Adjacent-gap nights — minimum_stay_rules_v3 only
7	gap	Gap-night minimum stay — minimum_stay_rules_v3 only
8	custom	Fixed calendar date range (start_date / end_date)

custom rules always win. global is the catch-all baseline that every other rule type can override.

Conflict resolution

When multiple rules match the same date, the highest-priority rule wins (largest priority number). Within the same rule type, the engine applies additional specificity ordering:

• time_based — a narrower booking window (smaller days_before) overrides a wider one on the same date.
• custom — a one-time range (yearly: false) overrides a recurring range (yearly: true) on the same dates.
• day_of_week and monthly — when multiple rules of the same type cover the same date, the one with the more specific condition (e.g. with months set vs. without) takes precedence.

Per-day values and fall-through

Rules can carry either a scalar value (applies to every matching date) or day_of_week_values (a 7-element array, index 0 = Sunday). A null element in day_of_week_values means the rule does not apply for that specific weekday — the engine falls through to the next applicable rule in the priority hierarchy for that day.

Seasonal and event rules

seasonal and event rules reference a custom_date_ranges entry by id. The date window (start, end) is defined in that entry; the rule sets the value to apply over the window. A new entry and a rule referencing it can be sent in the same PUT request — manually assign the id on the new entry so the referencing rule can use it in the same payload.

Which rule types apply to each setting

Setting	Supported rule types
last_minute_discount	time_based, seasonal, event, monthly, day_of_week, custom
far_future_premium	time_based, seasonal, event, monthly, day_of_week, custom
seasonality_adjustment	seasonal, event, monthly
day_of_week	global, time_based, seasonal, event, monthly, day_of_week, custom
minimum_stay_rules_v3	global, time_based, seasonal, event, monthly, day_of_week, custom, gap, adjacency
minimum_price_rules_v3	global, time_based, seasonal, event, monthly, day_of_week, custom
maximum_price_rules_v3	global, time_based, seasonal, event, monthly, day_of_week, custom
checkin_checkout > check_in_rules	global, time_based, seasonal, event, monthly, day_of_week, custom
checkin_checkout > check_out_rules	global, time_based, seasonal, event, monthly, day_of_week, custom
demand_sensitivity_rules	global, time_based, seasonal, event, monthly, day_of_week, custom
historical_anchoring_rules	global, time_based, seasonal, event, monthly, day_of_week, custom

Smoothing

last_minute_discount, far_future_premium and seasonality_adjustment accept a smooth boolean when type is CUS.

• Stepped (false, the default): each rule applies in full, so the price can jump where one rule ends and the next begins.
• Smooth (true): the value eases gradually from one rule to the next.

Short rules may not reach their full value. custom rules always apply exactly.

In seasonality_adjustment, smoothing replaces the linear interpolation of monthly rules with step: false.

Use POST /preferences/{listing_id}/preview to check the effect on prices before saving.