World Cup Pricing Example: Three Nights, Explained
You own a two-bedroom in Miami Beach with a $200 base price. The 2026 World Cup runs from June 11 to July 19 and Miami is a host city. Your calendar for the opening weekend has bookings on either side of three nights: Saturday June 13, Sunday June 14, and Monday June 15. You have a full set of pricing rules switched on, a $300 minimum, a $400 maximum, and two overrides.
The engine returns $300, $550, and $300. Two of those numbers are the same and got there by different routes. The third is above your own maximum. This example follows every line of all three receipts to show how that happens and what each line is telling you.
The setup
Six calendar nights are sent with the request, June 12 through 17. Two are reserved on the outside, one is reserved in the middle, and three are available. That shape is what makes the example useful: the same rule set does different things to a one-night gap, a reserved night, and the first night of a two-night gap.
The calendar in the request, June 12–17, 2026, calculated on Saturday June 13. Select a night to see what the calendar means for it.
The calculation date is Saturday, June 13, so June 13 is 0 days out, June 14 is 1 day out, and June 15 is 2 days out. Every rule in the request is in custom mode with explicit settings:
| Rule | Setting | In plain terms |
|---|---|---|
| Last-minute | Flat −20% inside 21 days | Any night within three weeks of today gets 20% off |
| Gap night | −15% for 1-night gaps | A single open night between two bookings gets 15% off |
| Adjacent day | −5%, one day before or after a booking | An open night touching a booking gets 5% off |
| Occupancy pacing | 0–4 days out: −10% below 50% booked, +5% at 50% or more | If the next few days are mostly empty, discount; if mostly full, add |
| Custom weekday | Friday +5%, Saturday +10% | A weekend premium on top of the model's own weekday effect |
| Stay rules | 1-night minimum; no Sunday check-in | Restrictions are reported alongside the price |
| Price limits | $300 minimum, $400 maximum | The floor and ceiling for the final price |
| Overrides | June 13: +10%; June 14: fixed $550 | A percentage nudge on Saturday; a hard price on Sunday |
The model factors for all three nights are +10% seasonality, +20% for the tournament, and +25% market demand, with a modeled weekday effect of +5% on Saturday, 0% on Sunday, and −5% on Monday.
The order of operations
The engine applies its stages in a fixed order, and two of the stages use different arithmetic. Reading a receipt is much easier once that order is fixed in your head.
Model effects and custom adjustments compound. Automatic rules share one basis. Limits clip, and a fixed override replaces.
- 01Base priceYour starting point for every night.
- 02Model effectsSeasonality, weekday, event, demand. Each multiplies the running price.
- 03Automatic rulesLast-minute, gap, adjacent, pacing. Percentages add, then apply once to the model price.
- 04Custom adjustmentsCustom weekday rule, then a percentage override. Each compounds.
- 05Price limitBelow the minimum or above the maximum, the price moves to the bound.
- 06Fixed overrideA fixed price replaces the result and ignores the limits.
- Model effects compound. Seasonality, weekday, event, and demand each multiply the running price in turn. +10% then +5% is ×1.155, not +15%.
- Automatic rules share one basis. Last-minute, gap, adjacent, and occupancy percentages are added together and applied once to the post-model price. Discounts of −20%, −15%, and −10% remove 45% of the model price, whatever order they are listed in.
- Custom adjustments compound again. The custom weekday percentage, then a percentage override, each multiply the running price.
- Limits clip. If the running price is below the minimum or above the maximum, a limit line moves it to the boundary. Missing bounds default to 70% and 1000% of the base price.
- A fixed override replaces. If a fixed price is set for the date, it becomes the price, regardless of the limits.
Every stage writes its own line on the receipt with a signed dollar amount, and the lines sum to the final price to the cent.
Three receipts
Every line is a signed dollar amount, and each receipt sums exactly to its served price. Colors mark the stage that wrote the line.
- Base price
- Model effects
- Automatic rules
- Custom adjustments
- Price limit
- Fixed override
Saturday, June 13: a one-night gap on a discount day
The model takes $200 to $346.50: seasonality adds $20, the Saturday weekday effect $11, the tournament $46.20, and demand $69.30. That is the price the engine would recommend with no rules at all.
Then three automatic rules fire at once. June 13 is 0 days out, inside the 21-day last-minute window: −20%. It is a single open night between the June 12 and June 14 reservations: −15%. And the 0–4 day window is only 40% booked, two of five nights: −10%. The percentages add to −45% of $346.50, and the running price falls to $190.58.
Two custom adjustments follow, and they compound. The custom Saturday rule adds 10% ($19.05), then the +10% percentage override for June 13 adds 10% of that ($20.97). The running price is $230.60.
That is below the $300 minimum, so the final line adds $69.40 and the night is served at $300.
The receipt is doing its job here. The minimum is contributing more than any single model effect, which means the discount stack is deeper than the floor allows on a World Cup Saturday. Whether that is right is the host's call, but the receipt turns it into a decision rather than a surprise: a narrower last-minute window during the tournament, or a seasonal override that pauses the gap discount, would change the outcome.
Sunday, June 14: reserved, and a fixed price wins
June 14 is already booked, and it still gets a receipt. The model price is $330: the same +10%, +20%, and +25%, with a 0% weekday effect on Sunday. None of the calendar-dependent rules apply, because last-minute, gap, adjacent, and occupancy rules only ever adjust nights a guest could still book. There is no custom Sunday rule either.
$330 sits inside the $300–$400 limits, so no limit line appears. Then the fixed override for June 14 sets the price to $550: a single line, fixed_price_override, contributing +$220. The maximum is $400 and the final price is $550 anyway, because a fixed price is an instruction rather than an adjustment, and it bypasses both limits.
Two things to read off this receipt. check_in_allowed is false, and that is the stay rule (no Sunday check-in) speaking, not the reservation. And the price on a reserved night is information for your calendar view; it is not a signal to change the rate of an existing booking.
Monday, June 15: a two-night gap, so the adjacent rule instead
Monday's model price is $313.50. The weekday effect is −5% here, and the tournament and demand factors are applied to a slightly smaller running price than on Saturday.
June 15 opens a two-night gap with June 16, and the gap rule in this request only covers one-night gaps, so there is no gap line. But June 15 is the day after the June 14 reservation, so the adjacent-day rule fires: −5%. With last-minute (−20%) and occupancy pacing (−10%), the automatic rules total −35% of $313.50, and the running price is $203.78.
No custom adjustments apply on a Monday and there is no override. The $300 minimum adds $96.22.
Saturday and Monday both end at $300, and a chart of final prices would show two identical bars. The receipts show that Saturday was $230.60 before its floor and Monday was $203.78, that different rules produced those numbers, and that the floor is doing $27 more work on Monday. That is the difference between a price and an explanation.
Follow the money
Each floating bar is one line of the receipt. The shaded band is the $300–$400 limits. Hover or tap a bar to read its line.
Read each bar as one receipt line. Blue bars are model effects and always compound. Teal bars are automatic rules; they are drawn one at a time, but each is a percentage of the same model price. Purple bars are custom adjustments. The shaded band is your limits, and an amber bar is the engine moving the price to the nearer edge of it. The red bar on Sunday is the fixed override leaving the band entirely.
Limit or override?
The June 14 receipt is the clearest illustration of a distinction that matters in practice. A price limit and a fixed override both produce a number you chose, but they sit at different points in the order of operations and mean different things.
Sunday's $330 model price sits inside the limits. A percentage that reaches $550 is clipped by the maximum; a fixed $550 is served as written.
If you had expressed the same intent as a percentage override, +67% on the $330 model price, the running price would have reached $550 before the limits, and the maximum would have clipped it back to $400 with a maximum_price_limit line of −$150. A percentage override is an adjustment, and adjustments are subject to your limits. A fixed override is a price, applied after the limits, and it is served as written.
Use a fixed price when you mean exactly that amount: a negotiated rate, a manual match to a competitor, an event night you have already decided on. Use a percentage override, with your limits as the safety net, when you want the model to keep working underneath your adjustment.
Change the rules
Every price below is recomputed with the same arithmetic as the receipts. The reserved night never responds to the calendar rules.
Lower the minimum and Saturday and Monday separate: their pre-limit prices were different all along, and the floor was hiding it. Switch off the automatic discounts and both nights climb above the floor on their own. Switch off Sunday's fixed price and it returns to its $330 model price, inside the limits. The reserved night is the one whose price never moves with the calendar rules, because none of them apply to it.
Reading the response as a developer
Each recommendation in the response carries the date, the final price, the stay restrictions (min_stay, check_in_allowed, check_out_allowed), and an explanation array of receipt lines. Every line has a stable code for your application logic, a display label, and a signed amount in the response currency. Adjustment lines also carry the adjustment_percent that produced them, and holiday/event lines carry details.
The three nights in this example use thirteen distinct codes between them:
| Code | Stage | Appears on |
|---|---|---|
base_price | Base | All three nights |
seasonality, day_of_week, known_holiday_event, market_demand | Model | All three nights |
last_minute_rule, occupancy_pacing_rule | Automatic rule | June 13, June 15 |
gap_night_rule | Automatic rule | June 13 |
adjacent_night_rule | Automatic rule | June 15 |
custom_day_of_week_rule, percentage_price_override | Custom adjustment | June 13 |
minimum_price_limit | Limit | June 13, June 15 |
fixed_price_override | Override | June 14 |
Two rules for reconciling. Sum the amount values with decimal-safe arithmetic and they equal price exactly; each amount is the difference between rounded running totals, so recomputing a line from its displayed percentage can differ by a cent. And do not treat a limit line and an override line as the same kind of thing: minimum_price_limit means the model and your rules produced something below your floor, while fixed_price_override means your instruction replaced the calculation.
The complete request and the three-night excerpt of the response follow. The dates are fixed so the example is reproducible to read; a live request prices from today forward with current model data, so the model lines will differ.
Expand the complete request JSON
{
"location": {
"latitude": 25.7907,
"longitude": -80.13
},
"currency": "USD",
"base_price": 200,
"calendar": [
{
"date": "2026-06-12",
"status": "reserved"
},
{
"date": "2026-06-13",
"status": "available"
},
{
"date": "2026-06-14",
"status": "reserved"
},
{
"date": "2026-06-15",
"status": "available"
},
{
"date": "2026-06-16",
"status": "available"
},
{
"date": "2026-06-17",
"status": "reserved"
}
],
"pricing_rules": {
"last_minute": {
"mode": "custom",
"settings": {
"start_days": 21,
"adjustment_percent": -20,
"adjustment_type": "flat"
}
},
"far_future": {
"mode": "balanced"
},
"gap_day": {
"mode": "custom",
"settings": [
{
"min_days": 1,
"max_days": 1,
"adjustment_percent": -15
}
],
"apply_on_weekends": true
},
"adjacent_day": {
"mode": "custom",
"settings": {
"days_before": 1,
"days_after": 1,
"adjustment_percent": -5
},
"apply_on_weekends": true
},
"occupancy_pacing": {
"mode": "custom",
"settings": {
"lead_time_ranges": [
{
"min_days": 0,
"max_days": 4
}
],
"occupancy_ranges": [
{
"min_percent": 0,
"max_percent": 49
},
{
"min_percent": 50,
"max_percent": 100
}
],
"adjustment_percent": [
[
-10
],
[
5
]
]
}
},
"day_of_week": {
"mode": "custom",
"settings": {
"adjustment_percent": {
"monday": 0,
"tuesday": 0,
"wednesday": 0,
"thursday": 0,
"friday": 5,
"saturday": 10,
"sunday": 0
}
}
}
},
"stay_rules": {
"min_stay": {
"mode": "custom",
"settings": {
"min_nights": 1
}
},
"check_in_out": {
"mode": "custom",
"settings": {
"allowed_check_in_days": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday",
"saturday"
],
"allowed_check_out_days": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday",
"saturday",
"sunday"
]
}
}
},
"price_limits": {
"min_price": 300,
"max_price": 400
},
"price_overrides": [
{
"start_date": "2026-06-13",
"end_date": "2026-06-13",
"adjustment_type": "percentage",
"adjustment_amount": 10
},
{
"start_date": "2026-06-14",
"end_date": "2026-06-14",
"adjustment_type": "fixed",
"adjustment_amount": 550
}
],
"advanced": {
"seasonality_sensitivity_percent": 100,
"demand_sensitivity_percent": 100,
"apply_negative_demand_adjustments": true
}
}
Expand the response excerpt with itemized explanations for all three nights
Only the first three rows of an illustrative two-year response are shown. A live request can use an inclusive start_date and end_date to select fewer rows.
{
"location": {
"latitude": 25.7907,
"longitude": -80.13
},
"currency": "USD",
"coverage": {
"calculation_date": "2026-06-13",
"start_date": "2026-06-13",
"end_date": "2028-06-11",
"recommendation_count": 730,
"timezone": "America/New_York"
},
"warnings": [],
"recommendations": [
{
"date": "2026-06-13",
"price": 300,
"min_stay": 1,
"check_in_allowed": true,
"check_out_allowed": true,
"explanation": [
{
"code": "base_price",
"label": "Base price",
"amount": 200
},
{
"code": "seasonality",
"label": "Seasonality",
"adjustment_percent": 10,
"amount": 20
},
{
"code": "day_of_week",
"label": "Day of week",
"adjustment_percent": 5,
"amount": 11
},
{
"code": "known_holiday_event",
"label": "Holiday/event",
"adjustment_percent": 20,
"amount": 46.2,
"details": [
"World Cup 2026 — Miami"
]
},
{
"code": "market_demand",
"label": "Market demand",
"adjustment_percent": 25,
"amount": 69.3
},
{
"code": "last_minute_rule",
"label": "Last-minute rule",
"adjustment_percent": -20,
"amount": -69.3
},
{
"code": "gap_night_rule",
"label": "Gap-night rule",
"adjustment_percent": -15,
"amount": -51.97
},
{
"code": "occupancy_pacing_rule",
"label": "Occupancy pacing rule",
"adjustment_percent": -10,
"amount": -34.65
},
{
"code": "custom_day_of_week_rule",
"label": "Custom Saturday rule",
"adjustment_percent": 10,
"amount": 19.05
},
{
"code": "percentage_price_override",
"label": "Percentage price override",
"adjustment_percent": 10,
"amount": 20.97
},
{
"code": "minimum_price_limit",
"label": "Minimum price limit",
"amount": 69.4
}
]
},
{
"date": "2026-06-14",
"price": 550,
"min_stay": 1,
"check_in_allowed": false,
"check_out_allowed": true,
"explanation": [
{
"code": "base_price",
"label": "Base price",
"amount": 200
},
{
"code": "seasonality",
"label": "Seasonality",
"adjustment_percent": 10,
"amount": 20
},
{
"code": "day_of_week",
"label": "Day of week",
"adjustment_percent": 0,
"amount": 0
},
{
"code": "known_holiday_event",
"label": "Holiday/event",
"adjustment_percent": 20,
"amount": 44,
"details": [
"World Cup 2026 — Miami"
]
},
{
"code": "market_demand",
"label": "Market demand",
"adjustment_percent": 25,
"amount": 66
},
{
"code": "fixed_price_override",
"label": "Fixed price override",
"amount": 220
}
]
},
{
"date": "2026-06-15",
"price": 300,
"min_stay": 1,
"check_in_allowed": true,
"check_out_allowed": true,
"explanation": [
{
"code": "base_price",
"label": "Base price",
"amount": 200
},
{
"code": "seasonality",
"label": "Seasonality",
"adjustment_percent": 10,
"amount": 20
},
{
"code": "day_of_week",
"label": "Day of week",
"adjustment_percent": -5,
"amount": -11
},
{
"code": "known_holiday_event",
"label": "Holiday/event",
"adjustment_percent": 20,
"amount": 41.8,
"details": [
"World Cup 2026 — Miami"
]
},
{
"code": "market_demand",
"label": "Market demand",
"adjustment_percent": 25,
"amount": 62.7
},
{
"code": "last_minute_rule",
"label": "Last-minute rule",
"adjustment_percent": -20,
"amount": -62.7
},
{
"code": "adjacent_night_rule",
"label": "Adjacent-night rule",
"adjustment_percent": -5,
"amount": -15.67
},
{
"code": "occupancy_pacing_rule",
"label": "Occupancy pacing rule",
"adjustment_percent": -10,
"amount": -31.35
},
{
"code": "minimum_price_limit",
"label": "Minimum price limit",
"amount": 96.22
}
]
}
]
}