Far-Future Pricing: Premiums and Lead-Time Ramps
Far-future pricing adjusts nights at or beyond a selected booking lead time. A flat policy applies immediately at full strength; a gradual policy ramps from zero at start_days to the maximum at end_days (365 by default) and holds it for every night further out.
See where the premium actually begins
A flat 10% begins at the threshold. A gradual adjustment starts at zero, reaches 10% at day 365 (the default end_days) and holds it beyond.
A 120-day threshold is inclusive. Flat pricing jumps to the full adjustment on day 120. Gradual pricing is still at zero on that date, because the date marks the beginning—not the end—of the ramp.
For the +10% gradual example with the default end_days of 365, day 240 is 120 of the 245 ramp days after the threshold:
The rule percentage is 10% × (240 − 120) ÷ (365 − 120) ≈ 4.89796%. The API rounds it to 4.9% before applying it, so the price is $200 × 1.049 = $209.80.
Day 365 reaches the full +10% ($220), and so does every later night. A 365-row response ends at lead day 364, one day short of the plateau; inspect the returned dates rather than treating “one year” as an inclusive index.
What to check if a premium seems too small
| Check | Why it matters |
|---|---|
| Is the stay past the threshold? | Earlier dates do not qualify |
| Is the mode gradual? | The full amount is not reached until end_days (365 by default) |
| Is a scoped rule selected? | A month or date range can replace the default settings |
| Is a maximum price active? | A valid premium can be reduced by a later owner limit |
Configure a flat premium
The JSON below is an addition to this complete Calendar Prices request. Merge fields into one request; do not send a rule fragment by itself.
{
"location": {
"latitude": 25.7907,
"longitude": -80.13
},
"currency": "USD",
"base_price": 200
}
All worked prices use USD and assume a $200 price after model effects, with no other adjustments unless stated. They demonstrate arithmetic, not live forecasts.
{
"pricing_rules": {
"far_future": {
"mode": "custom",
"settings": {
"start_days": 120,
"adjustment_percent": 10,
"adjustment_type": "flat"
}
}
}
}
This adds 10% to every night from 120 days out to the end of the
calendar, up to two years out (200 → 220). start_days must be at least
60. With gradual, the adjustment is zero at day 120 and rises linearly to
10% at end_days, then holds. end_days must be after start_days and
defaults to 365; a shorter response horizon does not change the ramp. Reserved and blocked dates are
excluded.
For both lead-time rules, adjustment_percent accepts percentages greater than −100 with at most two decimal places and no fixed upper limit.
Compare flat and gradual behavior
With a 120-day start and a +10% maximum:
| Days until arrival | Flat price | Gradual calculation | Gradual price |
|---|---|---|---|
| 119 | $200 | Outside window | $200 |
| 120 | $220 | 0% at start | $200 |
| 240 | $220 | 4.89796…% rounded to 4.9% | $209.80 |
| 365 | $220 | +10% at end_days | $220 |
| 600 | $220 | +10%, held | $220 |
Within the window, custom gradual percentage = maximum adjustment × min(1, (lead days − start days) / (end days − start days)), rounded to two decimal places before applying it. The API may return less than two years of dates; that does not change the ramp. Do not rescale it to the length of the returned array.
Presets
| Preset | Starts at | Reaches at day 365 | Beyond day 365 |
|---|---|---|---|
| conservative | 270 days | +5% | holds +5% |
| balanced | 180 days | +10% | holds +10% |
| aggressive | 120 days | +15% | holds +15% |
All far-future presets ramp linearly, reach full strength one year out and hold it for anything further out, so they matter on the 12-month calendar most hosts manage. Custom gradual settings behave the same way, with end_days choosing where the ramp completes. Use the preset mode without custom settings. Higher premiums are policy choices, not evidence that every distant night will sell at that rate.
Interactions to check
Far-future adjustments add to the other automatic-rule percentages, before custom weekday percentages and owner price limits. Known reserved and blocked dates are excluded. If a night is outside the returned horizon, it has no response row to inspect.
Choose the price path, not just the maximum
end_days. Compare a threshold date and a later returned date before adding other rules. To give selected dates a different policy, continue with seasonal overrides.