# Listing Preferences

> Web version: https://docs.usewheelhouse.com/rm/concepts/preferences

Read and update detailed pricing preferences for listings, including base price,
seasonality, discounts, min stay rules, and more.

> **Note:**
>
> These preferences are called **"Settings"** in the Wheelhouse app.

## Settings your channel may not support

Not every channel can act on every setting. Some have no concept of
check-in/check-out day rules, some cannot take minimum stays, and support for
long-term discounts ranges from none at all, through fixed weekly and monthly
tiers, to arbitrary ones. Which settings a listing accepts therefore depends on
the channel it is connected to.

A setting the channel cannot act on is **not applied** — it is discarded rather
than stored, so it never appears to have taken effect. The rest of the request
still applies, and the response is still a success.

Each listing reports what it accepts as `supported_settings`, on both the
listing object and the preferences object. Read it before sending a setting
rather than after: a setting reported `false` will be discarded. It reflects any
per-account early access, so two listings on the same channel can differ.

Every write also returns `warnings`, naming each setting that was not applied,
why, and which attributes it covered. The array is present and empty when
everything applied, so it can be read unconditionally. `reason` is
`not_supported_by_channel` when the channel has no such feature, or
`partially_supported_by_channel` when it accepts a narrower form than what was
sent and only the excess was dropped.

## Estimated fees

`fee_adjustments` is the estimated share of fees guests pay on top of the
nightly rate, as a percentage of that rate. It is the setting behind
`GET /listings/{listing_id}/fee_impact_calendar`, which returns it as a
per-date multiplier.

```json
{ "fee_adjustments": { "total_fee_percentage": 15, "auto_update": false } }
```

- `total_fee_percentage` is `-100` or more, with no upper bound: fees can exceed
  the nightly rate on short stays. Omitted means `0`.
- `auto_update`, when `true`, has Wheelhouse recalculate the percentage weekly
  from the fees on the listing's recent reservations, replacing whatever was
  set. It defaults to `false`.
- The object replaces the stored one as a whole, so send both keys. Sending
  `null` clears the setting.
- Reads return `null` when nothing is configured, otherwise both keys.

With no fee adjustment in effect, the fee impact calendar reports a multiplier
of `1.0`. Pass `fallback=estimate` to get the percentage `auto_update` would
set instead, estimated from the fees on the listing's recent reservations. Each
entry's `source` says whether its multiplier came from the setting (`setting`),
that estimate (`estimate`), or neither (`none`). Neighborhood prices include
fees, so multiply a listing's nightly rate by the multiplier before comparing
it with them.

## UI settings panel groups

The Wheelhouse Settings panel organizes preferences into labeled groups. The
table below maps each group to its corresponding API fields.

| UI Group | UI Setting Name | API Field(s) |
|---|---|---|
| Pricing Engine | Base price | `base_price`, `base_price_adjustment` |
| Pricing Engine | Seasonality | `seasonality_adjustment` |
| Pricing Engine | Day of week | `day_of_week` |
| Pricing Engine | Local events | `demand_sensitivity_rules` |
| Pricing Engine | Last minute | `last_minute_discount` |
| Pricing Engine | Far future | `far_future_premium` |
| Pricing Engine | Gaps & Adjacencies | `gap_night` |
| Model Weights | Historical protections | `historical_anchoring_rules`, `historical_anchoring_price_source`, `historical_anchoring_mode` |
| Limits | Maximum prices | `maximum_price_rules_v3` |
| Limits | Minimum prices | `minimum_price_rules_v3`, `min_min_price` |
| Operations | Minimum stays | `minimum_stay_rules_v3`, `min_min_stay` |
| Operations | Length of stay pricing | `long_term_discounts`, `weekly_discount`, `monthly_discount` |
| Operations | Asking Rate (+Est. Fees) | `fee_adjustments` |
| Calendar Pacing | Occupancy pacing | `occupancy_pacing` |
| Configuration | Events & Seasons | `custom_date_ranges` |

`demand_sensitivity_rules` is the Local events setting. The UI name changed when day of week
became its own setting; the field name did not, so existing integrations keep working unchanged.
`historical_anchoring_*` is the same case, shown as Historical protections.

For the full rules model (priority, conflict resolution, and per-day values),
see [Preferences rules](https://docs.usewheelhouse.com/rm/concepts/preferences-rules.md).
