# Wheelhouse Revenue Management API > Web version: https://docs.usewheelhouse.com/ The Wheelhouse Revenue Management API provides direct access to price recommendations, listing preferences, custom rates, reservations, and portfolio management for Revenue Management integrations. > **Beta:** > > This API is currently in beta. The interface and response formats may change in > future versions. ## Base URL All requests are made against the production server: ``` https://api.usewheelhouse.com/ss_api/v1 ``` ## Where to go next - **[Authentication](https://docs.usewheelhouse.com/rm/authentication.md)** — how to authenticate direct HTTP integrations and AI agents, and how read-only keys behave. - **[MCP server](https://docs.usewheelhouse.com/rm/mcp.md)** — connect AI assistants (Cursor, Claude, VS Code, and others) to your Wheelhouse account. - **[Agent plugin](https://docs.usewheelhouse.com/rm/wheelhouse-plugin.md)** — install Wheelhouse Plugin to get MCP plus portfolio skills (pacing, overpricing, custom rates, leaderboards). - **[Usage & limits](https://docs.usewheelhouse.com/rm/usage.md)** — pagination, rate-limit headers, and `GET /usage`. - **Concepts** — [identifying listings](https://docs.usewheelhouse.com/rm/concepts/listings.md), [listing preferences](https://docs.usewheelhouse.com/rm/concepts/preferences.md), [preferences rules](https://docs.usewheelhouse.com/rm/concepts/preferences-rules.md), and [dynamic sets](https://docs.usewheelhouse.com/rm/concepts/dynamic-sets.md). - **[API Reference](https://docs.usewheelhouse.com/rm/reference/wheelhouse-revenue-management-api.md)** — every endpoint, grouped by resource. - **[Changelog](https://docs.usewheelhouse.com/rm/changelog.md)** — dated list of additions and changes. ## OpenAPI specification The full API specification is available at a stable URL, always the latest version. Point code generators, API clients, and AI agents at it: - YAML: [`https://docs.usewheelhouse.com/rm/openapi.yaml`](https://docs.usewheelhouse.com/rm/openapi.yaml) - JSON: [`https://docs.usewheelhouse.com/rm/openapi.json`](https://docs.usewheelhouse.com/rm/openapi.json) Every page of these docs also has a Markdown version: add `.md` to its URL, e.g. [`/rm/authentication.md`](https://docs.usewheelhouse.com/rm/authentication.md) or [`/rm/reference/rm-get-listings.md`](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) (this page is [`/index.md`](https://docs.usewheelhouse.com/index.md)). An endpoint's Markdown has the parameters, request body, responses and an example request on one page, with shared types listed once at the end. Each page also has **Copy page** and **View as Markdown** buttons, and a client that sends `Accept: text/markdown` gets the Markdown version from the page's own URL. Agents can also start from [`/llms.txt`](https://docs.usewheelhouse.com/llms.txt), which lists the spec and every Markdown page, or read [`/llms-full.txt`](https://docs.usewheelhouse.com/llms-full.txt), which has all of them in one file. --- # Authentication > Web version: https://docs.usewheelhouse.com/rm/authentication ## MCP and AI agents When using this API through the Wheelhouse MCP server, authenticate with **OAuth** (WorkOS AuthKit). Sign in with your Wheelhouse account through your MCP client's OAuth flow — the same credentials you use in the Wheelhouse app. Do **not** send an RM API key yourself. The MCP server validates your OAuth token, resolves your user-specific RM API key, and attaches it as `X-Integration-Api-Key` on every upstream request. Your OAuth token is never forwarded to the RM API. For enablement and client setup (Cursor, Claude, VS Code, and others), see [MCP server](https://docs.usewheelhouse.com/rm/mcp.md). To install the MCP server together with portfolio skills, see [Agent plugin](https://docs.usewheelhouse.com/rm/wheelhouse-plugin.md). ## Direct API integrations For HTTP integrations that call the RM API directly, send an RM API key in the `X-Integration-Api-Key` header. You can generate this in your Wheelhouse account under **"Api Key"**. Each Wheelhouse user can hold up to 5 active RM API keys, and can create one only while holding fewer. A user who already held more before the limit keeps those keys. The key behind MCP access does not count toward the limit. The RM API key is a single key that authenticates both the integration and user context — no separate user key is required. ```bash curl https://api.usewheelhouse.com/ss_api/v1/listings \ -H "X-Integration-Api-Key: YOUR_API_KEY" ``` ## Read-only API keys Keys configured as read-only may use the HTTP methods `GET`, `HEAD`, `OPTIONS`, and `POST` only. **PUT** and **DELETE** requests return **403 Forbidden** with a message that the API key is read-only (other disallowed methods do as well). `POST` endpoints that create or modify data (such as creating a note) also return **403 Forbidden** for read-only keys; only non-mutating `POST` endpoints (such as previews) are allowed, plus `POST /feedback`, which changes nothing about your account. --- # Wheelhouse MCP Server > Web version: https://docs.usewheelhouse.com/rm/mcp The Wheelhouse MCP server exposes the Revenue Management API as [Model Context Protocol](https://modelcontextprotocol.io/) tools so AI assistants can read and update your Wheelhouse account on your behalf. > **Beta:** > > MCP access is a free beta for now. The Revenue Management API will become a paid > product once it is released. ## Enable access Before connecting a client: 1. Open your Wheelhouse account settings and go to [**API & MCP → MCP**](https://app.usewheelhouse.com/u/account/mcp). 2. Under **MCP Access**, click **Enable MCP Access**. Wheelhouse creates dedicated API keys for MCP on your behalf. Usage is tracked and rate-limited like your other RM API keys, and you can review activity in the API logs. Disabling MCP access revokes those keys immediately. The MCP page has a **Read-only** switch. It uses the same limits as a [read-only RM API key](https://docs.usewheelhouse.com/rm/authentication.md#read-only-api-keys): assistants can look up the account and run previews, and changes are rejected. ## Server URL ``` https://mcp.usewheelhouse.com/mcp ``` ## Authentication MCP clients authenticate with **OAuth** (WorkOS AuthKit). Sign in with your Wheelhouse account through your client's OAuth flow — the same credentials you use in the Wheelhouse app. Do **not** paste an RM API key into the MCP client. The server validates your OAuth token, resolves your user-specific RM API key, and attaches it as `X-Integration-Api-Key` on every upstream request. Your OAuth token is never forwarded to the RM API. See [Authentication](https://docs.usewheelhouse.com/rm/authentication.md) for how direct HTTP integrations differ. To install the MCP server together with Wheelhouse portfolio skills, see [Agent plugin](https://docs.usewheelhouse.com/rm/wheelhouse-plugin.md). The steps below connect the MCP server on its own. ## Client setup Enable MCP access first, then follow the steps for your client. ### Claude Desktop **Custom connector (recommended)** 1. Open **Settings → Connectors → Add custom connector**. 2. Paste the Wheelhouse MCP URL: `https://mcp.usewheelhouse.com/mcp` 3. Complete the OAuth sign-in flow with your Wheelhouse account. **Manual config** If your organization does not allow custom connectors, add this to `claude_desktop_config.json` and restart Claude Desktop: ```json { "mcpServers": { "wheelhouse": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.usewheelhouse.com/mcp"] } } } ``` ### Claude Code (CLI) Run this command in your terminal: ```bash claude mcp add --transport http wheelhouse https://mcp.usewheelhouse.com/mcp ``` ### Cursor 1. Open **Cursor Settings → Tools & MCP**, or create `.cursor/mcp.json` in your project (or global MCP settings). 2. Add the Wheelhouse server configuration below. 3. Click **Connect** next to Wheelhouse and sign in with your Wheelhouse account when prompted. ```json { "mcpServers": { "wheelhouse": { "url": "https://mcp.usewheelhouse.com/mcp" } } } ``` ### VS Code 1. Open the Command Palette and run **MCP: Add Server**. 2. Choose **HTTP** and use the configuration below (or add it to your MCP settings file). 3. Complete the OAuth sign-in flow with your Wheelhouse account when prompted. ```json { "servers": { "wheelhouse": { "type": "http", "url": "https://mcp.usewheelhouse.com/mcp" } } } ``` ### Other clients Clients that support stdio MCP servers can connect through the `mcp-remote` bridge: ```bash npx -y mcp-remote https://mcp.usewheelhouse.com/mcp ``` Remote server URL: `https://mcp.usewheelhouse.com/mcp` ## Usage notes - **Tools use Code Mode.** Discover RM API operations with `search`, inspect parameters with `get_schema`, and call them from `execute`. Use the [API Reference](https://docs.usewheelhouse.com/rm/reference/wheelhouse-revenue-management-api.md) for request parameters, response shapes, and endpoint behavior. - **Same rate limits.** MCP traffic uses your RM API key and is subject to the same limits described in [Usage & limits](https://docs.usewheelhouse.com/rm/usage.md) (60 requests per minute by default). Prefer batch endpoints when working across many listings. - **Confirm before writes.** Ask your assistant to show proposed changes (preference diffs, preview results, or concrete price impact) and approve before any PUT/DELETE or mutating POST. - **Feedback goes straight to us.** When something fails, is missing, or the docs were unclear, your assistant can send feedback with `POST /feedback` without asking first, and tells you afterwards. You can also ask it to send your own feedback. Every item is reviewed by the Wheelhouse team; it is not a support channel. - **Preference arrays replace fully.** When updating preferences, omitting a top-level field leaves it unchanged, but any array field you include fully replaces that array. Always read current preferences first, merge carefully, and confirm before writing. See [Listing preferences](https://docs.usewheelhouse.com/rm/concepts/preferences.md). - **Skills.** Workflow guidance for portfolio analysis, pacing, and preference writes lives in the [Wheelhouse Plugin](https://docs.usewheelhouse.com/rm/wheelhouse-plugin.md). Install it in your assistant (Cursor, Claude Code, Codex) alongside the MCP connection. --- # Wheelhouse Plugin > Web version: https://docs.usewheelhouse.com/rm/wheelhouse-plugin [Wheelhouse Plugin](https://github.com/pricemethod/wheelhouse-plugin) is the Wheelhouse agent plugin. It packages Revenue Management **skills** and the [MCP server](https://docs.usewheelhouse.com/rm/mcp.md) so AI assistants can run portfolio workflows — pacing, pricing diagnostics, custom rates, and leaderboards — instead of calling tools ad hoc. The plugin repository is public: `https://github.com/pricemethod/wheelhouse-plugin` > **Beta:** > > MCP access is a free beta for now. Enable it before you install the plugin. ## Prerequisites 1. A Wheelhouse account. 2. **Enable MCP Access** under [API & MCP → MCP](https://app.usewheelhouse.com/u/account/mcp) in account settings. Wheelhouse creates dedicated API keys for MCP on your behalf. See [MCP server](https://docs.usewheelhouse.com/rm/mcp.md) for what that enablement does. ## Install Add the Wheelhouse Plugin repository as a plugin marketplace, then install the plugins it publishes. The marketplace is named `wheelhouse-plugin`. It ships two plugins, and installing one does not install the other: | Plugin | What it covers | | --- | --- | | `wheelhouse-skills` | Read-only portfolio pacing, pricing diagnostics, leaderboards, and local data sync | | `wheelhouse-writes` | Write-capable preferences, events and seasons, and custom rates | The read-only plugin used to be published as `wheelhouse-plugin`. If you installed that name, remove `wheelhouse-plugin@wheelhouse-plugin` and install `wheelhouse-skills@wheelhouse-plugin`. After a plugin loads, sign in with your Wheelhouse account when the MCP OAuth flow prompts. Do **not** paste an RM API key into chat. ### Claude Code In a Claude Code session: ```text /plugin marketplace add pricemethod/wheelhouse-plugin /plugin install wheelhouse-skills@wheelhouse-plugin /plugin install wheelhouse-writes@wheelhouse-plugin ``` Or from the terminal: ```bash claude plugin marketplace add pricemethod/wheelhouse-plugin claude plugin install wheelhouse-skills@wheelhouse-plugin claude plugin install wheelhouse-writes@wheelhouse-plugin ``` `wheelhouse-plugin` is the marketplace. `wheelhouse-skills` and `wheelhouse-writes` are the plugins inside it. Sign in with your Wheelhouse account when the MCP OAuth flow prompts. ### Codex ```bash codex plugin marketplace add pricemethod/wheelhouse-plugin ``` Then install **wheelhouse-skills** and **wheelhouse-writes** from the Codex plugins list. Each plugin has its own manifest (`wheelhouse-skills/.codex-plugin/plugin.json` and `wheelhouse-writes/.codex-plugin/plugin.json`). The marketplace manifest is `.agents/plugins/marketplace.json`. ### Cursor Register the marketplace from the Cursor CLI, then install **wheelhouse-skills** and **wheelhouse-writes** from **Customize**: ```bash cursor-agent plugin marketplace add https://github.com/pricemethod/wheelhouse-plugin ``` On Teams and Enterprise plans you can also import the repository under **Dashboard → Plugins**: 1. Open the Cursor **Dashboard → Plugins**. 2. Under **Team Marketplaces**, click **Add Marketplace** and import `https://github.com/pricemethod/wheelhouse-plugin`. 3. Review **wheelhouse-skills** and **wheelhouse-writes** and set each plugin's installation mode. 4. Teammates install them from **Customize** in the sidebar (or receive a plugin automatically if it is required). When the Wheelhouse MCP prompts, sign in with your Wheelhouse account. Skills in each plugin are discovered automatically. The bundled MCP server is `https://mcp.usewheelhouse.com/mcp`. ## Skill selection guide You don't have to name a skill. Ask in plain English and the assistant picks the right workflow. If you already know which skill you need, starting with it saves context. Once the plugin and MCP are connected, try: ``` How is this listing pacing versus last year? ``` ``` Are September and October overpriced? ``` ``` Who needs attention in my portfolio? ``` | Your question | Start with | | --- | --- | | How is this listing or portfolio pacing vs last year? | `stly-pacing` | | Are future months overpriced vs last year's booked rates? | `future-rate-overpricing` | | Did a recent rate or preference change drive bookings? | `price-change-attribution` | | Set a custom rate on these dates | `custom-rate-intervention` | | Sync listings and KPIs to disk | `wheelhouse-data-sync-api` | | Who needs attention across my portfolio? | `wheelhouse-leaderboard` | | Push leaderboard flags back as Tags or Notes | `wheelhouse-leaderboard-writeback` | | General MCP tool use or preference writes | `wheelhouse-rm-mcp` | | Shared RM domain context or skill conventions | `wheelhouse-project-instructions` | You can also connect the MCP server [without the plugin](https://docs.usewheelhouse.com/rm/mcp.md) if you only need raw tools. Each tool maps to an RM API operation — see the [API Reference](https://docs.usewheelhouse.com/rm/reference/wheelhouse-revenue-management-api.md). ## Authentication MCP clients authenticate with **OAuth**. Sign in with your Wheelhouse account — the same credentials you use in the Wheelhouse app. See [Authentication](https://docs.usewheelhouse.com/rm/authentication.md). Cache and writeback skills (`wheelhouse-data-sync-api`, `wheelhouse-leaderboard-writeback`) use a local API key **file** on disk. Follow those skills' setup; never paste the key into the conversation. --- # Usage & Limits > Web version: https://docs.usewheelhouse.com/rm/usage ## Pagination List endpoints that return large result sets support pagination via the `page`, `per_page`, and `offset` query parameters. `per_page` controls how many items are returned per page (up to 100). Use `page` (1-based) or `offset` (0-based item skip count) to advance through the result set — do not use both in the same request. Iterate by incrementing `page` until a response returns fewer items than `per_page`. ## Rate limits RM API keys are rate-limited to **60 requests per minute** by default. Exceeding this limit returns **429 Too Many Requests**. The limit resets on a rolling one-minute window. **Every response tells you where you stand**, so you never have to guess or spend a request finding out: | Header | Meaning | |---|---| | `X-RateLimit-Limit` | Requests allowed per window for the key you used. | | `X-RateLimit-Remaining` | Requests still available in the current window. Never negative. | | `X-RateLimit-Reset` | Unix timestamp (seconds) when the window frees up. | The request carrying the headers is itself counted, so an idle key's first response reports one fewer than the limit. A **429** carries the same three headers plus **`Retry-After`**, the number of seconds to wait. Prefer `Retry-After` over your own backoff schedule when it is present — it is the actual reset, not an estimate. If you receive a 429 and no `Retry-After`, wait before retrying. The recommended strategy is **exponential backoff**: after the first failure wait 1 second, then double the delay on each subsequent retry (2 s, 4 s, 8 s, …), up to a reasonable maximum (e.g. 60 seconds). Adding a small random jitter (±10–20% of the wait time) prevents multiple concurrent clients from retrying in lockstep. If your integration regularly reaches the limit, consider batching requests (e.g. using `GET /preferences` or `PUT /preferences` for multiple listings at once) or contact Wheelhouse to discuss a higher limit. `GET /usage` reports volumes, error rates, and response times over a window of up to 7 days, broken down by day, by endpoint, and by API key. It is cached for a few minutes, so poll it on the order of minutes, not seconds, and read `generated_at` to see how fresh a response is. Live rate-limit headroom is on the `X-RateLimit-*` headers of any response — they are current as of that request and cost nothing extra. ### Keeping a local copy fresh An integration that re-reads every endpoint for every listing on a schedule spends most of its rate limit on data that has not changed. Find out what changed first, and re-read only that. **Use webhooks for recommendations, reservations and flags.** Subscribe to `recommendations.updated`, `reservations.ingested` and `flags.detected` (see [Webhooks](https://docs.usewheelhouse.com/rm/reference/webhooks.md)). Each delivery names the listings to re-read. `reservations.ingested` and `flags.detected` send nothing for a listing where nothing changed. `recommendations.updated` names every active listing in a market after its nightly pricing run, including listings whose numbers did not move. For a listing that `reservations.ingested` names, `GET /listings/{listing_id}/reservations` with `date_filter_type=updated_at` returns only the reservations that changed since your last read. **Poll `GET /listings/{listing_id}/recent_changes` for preferences and custom rates.** No webhook covers these. The endpoint returns two timestamps: - `settings`: when the listing's preferences last changed. - `rates`: when a custom rate on the listing was last added, changed, split or removed. Store both, and on each poll re-read only what moved: ``` for each listing: changes = GET /listings/{listing_id}/recent_changes if changes.settings != stored.settings: GET /preferences/{listing_id} if changes.rates != stored.rates: GET /listings/{listing_id}/custom_rates stored = changes ``` For a listing where nothing changed, this costs one request instead of two. Plan around these gaps in webhooks and `recent_changes`: - `rates` does not move when a custom rate expires (its `expires_at` passes) or its dates pass and `GET /listings/{listing_id}/custom_rates` stops returning it. Nothing is written when that happens, and such a rate no longer affects any future price. If your local copy should drop it at that point, filter on `expires_at` and `end_date` yourself. - `flags.detected` does not fire when a flag is cleared. To see cleared flags, re-read `GET /listings/{listing_id}/flags` on your own schedule. - `recent_changes` does not report reservations or the price calendar. Reservations are covered by `reservations.ingested`. Neither webhooks nor `recent_changes` report price calendar changes, so re-read `GET /listings/{listing_id}/price_calendar` on your own schedule. - `recent_changes` costs one request per listing. `GET /preferences` reads the preferences of several listings in one request, which can cost less than one `recent_changes` call per listing. --- # Identifying Listings > Web version: https://docs.usewheelhouse.com/rm/concepts/listings Most endpoints require a `listing_id` and `channel` path or query parameter to identify the listing a request is being made for. There are two ways to fill them in, and both values come from the `GET /listings` endpoint. **By channel listing ID (default).** A channel's listing IDs are only unique within that channel, so `channel` is what disambiguates them: - **`listing_id`** — the `id` field from the listing object. - **`channel`** — the `channel` field from the same listing object. **By Wheelhouse listing ID.** Pass the literal value `wheelhouse` as `channel`, and `listing_id` is read as a Wheelhouse listing ID: - **`listing_id`** — the `wheelhouse_id` field from the listing object. - **`channel`** — the literal string `wheelhouse`. Wheelhouse listing IDs are unique across all channels, so no channel has to be named alongside them. This is the more convenient form when you already hold Wheelhouse IDs — for example from `GET /listings/kpis`, which returns them as `listing_id`, or from a Wheelhouse listing URL. Note that the two ID spaces are distinct: passing a Wheelhouse ID without `channel=wheelhouse`, or a channel listing ID with it, returns **404 Not Found**. Either form works anywhere a listing is identified, including the batched `listing_ids` parameters on `GET /preferences`, `PUT /sets/{set_id}/associated_listings`, and `DELETE /sets/{set_id}/associated_listings`, and the `copy_preferences_from` object on `PUT /preferences/{listing_id}/copy` (whose nested `channel` is resolved independently of the top-level one, so the source and target listing may each be identified their own way). Which form you use does not change what you can reach: a Wheelhouse listing ID grants no access to a listing that a channel listing ID would not. It does change how an unreachable listing is reported. Because Wheelhouse IDs are sequential and span every account, a listing you cannot access returns **404 Not Found** under `channel=wheelhouse` — the same response as an ID that matches nothing — so that the ID space cannot be walked to discover other accounts' listings. Under a channel listing ID, a listing you cannot access still returns **403 Forbidden**. Listings shared with you to manage are reachable under both forms. A typical flow is to call `GET /listings` once to build a local map of your listings, then use the `id` and `channel` values from that map — or each listing's `wheelhouse_id` with `channel=wheelhouse` — for all subsequent listing-specific calls. ## Inactive listings A listing is inactive when Wheelhouse no longer syncs it: for example, its channel stopped returning it, or its channel account was disconnected. The listing object reports this as `is_active: false`. `GET /listings` leaves inactive listings out by default; pass `exclude_inactive=false` to include them. Endpoints that act on one listing return **406 Not Acceptable** for an inactive listing: ```json {"error": "Listing '12345' is inactive"} ``` This applies to reads as well as writes, including `GET /listings/{listing_id}/price_calendar`, `GET /listings/{listing_id}/last_posted_prices` and `GET /preferences/{listing_id}`. Retrying does not help. The listing becomes active again only if a later sync finds it on its channel, so skip it until then. `PUT /preferences` does not fail the whole request for an inactive listing. It reports that listing in `errors` with code `406` and applies the rest of the batch. Under `channel=wheelhouse`, a listing you cannot access returns **404 Not Found** even when it is inactive. ## Multi-unit listings Some listings represent a single bookable property that has multiple independently bookable units underneath it — for example, a building with several apartments, or a property with a main house and a guest cottage managed as one listing. These are called **multi-unit listings**. You can identify a multi-unit listing by the `number_of_active_units` field on the listing object (returned by `GET /listings` and `GET /listings/{listing_id}`). A non-null value indicates a multi-unit listing; `null` indicates a standard single-unit listing. For endpoints that return per-date data (such as `GET /listings/{listing_id}/price_calendar` and `GET /listings/{listing_id}/last_posted_prices`), multi-unit listings return **one row per unit per date**. Each row includes a `unit_number` field (a positive integer starting at `1`) that identifies which unit the row belongs to. Single-unit listings always return `unit_number: 0`. When processing calendar data for a multi-unit listing, group rows by `unit_number` to get the per-unit availability and pricing. Preferences and settings (fetched via `GET /preferences/{listing_id}`) apply at the listing level and are shared across all units. --- # 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). --- # Preferences Rules > Web version: https://docs.usewheelhouse.com/rm/concepts/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, which resets any submitted value to the default for the rule's type. The exceptions are `time_based` rules at `9`, `gap` rules at `9` or `10`, and fractional `adjacency` priorities between 6 and 7. A rule at `9` or `10` wins over `custom` rules. In the Wheelhouse app, **Rule prioritization** sets these (see [How minimum stay rules combine](#how-minimum-stay-rules-combine)). | 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 win over every other default priority. `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. ## How minimum stay rules combine `minimum_stay_rules_v3` follows the same priority order, with three differences: - **Gap rules adjust the value below them instead of replacing it.** The engine applies the rules from lowest to highest priority. When it reaches a `gap` rule, it looks at the minimum stay the lower-priority rules set for the date. If the date sits in a run of available nights that ends at an unavailable night, and starts at one or today, and the run is too short for that minimum stay, the `gap` rule lowers it to the length of the run, but never below the rule's own `value` (with `gap_flexibility`, to the length of the run minus that many nights, with the same limit). If the run fits the minimum stay, or is shorter than the rule's `value`, the date keeps its minimum stay. A run that reaches the end of the calendar never counts as a gap. - **Rule prioritization can raise `time_based` and `gap` rules above `custom` rules.** The Wheelhouse app's **Rule prioritization** option gives a raised `time_based` rule priority `9`. `apply_gap_night_rules_to_overrides: true` gives `gap` rules priority `9`, or `10` when a `time_based` rule already has `9`. A raised rule applies after `custom` rules, so it wins on the dates it matches. The `priority` you read back on each rule shows whether it was raised. Apart from these, and fractional `adjacency` priorities between 6 and 7 that order adjacency rules among themselves, any submitted `priority` is reset to the default for the rule's type. - **`min_min_stay` is applied last, as a floor.** After all rules, any date with a minimum stay below `min_min_stay` is raised to it. `GET /listings/{listing_id}/price_recommendations` returns only the final `min_stay` for each date. It does not say which rule set it. To find out, evaluate the listing's rules from `GET /preferences/{listing_id}` against the date, as in the example below. ### Example A listing has these rules, and no `min_min_stay`: | Rule | Priority | `value` | |---|---|---| | `global` | 1 | 2 | | `time_based`, `days_before: 14` | 3 | 3 | | `gap` | 7 | 2 | | `custom`, December 20 to January 3 | 8 | 7 | The `min_stay` returned for four dates: | Date | Matching rules, lowest priority first | `min_stay` | |---|---|---| | 10 days out, in a run of 5 available nights | `global` sets 2. `time_based` sets 3. The run fits 3, so `gap` changes nothing. | 3 | | 10 days out, in a run of 2 available nights between two bookings | `global` sets 2. `time_based` sets 3. The run does not fit 3, and is not shorter than the `gap` rule's 2, so `gap` lowers it to 2. | 2 | | December 26, more than 14 days out, in a run of 3 available nights between two bookings | `global` sets 2. The run fits 2, so `gap` changes nothing. `custom` sets 7. | 7 | | The same December 26, with `apply_gap_night_rules_to_overrides: true` | `global` sets 2. `custom` sets 7. `gap` now has priority 9 and applies last. The run does not fit 7, so `gap` lowers it to 3. | 3 | With `min_min_stay: 3`, the second date returns 3 instead of 2, because the floor applies after the `gap` rule. ## 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. --- # Dynamic Sets > Web version: https://docs.usewheelhouse.com/rm/concepts/dynamic-sets Dynamic sets are user-curated sets of comparison listings used to track competitive performance. Use these endpoints to build a set from scratch (search for candidate listings near a location, create a set from them, and upgrade it to paid), list a user's sets, inspect a set's definition and member listings, retrieve aggregated performance metrics, manage which of the user's own listings the set is associated with, and fetch a set's change history, time-series metrics, and metric distributions. `GET /sets` returns both free and paid sets; the `is_paid` field on each set indicates which. Everything involved in **building** a set works on a free one — creating it, adding and removing its member listings, reviewing them, and managing which of your own listings it is associated with. What the paid plan buys is the **set-level analytics** computed across the set, including its price calendar. A paid-only endpoint returns `404 Not Found` for a free set, which is indistinguishable from a set that does not exist, so check `is_paid` before calling one. | Endpoint | Free sets | Paid sets | |---|---|---| | `GET /sets` | ✅ | ✅ | | `POST /sets` | ✅ (creates a free set) | — | | `GET /sets/candidates` | ✅ (no set required) | ✅ | | `GET /sets/{set_id}` | ✅ | ✅ | | `POST /sets/{set_id}/upgrade` | ✅ (this is what upgrades it) | — | | `POST /sets/{set_id}/share` | ✅ | ✅ | | `GET /sets/{set_id}/listings` | ✅ | ✅ | | `PUT /sets/{set_id}/listings` | ✅ | ✅ | | `DELETE /sets/{set_id}/listings` | ✅ | ✅ | | `GET /sets/{set_id}/associated_listings` | ✅ | ✅ | | `PUT /sets/{set_id}/associated_listings` | ✅ | ✅ | | `DELETE /sets/{set_id}/associated_listings` | ✅ | ✅ | | `GET /sets/{set_id}/aggregated_metrics` | ❌ 404 | ✅ | | `GET /sets/{set_id}/price_calendar` | ❌ 404 | ✅ (up to 25 members) | | `GET /sets/{set_id}/time_series` | ❌ 404 | ✅ | | `GET /sets/{set_id}/distribution` | ❌ 404 | ✅ | | `GET /sets/{set_id}/changelog` | ❌ 404 | ✅ | Upgrade a free set with `POST /sets/{set_id}/upgrade`, which purchases the paid plan and charges the billable user. Sets the user owns as well as sets shared with the user are included throughout; modifying a shared set requires editor or manager access to it. --- # Pricing Tiers > Web version: https://docs.usewheelhouse.com/rm/concepts/pricing-tiers Each listing is on a pricing tier, which `GET /listings/{listing_id}/pricing_tier` returns as `name`. The tier sets how far ahead price recommendations reach and which features the listing can use. There are five tiers: | Tier | What it is | |---|---| | `Free` | No Pro plan. | | `Pro Flex`, `Pro Flat` | The paid Pro plans. They differ in how they are billed, not in what the API allows. | | `Pro Trial` | A trial of Pro, with the same access as the paid Pro plans. | | `Pro Onboarding` | An onboarding plan, with the same access as the paid Pro plans except that Wheelhouse does not post prices to the channel on most channels. | Every tier except `Free` counts as a **Pro listing** wherever these docs say so. ## What each tier allows | | `Free` | `Pro Flex`, `Pro Flat`, `Pro Trial` | `Pro Onboarding` | |---|---|---|---| | `GET /listings/{listing_id}/price_recommendations` | 30 days ahead by default | 545 days (18 months) ahead by default | 545 days (18 months) ahead by default | | `GET /listings/{listing_id}/price_calendar` | Today through 545 days ahead by default, up to 3 years per request | Same | Same | | `GET /listings/{listing_id}/calendar_day_history` | **402 Payment Required** | Stay dates up to 180 days back | Stay dates up to 180 days back | | Market report endpoints (`/market_report`) | **404 Not Found** for a market where you hold only `Free` listings | Available | Available | | `POST /listings/{listing_id}/sync` | **429 Too Many Requests** | No daily limit | **429 Too Many Requests** | | Automatic price posting | Not available (except on some channels) | Available, and on when `automatic_rate_posting_enabled` is `true` | Not available (except on some channels) | The `price_recommendations` horizons are defaults. Some channels give longer ones, for `Free` listings up to 180 days. On some channels, a Pro listing due to move to `Free` already gets the `Free` horizon. A custom horizon configured for a listing replaces all of these, and `GET /listings/{listing_id}/pricing_tier` reports it as `horizon`. `price_recommendations` and `price_calendar` reach different distances because they return different things. `price_recommendations` computes Wheelhouse recommendations, and the tier limits how many days it computes. `price_calendar` returns the price and availability stored for each date, so its range does not depend on the tier. The market report endpoints return **404 Not Found**, not **402**, for a market without a Pro listing, and `GET /market_report` lists only markets where you hold one. ## Dynamic sets have their own plan Dynamic sets are billed separately from listing tiers. Each set is free or paid (`is_paid`), and the set-level analytics endpoints return **404 Not Found** for a free set. See [Dynamic Sets](https://docs.usewheelhouse.com/rm/concepts/dynamic-sets.md) for the endpoints that need a paid set. --- # Changelog > Web version: https://docs.usewheelhouse.com/rm/changelog ### 2026-11-19 - Added `basis` to `GET /market_report/{market_id}/time_series`. Pass `basis=stly` to get each stay date's values as they stood around the same time last year, under this year's `stay_date` and with the same fields, so the rows of both bases can be joined on `stay_date`. It is in early access: accounts without early access get a `403`, and a market whose last year figures are not available yet returns a `404`. `basis=current`, the default, returns today's values as before. - **Behavior change:** `GET /preferences/{listing_id}/changelog` is no longer limited to the last 90 days. A request returns up to one year, ending at `end_date`, and older history is read by moving `end_date` back. A `start_date` more than 90 days ago used to be moved to 90 days ago; it now returns up to a year, so such a request can return more events than before. - **Behavior change:** `GET /preferences/{listing_id}/changelog` leaves out `Settings changed` events on the `end_date` day, like every other event type. It used to include them, so paging back with adjacent ranges returned a settings change made on the shared day twice. The default `end_date` (tomorrow) is unaffected. - Added `event` to `GET /preferences/{listing_id}/changelog` to return only some event types, e.g. `?event[]=Settings changed&event[]=Custom rates` to leave out automatic price posts. Without it, every type is returned as before. ### 2026-11-17 - Documentation fix: the `id` on a `checkin_checkout` rule pairs the check-in rule with its check-out rule. It is derived from the rule's contents and was documented as a stable identifier, which it is not: it changes when the rule changes. Requests don't use it to identify a rule (`PUT /preferences/{listing_id}` replaces `checkin_checkout` as a whole), so re-read it after a save rather than storing it. - **Behavior change:** a `checkin_checkout` rule's `id` no longer depends on the default priority the server fills in for its type, or on the key order and `null` fields it was stored with. Saving any preference used to change the `id` of a rule stored without a priority, because the save filled the priority in. A non-default priority, such as a prioritized `time_based` rule's, still counts, so that rule keeps a different `id` from the same rule at the default priority. Existing `custom`, `monthly`, `time_based` and `day_of_week` rule ids change once, on the listing's next save or read. `seasonal` and `event` rule ids are unchanged. - Documentation fix: `demand_sensitivity_rules` is shown in the Wheelhouse UI as **Local events**, under Pricing Engine rather than Model Weights, now that day of week is its own setting. The `demand_sensitivity` note category is labelled Local Events for the same reason. Field names, rule types and behavior are unchanged. - `GET /listings/kpis` can now rank listings on a calendar month, quarter or year instead of a rolling window. Pass `period` (`monthly`, `quarterly` or `yearly`) and `period_start` (the first day of the period, e.g. `2026-07-01`) in place of `window`. Add `compare=previous_year` to also return the same period one year earlier as `compare_value`, with `change` and `change_ratio`, and `rank_by=change` or `rank_by=change_ratio` to rank on the year-over-year change, e.g. to see which listings improved most on last summer. The comparison is the earlier period's final figure, not the figure as it stood at the same point last year. `basis=stly` works with `window` only. Existing `window` calls are unaffected. ### 2026-11-16 - Added `POST /feedback`, which sends feedback about the API to the Wheelhouse team: a `message`, an optional `category` (`bug`, `confusing_docs`, `missing_capability`, `praise` or `other`), and optionally the `endpoint` and `listing_id` it is about. It accepts read-only keys and is not billed. See [Feedback](https://docs.usewheelhouse.com/rm/reference/feedback.md). - Added `GET`, `PUT` and `DELETE /listings/{listing_id}/ota_links` to read and manage a listing's links to its pages on Airbnb, Vrbo and Booking.com and to its direct booking website. See [Listing OTA Links](https://docs.usewheelhouse.com/rm/reference/listing-ota-links.md). - Added `basis` to `GET /listings/{listing_id}/kpis`, `/kpis/monthly`, `/kpis/quarterly` and `/kpis/yearly`. Pass `basis=stly` to get the listing's KPIs as they stood at the same time last year instead of today's, in the same response shape. Rolling windows are measured 52 weeks earlier. Each monthly, quarterly or yearly row holds the same period a year earlier, as it stood 52 weeks ago, under the current `month`, `quarter` or `year` it compares with, so the rows of both bases can be joined on that key. `model_date`, `comp_set_count`, the comp-set metrics, `revenue_blocked`, `min_price_occurrence`, `revenue_score` and the `occupancy_neighborhood` metrics are not available for last year and are `null`. It is in early access: accounts without early access get a `403`. `basis=current`, the default, returns today's KPIs as before. - Added `basis` to `GET /listings/kpis`. Pass `basis=stly` to rank listings on their values as they stood at the same time last year, measured over the same window 52 weeks earlier, instead of today's. It is in early access: accounts without early access get a `403`. `min_price_occurrence`, `revenue_blocked`, `revenue_score` and the `occupancy_neighborhood` metrics are not available for last year and return `400`. Listings with no stats for last year are absent from the ranking. `basis=current`, the default, keeps the existing ranking. - Documentation fix: endpoints that act on one listing return `406 Not Acceptable` when the listing is inactive. Only `GET /listings/{listing_id}/neighborhood/pricing` and `/neighborhood/occupancy` documented it. It is now listed on every affected endpoint and explained in [Inactive Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md#inactive-listings). No behavior change. ### 2026-11-15 - **Fix:** `attr_seasonality` on `GET /listings/{listing_id}/price_recommendations` and `POST /preferences/{listing_id}/preview` with `attribution=true` is now a whole number, like the other `attr_*` fields. It could previously have a fractional part or be `null`. - Documentation fix: the listing returned by `GET /listings`, `GET /listings/{listing_id}`, `GET /segments/{segment_id}/listings` and `/sets/{set_id}/associated_listings` documents `meta`, which it has always returned. No behavior change. - Documentation fix: `updated_at` on `GET /market_report/{market_id}/time_series`, `GET /market_report/{market_id}/distribution`, `GET /sets/{set_id}/time_series` and `GET /sets/{set_id}/distribution` is a timestamp such as `2026-08-30 04:17:22 UTC`, as on `GET /market_report/{market_id}/bedroom_groups`, not ISO-8601. No behavior change. - Documentation fix: `POST /listings/{listing_id}/sync`, `POST /teams/memberships/{master_user_id}` and `DELETE /teams/memberships/{master_user_id}` return an empty JSON object. No behavior change. - Documentation fix: `description` on a note (`GET`, `POST` and `PUT /listings/{listing_id}/notes`) is `null` when the note has no text. Creating a note without a `description` has always been allowed, and the field has always come back `null`. The schema now marks it nullable. No behavior change. ### 2026-11-12 - Documentation fix: `currency` on `GET /listings/{listing_id}/price_calendar` and on `calendar_snapshots` in `GET /listings/{listing_id}/calendar_day_history` is `null` when no currency is recorded for the night. Both endpoints have always returned it that way. No behavior change. ### 2026-11-10 - Added `asking_rate_available`, the Asking Rate over available nights only: sum of nightly prices on available nights / number of available nights, excluding fees. Booked and blocked nights count in neither, nor do nights without a price, and it is `null` rather than `0` when no available night has a price. It is returned wherever `asking_rate` is: `GET /listings/{listing_id}/kpis` (every period in both directions), `GET /listings/kpis`, `GET /listings/{listing_id}/kpis/monthly`, `/kpis/quarterly` and `/kpis/yearly`, `GET /sets/{set_id}/aggregated_metrics` and `GET /segments/{segment_id}/aggregated_metrics`. Values fill in as each listing's stats are next regenerated. - Documentation fix: `asking_rate` averages booked and available nights, not available nights only, with each booked night at the rate it was booked for. Blocked nights are left out. Its description now says so. No behavior change. - `GET /listings/{listing_id}/reservations` takes `date_filter_type=updated_at`, which returns the reservations whose `updated_at` falls in the window from `start_date` (included) to `end_date` (excluded). With this filter type, `start_date` and `end_date` also take ISO 8601 timestamps such as `2026-09-01T00:00:00Z`, so an integration can poll for the reservations that changed since its last request instead of re-reading every reservation. - Extended `GET /listings/{listing_id}/kpis/monthly`, `/kpis/quarterly`, and `/kpis/yearly` with `asking_rate_highest` and `asking_rate_lowest` (Asking Rate (Highest) and (Lowest): the highest and lowest nightly asking price on any night in the period), matching the rolling KPIs of the same name. - `GET /listings/{listing_id}/price_recommendations` returns `events` on each day: the events in the listing's market that run over that date. It is an empty array on a date that no event covers. ### 2026-11-09 - **Fix:** `rates` on `GET /listings/{listing_id}/recent_changes` now moves when a custom rate is removed outright, through `DELETE /listings/{listing_id}/custom_rates`, `DELETE /listings/{listing_id}/bulk_custom_rates` or the Wheelhouse app. It used to move only when a rate was added, changed or split, so an integration polling it never saw a removal. A rate expiring, or its dates passing, still does not move it. - Added `market_name` to the listing returned by `GET /listings`, `GET /listings/{listing_id}`, `GET /segments/{segment_id}/listings` and `/sets/{set_id}/associated_listings`: the human-readable name of the listing's `market_id`, so it no longer takes a `GET /market_report` call to resolve. - `POST /preferences/{listing_id}/preview` documents the `attribution` query parameter. With `attribution=true`, each day carries the same `attr_*` and `historical_anchor_*` breakdown as `GET /listings/{listing_id}/price_recommendations`, so the two responses can be compared to see what a preference change does. - **Behavior change:** `POST /preferences/{listing_id}/preview` now returns each day's `min_stay`, from the listing's min stay settings with the request's changes applied. It was previously always omitted. - Extended `GET /listings/{listing_id}/kpis/monthly`, `/kpis/quarterly`, and `/kpis/yearly` with `bookings` (Bookings: reservations with at least one night in the period), matching the rolling KPI of the same name. Quarterly and yearly values add up the months, so a stay that spans months counts once in each month it touches. - Added `DELETE /segments/{segment_id}` endpoint. Deletes a portfolio segment owned by the authenticated user. A segment assigned to a team member cannot be deleted until it is unassigned. - `GET /listings/{listing_id}/price_recommendations` and `POST /preferences/{listing_id}/preview` now return `min_price` on each day: the minimum price applied to that day, in the response `currency`. It is the higher of the minimum price rule for the date and `min_min_price`, except on days with a fixed custom rate, where only `min_min_price` applies. `null` when no minimum applies. - Documentation: added [How minimum stay rules combine](https://docs.usewheelhouse.com/rm/concepts/preferences-rules.md#how-minimum-stay-rules-combine), with a worked example. A `gap` rule lowers the minimum stay that lower-priority rules set, rather than replacing it. Rule prioritization can raise `time_based` and `gap` rules above `custom` rules, and `min_min_stay` applies last. The `min_stay` on `GET /listings/{listing_id}/price_recommendations` is the final value and does not say which rule set it. No behavior change. - Documentation fix: `base_price: null` on `GET /preferences/{listing_id}`, `GET /listings` and `GET /listings/{listing_id}` means the listing's base price follows the Wheelhouse recommendation, multiplied by `base_price_adjustment`. It does not mean the listing has no base price. The base price in use is the top-level `base_price` on `GET /listings/{listing_id}/price_recommendations`, which is never `null`. `base_price_adjustment` is a multiplier (`0.9`, `1.0` or `1.1` for the presets), not a percentage. No behavior change. - Documentation: added [Pricing Tiers](https://docs.usewheelhouse.com/rm/concepts/pricing-tiers.md), which lists what each tier returned by `GET /listings/{listing_id}/pricing_tier` allows: the `price_recommendations` horizon next to the `price_calendar` range, and which endpoints return `402`, `404` or `429` for which tiers. `Pro Trial` and `Pro Onboarding` get the same 545-day `price_recommendations` horizon as the paid Pro plans. No behavior change. - Documentation: added [Keeping a local copy fresh](https://docs.usewheelhouse.com/rm/usage.md#keeping-a-local-copy-fresh), on refreshing a local copy without re-reading every endpoint: webhooks for recommendations, reservations and flags, and `GET /listings/{listing_id}/recent_changes` for preferences and custom rates. No behavior change. ### 2026-11-06 - Extended `GET /listings/{listing_id}/kpis/monthly`, `/kpis/quarterly`, and `/kpis/yearly` with `nights_calendar` (Nights (Calendar): nights in the period, irrespective of listing status), matching the rolling KPI of the same name. - Documentation fix: `POST /preferences/{listing_id}/preview` returns `201`, not `200`. It always has. - Documentation fix: a tag's `type` is `UserTag` or `ImportedTag`, not `user`. - Documentation fix: `exclude_inactive` on `GET /listings`, `GET /segments/{segment_id}/listings` and `GET /listings/kpis` also leaves out listings that are not linked to a channel. ### 2026-11-03 - `POST /listings/{listing_id}/sync` returns `503 Service Unavailable` with a `Retry-After` header while syncing with the listing's channel is paused, for example during the channel's scheduled maintenance. A refused sync does not count toward the daily limit. ### 2026-10-29 - Add `GET /price_models`, listing the price models customers can pick from, and `price_model_id` on `GET /listings/{listing_id}/price_recommendations` and `POST /preferences/{listing_id}/preview` to price with one of them, now that several can be available at once. - **Behavior change:** `price_model=opt_in` returns `400` when more than one opt-in model is available; pass `price_model_id` instead. `price_model=current` prices with the model the listing gets without a pick of its own. - Documentation fix: the `GET /market_report` description no longer says the response includes a market boundary. It does not. No behavior change. ### 2026-10-27 - Bug fix: `PUT /listings/{listing_id}/bulk_custom_rates` with an empty `custom_rates` array returns `200` with an empty `updated_custom_rates`. It previously returned `500`. - Documentation fix: `days_before` and `days_after` on a time-based calendar rule are `null` when that side of the window is unset. Preference reads have always returned them that way. No behavior change. - **Behavior change:** `GET /notification_settings` and `PUT /notification_settings` include `api_spend_alert`, the alert sent when API usage in the billing cycle passes the account's spend alert threshold. The response lists only documented event types. A setting stored under any other event name stays as it is and is left out of the response. ### 2026-10-26 - `last_minute_discount`, `far_future_premium` and `seasonality_adjustment` now take `smooth`. When `true`, the value eases between rules instead of stepping at each rule's edge. See [Smoothing](https://docs.usewheelhouse.com/rm/concepts/preferences-rules.md#smoothing). - **Behavior change:** a `day_of_week` setting of `CON` or `AGG` sent without `rules` now stores the matching preset rule. It previously stored the type with no rules and priced like `REC`. `PUT /preferences/{listing_id}/{setting}` now accepts `day_of_week`. - **Behavior change:** `PUT /preferences`, `PUT /preferences/{listing_id}` and `POST /preferences/{listing_id}/preview` now return **400** naming the field, rather than a 500, when `checkin_checkout` is missing `check_in_rules` or `check_out_rules`, or when `occupancy_pacing` has no `global` matrix or a `values` that is not one array per row with one value per column. None of these payloads could be saved before. - Sending `gap_night` for a listing with more than one unit now returns a warning with the new `reason` `not_supported_for_multi_unit`: gap night pricing does not apply to those listings, though the setting is still stored. - Documentation fix: on listings that accept length-of-stay premiums, `weekly_discount`, `monthly_discount` and `long_term_discounts` rule values are signed (`-10` is a 10% discount). An empty `check_out_rules` leaves check-out unrestricted. No behavior change. - Documentation fix: `occupancy_pacing.values` was documented as accepting a flat list; only one array per row has ever been accepted. The check-in/check-out, gap night and day-of-week descriptions now state the value formats and how overlapping rules resolve. ### 2026-10-23 - `GET /listings/{listing_id}/kpis/monthly`, `/kpis/quarterly`, and `/kpis/yearly` now return future periods through the maximum calendar horizon (1.5 years from today), where they previously stopped 12 months ahead. Monthly responses carry up to six more future months, and quarterly and yearly responses can include later quarters and years. The furthest month, quarter and year include only the nights up to the horizon, so their nights and revenue cover part of the period. Past periods and the response shape are unchanged. ### 2026-10-22 - Preferences now include `historical_anchoring_price_source`, which sets which historical price historical anchoring weighs in: `observed` (the listing's price as Wheelhouse saw it on the channel once the date booked), `posted` (the price Wheelhouse last posted for the date before it booked) or `posted_with_fallback` (the posted price where there is one, otherwise the observed price). Every preferences read returns it, and `PUT /preferences`, `PUT /preferences/{listing_id}` and `POST /preferences/{listing_id}/preview` take it. Listings that never chose a source read `observed`, which is how they have been priced so far. ### 2026-10-18 - Documentation fix: the per-day values (`sunday` through `saturday`) on custom rates are numbers, not integers, on both reads and writes. Responses can carry decimal values such as `90.25`, and the write endpoints accept them. The API's behavior is unchanged. ### 2026-10-17 - Documentation fix: an array query parameter takes more than one value only in brackets, for example `?metric[]=asking_rate_w_fees&metric[]=occupancy`. These docs previously showed the key repeated without brackets (`?metric=asking_rate_w_fees&metric=occupancy`), which keeps only the last value: `GET /preferences` returns one listing and `DELETE /sets/{set_id}/associated_listings` removes one. This applies to `listing_ids`, `dates`, `metric`, `market_ids`, and `room_types`. A single value can still be sent without brackets. The API's behavior is unchanged. ### 2026-10-16 - **Breaking:** portfolio segment `filter_backend` no longer accepts wide `listing_stats.{metric}_{window}` numeric range keys (for example `listing_stats.revenue_0_30_gte`). Performance filters use scoped keys `listing_stats_rolling:metric:{metric}:{window}` instead (for example `listing_stats_rolling:metric:revenue:next_30_gte`). `listing_stats.last_booked_at` date-range filters are unchanged. - With `attribution=true`, `GET /listings/{listing_id}/price_recommendations` now names the historical price behind each date historical anchoring raised: `historical_anchor_date`, `historical_anchor_price` (in the response `currency`), `historical_anchor_source` (`observed` or `posted`) and `historical_anchor_pct`, the anchoring percentage in effect for the date. The fields are left out on dates anchoring did not raise, and `attr_historical_anchoring` is unchanged. ### 2026-10-15 - **Behavior change:** `GET /preferences/{listing_id}/changelog` events can now have `status` `warning`, a partial success. A Streamline price post that posted some dates but was rejected for dates with no PM season set up in Streamline used to return `error`; it now returns `warning`, with the same `msg` saying which dates were rejected and how to fix them. Treat `warning` as needing the user's attention. - Bug fix: `amenities` on `GET /sets/candidates` and `GET /sets/{set_id}/listings` lists each amenity as its own array element. Since 2026-09-21 some responses returned the whole list as a single element. ### 2026-10-13 - Added `fallback` to `GET /listings/{listing_id}/fee_impact_calendar`. With `fallback=estimate`, a listing with no fee adjustment in effect gets a multiplier estimated from the fees on its recent reservations instead of `1.0`. Each entry now carries `source` (`setting`, `estimate` or `none`) saying where its multiplier came from. Without the parameter the multiplier is unchanged. - Documentation fix: `GET /listings/{listing_id}/neighborhood_pricing` prices have always included the fees guests pay on top of the nightly rate, as in the Wheelhouse pricing chart. The description now says so and how to compare a listing's nightly rate with them. No behavior change. ### 2026-10-12 - Preferences now include `historical_anchoring_mode`, which sets how a historical anchoring percentage applies. `blended`, the default and how every listing has been priced so far, averages the historical price with the recommendation. `anchor_only` takes the percentage of the historical price alone, so 50% of a $1,200 historical price sets a $600 floor, below which the recommendation is raised. Every preferences read returns it, and `PUT /preferences`, `PUT /preferences/{listing_id}` and `POST /preferences/{listing_id}/preview` take it. Existing listings stay on `blended`. ### 2026-10-09 - Added `category` to each flag returned by `GET /listings/{listing_id}/flags`: `engine`, `info`, `performance` or `settings`, saying what the flag means for the listing's pricing. It is `null` for an older flag that Wheelhouse no longer raises. New flags can be added to any category, so decide how to treat a flag from its `category` rather than from a list of flag names. ### 2026-10-06 - **Behavior change:** `GET /listings` no longer returns each listing's photo URLs (`meta.photos`) unless you ask for them with the new `include_photos=true` query parameter. `num_photos` is still returned. ### 2026-10-05 - Added `is_hidden` to the listing object returned by `GET /listings`, `GET /listings/{listing_id}`, `GET /segments/{segment_id}/listings` and the `/sets/{set_id}/associated_listings` endpoints. It is `true` for a listing that has been hidden in the Wheelhouse app. Hidden listings are still returned and ranked with `exclude_inactive=true`, so filter on `is_hidden` to leave them out. ### 2026-10-01 - **Behavior change:** a user with *restricted editor* access to a shared listing can no longer change its tags with `PUT /listings/{listing_id}/tags`, nor update it through the batch `PUT /preferences`. The Wheelhouse app refuses restricted editors tag changes and updates to several listings at once. The batch endpoint is refused however many listings a request names: the listing is reported in `errors` with status `403`, and the rest of the batch still applies. Update a single listing's preferences with `PUT /preferences/{listing_id}`, which restricted editors can still use. - **Behavior change:** `PUT /sets/{set_id}/associated_listings` now requires manage access to each shared listing, as in the Wheelhouse app. A user with *viewer* access to a shared listing could previously associate it with a set, and now gets `403`. Removing a listing from a set with `DELETE` is unchanged. - Owners, editors and managers are unaffected by either change. - Each Wheelhouse user can now hold up to 5 active RM API keys. Creating another returns an error until the user holds fewer than 5. Users already holding more keep all of them. Team members each have their own limit. The key behind MCP access is not counted. See [Direct API integrations](https://docs.usewheelhouse.com/rm/authentication.md#direct-api-integrations). - Added `owner_user_id` to `GET /listings` and `GET /listings/kpis`. It narrows either response to the listings owned by one Wheelhouse account, matching `owner_user.id` on the listing, so a team member can read or rank one team's portfolio at a time by passing a membership's `user_id` from `GET /teams/memberships`. It grants access to no listing you could not already reach, so an account whose listings you cannot access returns an empty list. ### 2026-09-24 - Documentation fix: `listing_preferences` on the listing object (`GET /listings`, `GET /listings/{listing_id}`) was documented as an unstructured object. It has always carried a summary of the listing's pricing preferences — automatic rate posting, base price and adjustment, fees, long-term discount percentages, guest counts, nickname, and the global minimum and maximum price and minimum stay where configured — and the schema now lists those fields. The schema also now marks as required the fields that are always present on the listing object (`id`, `channel`), on price calendar, last posted price and minimum stay calendar rows, and on the pricing tier, check-in/check-out, min/max price and neighborhood responses, and lists the two `custom_type` values a price recommendation can carry. No behavior or response-shape change. - Documentation fix: `name` on `GET /listings/{listing_id}/pricing_tier` listed a tier the endpoint never returns and omitted two it does. The values are `Free`, `Pro Flex`, `Pro Flat`, `Pro Trial` and `Pro Onboarding`. No behavior change. ### 2026-09-21 - **Behavior change:** `amenities` on `GET /sets/candidates` and `GET /sets/{set_id}/listings` is now an array of amenity names. It was previously a single comma-separated string. - Documentation fix: optional fields on those listing responses (including `guests_included`) have always been `null` when unknown. Custom rate responses have always returned `currency` as `null` for adjustment rates, and a weekday value as `null` when that day is unset. The schema now matches. No other response-shape change. ### 2026-09-19 - Documentation fix: several response fields have always been able to be `null` or to carry a shape the schema omitted. The schema now matches what the endpoints already return. No behavior or response-shape change. In particular: optional reservation fields (including `comments` and monetary amounts); tag `description`; `reservation_id` on the price calendar and calendar-day history (a string, the channel reservation ID); custom-rate periods, which do not include `id` or `listing_id` on read; `custom` calendar rules, which may send `day_of_week_values` instead of `value` and may include an `id`; calendar-rule `priority`, which can be fractional; and legacy `days_after` / `days_one_sided_gap` on adjacency rules. ### 2026-09-18 - Preferences now document and validate `fee_adjustments`: the estimated share of fees guests pay on top of the nightly rate (`total_fee_percentage`, `-100` or more) and whether it is refreshed weekly from the listing's recent reservations (`auto_update`). Every preferences read returns it, `null` when nothing is configured, and `PUT /preferences` and `PUT /preferences/{listing_id}` take it. The object replaces the stored one as a whole, and `null` clears it. **Behavior change:** the object was previously stored as sent, without validation; a `fee_adjustments` that is not an object, or a `total_fee_percentage` below `-100`, is now rejected with **400**. `GET /listings/{listing_id}/fee_impact_calendar` continues to report the setting as a multiplier. ### 2026-09-17 - Documentation fix: `custom_type` on `GET /listings/{listing_id}/price_recommendations` and the preferences preview response has always been `null` when the night is a Wheelhouse recommendation, not an empty string. The schema now marks the field nullable and the description matches. No behavior or response-shape change. ### 2026-09-01 - The `bedrooms` parameter on `GET /market_report/{market_id}/time_series` and `/distribution` no longer takes a fixed set of five groups. Which bedroom groups a market is broken down by is derived from the listings in it, so a market with many larger listings is broken down further (`0`, `1`, `2`, `3`, `4`, `5`, `6+`) than one without them (`0`, `1`, `2+`). Read a market's groups from the new `GET /market_report/{market_id}/bedroom_groups`, which also reports how many listings sit behind each one. A group the market has no data for is rejected with **400**, and the error names the groups it does have. Existing calls keep working where the market is broken down past the group they name: `bedrooms=4+` is answered from the 4 bedroom group in a market broken down into `4`, `5` and `6+`. ### 2026-08-27 - **Breaking:** the `geometry` fields have been removed from the `GET /market_report` response — both the market's own `geometry` (the polygons describing its boundary) and the per-entry `geometry` under `postal_codes` (each postal code's boundary). Anything drawing market or postal code outlines from this endpoint will find both absent; the rest of the response is unchanged, `postal_codes[].latlong` included, so a centroid is still available per postal code. Set boundaries are unaffected — `boundary` on the dynamic set endpoints still returns MultiPolygon coordinates. ### 2026-08-18 - Extended `GET /listings/{listing_id}/kpis/monthly`, `/kpis/quarterly`, and `/kpis/yearly` with `nights_percent_open` (Nights (Bookable %): bookable nights / calendar nights). ### 2026-08-14 - Documented installing the [Wheelhouse Plugin](https://docs.usewheelhouse.com/rm/wheelhouse-plugin.md) from `https://github.com/pricemethod/wheelhouse-plugin` for Claude Code, Codex, and Cursor. - `GET /sets` now takes `name` and `kind` filters, so an account with many sets can find one without paging through the whole list. `name` is a case-insensitive pattern in which `*` stands for any run of characters — `*Palm Springs*` matches the phrase anywhere in the name, and a value without a `*` has to match the name in full. `kind` takes one value or several comma-separated, and `kind=other` also matches sets that carry no kind, which is what those sets already report. Sending both filters returns the sets matching each of them, and either combines with the existing pagination parameters. - Documentation fix: `GET /preferences/{listing_id}/changelog` was titled as the changelog for a listing's *preferences*, which undersold it — it has always returned every change recorded against the listing, including prices posted, failed posts and calendar syncs, custom rates added, split or removed, a change of pricing engine, and reservations imported. The title now says so, the description lists what is covered, and `GET /listings/{listing_id}/custom_rates` now points here for custom rate history rather than leaving it to be inferred that it carries none. No behavior or response-shape change. ### 2026-08-11 - **Behavior change:** preference settings the listing's channel cannot act on are no longer stored. Previously a setting the channel had no support for was accepted, saved and logged to the changelog — so the write looked successful and the changelog confirmed it, but the value was never posted to the channel. Such settings are now discarded instead, matching what the Wheelhouse app has always done. The rest of the request still applies and the response is still a success. - Preference write responses now carry `warnings`, naming each setting that was not applied, why (`not_supported_by_channel`, or `partially_supported_by_channel` when only part of it was too narrow for the channel), and the attributes it covered. The array is present and empty when everything applied, so it can be read unconditionally. Applies to `PUT /preferences`, `PUT /preferences/{listing_id}`, `PUT /preferences/{listing_id}/copy` and `POST /preferences/{listing_id}/preview`. - Listings and preferences now report `supported_settings` — whether `checkin_checkout`, minimum stays and long-term discounts can be set, and which form of long-term discount the channel takes. Check it before sending a setting rather than after. It reflects per-account early access, so two listings on the same channel can differ. See the [Listing Preferences](https://docs.usewheelhouse.com/rm/concepts/preferences.md) section. ### 2026-08-10 - Every response now carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`, and a **429** additionally carries `Retry-After`. Your current standing arrives with work you were already doing, so pacing an integration no longer costs a request — and the 429 itself now tells you when to retry. See [Rate Limits](https://docs.usewheelhouse.com/rm/usage.md#rate-limits). - Added `GET /usage`, so an integration can inspect its own API usage rather than reading the audit log in the Wheelhouse app. It reports request volumes, error rates (including 429s) and response times across every RM API key on the account, broken down by day, by endpoint and by key, over a window of up to 7 days. Endpoint breakdowns are grouped by route pattern rather than exact path, so all calls to `GET /listings/{listing_id}/notes` count as one entry. Results are cached for a few minutes — see `generated_at` — and a window too busy to read in full is reported as `window.truncated` with the shorter window it actually covers. ### 2026-08-07 - Extended `GET /listings/{listing_id}/kpis/monthly`, `/kpis/quarterly`, and `/kpis/yearly` with additional metrics already persisted on the periodic stats tables: `adr_fees`, `asking_rate`, `nights_available`, `nights_blocked`, `nights_bookable`, `nights_booked`, `revenue_available`, `revenue_blocked`, `revenue_fees`, and `revenue_fees_taxes`. Names match the rolling KPI lexicon. ### 2026-08-06 - Added `GET /sets/{set_id}/price_calendar`, the API equivalent of the set calendar in the app. `booking_probability_percent` is bounded to 10–90 for unavailable nights, mirroring the app, which renders those extremes as `<10%` and `>90%` rather than asserting certainty about a listing it only scrapes; an available night reports `0`. The rest: a night-by-night calendar for each active member listing of a set, with prices converted to one currency so comps priced differently are comparable. **Paid sets only**, and only for sets with at most 25 member listings; a larger set responds with `422`. Both limits track where the data comes from: Wheelhouse requests the detailed per-night scraping that backs this endpoint only for paid sets at or under that size, so beyond it there would be little to return. The night object follows `GET /listings/{listing_id}/price_calendar` except that it carries no `is_booked` flag and no `reservation_id`, neither of which applies to a listing that is not yours. In their place, `booking_probability_percent` reports Wheelhouse's assessment that a night is booked rather than merely held, as a whole percentage. - Added `PUT` and `DELETE /sets/{set_id}/listings`, which add and remove a set's **member listings** — the comparison listings the set is built from. Previously members could only be chosen when the set was created with `POST /sets`, with no way to adjust them afterwards, so a set could not be refined once built. Identify listings by the internal `listing_id` values from `GET /sets/candidates`; only eligible comparison candidates can be added, the same restriction `POST /sets` applies. Both return the set's members grouped by status, matching `GET /sets/{set_id}/listings`, and both work on free and paid sets. Not to be confused with the associated_listings endpoints, which manage which of *your own* listings the set is compared against. - **Fix:** `GET /sets/{set_id}/listings` and `GET`, `PUT`, `DELETE /sets/{set_id}/associated_listings` returned `404 Not Found` ("Dynamic set not found") for a **free** set. Building a set was therefore impossible before paying for it: you could not review which listings were in it, nor associate it with one of your own listings. All four now work on free and paid sets alike. The per-listing metrics returned by `/listings` were already available ungated through `GET /sets/candidates`, which returns the same object. The paid gate stays on the set-level analytics — aggregated_metrics, time_series, distribution and changelog. - Added `canceled_at` to the reservation object returned by `GET /listings/{listing_id}/reservations`. It carries the timestamp a reservation was cancelled, or `null` if it stands, and is set whenever `status` is `Canceled` — previously the status told you a reservation had been cancelled but not when. Note the single-l spelling, which matches the `Canceled` status value rather than the `cancelled` field of the `PUT` request body. ### 2026-08-05 - **Fix:** `GET /segments/{segment_id}/listings` and `GET /segments/{segment_id}/aggregated_metrics` evaluated a segment's filter only against listings the user **owns**, so a user whose portfolio is entirely made up of listings shared with them to manage got an empty result from every segment. Both endpoints now match owned and managed listings, consistent with `GET /listings`, and both accept `include_managed_listings` to control it (default true for RM API keys, false for channel integration keys). - Listings can now be identified by their **Wheelhouse listing ID** as well as by the channel's own listing ID. Pass `channel=wheelhouse` and `listing_id` is read as a Wheelhouse ID (the `wheelhouse_id` field of `GET /listings`, also returned as `listing_id` by `GET /listings/kpis`) rather than as a channel listing ID. Wheelhouse IDs are unique across channels, so no channel needs naming alongside them. This works everywhere a listing is identified, including the batched `listing_ids` parameters and `copy_preferences_from`. Under `channel=wheelhouse` a listing you cannot access returns **404**, not 403, so the sequential ID space cannot be walked to discover other accounts' listings; the channel-listing-ID form keeps its existing 403. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). Existing calls are unaffected — omitting `channel=wheelhouse` keeps the channel listing ID behavior. ### 2026-08-04 - Added the Webhooks endpoints: `GET /webhook_events`, `GET /webhooks`, `POST /webhooks`, `GET /webhooks/{id}`, `PUT /webhooks/{id}`, `DELETE /webhooks/{id}`, `POST /webhooks/{id}/rotate_secret`, and `GET /webhooks/{id}/deliveries`. Register an HTTPS endpoint to be notified when price recommendations change (`recommendations.updated`), when new reservations are ingested (`reservations.ingested`), or when new listing flags are detected (`flags.detected`), instead of polling for changes. Deliveries are batched over a five-minute window, name the affected `listing_ids` rather than carrying the changed values, and are signed with a per-subscription HMAC-SHA256 `Wh-Signature` header. See the [Webhooks](https://docs.usewheelhouse.com/rm/reference/webhooks.md) section for verification and retry semantics. ### 2026-08-03 - Added `GET /listings/kpis`, which returns one rolling-window KPI for every listing the authenticated user can access, ranked by value and paginated. It answers portfolio-wide questions — best and worst performers on a metric — in one call rather than one per listing. Choose the metric and window with `metric` and `window`; pass `currency` to convert monetary metrics before ranking so that portfolios spanning currencies order correctly. Each row carries `listing_id` (Wheelhouse's id), `partner_listing_id` (the channel's), `value`, `currency`, and `updated_at`. Comp-set metrics are not covered yet. ### 2026-07-31 - Documentation fix: `GET /listings/{listing_id}/kpis/monthly`, `/kpis/quarterly`, and `/kpis/yearly` were described as returning only history. They have always returned **future periods as well** — monthly spans up to 15 months back and up to 12 months forward, quarterly and yearly likewise extend up to 12 months ahead. The word "historical" has been dropped from their titles and each endpoint now documents its full window, with a note that current and future periods reflect bookings on the books plus asking rates for open nights and will therefore change as bookings come in. No behavior or response-shape change. - **Behavior change:** `include_managed_listings` on `GET /listings` now defaults to **true**. `GET /listings` returns every listing the authenticated user can access — owned listings plus listings shared with them to manage — where it previously returned owned listings only unless the parameter was passed explicitly. Pass `include_managed_listings=false` to keep the previous behavior. Use each listing's `access_level` and `owner_user` to tell the two apart. - Added `owner_user` to the listing response. It identifies the Wheelhouse account a listing belongs to (`id`, `email`, `first_name`, `last_name`), which makes it possible to tell whose portfolio each listing sits in when a response mixes owned and managed listings — for example `GET /listings?include_managed_listings=true`. Note that neither `owner_name` (the property owner name supplied by the channel) nor `source_user_id` (the host ID in the channel's own namespace) identifies a Wheelhouse account; their descriptions have been clarified accordingly. ### 2026-07-10 - Extended `GET /listings/{listing_id}/kpis` to cover the full [Wheelhouse metrics lexicon](https://www.usewheelhouse.com/research-metrics), now served from a dedicated rolling-stats store. New metrics: `adr_fees`, `asking_rate_fees`, `nights_bookable`, `nights_booked`, `nights_calendar`, `nights_percent_open`, `pickup_bookings`, `revenue_fees`, `revenue_fees_taxes`, `last_booked_days`, `lead_time`, `length_of_stay`. `nights_available`, `nights_blocked`, `revenue_available`, `revenue_blocked`, and `min_price_occurrence` now also return backward-looking (`N_0`) periods; `asking_rate_lowest` and `asking_rate_highest` now return all periods in both directions; `pickup` now covers all backward-looking periods (7/14/21/30/60/90/180/365). **Breaking:** `revenue_score` is now keyed by cumulative forward-looking periods (`0_7` … `0_365`) instead of the non-overlapping `0_30`/`31_60`/`61_90` windows; the scalar `last_booked_at` field has been removed in favor of the `last_booked_days` metric; and each metric field is `null` until rolling stats have been generated for the listing. ### 2026-07-08 - Renamed the performance metrics returned by `GET /sets/candidates` and `GET /sets/{set_id}/listings` to the public [Wheelhouse metrics](https://www.usewheelhouse.com/research-metrics) lexicon, matching the other RM API KPI endpoints: `anr` → `adr`, `apr` → `asking_rate`, `nrevenue` → `revenue`, `nrevpar` → `revpar`, `nrevpar_open` → `revpar_adjusted`, `open_occupancy` → `occupancy_adjusted`, `openness` → `nights_percent_open`, `los` → `length_of_stay`, and `*_nights` → `nights_*` (each keeps its `_365_0`/`_90_0` period suffix). ### 2026-07-07 - Added dynamic-set creation endpoints: `GET /sets/candidates` (search market listings with metrics near a location to build a set from), `POST /sets` (create a free set from selected listings), and `POST /sets/{set_id}/upgrade` (purchase the paid Dynamic Sets plan for a set to unlock its KPI endpoints). `GET /sets` and `GET /sets/{set_id}` now also return **free** sets, each carrying an `is_paid` flag. - Added `GET /segments/{segment_id}/aggregated_metrics` endpoint. Returns monthly performance metrics aggregated across the listings matched by a segment's filter, mirroring `GET /sets/{set_id}/aggregated_metrics`. Monetary values default to the currency of the segment's most common market. ### 2026-07-03 - Added `GET /notification_settings` and `PUT /notification_settings` endpoints. Users can now read which alerts they receive and enable or disable individual alert `event`/`channel` (in-app or email) settings via the API. ### 2026-07-02 - Added the Team endpoints: `GET /teams/members`, `POST /teams/members/invite`, `DELETE /teams/members/{sub_user_id}`, `POST /teams/members/{sub_user_id}/auto_managed_listing_level`, `POST /teams/members/{sub_user_id}/assigned_segments`, `POST /teams/members/{sub_user_id}/refresh_auto_managed_listings`, `GET /teams/memberships`, `POST /teams/memberships/{master_user_id}`, and `DELETE /teams/memberships/{master_user_id}` to manage team members and memberships. ### 2026-06-30 - Added `POST /segments` endpoint. Creates a new portfolio segment owned by the authenticated user. Accepts `filter_backend` to define the listing filter criteria. - Added `PUT /segments/{segment_id}` endpoint. Updates the name, description, `filter_backend`, and/or default status of an existing segment. ### 2026-06-29 - Added `POST /listings/{listing_id}/sync` endpoint. Triggers a manual sync that pushes the latest Wheelhouse price recommendations to the connected channel and refreshes reservation data — equivalent to the Sync button in the UI. Available on paid plans only; subject to a per-day rate limit and a 60-second debounce. ### 2026-06-26 - Added `GET /listings/{listing_id}/base_price_history` endpoint. Returns a daily log of Wheelhouse base price recommendations and effective base prices for a listing over the last 30 days (or a custom date range). - Added `GET /listings/{listing_id}/calendar_day_history` endpoint. Returns the history of price postings and calendar state snapshots for a specific stay date. Requires the Historical Price Changes feature on the listing's plan. ### 2026-06-24 - Extended `GET /listings/{listing_id}/kpis` with additional metrics: `revenue_available`, `revenue_blocked`, `min_price_occurrence`, `occupancy_neighborhood`, `occupancy_neighborhood_pp`, `occupancy_neighborhood_ratio`, `occupancy_neighborhood_adjusted`, `occupancy_neighborhood_adjusted_pp`, `occupancy_neighborhood_adjusted_ratio` (all forward-only, periods 7/14/21/30/60/90/180/365); `comp_set_occupancy`, `comp_set_occupancy_adjusted`, `comp_set_revenue` (forward-only, periods 7/30/60); `pickup` (backward-only, periods 7/14/30); `asking_rate_lowest` and `asking_rate_highest` (backward-only, period 365); `revenue_score` (non-overlapping windows 0–30, 31–60, 61–90 days); and scalar `comp_set_count`. ### 2026-06-23 - Added `GET /listings/{listing_id}/custom_rates` endpoint. Returns all active and upcoming custom rate periods for a listing, excluding expired ones. ### 2026-06-18 - Split `GET /listings/{listing_id}/kpis` into four dedicated endpoints: `GET /listings/{listing_id}/kpis` (rolling-window metrics — bidirectional periods 7/14/21/30/60/90/180/365), `GET /listings/{listing_id}/kpis/monthly` (up to 15 months back incl. default dynamic-set metrics), `GET /listings/{listing_id}/kpis/quarterly` (up to 5 recent quarters), and `GET /listings/{listing_id}/kpis/yearly` (up to 5 years). Each response includes `currency`. The old `days` parameter is no longer accepted. ### 2026-06-17 - Added `GET /notifications` and `POST /notifications/dismiss` endpoints. Users can now list their active in-app notifications and dismiss specific ones by ID via the API. - Added optional `expires_at` field to `PUT /listings/{listing_id}/custom_rates` and `PUT /listings/{listing_id}/bulk_custom_rates`. Custom rates can now be set with an expiry timestamp after which they are no longer applied. - Added `GET /listings/{listing_id}/fee_impact_calendar` endpoint. Returns a per-date fee multiplier derived from the listing's estimated fee setting. Multiply any nightly price by the multiplier to get the fee-inclusive price. - Added `GET /listings/{listing_id}/min_stay_calendar` endpoint. Returns the per-date minimum stay derived from the listing's minimum stay rules for a given date range. ### 2026-06-10 - Added the Notes endpoints: `GET /listings/{listing_id}/notes`, `POST /listings/{listing_id}/notes`, `PUT /listings/{listing_id}/notes/{note_id}`, and `DELETE /listings/{listing_id}/notes/{note_id}` to manage the notes of a listing. - Added the Dynamic Sets endpoints: `GET /sets`, `GET /sets/{set_id}`, `GET /sets/{set_id}/aggregated_metrics`, `GET /sets/{set_id}/listings`, `GET /sets/{set_id}/associated_listings`, `PUT /sets/{set_id}/associated_listings`, `DELETE /sets/{set_id}/associated_listings`, `GET /sets/{set_id}/changelog`, `GET /sets/{set_id}/time_series`, and `GET /sets/{set_id}/distribution`. RM API users can access their paid dynamic sets. - Added `GET /listings/{listing_id}/neighborhood/pricing` endpoint to fetch daily neighborhood price data (median, p25, p75, listing count) for the listing's local cluster. - Added `GET /listings/{listing_id}/neighborhood/occupancy` endpoint to fetch daily neighborhood occupancy and booking model data for the listing's local cluster. ### 2026-06-09 - Added `GET /listings/{listing_id}/last_posted_prices` endpoint. Returns the last price posted to the channel per stay date. For available nights this is the most recently posted price; for booked nights it is the last price posted at or before the time the booking was recorded. - Added `GET /market_report`, `GET /market_report/{market_id}/time_series`, and `GET /market_report/{market_id}/distribution` endpoints. RM API users can access market-level data for markets in which they have listings. ### 2026-04-20 - All **PUT** endpoints now return **409 Conflict** when a concurrent request for the same resource is already in progress. Retry the request after the concurrent request completes. - Added `GET /listings/{listing_id}/price_calendar` endpoint to fetch the price calendar for a single listing. ### 2026-04-16 - Documented **403 Forbidden** for read-only RM API keys on **PUT** and **DELETE** operations. ### 2026-04-08 - Extension of `GET /listings/{listing_id}/base_price_recommendation` endpoint to include attribution breakdown. ### 2026-03-09 - Initial release of the Wheelhouse Revenue Management API. - Endpoints: `GET /listings`, `GET /listings/{listing_id}`, `GET /listings/{listing_id}/pricing_tier`, `GET /listings/{listing_id}/recent_changes`, `GET /listings/{listing_id}/kpis`. - Endpoints: `GET /listings/{listing_id}/price_recommendations`, `GET /listings/{listing_id}/base_price_recommendation`, `GET /listings/{listing_id}/checkin_checkout`, `GET /listings/{listing_id}/min_max_prices`, `GET /listings/{listing_id}/monthly_seasonality`. - Endpoints: `GET /preferences`, `PUT /preferences`, `GET /preferences/{listing_id}`, `PUT /preferences/{listing_id}`, `PUT /preferences/{listing_id}/copy`, `PUT /preferences/{listing_id}/{setting}`, `GET /preferences/{listing_id}/long_term_discounts`, `GET /preferences/{listing_id}/changelog`, `POST /preferences/{listing_id}/preview`. - Endpoints: `PUT /listings/{listing_id}/custom_rates`, `DELETE /listings/{listing_id}/custom_rates`, `PUT /listings/{listing_id}/bulk_custom_rates`, `DELETE /listings/{listing_id}/bulk_custom_rates`. - Endpoints: `GET /listings/{listing_id}/reservations` (with `date_filter_type` parameter). - Endpoints: `GET /listings/{listing_id}/tags`, `PUT /listings/{listing_id}/tags`, `GET /listings/{listing_id}/flags`. - Endpoints: `GET /segments`, `GET /segments/{segment_id}/listings`. --- # Wheelhouse Revenue Management API > Version v1.0 (beta). Web version: https://docs.usewheelhouse.com/rm/reference/wheelhouse-revenue-management-api · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml ## Overview The Wheelhouse Revenue Management API provides direct access to price recommendations, listing preferences, custom rates, reservations, and portfolio management for Revenue Management integrations. ## Beta Status This API is currently in beta. The interface and response formats may change in future versions. ## Authentication ### MCP and AI agents When using this API through the Wheelhouse MCP server, authenticate with **OAuth** (WorkOS AuthKit). Sign in with your Wheelhouse account through your MCP client's OAuth flow — the same credentials you use in the Wheelhouse app. Do **not** send an RM API key yourself. The MCP server validates your OAuth token, resolves your user-specific RM API key, and attaches it as `X-Integration-Api-Key` on every upstream request. Your OAuth token is never forwarded to the RM API. ### Direct API integrations For HTTP integrations that call the RM API directly, send an RM API key in the `X-Integration-Api-Key` header. You can generate this in your Wheelhouse account under "Api Key". Each Wheelhouse user can hold up to 5 active RM API keys, and can create one only while holding fewer. A user who already held more before the limit keeps those keys. The key behind MCP access does not count toward the limit. The RM API key is a single key that authenticates both the integration and user context — no separate user key is required. ### Read-only API keys Keys configured as read-only may use the HTTP methods `GET`, `HEAD`, `OPTIONS`, and `POST` only. **PUT** and **DELETE** requests return **403 Forbidden** with a message that the API key is read-only (other disallowed methods do as well). `POST` endpoints that create or modify data (such as creating a note) also return **403 Forbidden** for read-only keys; only non-mutating `POST` endpoints (such as previews) are allowed, plus `POST /feedback`, which changes nothing about your account. ## Pagination List endpoints that return large result sets support pagination via the `page`, `per_page`, and `offset` query parameters. `per_page` controls how many items are returned per page (up to 100). Use `page` (1-based) or `offset` (0-based item skip count) to advance through the result set — do not use both in the same request. Iterate by incrementing `page` until a response returns fewer items than `per_page`. ## Rate Limits RM API keys are rate-limited to **60 requests per minute** by default. Exceeding this limit returns **429 Too Many Requests**. The limit resets on a rolling one-minute window. **Every response tells you where you stand**, so you never have to guess or spend a request finding out: | Header | Meaning | |---|---| | `X-RateLimit-Limit` | Requests allowed per window for the key you used. | | `X-RateLimit-Remaining` | Requests still available in the current window. Never negative. | | `X-RateLimit-Reset` | Unix timestamp (seconds) when the window frees up. | The request carrying the headers is itself counted, so an idle key's first response reports one fewer than the limit. A **429** carries the same three headers plus **`Retry-After`**, the number of seconds to wait. Prefer `Retry-After` over your own backoff schedule when it is present — it is the actual reset, not an estimate. If you receive a 429 and no `Retry-After`, wait before retrying. The recommended strategy is **exponential backoff**: after the first failure wait 1 second, then double the delay on each subsequent retry (2 s, 4 s, 8 s, …), up to a reasonable maximum (e.g. 60 seconds). Adding a small random jitter (±10–20% of the wait time) prevents multiple concurrent clients from retrying in lockstep. If your integration regularly reaches the limit, consider batching requests (e.g. using `GET /preferences` or `PUT /preferences` for multiple listings at once) or contact Wheelhouse to discuss a higher limit. ### Keeping a local copy fresh An integration that re-reads every endpoint for every listing on a schedule spends most of its rate limit on data that has not changed. Find out what changed first, and re-read only that. **Use webhooks for recommendations, reservations and flags.** Subscribe to `recommendations.updated`, `reservations.ingested` and `flags.detected` (see [Webhooks](https://docs.usewheelhouse.com/rm/reference/webhooks.md)). Each delivery names the listings to re-read. `reservations.ingested` and `flags.detected` send nothing for a listing where nothing changed. `recommendations.updated` names every active listing in a market after its nightly pricing run, including listings whose numbers did not move. For a listing that `reservations.ingested` names, `GET /listings/{listing_id}/reservations` with `date_filter_type=updated_at` returns only the reservations that changed since your last read. **Poll `GET /listings/{listing_id}/recent_changes` for preferences and custom rates.** No webhook covers these. The endpoint returns two timestamps: - `settings`: when the listing's preferences last changed. - `rates`: when a custom rate on the listing was last added, changed, split or removed. Store both, and on each poll re-read only what moved: ``` for each listing: changes = GET /listings/{listing_id}/recent_changes if changes.settings != stored.settings: GET /preferences/{listing_id} if changes.rates != stored.rates: GET /listings/{listing_id}/custom_rates stored = changes ``` For a listing where nothing changed, this costs one request instead of two. Plan around these gaps in webhooks and `recent_changes`: - `rates` does not move when a custom rate expires (its `expires_at` passes) or its dates pass and `GET /listings/{listing_id}/custom_rates` stops returning it. Nothing is written when that happens, and such a rate no longer affects any future price. If your local copy should drop it at that point, filter on `expires_at` and `end_date` yourself. - `flags.detected` does not fire when a flag is cleared. To see cleared flags, re-read `GET /listings/{listing_id}/flags` on your own schedule. - `recent_changes` does not report reservations or the price calendar. Reservations are covered by `reservations.ingested`. Neither webhooks nor `recent_changes` report price calendar changes, so re-read `GET /listings/{listing_id}/price_calendar` on your own schedule. - `recent_changes` costs one request per listing. `GET /preferences` reads the preferences of several listings in one request, which can cost less than one `recent_changes` call per listing. ## Identifying Listings Most endpoints require a `listing_id` and `channel` path or query parameter to identify the listing a request is being made for. There are two ways to fill them in, and both values come from the `GET /listings` endpoint ([see Listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md)). **By channel listing ID (default).** A channel's listing IDs are only unique within that channel, so `channel` is what disambiguates them: - **`listing_id`** — the `id` field from the listing object. - **`channel`** — the `channel` field from the same listing object. **By Wheelhouse listing ID.** Pass the literal value `wheelhouse` as `channel`, and `listing_id` is read as a Wheelhouse listing ID: - **`listing_id`** — the `wheelhouse_id` field from the listing object. - **`channel`** — the literal string `wheelhouse`. Wheelhouse listing IDs are unique across all channels, so no channel has to be named alongside them. This is the more convenient form when you already hold Wheelhouse IDs — for example from `GET /listings/kpis`, which returns them as `listing_id`, or from a Wheelhouse listing URL. Note that the two ID spaces are distinct: passing a Wheelhouse ID without `channel=wheelhouse`, or a channel listing ID with it, returns **404 Not Found**. Either form works anywhere a listing is identified, including the batched `listing_ids` parameters on `GET /preferences`, `PUT /sets/{set_id}/associated_listings`, and `DELETE /sets/{set_id}/associated_listings`, and the `copy_preferences_from` object on `PUT /preferences/{listing_id}/copy` (whose nested `channel` is resolved independently of the top-level one, so the source and target listing may each be identified their own way). Which form you use does not change what you can reach: a Wheelhouse listing ID grants no access to a listing that a channel listing ID would not. It does change how an unreachable listing is reported. Because Wheelhouse IDs are sequential and span every account, a listing you cannot access returns **404 Not Found** under `channel=wheelhouse` — the same response as an ID that matches nothing — so that the ID space cannot be walked to discover other accounts' listings. Under a channel listing ID, a listing you cannot access still returns **403 Forbidden**. Listings shared with you to manage are reachable under both forms. A typical flow is to call `GET /listings` once to build a local map of your listings, then use the `id` and `channel` values from that map — or each listing's `wheelhouse_id` with `channel=wheelhouse` — for all subsequent listing-specific calls. ## Inactive Listings A listing is inactive when Wheelhouse no longer syncs it: for example, its channel stopped returning it, or its channel account was disconnected. The listing object reports this as `is_active: false`. `GET /listings` leaves inactive listings out by default; pass `exclude_inactive=false` to include them. Endpoints that act on one listing return **406 Not Acceptable** for an inactive listing: ```json {"error": "Listing '12345' is inactive"} ``` This applies to reads as well as writes, including `GET /listings/{listing_id}/price_calendar`, `GET /listings/{listing_id}/last_posted_prices` and `GET /preferences/{listing_id}`. Retrying does not help. The listing becomes active again only if a later sync finds it on its channel, so skip it until then. `PUT /preferences` does not fail the whole request for an inactive listing. It reports that listing in `errors` with code `406` and applies the rest of the batch. Under `channel=wheelhouse`, a listing you cannot access returns **404 Not Found** even when it is inactive (see [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md)). ## Multi-Unit Listings Some listings represent a single bookable property that has multiple independently bookable units underneath it — for example, a building with several apartments, or a property with a main house and a guest cottage managed as one listing. These are called **multi-unit listings**. You can identify a multi-unit listing by the `number_of_active_units` field on the listing object (returned by `GET /listings` and `GET /listings/{listing_id}`). A non-null value indicates a multi-unit listing; `null` indicates a standard single-unit listing. For endpoints that return per-date data (such as `GET /listings/{listing_id}/price_calendar` and `GET /listings/{listing_id}/last_posted_prices`), multi-unit listings return **one row per unit per date**. Each row includes a `unit_number` field (a positive integer starting at `1`) that identifies which unit the row belongs to. Single-unit listings always return `unit_number: 0`. When processing calendar data for a multi-unit listing, group rows by `unit_number` to get the per-unit availability and pricing. Preferences and settings (fetched via `GET /preferences/{listing_id}`) apply at the listing level and are shared across all units. ## Pricing Tiers Each listing is on a pricing tier, which `GET /listings/{listing_id}/pricing_tier` returns as `name`. The tier sets how far ahead price recommendations reach and which features the listing can use. There are five tiers: | Tier | What it is | |---|---| | `Free` | No Pro plan. | | `Pro Flex`, `Pro Flat` | The paid Pro plans. They differ in how they are billed, not in what the API allows. | | `Pro Trial` | A trial of Pro, with the same access as the paid Pro plans. | | `Pro Onboarding` | An onboarding plan, with the same access as the paid Pro plans except that Wheelhouse does not post prices to the channel on most channels. | Every tier except `Free` counts as a **Pro listing** wherever these docs say so. | | `Free` | `Pro Flex`, `Pro Flat`, `Pro Trial` | `Pro Onboarding` | |---|---|---|---| | `GET /listings/{listing_id}/price_recommendations` | 30 days ahead by default | 545 days (18 months) ahead by default | 545 days (18 months) ahead by default | | `GET /listings/{listing_id}/price_calendar` | Today through 545 days ahead by default, up to 3 years per request | Same | Same | | `GET /listings/{listing_id}/calendar_day_history` | **402 Payment Required** | Stay dates up to 180 days back | Stay dates up to 180 days back | | Market report endpoints (`/market_report`) | **404 Not Found** for a market where you hold only `Free` listings | Available | Available | | `POST /listings/{listing_id}/sync` | **429 Too Many Requests** | No daily limit | **429 Too Many Requests** | | Automatic price posting | Not available (except on some channels) | Available, and on when `automatic_rate_posting_enabled` is `true` | Not available (except on some channels) | The `price_recommendations` horizons are defaults. Some channels give longer ones, for `Free` listings up to 180 days. On some channels, a Pro listing due to move to `Free` already gets the `Free` horizon. A custom horizon configured for a listing replaces all of these, and `GET /listings/{listing_id}/pricing_tier` reports it as `horizon`. `price_recommendations` and `price_calendar` reach different distances because they return different things. `price_recommendations` computes Wheelhouse recommendations, and the tier limits how many days it computes. `price_calendar` returns the price and availability stored for each date, so its range does not depend on the tier. The market report endpoints return **404 Not Found**, not **402**, for a market without a Pro listing, and `GET /market_report` lists only markets where you hold one. Dynamic sets have their own plan, separate from listing tiers. Each set is free or paid (`is_paid`), and the set-level analytics endpoints return **404 Not Found** for a free set. See [Dynamic Sets](https://docs.usewheelhouse.com/rm/reference/dynamic-sets.md) for the endpoints that need a paid set. ## Endpoints by tag - [Listings](https://docs.usewheelhouse.com/rm/reference/listings.md) - [Recommendations](https://docs.usewheelhouse.com/rm/reference/recommendations.md) - [Listing Preferences](https://docs.usewheelhouse.com/rm/reference/listing-preferences.md) - [Custom Rates](https://docs.usewheelhouse.com/rm/reference/custom-rates.md) - [Reservations](https://docs.usewheelhouse.com/rm/reference/reservations.md) - [Listing Tags](https://docs.usewheelhouse.com/rm/reference/listing-tags.md) - [Listing OTA Links](https://docs.usewheelhouse.com/rm/reference/listing-ota-links.md) - [Listing Flags](https://docs.usewheelhouse.com/rm/reference/listing-flags.md) - [Notes](https://docs.usewheelhouse.com/rm/reference/notes.md) - [Calendar](https://docs.usewheelhouse.com/rm/reference/calendar.md) - [Segments](https://docs.usewheelhouse.com/rm/reference/segments.md) - [Market Reports](https://docs.usewheelhouse.com/rm/reference/market-reports.md) - [Neighborhood Data](https://docs.usewheelhouse.com/rm/reference/neighborhood-data.md) - [Dynamic Sets](https://docs.usewheelhouse.com/rm/reference/dynamic-sets.md) - [Notifications](https://docs.usewheelhouse.com/rm/reference/notifications.md) - [Teams](https://docs.usewheelhouse.com/rm/reference/teams.md) - [Webhooks](https://docs.usewheelhouse.com/rm/reference/webhooks.md) - [Usage](https://docs.usewheelhouse.com/rm/reference/usage.md) - [Feedback](https://docs.usewheelhouse.com/rm/reference/feedback.md) --- # Listings > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/listings · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml Read listing data and metadata. The RM API provides read-only access to listings. ## Endpoints - [GET /listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md): Retrieve all listings for the authenticated user. - [GET /listings/kpis](https://docs.usewheelhouse.com/rm/reference/rm-get-bulk-listing-kpis.md): Rank every listing by one KPI. - [GET /listings/{listing_id}](https://docs.usewheelhouse.com/rm/reference/rm-get-listing.md): Get a single listing. - [GET /listings/{listing_id}/pricing_tier](https://docs.usewheelhouse.com/rm/reference/rm-get-listing-pricing-tier.md): Get the pricing tier for a listing. - [GET /listings/{listing_id}/recent_changes](https://docs.usewheelhouse.com/rm/reference/rm-get-listing-recent-changes.md): Get times of latest changes for a listing. - [POST /listings/{listing_id}/sync](https://docs.usewheelhouse.com/rm/reference/rm-post-listing-sync.md): Trigger a manual sync for a listing. - [GET /listings/{listing_id}/kpis](https://docs.usewheelhouse.com/rm/reference/rm-get-listing-kpis.md): Get rolling-window KPIs for a listing. - [GET /listings/{listing_id}/kpis/monthly](https://docs.usewheelhouse.com/rm/reference/rm-get-listing-kpis-monthly.md): Get monthly stats for a listing. - [GET /listings/{listing_id}/kpis/quarterly](https://docs.usewheelhouse.com/rm/reference/rm-get-listing-kpis-quarterly.md): Get quarterly stats for a listing. - [GET /listings/{listing_id}/kpis/yearly](https://docs.usewheelhouse.com/rm/reference/rm-get-listing-kpis-yearly.md): Get yearly stats for a listing. --- # Recommendations > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/recommendations · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml Retrieve Wheelhouse price recommendations, base price suggestions, check-in/check-out calendars, min/max price calendars, and monthly seasonality factors. ## Endpoints - [GET /listings/{listing_id}/price_recommendations](https://docs.usewheelhouse.com/rm/reference/rm-get-price-recommendations.md): Get daily price recommendations for a listing. - [GET /price_models](https://docs.usewheelhouse.com/rm/reference/rm-get-price-models.md): List the price models customers can pick from. - [POST /preferences/{listing_id}/preview](https://docs.usewheelhouse.com/rm/reference/rm-preview-preferences.md): Preview price recommendations for a listing with hypothetical preference changes. - [GET /listings/{listing_id}/base_price_recommendation](https://docs.usewheelhouse.com/rm/reference/rm-get-base-price-recommendation.md): Get base price recommendation options for a listing. - [GET /listings/{listing_id}/checkin_checkout](https://docs.usewheelhouse.com/rm/reference/rm-get-checkin-checkout.md): Get check-in/check-out calendar for a listing. - [GET /listings/{listing_id}/min_max_prices](https://docs.usewheelhouse.com/rm/reference/rm-get-min-max-prices.md): Get minimum and maximum price calendar for a listing. - [GET /listings/{listing_id}/monthly_seasonality](https://docs.usewheelhouse.com/rm/reference/rm-get-monthly-seasonality.md): Get recommended monthly seasonality adjustment factors for a listing. - [GET /listings/{listing_id}/base_price_history](https://docs.usewheelhouse.com/rm/reference/rm-get-base-price-history.md): Get the base price recommendation history for a listing. --- # Listing Preferences > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/listing-preferences · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml 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. `reason` is `not_supported_for_multi_unit` for a setting that is stored but has no effect because the listing has more than one unit; today that is only `gap_night`. ## 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` | | 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. ## Endpoints - [GET /preferences](https://docs.usewheelhouse.com/rm/reference/rm-get-preferences-batch.md): Retrieve preferences for a batch of listings. - [PUT /preferences](https://docs.usewheelhouse.com/rm/reference/rm-put-preferences-batch.md): Update preferences for a batch of listings. - [GET /preferences/{listing_id}](https://docs.usewheelhouse.com/rm/reference/rm-get-preferences.md): Get preferences for a listing. - [PUT /preferences/{listing_id}](https://docs.usewheelhouse.com/rm/reference/rm-put-preferences.md): Update preferences for a listing. - [PUT /preferences/{listing_id}/copy](https://docs.usewheelhouse.com/rm/reference/rm-copy-preferences.md): Copy preferences from one listing to another. - [PUT /preferences/{listing_id}/{setting}](https://docs.usewheelhouse.com/rm/reference/rm-put-preference-setting.md): Update a single pricing setting for a listing. - [GET /preferences/{listing_id}/long_term_discounts](https://docs.usewheelhouse.com/rm/reference/rm-get-long-term-discounts.md): Get the long-term discount settings for a listing. - [GET /preferences/{listing_id}/changelog](https://docs.usewheelhouse.com/rm/reference/rm-get-preferences-changelog.md): Get the changelog of all changes to a listing. --- # Custom Rates > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/custom-rates · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml Set and delete custom fixed or adjustment rates for specific date ranges on a listing. ## Endpoints - [GET /listings/{listing_id}/custom_rates](https://docs.usewheelhouse.com/rm/reference/rm-get-custom-rates.md): Get all active and upcoming custom rates for a listing. - [PUT /listings/{listing_id}/custom_rates](https://docs.usewheelhouse.com/rm/reference/rm-put-custom-rate.md): Set a custom rate for a listing. - [DELETE /listings/{listing_id}/custom_rates](https://docs.usewheelhouse.com/rm/reference/rm-delete-custom-rate.md): Delete custom rates for a date range on a listing. - [PUT /listings/{listing_id}/bulk_custom_rates](https://docs.usewheelhouse.com/rm/reference/rm-bulk-put-custom-rates.md): Set multiple custom rates for a listing in bulk. - [DELETE /listings/{listing_id}/bulk_custom_rates](https://docs.usewheelhouse.com/rm/reference/rm-bulk-delete-custom-rates.md): Delete multiple custom rate ranges for a listing in bulk. --- # Reservations > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/reservations · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml Retrieve reservations for a listing. ## Endpoints - [GET /listings/{listing_id}/reservations](https://docs.usewheelhouse.com/rm/reference/rm-get-reservations.md): Get reservations for a listing. --- # Listing Tags > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/listing-tags · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml Read and update user-defined tags on listings for filtering and grouping. ## Endpoints - [GET /listings/{listing_id}/tags](https://docs.usewheelhouse.com/rm/reference/rm-get-tags.md): Get user-defined tags for a listing. - [PUT /listings/{listing_id}/tags](https://docs.usewheelhouse.com/rm/reference/rm-put-tags.md): Update user-defined tags for a listing. --- # Listing OTA Links > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/listing-ota-links · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml Links from a listing to its pages on other booking platforms (Airbnb, Vrbo, Booking.com) and to its direct booking website. A link can come from more than one source: the listing's PMS (`pms`), a user in Wheelhouse or through this API (`user`), or a bulk upload (`bulk`). `GET /listings/{listing_id}/ota_links` returns each page once, with every source that links the listing to it in `sources`. Each source has its own `link_id`, which `DELETE /listings/{listing_id}/ota_links/{link_id}` takes. Links from the PMS change only in the PMS. Another account linking the same page is never shown, and does not stop this listing from linking it. ## Endpoints - [GET /listings/{listing_id}/ota_links](https://docs.usewheelhouse.com/rm/reference/rm-get-ota-links.md): List a listing's links to other booking platforms. - [PUT /listings/{listing_id}/ota_links](https://docs.usewheelhouse.com/rm/reference/rm-put-ota-link.md): Add a link to another booking platform. - [DELETE /listings/{listing_id}/ota_links/{link_id}](https://docs.usewheelhouse.com/rm/reference/rm-delete-ota-link.md): Remove a link to another booking platform. --- # Listing Flags > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/listing-flags · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml Flags are system-managed tags that Wheelhouse sets automatically on listings to convey internal state or signals. Unlike user-defined tags, flags are read-only and cannot be modified via the API. Each flag carries a `category` saying what it means for the listing's pricing: a setup that keeps Wheelhouse from pricing the listing as recommended (`engine`), a pricing setting worth reviewing (`settings`), a booking signal (`performance`), or context (`info`). ## Endpoints - [GET /listings/{listing_id}/flags](https://docs.usewheelhouse.com/rm/reference/rm-get-flags.md): Get system-defined flags for a listing. --- # Notes > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/notes · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml Notes are user-created annotations on a listing, optionally tied to a date range, a settings category, and a reminder. Use these endpoints to fetch, create, update, and delete the notes of a listing. Notes can be `active` or `archived`; deleting a note removes it permanently — deleted notes are no longer returned by the API and cannot be restored. ## Endpoints - [GET /listings/{listing_id}/notes](https://docs.usewheelhouse.com/rm/reference/rm-get-notes.md): Get the notes of a listing. - [POST /listings/{listing_id}/notes](https://docs.usewheelhouse.com/rm/reference/rm-post-note.md): Create a note on a listing. - [PUT /listings/{listing_id}/notes/{note_id}](https://docs.usewheelhouse.com/rm/reference/rm-put-note.md): Update a note. - [DELETE /listings/{listing_id}/notes/{note_id}](https://docs.usewheelhouse.com/rm/reference/rm-delete-note.md): Delete a note. --- # Calendar > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/calendar · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml Fetch the price calendar for a listing. The calendar reflects current prices, availability, and booking state for each stay date. ## Endpoints - [GET /listings/{listing_id}/price_calendar](https://docs.usewheelhouse.com/rm/reference/rm-get-price-calendar.md): Get the price calendar for a listing. - [GET /listings/{listing_id}/last_posted_prices](https://docs.usewheelhouse.com/rm/reference/rm-get-last-posted-prices.md): Get the last posted price per stay date for a listing. - [GET /listings/{listing_id}/calendar_day_history](https://docs.usewheelhouse.com/rm/reference/rm-get-calendar-day-history.md): Get the historical snapshots of a calendar day for a listing. - [GET /listings/{listing_id}/fee_impact_calendar](https://docs.usewheelhouse.com/rm/reference/rm-get-fee-impact-calendar.md): Get the estimated fee multiplier per stay date for a listing. - [GET /listings/{listing_id}/min_stay_calendar](https://docs.usewheelhouse.com/rm/reference/rm-get-min-stay-calendar.md): Get the minimum stay calendar for a listing. --- # Segments > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/segments · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml Portfolio segments group listings by filter criteria. The `filter_backend` field is the core of a segment — it defines which listings belong to it. Use `POST /segments` to create a segment, `PUT /segments/{segment_id}` to update one, `DELETE /segments/{segment_id}` to delete one, `GET /segments` to list all segments for the authenticated user, `GET /segments/{segment_id}/listings` to retrieve the listings matched by a segment's filter, and `GET /segments/{segment_id}/aggregated_metrics` to fetch aggregated performance metrics for those listings. See the `filter_backend_object` schema for a full reference of available filter keys, operator suffixes, and value formats. ## Endpoints - [GET /segments](https://docs.usewheelhouse.com/rm/reference/rm-get-segments.md): List portfolio segments. - [POST /segments](https://docs.usewheelhouse.com/rm/reference/rm-post-segments.md): Create a portfolio segment. - [PUT /segments/{segment_id}](https://docs.usewheelhouse.com/rm/reference/rm-put-segment.md): Update a portfolio segment. - [DELETE /segments/{segment_id}](https://docs.usewheelhouse.com/rm/reference/rm-delete-segment.md): Delete a portfolio segment. - [GET /segments/{segment_id}/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-segment-listings.md): List listings in a segment. - [GET /segments/{segment_id}/aggregated_metrics](https://docs.usewheelhouse.com/rm/reference/rm-get-segment-aggregated-metrics.md): Get aggregated metrics for a segment. --- # Market Reports > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/market-reports · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml Access aggregated market-level data for the markets in which the authenticated user has at least one Pro tier listing. Use these endpoints to retrieve time-series metrics (e.g. occupancy, asking rate, RevPAR) and metric distributions across a market for a given month. Results can be filtered by bedroom count, property type, and performance tier. ## Endpoints - [GET /market_report](https://docs.usewheelhouse.com/rm/reference/rm-get-market-report.md): List markets for a country. - [GET /market_report/{market_id}/bedroom_groups](https://docs.usewheelhouse.com/rm/reference/rm-get-market-bedroom-groups.md): Get the bedroom groups a market is broken down by. - [GET /market_report/{market_id}/time_series](https://docs.usewheelhouse.com/rm/reference/rm-get-market-time-series.md): Get time-series market metrics. - [GET /market_report/{market_id}/distribution](https://docs.usewheelhouse.com/rm/reference/rm-get-market-distribution.md): Get market metric distributions for a month. --- # Neighborhood Data > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/neighborhood-data · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml Daily market and neighborhood price data for a listing's location. The neighborhood data reflects the local cluster of comparable properties near the listing (same bedroom count, same geographic cluster), providing context for competitive pricing. Additional data sources — including market-wide aggregates and dynamic comparison sets — will be added here in future releases. ## Endpoints - [GET /listings/{listing_id}/neighborhood/pricing](https://docs.usewheelhouse.com/rm/reference/rm-get-neighborhood-pricing.md): Get daily neighborhood pricing data for a listing. - [GET /listings/{listing_id}/neighborhood/occupancy](https://docs.usewheelhouse.com/rm/reference/rm-get-neighborhood-occupancy.md): Get daily neighborhood occupancy and booking data for a listing. --- # Dynamic Sets > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/dynamic-sets · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml Dynamic sets are user-curated sets of comparison listings used to track competitive performance. Use these endpoints to build a set from scratch (search for candidate listings near a location, create a set from them, and upgrade it to paid), list a user's sets, inspect a set's definition and member listings, retrieve aggregated performance metrics, manage which of the user's own listings the set is associated with, and fetch a set's change history, time-series metrics, and metric distributions. `GET /sets` returns both free and paid sets; the `is_paid` field on each set indicates which. Everything involved in **building** a set works on a free one — creating it, adding and removing its member listings, reviewing them, and managing which of your own listings it is associated with. What the paid plan buys is the **set-level analytics** computed across the set, including its price calendar. A paid-only endpoint returns `404 Not Found` for a free set, which is indistinguishable from a set that does not exist, so check `is_paid` before calling one. | Endpoint | Free sets | Paid sets | |---|---|---| | `GET /sets` | ✅ | ✅ | | `POST /sets` | ✅ (creates a free set) | — | | `GET /sets/candidates` | ✅ (no set required) | ✅ | | `GET /sets/{set_id}` | ✅ | ✅ | | `POST /sets/{set_id}/upgrade` | ✅ (this is what upgrades it) | — | | `POST /sets/{set_id}/share` | ✅ | ✅ | | `GET /sets/{set_id}/listings` | ✅ | ✅ | | `PUT /sets/{set_id}/listings` | ✅ | ✅ | | `DELETE /sets/{set_id}/listings` | ✅ | ✅ | | `GET /sets/{set_id}/associated_listings` | ✅ | ✅ | | `PUT /sets/{set_id}/associated_listings` | ✅ | ✅ | | `DELETE /sets/{set_id}/associated_listings` | ✅ | ✅ | | `GET /sets/{set_id}/aggregated_metrics` | ❌ 404 | ✅ | | `GET /sets/{set_id}/price_calendar` | ❌ 404 | ✅ (up to 25 members) | | `GET /sets/{set_id}/time_series` | ❌ 404 | ✅ | | `GET /sets/{set_id}/distribution` | ❌ 404 | ✅ | | `GET /sets/{set_id}/changelog` | ❌ 404 | ✅ | Upgrade a free set with `POST /sets/{set_id}/upgrade`, which purchases the paid plan and charges the billable user. Sets the user owns as well as sets shared with the user are included throughout; modifying a shared set requires editor or manager access to it. ## Endpoints - [GET /sets](https://docs.usewheelhouse.com/rm/reference/rm-get-sets.md): List dynamic sets. - [POST /sets](https://docs.usewheelhouse.com/rm/reference/rm-create-set.md): Create a dynamic set. - [GET /sets/candidates](https://docs.usewheelhouse.com/rm/reference/rm-get-set-candidates.md): Search candidate listings for a dynamic set. - [GET /sets/{set_id}](https://docs.usewheelhouse.com/rm/reference/rm-get-set.md): Get a single dynamic set. - [POST /sets/{set_id}/upgrade](https://docs.usewheelhouse.com/rm/reference/rm-upgrade-set.md): Upgrade a dynamic set to a paid set. - [GET /sets/{set_id}/aggregated_metrics](https://docs.usewheelhouse.com/rm/reference/rm-get-set-aggregated-metrics.md): Get aggregated metrics for a dynamic set. - [GET /sets/{set_id}/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-set-listings.md): List the listings in a dynamic set. - [PUT /sets/{set_id}/listings](https://docs.usewheelhouse.com/rm/reference/rm-put-set-listings.md): Add member listings to a dynamic set. - [DELETE /sets/{set_id}/listings](https://docs.usewheelhouse.com/rm/reference/rm-delete-set-listings.md): Remove member listings from a dynamic set. - [GET /sets/{set_id}/associated_listings](https://docs.usewheelhouse.com/rm/reference/rm-get-set-associated-listings.md): List the user listings associated with a dynamic set. - [PUT /sets/{set_id}/associated_listings](https://docs.usewheelhouse.com/rm/reference/rm-put-set-associated-listings.md): Associate user listings with a dynamic set. - [DELETE /sets/{set_id}/associated_listings](https://docs.usewheelhouse.com/rm/reference/rm-delete-set-associated-listings.md): Remove associated user listings from a dynamic set. - [GET /sets/{set_id}/price_calendar](https://docs.usewheelhouse.com/rm/reference/rm-get-set-price-calendar.md): Get the price calendar of a dynamic set's member listings. - [GET /sets/{set_id}/changelog](https://docs.usewheelhouse.com/rm/reference/rm-get-set-changelog.md): Get the changelog of a dynamic set. - [POST /sets/{set_id}/share](https://docs.usewheelhouse.com/rm/reference/rm-share-set.md): Share a dynamic set with other users. - [GET /sets/{set_id}/time_series](https://docs.usewheelhouse.com/rm/reference/rm-get-set-time-series.md): Get time-series metrics for a dynamic set. - [GET /sets/{set_id}/distribution](https://docs.usewheelhouse.com/rm/reference/rm-get-set-distribution.md): Get metric distributions for a dynamic set. --- # Notifications > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/notifications · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml In-app notifications surfaced in the Wheelhouse dashboard at `/u/account/notifications`. Use these endpoints to list a user's active notifications and to dismiss them. Only non-dismissed, non-expired notifications are returned. Use the notification settings endpoints to configure which alerts the user receives, and on which channel (in-app or email). ## Endpoints - [GET /notifications](https://docs.usewheelhouse.com/rm/reference/rm-get-notifications.md): List active notifications. - [POST /notifications/dismiss](https://docs.usewheelhouse.com/rm/reference/rm-dismiss-notifications.md): Dismiss notifications. - [GET /notification_settings](https://docs.usewheelhouse.com/rm/reference/rm-get-notification-settings.md): List notification alert settings. - [PUT /notification_settings](https://docs.usewheelhouse.com/rm/reference/rm-update-notification-settings.md): Configure notification alert settings. --- # Teams > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/teams · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml Teams let a Wheelhouse account (the team owner) grant other Wheelhouse accounts access to manage its listings. Use `GET /teams/members` to list the team members the authenticated user manages, `POST /teams/members/invite` to invite a new member by email, `DELETE /teams/members/{sub_user_id}` to remove one, and the `auto_managed_listing_level`, `assigned_segments`, and `refresh_auto_managed_listings` endpoints to control which of the owner's listings a member can access and at what level. Use `GET /teams/memberships` to list the teams the authenticated user belongs to as a member, `POST /teams/memberships/{master_user_id}` to accept a pending invitation, and `DELETE /teams/memberships/{master_user_id}` to leave a team or decline an invitation. ## Endpoints - [GET /teams/members](https://docs.usewheelhouse.com/rm/reference/rm-get-team-members.md): List team members. - [POST /teams/members/invite](https://docs.usewheelhouse.com/rm/reference/rm-post-team-member-invite.md): Invite a team member. - [DELETE /teams/members/{sub_user_id}](https://docs.usewheelhouse.com/rm/reference/rm-delete-team-member.md): Remove a team member. - [POST /teams/members/{sub_user_id}/auto_managed_listing_level](https://docs.usewheelhouse.com/rm/reference/rm-post-team-member-auto-managed-listing-level.md): Set a team member's auto managed listing level. - [POST /teams/members/{sub_user_id}/assigned_segments](https://docs.usewheelhouse.com/rm/reference/rm-post-team-member-assigned-segments.md): Assign portfolio segments to a team member. - [POST /teams/members/{sub_user_id}/refresh_auto_managed_listings](https://docs.usewheelhouse.com/rm/reference/rm-post-team-member-refresh-auto-managed-listings.md): Refresh a team member's auto managed listing access. - [GET /teams/memberships](https://docs.usewheelhouse.com/rm/reference/rm-get-team-memberships.md): List team memberships. - [POST /teams/memberships/{master_user_id}](https://docs.usewheelhouse.com/rm/reference/rm-post-team-membership.md): Accept a team invitation. - [DELETE /teams/memberships/{master_user_id}](https://docs.usewheelhouse.com/rm/reference/rm-delete-team-membership.md): Leave a team, or decline an invitation. --- # Webhooks > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/webhooks · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml Webhooks notify your integration when data changes, so you can keep a local copy fresh without polling. Register an HTTPS endpoint with `POST /webhooks`, choosing which of the event types listed by `GET /webhook_events` it should receive. **Events describe what changed, not the new values.** A delivery names the listings affected and expects you to re-read the detail through the relevant endpoint — price recommendations, reservations or flags. This keeps payloads small and stable, and means you never have to reconcile a webhook body against an API response. ## What fires each event Each event type has its own trigger, and they differ in how closely a delivery tracks a change to the individual listing it names. `reservations.ingested` and `flags.detected` name a listing only when that listing's own data actually changed, so a portfolio where nothing happened receives no request at all rather than an empty one. `recommendations.updated` is broader: its main trigger is a market being repriced, which names every active listing in that market. Read a delivery as "these listings are worth re-reading" rather than as proof that each one is different. ### `recommendations.updated` Fires when a listing's price recommendations have been recomputed or posted, which is the point at which the numbers you can read may have changed. Two things cause that: * **The nightly pricing run for a market completes.** Every active listing in that market is named, because the run may have moved any of them. This is the bulk of the volume, and it is why the event batches per market — see `market_id` in the payload. * **Rates are posted for a single listing**, whether by automatic price posting, by `POST /listings/{listing_id}/sync`, or by a post from the Wheelhouse app. Only that listing is named. Note that the nightly trigger does not compare each listing's numbers before naming it: a market being repriced names every active listing in it, including any whose recommendations ended up identical to yesterday's. So a delivery tells you a recompute covered these listings, not that every one of them moved. It does **not** fire because you changed a listing's settings. A preference write that alters future recommendations is not itself this event; the recommendations move when they are next computed or posted, and the event follows then. ### `reservations.ingested` Fires when the set of reservations you would read back for a listing has changed. That covers: * **A reservation arrives** that Wheelhouse did not already hold, whether picked up by a channel sync or pushed in by the integration that manages the listing's reservations. * **A reservation Wheelhouse already held is amended** — its dates, prices, payout, fees, taxes, deposits, discounts, currency, unit assignment, or booking time change. * **A reservation is cancelled**, whether the channel reports it cancelled or simply stops returning it. Cancellations detected by a reservation's disappearance are limited to stays ending within roughly the last month, so a very old reservation vanishing from a channel feed is not treated as a cancellation and does not fire. * **A reservation is removed outright** instead of being marked cancelled. Removals come from the integration that manages the listing's reservations, so a re-read finds the reservation simply gone rather than reported as `Canceled`. It does **not** fire when a sync re-reads a reservation and finds it unchanged. Reservations are compared field by field, so a listing whose bookings are simply confirmed again each day never notifies. This is what keeps the event proportional to real booking activity rather than to sync frequency. ### `flags.detected` Fires when a listing gains a flag it did not already have. Flags are the automatically derived conditions returned by `GET /listings/{listing_id}/flags`, and they are recomputed as a listing, its settings, or its performance change. Only newly raised flags fire it, and the delivery names the listing rather than the flag, so re-read the flags endpoint to see which are now set. It does **not** fire when a flag is **cleared** — a listing whose last flag has just been resolved sends nothing, so do not treat the absence of deliveries as a stable flag state. If you track flags clearing as well as raising, re-read the endpoint on your own schedule in addition to reacting to this event. **Deliveries are batched.** Events occurring within a five-minute window collapse into a single request whose `data.listing_ids` names every listing involved, so a nightly repricing run across a large portfolio arrives as a handful of requests rather than thousands. Each delivery only ever names listings you have access to. **Verify every delivery.** Requests carry a `Wh-Signature` header of the form `t=,v1=`, where the hex is `HMAC-SHA256(secret, ".")`. Recompute it with the subscription's secret and compare; reject the request if it does not match, or if `t` is older than your tolerance (five minutes is a reasonable choice) to prevent replay. The secret is returned **only** when the subscription is created and by `POST /webhooks/{id}/rotate_secret` — it cannot be read back afterwards. **Delivery is at-least-once, so de-duplicate.** Retries reuse the same `Wh-Event-Id` header (also `data`-adjacent as the envelope `id`); treat a repeated id as already handled. Respond with any 2xx status as soon as you have durably accepted the request — do not do your processing before responding, since we time out after 15 seconds. Failed attempts are retried with backoff over roughly 20 minutes, and a subscription that keeps failing is disabled automatically; re-enable it with `PUT /webhooks/{id}` once your endpoint is healthy. Use `GET /webhooks/{id}/deliveries` to see what we actually sent and what your endpoint returned. ## Endpoints - [GET /webhook_events](https://docs.usewheelhouse.com/rm/reference/rm-get-webhook-events.md): List subscribable event types. - [GET /webhooks](https://docs.usewheelhouse.com/rm/reference/rm-get-webhooks.md): List webhook subscriptions. - [POST /webhooks](https://docs.usewheelhouse.com/rm/reference/rm-create-webhook.md): Create a webhook subscription. - [GET /webhooks/{id}](https://docs.usewheelhouse.com/rm/reference/rm-get-webhook.md): Get a webhook subscription. - [PUT /webhooks/{id}](https://docs.usewheelhouse.com/rm/reference/rm-update-webhook.md): Update a webhook subscription. - [DELETE /webhooks/{id}](https://docs.usewheelhouse.com/rm/reference/rm-delete-webhook.md): Delete a webhook subscription. - [POST /webhooks/{id}/rotate_secret](https://docs.usewheelhouse.com/rm/reference/rm-rotate-webhook-secret.md): Rotate a webhook signing secret. - [GET /webhooks/{id}/deliveries](https://docs.usewheelhouse.com/rm/reference/rm-get-webhook-deliveries.md): List recent delivery attempts. --- # Usage > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/usage · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml Tells you how your own integration is behaving, without going to the Wheelhouse app to read the audit log by hand. `GET /usage` reports volumes, error rates and response times over a window of up to 7 days, broken down by day, by endpoint and by API key. It is cached for a few minutes, so poll it on the order of minutes, not seconds, and read `generated_at` to see how fresh a response is. ## Endpoints - [GET /usage](https://docs.usewheelhouse.com/rm/reference/rm-get-usage.md): Aggregated API usage for the authenticated user. --- # Feedback > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/feedback · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml Tell the Wheelhouse team what worked, what broke, what was confusing, or what you could not do with this API. Feedback can come from a person or from an AI agent working for them, and every item is read and triaged by the Wheelhouse team. **Agents:** send feedback when a request fails in a way the documentation did not prepare you for, when you cannot find an endpoint or field for something the user asked, or when the documentation was unclear or wrong. One item per issue, written so someone without your conversation can understand it: what you tried, what happened, and what you expected. This is not a support channel and nobody replies to feedback. For help with an account, contact support@usewheelhouse.com. ## Endpoints - [POST /feedback](https://docs.usewheelhouse.com/rm/reference/rm-post-feedback.md): Send feedback about the API. --- # Retrieve all listings for the authenticated user. `GET /listings` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-listings · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetListings` · Tag: Listings Returns every listing the authenticated user can access: listings they own (connected via their channel accounts) plus listings they have been granted access to manage in Wheelhouse (shared / delegated access on another user's listings). Set `include_managed_listings` to false to restrict the response to owned listings only. Each listing carries an `access_level` and an `owner_user`, so managed listings can be told apart from owned ones and attributed to the account they belong to. Pass `owner_user_id` to return the listings of one account only, such as a team you belong to. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `exclude_inactive` | boolean | no | Exclude inactive listings, and listings not linked to a channel, from the response. Hidden listings are not inactive and are still returned; see `is_hidden`. (default: `true`) | | `include_managed_listings` | boolean | no | When true (default), includes listings the user manages for another Wheelhouse account (valid shared-access grants), in addition to listings they own. Set to false to return only owned listings. (default: `true`) | | `include_photos` | boolean | no | Set to true to include the URLs of each listing's photos in `meta.photos`. `num_photos` is returned either way. (default: `false`) | | `owner_user_id` | integer | no | Return only the listings owned by this Wheelhouse user, that is, those whose `owner_user.id` matches. Pass a membership's `user_id` from [`GET /teams/memberships`](https://docs.usewheelhouse.com/rm/reference/rm-get-team-memberships.md) to read one team's listings. It narrows the listings you can already access and grants no others, so a user whose listings you cannot access returns an empty list. | | `per_page` | integer | no | Number of listings per page. (default: `50`, min: 1, max: 100) | | `page` | integer | no | Page number to retrieve. | | `offset` | integer | no | Number of items to skip before starting to collect the result set. | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of listings. Body (`application/json`): array of object `listing_response` A listing as returned by the RM API. - `id` (string, required): The channel's unique listing identifier. Always the channel's ID, whichever way the request identified the listing; the Wheelhouse listing ID is the separate `wheelhouse_id` field. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). - `channel` (string, required): The channel name of the listing. - `wheelhouse_id` (integer, nullable): The Wheelhouse internal listing ID. - `title` (string, nullable): The listing's name. - `nickname` (string, nullable): Listing nickname used as a shortened title. - `description` (string, nullable): The listing's description text. - `location` (object, nullable): The listing's location. - `country` (string, nullable): ISO-3166 2-letter country code. - `postal_code` (string, nullable) - `address` (string, nullable) - `latitude` (number, nullable) - `longitude` (number, nullable) - `num_bedrooms` (integer, nullable): Number of bedrooms. - `num_beds` (integer, nullable): Number of beds. - `num_bathrooms` (number, nullable): Number of bathrooms (may be fractional, e.g. 1.5). - `room_type` (string, nullable): The room type of the listing. - `property_type` (string, nullable): The property type of the listing. - `currency` (string, nullable): The ISO-4217 3-letter currency code of the listing. - `star_rating` (number, nullable): Star rating. - `num_reviews` (integer, nullable): Number of reviews. - `num_photos` (integer, nullable): Number of photos. - `thumb_url` (string, nullable): URL of the listing's thumbnail image. - `access_level` (string, nullable, one of: `owner`, `viewer`, `restricted_editor`, `editor`, `manager`): How the authenticated user accesses this listing in the RM API: `owner` for listings on their account, or the delegated role when shared access applies (`viewer`, `restricted_editor`, `editor`, `manager`). **API permissions by level:** - `owner`, `editor`, `manager` — full read and write access (GET, PUT, POST, DELETE). - `restricted_editor` — read and write access to the listing itself, except that `PUT /listings/{listing_id}/tags` returns 403 and the batch `PUT /preferences` reports the listing in `errors` with status 403. - `viewer` — read-only; write endpoints (PUT, POST, DELETE) return 403, except that a viewer may remove the listing from a set with `DELETE /sets/{set_id}/associated_listings`. - `amenities` (array of string, nullable): List of amenities available at the listing. - `owner_name` (string, nullable): The property owner's name, as supplied by the channel. This is display text about the physical property's owner and is unrelated to the Wheelhouse account that holds the listing — see `owner_user` for that. - `owner_user` (object, nullable): The Wheelhouse account this listing belongs to. Use this to tell whose portfolio a listing sits in when a response mixes owned and managed listings — for example `GET /listings?include_managed_listings=true`, or the listings of a portfolio segment or dynamic set. For listings the authenticated user owns (`access_level` of `owner`) this is the authenticated user's own account. For managed listings it is the account that granted the shared access. - `id` (integer): The Wheelhouse internal user ID of the owning account. - `email` (string): Email address of the owning account. - `first_name` (string, nullable): First name of the owning account. - `last_name` (string, nullable): Last name of the owning account. - `source_user_id` (string, nullable): The ID of the listing's host on the source channel, as reported by that channel. This is an identifier in the channel's own namespace, not a Wheelhouse account — see `owner_user` for the Wheelhouse account the listing belongs to. - `channel_ids` (object, nullable): A mapping of channel names to the channel's listing ID. - `airbnb` (string, nullable) - `tripadvisor` (string, nullable) - `vrbo` (string, nullable) - `wheelhouse` (string, nullable) - `links` (object, nullable): Useful links to the Wheelhouse app. - `calendar` (string, nullable): Link to the listing calendar page on Wheelhouse. - `upgrade` (string, nullable): Link to the upgrade flow for this listing on Wheelhouse. - `security_deposit` (number, nullable): Security deposit amount in the listing's currency. - `base_min_night_stay` (integer, nullable): The minimum night stay floor for this listing. - `listing_preferences` (object, nullable): A summary of the listing's pricing preferences and fee configuration. Use `GET /preferences/{listing_id}` for the full structured preference object, including date-specific rules. - `automatic_rate_posting_enabled` (boolean, nullable): Whether recommended prices are posted to the channel automatically. - `base_price` (number, nullable): The base price the user set by hand, in the listing's currency. `null` does not mean the listing has no base price. It means the base price follows the Wheelhouse recommendation, multiplied by `base_price_adjustment` (or by `1.0` when that is also `null`). To read the base price in use, call `GET /listings/{listing_id}/price_recommendations` and read its top-level `base_price`. - `base_price_adjustment` (number, nullable): Multiplier applied to the recommended base price when `base_price` is `null`. The presets are `0.9` (conservative), `1.0` (recommended), and `1.1` (aggressive). Any other value is a custom adjustment. When both fields are `null`, the pricing engine uses `1.0`. - `fees` (array of object): Fees charged when booking the listing. Only fees with a configured value are listed. - `name` (string, required): The name of the fee as it appears on line items. - `type` (string, required, one of: `cleaning`, `extra_guest`): Classification of the fee. - `multiplier` (string, required, one of: `PER_STAY`, `PER_NIGHT`): What the fee is charged per. - `value_type` (string, required, one of: `FIXED`, `PERCENTAGE`): Whether `value` is a fixed amount in the listing's currency or a percentage of the booking value. - `value` (number, required): The fee amount. - `max_price` (integer): The global maximum nightly price for automated pricing. Only present when a maximum price is configured. - `min_price` (integer): The global minimum nightly price for automated pricing. Only present when a minimum price is configured. - `minimum_stay` (integer): The global minimum stay in nights. Only present when a minimum stay is configured. - `monthly_discount_pct` (number, nullable): The percent discount given to bookings of 28 nights or more. - `nickname` (string, nullable): User-editable nickname for the listing. - `num_included_guests` (integer, nullable): The number of guests included in the nightly price. - `num_max_guests` (integer, nullable): The maximum number of guests the listing sleeps. - `weekly_discount_pct` (number, nullable): The percent discount given to bookings of 7 nights or more. - `meta` (object, nullable): Supplementary listing attributes. `photos` is present only where photos are requested, such as `GET /listings` with `include_photos=true`; the other fields repeat the top-level fields of the same name. - `amenities` (array of string, nullable) - `num_beds` (integer, nullable) - `num_photos` (integer, nullable) - `num_reviews` (integer, nullable) - `photos` (array of object, nullable): The listing's photos. - `caption` (string, nullable): The photo's caption. - `regular` (string, nullable): URL of the web-sized photo. - `thumbnail` (string, nullable): URL of the thumbnail-sized photo. - `security_deposit` (number, nullable) - `source_user_id` (string, nullable) - `star_rating` (number, nullable) - `market_id` (integer, nullable): The Wheelhouse market ID for this listing. - `market_name` (string, nullable): The human-readable name of the market identified by `market_id`, e.g. `San Francisco, CA, United States`. It is the same `market_name` that `GET /market_report` returns, so there is no need to look it up there. `null` when the listing has no market. - `is_active` (boolean, nullable): Whether the listing is currently active. - `is_hidden` (boolean): Whether the listing has been hidden in the Wheelhouse app. Hiding a listing does not deactivate or disconnect it, so a hidden listing is still returned with `exclude_inactive=true`; filter on this field to leave hidden listings out. Unrelated to the `hidden` membership status of a listing in a dynamic set. - `wheelhouse_created_at` (string, nullable): The datetime the listing was created in Wheelhouse (Rails-style timestamp, e.g. `2016-09-20 02:07:32 -0700`). - `number_of_active_units` (integer, nullable): The number of independently bookable units under this listing. `null` for standard single-unit listings; a positive integer for multi-unit listings. See the **Multi-Unit Listings** section in the overview. - `supported_settings` (object `supported_settings`, read-only): Which listing preference settings this listing's channel can act on. A setting reported `false` is discarded on write rather than posted to the channel, so check this before sending it. Reflects any per-account early access, so two listings on the same channel can differ. - `checkin_checkout` (boolean): Whether `checkin_checkout` rules can be set. - `min_stays` (boolean): Whether minimum stay settings (`min_min_stay`, `min_stays_enabled`, `minimum_stay_rules`) can be set. - `long_term_discounts` (boolean): Whether long-term discounts (`long_term_discounts`, `weekly_discount`, `monthly_discount`) can be set at all. - `long_term_discount_type` (string, one of: `disabled`, `simple`, `rules`, `complex`): The form of long-term discount the channel accepts. `disabled` takes none; `simple` takes only flat `weekly_discount` and `monthly_discount` values and ignores a `rules` object; `rules` additionally takes the 7 and 28 night tiers; `complex` takes arbitrary tiers. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "id": "string", "channel": "string", "wheelhouse_id": 0, "title": "string", "nickname": "string", "description": "string", "location": { "country": "string", "postal_code": "string", "address": "string", "latitude": 0, "longitude": 0 }, "num_bedrooms": 0, "num_beds": 0, "num_bathrooms": 0, "room_type": "string", "property_type": "string", "currency": "string", "star_rating": 0, "num_reviews": 0, "num_photos": 0, "thumb_url": "string", "access_level": "owner", "amenities": [ "string" ], "owner_name": "string", "owner_user": { "id": 0, "email": "string", "first_name": "string", "last_name": "string" }, "source_user_id": "string", "channel_ids": { "airbnb": "string", "tripadvisor": "string", "vrbo": "string", "wheelhouse": "string" }, "links": { "calendar": "string", "upgrade": "string" }, "security_deposit": 0, "base_min_night_stay": 0, "listing_preferences": { "automatic_rate_posting_enabled": true, "base_price": 0, "base_price_adjustment": 0, "fees": [ { "name": "string", "type": "cleaning", "multiplier": "PER_STAY", "value_type": "FIXED", "value": 0 } ], "max_price": 0, "min_price": 0, "minimum_stay": 0, "monthly_discount_pct": 0, "nickname": "string", "num_included_guests": 0, "num_max_guests": 0, "weekly_discount_pct": 0 }, "meta": { "amenities": [ "string" ], "num_beds": 0, "num_photos": 0, "num_reviews": 0, "photos": [ { "caption": "string", "regular": "string", "thumbnail": "string" } ], "security_deposit": 0, "source_user_id": "string", "star_rating": 0 }, "market_id": 0, "market_name": "string", "is_active": true, "is_hidden": true, "wheelhouse_created_at": "string", "number_of_active_units": 0, "supported_settings": { "checkin_checkout": true, "min_stays": true, "long_term_discounts": true, "long_term_discount_type": "disabled" } } ] ``` ### 401 API key authorization failed. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Rank every listing by one KPI. `GET /listings/kpis` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-bulk-listing-kpis · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetBulkListingKpis` · Tag: Listings Returns a single KPI for every listing the authenticated user can access, ranked by value. Use it to answer portfolio-wide questions (the best or worst performers on a metric) in one call instead of one call per listing. Pick the metric with `metric`, then either a rolling window with `window` or a calendar period with `period` and `period_start`. Exactly one of `window` and `period` is required. **Rolling windows.** `0_30` is the next 30 days and `30_0` the trailing 30. Values come from the same store as [`GET /listings/{listing_id}/kpis`](https://docs.usewheelhouse.com/rm/reference/rm-get-listing-kpis.md), so the two always agree; that endpoint remains the way to read every metric and window for one listing. **Calendar periods.** `period=monthly&period_start=2026-07-01` ranks on July 2026, `period=quarterly&period_start=2026-07-01` on the third quarter and `period=yearly&period_start=2026-01-01` on the year. `period_start` must be the first day of the period. Values are the ones [`GET /listings/{listing_id}/kpis/monthly`](https://docs.usewheelhouse.com/rm/reference/rm-get-listing-kpis-monthly.md), `/kpis/quarterly` and `/kpis/yearly` return. Periods are held from three years back through the calendar horizon. A period from the current one onward is not final: it reflects the bookings on the books so far, and changes as bookings come in. Every metric that is computed in both directions can be ranked by period except `asking_rate_fees`, `last_booked_days` and `min_price_occurrence`; forward-only and backward-only metrics cannot. A ranking covers one period, so to compare several months call it once per month. **Year over year.** With a `period`, pass `compare=previous_year` to add the same period one year earlier to each row as `compare_value`, along with `change` (`value - compare_value`) and `change_ratio` (`value / compare_value`). The comparison is the earlier period's final figure, not the figure as it stood at the same point last year, so comparing a period still in progress against a finished one favours the finished one. `rank_by=change` or `rank_by=change_ratio` ranks on the comparison instead of the value. For a rate such as `occupancy`, `change` is a difference of fractions, so `0.05` is five percentage points. **Metrics** (window `0_N` and `N_0`): `adr`, `adr_fees`, `asking_rate`, `asking_rate_available`, `asking_rate_fees`, `asking_rate_highest`, `asking_rate_lowest`, `bookings`, `last_booked_days`, `lead_time`, `length_of_stay`, `min_price_occurrence`, `nights_available`, `nights_blocked`, `nights_bookable`, `nights_booked`, `nights_calendar`, `nights_percent_open`, `occupancy`, `occupancy_adjusted`, `revenue`, `revenue_available`, `revenue_blocked`, `revenue_fees`, `revenue_fees_taxes`, `revpar`, `revpar_adjusted_occupancy`, `revpar_adjusted_occupancy_fees`, `revpar_fees`. **Forward-only metrics** (window `0_N` only): `occupancy_neighborhood`, `occupancy_neighborhood_pp`, `occupancy_neighborhood_ratio`, `occupancy_neighborhood_adjusted`, `occupancy_neighborhood_adjusted_pp`, `occupancy_neighborhood_adjusted_ratio`, `revenue_score`. **Backward-only metrics** (window `N_0` only): `pickup`, `pickup_bookings`. Asking for a window a metric is not computed for returns a 400. Monetary metrics — the `adr`, `asking_rate`, `revenue` and `revpar` families — are stored in the currency of the listing's market, falling back to the listing's own currency when it has no market, and each row reports which in its `currency`. For a portfolio spanning currencies, pass `currency` to convert every value before ranking, so that the ordering is meaningful. Without it, rows are ranked on unconverted numbers. `currency` is ignored for metrics that are not amounts of money. A listing with no value for the requested window sorts last whichever direction you rank in, with `value` set to null, so a ranking never opens with blanks. Listings for which no stats have been generated at all are absent. Values are recomputed by the nightly stats pipeline and when a listing's calendar is refreshed; `updated_at` on each row tells you how current it is. Comp-set metrics (`comp_set_occupancy` and friends) are not available here yet. **Same time last year.** Pass `basis=stly` to rank on each listing's values as they stood at the same time last year: the same window, measured 52 weeks earlier, so `0_30` is the 30 days that followed the same day last year. Rows have the same shape and currency handling as `basis=current`. Last year's values cover every metric above except `min_price_occurrence`, `revenue_blocked`, `revenue_score` and the `occupancy_neighborhood` metrics, which return a 400. Listings with no stats for last year are absent from the ranking. `basis=stly` ranks rolling windows only and returns a 400 with `period`. `basis=stly` is in early access; accounts without early access get a 403. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/kpis` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `metric` | string | yes | The KPI to return. See the metric lists above. (example: `occupancy_adjusted`) | | `window` | string | no | Rolling window to return. `0_30` is the next 30 days, `30_0` the trailing 30. Required unless `period` is given. (one of: `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`, `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`, example: `0_30`) | | `period` | string | no | Rank on a calendar month, quarter or year instead of a rolling window. Requires `period_start`; cannot be combined with `window`. (one of: `monthly`, `quarterly`, `yearly`) | | `period_start` | string (date) | no | First day of the period to rank on, e.g. `2026-07-01` for July 2026 or the third quarter of 2026. Required with `period`. (example: `2026-07-01`) | | `compare` | string | no | With `period`, also return the same period one year earlier (its final figure) as `compare_value`, with `change` and `change_ratio`. (one of: `previous_year`) | | `rank_by` | string | no | What to rank on. `change` and `change_ratio` need `compare`. `sort` sets the direction, and a listing with no value to rank on sorts last either way. (one of: `value`, `change`, `change_ratio`, default: `value`) | | `basis` | string | no | Rank on today's values (`current`) or on the values as they stood at the same time last year (`stly`). See the description above for the metrics `stly` does not cover. `stly` works with `window` only; for a period, use `compare=previous_year`. `stly` is in early access. (one of: `current`, `stly`, default: `current`) | | `sort` | string | no | Rank highest value first (`desc`) or lowest first (`asc`). (one of: `desc`, `asc`, default: `desc`) | | `currency` | string | no | ISO-4217 code to convert monetary values to before ranking. Recommended for portfolios spanning more than one currency. Ignored for metrics that are not amounts of money. (example: `USD`) | | `exclude_inactive` | boolean | no | Exclude inactive listings, and listings not linked to a channel, from the ranking. Hidden listings are not inactive and are still ranked; read `is_hidden` from `GET /listings` to leave them out. (default: `true`) | | `include_managed_listings` | boolean | no | When true (default), includes listings the user manages for another Wheelhouse account, in addition to listings they own. Set to false to rank only owned listings. (default: `true`) | | `owner_user_id` | integer | no | Rank only the listings owned by this Wheelhouse user, matching `owner_user.id` on [`GET /listings`](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md). Pass a membership's `user_id` from [`GET /teams/memberships`](https://docs.usewheelhouse.com/rm/reference/rm-get-team-memberships.md) to rank one team's portfolio. It narrows the listings you can already access and grants no others, so a user whose listings you cannot access returns an empty list. | | `page` | integer | no | Page of the ranking to return. (default: `1`) | | `per_page` | integer | no | Rows per page (max 100). (default: `50`, max: 100) | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/kpis?metric=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 One row per listing, ranked by the requested metric. Body (`application/json`): array of object - `listing_id` (integer, example: `84521`): Wheelhouse's own listing id. - `partner_listing_id` (string, nullable, example: `12345`): The channel's unique listing identifier, as accepted by the single-listing endpoints. Always the channel's ID; the Wheelhouse listing ID is the `listing_id` field above. - `value` (number, nullable, example: `0.82`): The metric's value for the requested window. Null when the listing has no value for it. - `currency` (string, nullable, example: `USD`): ISO-4217 currency the value is expressed in — the requested `currency` when one was given, otherwise the market's currency the value is stored in. Null for metrics that are not amounts of money. - `updated_at` (string (date-time), nullable): When this metric was last recomputed for the listing. Null when ranking by `period`. - `compare_value` (number, nullable, example: `0.74`): Only with `compare`. The same metric for the same period one year earlier, in the same currency as `value`. Null when the listing has no value for that period. - `change` (number, nullable, example: `0.08`): Only with `compare`. `value - compare_value`. Null when either is null. - `change_ratio` (number, nullable, example: `1.108`): Only with `compare`. `value / compare_value`, so `1.1` is ten percent up. Null when either is null or `compare_value` is zero. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "listing_id": 84521, "partner_listing_id": "12345", "value": 0.82, "currency": "USD", "updated_at": "2026-01-01T00:00:00Z", "compare_value": 0.74, "change": 0.08, "change_ratio": 1.108 } ] ``` ### 400 Missing or unknown metric, window or period; both or neither of `window` and `period`; a window the metric is not computed for; a metric not available by period; a `period_start` that is not the first day of the period; `compare` or `rank_by` used incorrectly; with `basis=stly`, a metric not available for last year; or `basis=stly` with `period`. ### 401 API key authorization failed. ### 403 `basis=stly` was requested by an account without early access to it. ### 422 No exchange rate is available for the requested currency. --- # Get a single listing. `GET /listings/{listing_id}` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-listing · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetListing` · Tag: Listings ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The listing. Body (`application/json`): object `listing_response` A listing as returned by the RM API. - `id` (string, required): The channel's unique listing identifier. Always the channel's ID, whichever way the request identified the listing; the Wheelhouse listing ID is the separate `wheelhouse_id` field. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). - `channel` (string, required): The channel name of the listing. - `wheelhouse_id` (integer, nullable): The Wheelhouse internal listing ID. - `title` (string, nullable): The listing's name. - `nickname` (string, nullable): Listing nickname used as a shortened title. - `description` (string, nullable): The listing's description text. - `location` (object, nullable): The listing's location. - `country` (string, nullable): ISO-3166 2-letter country code. - `postal_code` (string, nullable) - `address` (string, nullable) - `latitude` (number, nullable) - `longitude` (number, nullable) - `num_bedrooms` (integer, nullable): Number of bedrooms. - `num_beds` (integer, nullable): Number of beds. - `num_bathrooms` (number, nullable): Number of bathrooms (may be fractional, e.g. 1.5). - `room_type` (string, nullable): The room type of the listing. - `property_type` (string, nullable): The property type of the listing. - `currency` (string, nullable): The ISO-4217 3-letter currency code of the listing. - `star_rating` (number, nullable): Star rating. - `num_reviews` (integer, nullable): Number of reviews. - `num_photos` (integer, nullable): Number of photos. - `thumb_url` (string, nullable): URL of the listing's thumbnail image. - `access_level` (string, nullable, one of: `owner`, `viewer`, `restricted_editor`, `editor`, `manager`): How the authenticated user accesses this listing in the RM API: `owner` for listings on their account, or the delegated role when shared access applies (`viewer`, `restricted_editor`, `editor`, `manager`). **API permissions by level:** - `owner`, `editor`, `manager` — full read and write access (GET, PUT, POST, DELETE). - `restricted_editor` — read and write access to the listing itself, except that `PUT /listings/{listing_id}/tags` returns 403 and the batch `PUT /preferences` reports the listing in `errors` with status 403. - `viewer` — read-only; write endpoints (PUT, POST, DELETE) return 403, except that a viewer may remove the listing from a set with `DELETE /sets/{set_id}/associated_listings`. - `amenities` (array of string, nullable): List of amenities available at the listing. - `owner_name` (string, nullable): The property owner's name, as supplied by the channel. This is display text about the physical property's owner and is unrelated to the Wheelhouse account that holds the listing — see `owner_user` for that. - `owner_user` (object, nullable): The Wheelhouse account this listing belongs to. Use this to tell whose portfolio a listing sits in when a response mixes owned and managed listings — for example `GET /listings?include_managed_listings=true`, or the listings of a portfolio segment or dynamic set. For listings the authenticated user owns (`access_level` of `owner`) this is the authenticated user's own account. For managed listings it is the account that granted the shared access. - `id` (integer): The Wheelhouse internal user ID of the owning account. - `email` (string): Email address of the owning account. - `first_name` (string, nullable): First name of the owning account. - `last_name` (string, nullable): Last name of the owning account. - `source_user_id` (string, nullable): The ID of the listing's host on the source channel, as reported by that channel. This is an identifier in the channel's own namespace, not a Wheelhouse account — see `owner_user` for the Wheelhouse account the listing belongs to. - `channel_ids` (object, nullable): A mapping of channel names to the channel's listing ID. - `airbnb` (string, nullable) - `tripadvisor` (string, nullable) - `vrbo` (string, nullable) - `wheelhouse` (string, nullable) - `links` (object, nullable): Useful links to the Wheelhouse app. - `calendar` (string, nullable): Link to the listing calendar page on Wheelhouse. - `upgrade` (string, nullable): Link to the upgrade flow for this listing on Wheelhouse. - `security_deposit` (number, nullable): Security deposit amount in the listing's currency. - `base_min_night_stay` (integer, nullable): The minimum night stay floor for this listing. - `listing_preferences` (object, nullable): A summary of the listing's pricing preferences and fee configuration. Use `GET /preferences/{listing_id}` for the full structured preference object, including date-specific rules. - `automatic_rate_posting_enabled` (boolean, nullable): Whether recommended prices are posted to the channel automatically. - `base_price` (number, nullable): The base price the user set by hand, in the listing's currency. `null` does not mean the listing has no base price. It means the base price follows the Wheelhouse recommendation, multiplied by `base_price_adjustment` (or by `1.0` when that is also `null`). To read the base price in use, call `GET /listings/{listing_id}/price_recommendations` and read its top-level `base_price`. - `base_price_adjustment` (number, nullable): Multiplier applied to the recommended base price when `base_price` is `null`. The presets are `0.9` (conservative), `1.0` (recommended), and `1.1` (aggressive). Any other value is a custom adjustment. When both fields are `null`, the pricing engine uses `1.0`. - `fees` (array of object): Fees charged when booking the listing. Only fees with a configured value are listed. - `name` (string, required): The name of the fee as it appears on line items. - `type` (string, required, one of: `cleaning`, `extra_guest`): Classification of the fee. - `multiplier` (string, required, one of: `PER_STAY`, `PER_NIGHT`): What the fee is charged per. - `value_type` (string, required, one of: `FIXED`, `PERCENTAGE`): Whether `value` is a fixed amount in the listing's currency or a percentage of the booking value. - `value` (number, required): The fee amount. - `max_price` (integer): The global maximum nightly price for automated pricing. Only present when a maximum price is configured. - `min_price` (integer): The global minimum nightly price for automated pricing. Only present when a minimum price is configured. - `minimum_stay` (integer): The global minimum stay in nights. Only present when a minimum stay is configured. - `monthly_discount_pct` (number, nullable): The percent discount given to bookings of 28 nights or more. - `nickname` (string, nullable): User-editable nickname for the listing. - `num_included_guests` (integer, nullable): The number of guests included in the nightly price. - `num_max_guests` (integer, nullable): The maximum number of guests the listing sleeps. - `weekly_discount_pct` (number, nullable): The percent discount given to bookings of 7 nights or more. - `meta` (object, nullable): Supplementary listing attributes. `photos` is present only where photos are requested, such as `GET /listings` with `include_photos=true`; the other fields repeat the top-level fields of the same name. - `amenities` (array of string, nullable) - `num_beds` (integer, nullable) - `num_photos` (integer, nullable) - `num_reviews` (integer, nullable) - `photos` (array of object, nullable): The listing's photos. - `caption` (string, nullable): The photo's caption. - `regular` (string, nullable): URL of the web-sized photo. - `thumbnail` (string, nullable): URL of the thumbnail-sized photo. - `security_deposit` (number, nullable) - `source_user_id` (string, nullable) - `star_rating` (number, nullable) - `market_id` (integer, nullable): The Wheelhouse market ID for this listing. - `market_name` (string, nullable): The human-readable name of the market identified by `market_id`, e.g. `San Francisco, CA, United States`. It is the same `market_name` that `GET /market_report` returns, so there is no need to look it up there. `null` when the listing has no market. - `is_active` (boolean, nullable): Whether the listing is currently active. - `is_hidden` (boolean): Whether the listing has been hidden in the Wheelhouse app. Hiding a listing does not deactivate or disconnect it, so a hidden listing is still returned with `exclude_inactive=true`; filter on this field to leave hidden listings out. Unrelated to the `hidden` membership status of a listing in a dynamic set. - `wheelhouse_created_at` (string, nullable): The datetime the listing was created in Wheelhouse (Rails-style timestamp, e.g. `2016-09-20 02:07:32 -0700`). - `number_of_active_units` (integer, nullable): The number of independently bookable units under this listing. `null` for standard single-unit listings; a positive integer for multi-unit listings. See the **Multi-Unit Listings** section in the overview. - `supported_settings` (object `supported_settings`, read-only): Which listing preference settings this listing's channel can act on. A setting reported `false` is discarded on write rather than posted to the channel, so check this before sending it. Reflects any per-account early access, so two listings on the same channel can differ. - `checkin_checkout` (boolean): Whether `checkin_checkout` rules can be set. - `min_stays` (boolean): Whether minimum stay settings (`min_min_stay`, `min_stays_enabled`, `minimum_stay_rules`) can be set. - `long_term_discounts` (boolean): Whether long-term discounts (`long_term_discounts`, `weekly_discount`, `monthly_discount`) can be set at all. - `long_term_discount_type` (string, one of: `disabled`, `simple`, `rules`, `complex`): The form of long-term discount the channel accepts. `disabled` takes none; `simple` takes only flat `weekly_discount` and `monthly_discount` values and ignores a `rules` object; `rules` additionally takes the 7 and 28 night tiers; `complex` takes arbitrary tiers. Example shape (generated from the schema; placeholder values, not a real response): ```json { "id": "string", "channel": "string", "wheelhouse_id": 0, "title": "string", "nickname": "string", "description": "string", "location": { "country": "string", "postal_code": "string", "address": "string", "latitude": 0, "longitude": 0 }, "num_bedrooms": 0, "num_beds": 0, "num_bathrooms": 0, "room_type": "string", "property_type": "string", "currency": "string", "star_rating": 0, "num_reviews": 0, "num_photos": 0, "thumb_url": "string", "access_level": "owner", "amenities": [ "string" ], "owner_name": "string", "owner_user": { "id": 0, "email": "string", "first_name": "string", "last_name": "string" }, "source_user_id": "string", "channel_ids": { "airbnb": "string", "tripadvisor": "string", "vrbo": "string", "wheelhouse": "string" }, "links": { "calendar": "string", "upgrade": "string" }, "security_deposit": 0, "base_min_night_stay": 0, "listing_preferences": { "automatic_rate_posting_enabled": true, "base_price": 0, "base_price_adjustment": 0, "fees": [ { "name": "string", "type": "cleaning", "multiplier": "PER_STAY", "value_type": "FIXED", "value": 0 } ], "max_price": 0, "min_price": 0, "minimum_stay": 0, "monthly_discount_pct": 0, "nickname": "string", "num_included_guests": 0, "num_max_guests": 0, "weekly_discount_pct": 0 }, "meta": { "amenities": [ "string" ], "num_beds": 0, "num_photos": 0, "num_reviews": 0, "photos": [ { "caption": "string", "regular": "string", "thumbnail": "string" } ], "security_deposit": 0, "source_user_id": "string", "star_rating": 0 }, "market_id": 0, "market_name": "string", "is_active": true, "is_hidden": true, "wheelhouse_created_at": "string", "number_of_active_units": 0, "supported_settings": { "checkin_checkout": true, "min_stays": true, "long_term_discounts": true, "long_term_discount_type": "disabled" } } ``` ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get the pricing tier for a listing. `GET /listings/{listing_id}/pricing_tier` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-listing-pricing-tier · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetListingPricingTier` · Tag: Listings ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/pricing_tier` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/pricing_tier?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The pricing tier information. Body (`application/json`): object `pricing_tier_response` The listing's pricing tier and recommendation horizon. - `name` (string, required, one of: `Free`, `Pro Flex`, `Pro Flat`, `Pro Trial`, `Pro Onboarding`): The name of the pricing tier. See [Pricing Tiers](https://docs.usewheelhouse.com/rm/concepts/pricing-tiers.md) for what each tier allows. - `horizon` (integer, required): The number of days ahead Wheelhouse prices the listing. This is a custom horizon when one is configured for the listing, otherwise the horizon of the listing's plan. For a `Free` listing without a custom horizon, `GET /listings/{listing_id}/price_recommendations` returns fewer days than this. See [Pricing Tiers](https://docs.usewheelhouse.com/rm/concepts/pricing-tiers.md). Example shape (generated from the schema; placeholder values, not a real response): ```json { "name": "Free", "horizon": 0 } ``` ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get times of latest changes for a listing. `GET /listings/{listing_id}/recent_changes` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-listing-recent-changes · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetListingRecentChanges` · Tag: Listings Returns when the listing's preferences and custom rates last changed. Compare the timestamps with the ones from your previous call, and re-read `GET /preferences/{listing_id}` or `GET /listings/{listing_id}/custom_rates` only when they moved. See [Keeping a local copy fresh](https://docs.usewheelhouse.com/rm/usage.md#keeping-a-local-copy-fresh). ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/recent_changes` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/recent_changes?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Recent change timestamps in UTC. Body (`application/json`): object - `settings` (string (date-time)): When the listing's preferences were last updated (ISO-8601). In this response, 'settings' refers to listing preferences — what the Wheelhouse app calls 'Settings'. - `rates` (string (date-time), nullable): When a custom rate on the listing was last added, changed, split or removed (ISO-8601). A rate expiring, or its dates passing, does not change it. `null` when no custom rate is on record for the listing (old rate history is deleted after a while, so `null` does not prove the listing never had one). Example shape (generated from the schema; placeholder values, not a real response): ```json { "settings": "2026-01-01T00:00:00Z", "rates": "2026-01-01T00:00:00Z" } ``` ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Trigger a manual sync for a listing. `POST /listings/{listing_id}/sync` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-post-listing-sync · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPostListingSync` · Tag: Listings Enqueues a price-posting job that pushes the latest Wheelhouse price recommendations to the connected channel and refreshes reservation data. Equivalent to clicking the **Sync** button in the Wheelhouse UI. **Plan requirement:** Manual syncs are only available on paid (Pro) plans. Listings on free or onboarding plans will receive `429 Too Many Requests`. **Rate limit:** The number of syncs allowed per day is determined by the listing's pricing plan. Returns `429 Too Many Requests` when the daily limit is exceeded. **Debounce:** To prevent duplicate jobs from stacking up, if another sync for the same listing was requested within the last 60 seconds, the endpoint returns `423 Locked`. Wait at least 60 seconds before retrying. **Paused channels:** While syncing with the listing's channel is paused, for example during the channel's scheduled maintenance, the endpoint returns `503 Service Unavailable` with a `Retry-After` header. A refused sync does not count toward the daily limit. The request returns `202 Accepted` immediately — the sync runs asynchronously in the background. Use `GET /listings/{listing_id}/pricing_tier` or poll the Wheelhouse dashboard to confirm when the sync has completed. ## Request `POST https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/sync` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Example request ```bash curl -X POST 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/sync?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 202 Sync accepted and queued. The body is an empty object. Body (`application/json`): object Example shape (generated from the schema; placeholder values, not a real response): ```json {} ``` ### 401 API key authorization failed. ### 403 Listing authorization failed (listing does not belong to the authenticated user, or the API key is read-only). ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 423 A sync was already requested for this listing within the last 60 seconds. Retry after the debounce window has elapsed. ### 429 Daily sync limit reached for this listing, or the listing plan does not include manual syncs. ### 503 Syncing with the listing's channel is paused. Retry after the number of seconds in the `Retry-After` header. Body (`application/json`): object - `error` (string, example: `channel_paused`) - `channel` (string): The paused channel's short ID. - `channel_name` (string) - `message` (string): A message to show the user. - `resumes_at` (string (date-time), nullable): When the pause is scheduled to end, or null if it has no scheduled end. Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "channel_paused", "channel": "string", "channel_name": "string", "message": "string", "resumes_at": "2026-01-01T00:00:00Z" } ``` --- # Get rolling-window KPIs for a listing. `GET /listings/{listing_id}/kpis` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-listing-kpis · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetListingKpis` · Tag: Listings Returns rolling-window performance metrics covering the full [Wheelhouse metrics lexicon](https://www.usewheelhouse.com/research-metrics). Each metric is an object keyed by period strings such as `"0_7"` (next 7 days), `"0_30"` (next 30 days), `"30_0"` (past 30 days), etc. **Bidirectional metrics** (periods 7/14/21/30/60/90/180/365, both past and future): `adr`, `adr_fees`, `asking_rate`, `asking_rate_available`, `asking_rate_fees`, `asking_rate_highest`, `asking_rate_lowest`, `bookings`, `last_booked_days`, `lead_time`, `length_of_stay`, `min_price_occurrence`, `nights_available`, `nights_blocked`, `nights_bookable`, `nights_booked`, `nights_calendar`, `nights_percent_open`, `occupancy`, `occupancy_adjusted`, `revenue`, `revenue_available`, `revenue_blocked`, `revenue_fees`, `revenue_fees_taxes`, `revpar`, `revpar_adjusted_occupancy`, `revpar_adjusted_occupancy_fees`, `revpar_fees`. **Forward-only metrics** (periods 7/14/21/30/60/90/180/365, future only): `occupancy_neighborhood`, `occupancy_neighborhood_pp`, `occupancy_neighborhood_ratio`, `occupancy_neighborhood_adjusted`, `occupancy_neighborhood_adjusted_pp`, `occupancy_neighborhood_adjusted_ratio`, `revenue_score`. **Backward-only metrics** (periods 7/14/21/30/60/90/180/365, past only): `pickup`, `pickup_bookings`. **Comp-set metrics** (periods 7/30/60, forward only): `comp_set_occupancy`, `comp_set_occupancy_adjusted`, `comp_set_revenue`. **Scalars:** `comp_set_count`. A metric field is `null` when it has not been generated yet for the listing; individual period keys are `null` where the metric does not apply or the window has no data. All monetary values are in the listing's `currency`. **Same time last year.** Pass `basis=stly` to get the listing's values as they stood at the same time last year: each window measured 52 weeks earlier, so `0_30` is the 30 days that followed the same day last year. The response has the same shape as `basis=current`. `model_date`, `comp_set_count`, the comp-set metrics, `revenue_blocked`, `min_price_occurrence`, `revenue_score` and the `occupancy_neighborhood` metrics are not available for last year and are `null`. `basis=stly` is in early access; accounts without early access get a 403. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/kpis` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | | `basis` | string | no | Return today's values (`current`) or the values as they stood at the same time last year (`stly`). See the description above for what `stly` returns. (one of: `current`, `stly`, default: `current`) | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/kpis?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Rolling-window KPIs. Body (`application/json`): object `listing_kpis_response` Rolling-window KPIs for a listing. - `currency` (string, example: `USD`): ISO-4217 currency code for all monetary values in this response. - `model_date` (string (date), nullable): Date the rolling-window stats were last computed. Null when no stat data exists. - `adr` (object `kpi_rolling_window_bidirectional`, nullable): Average Daily Rate per period: average price of booked nights, excluding fees. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `adr_fees` (object `kpi_rolling_window_bidirectional`, nullable): Average Daily Rate (+ Fees) per period: average price of booked nights, including fees. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `asking_rate` (object `kpi_rolling_window_bidirectional`, nullable): Asking Rate (Booked + Available Nights) per period: average nightly price across booked and available nights, excluding fees. A booked night counts at the rate it was booked for, an available night at its current price. Blocked nights are left out. `null` when no night qualifies. See `asking_rate_available` for available nights only. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `asking_rate_available` (object `kpi_rolling_window_bidirectional`, nullable): Asking Rate (Available Nights) per period: sum of nightly prices on available nights / number of available nights, excluding fees. Booked and blocked nights, and nights without a price, count in neither. `null`, not `0`, when no available night has a price. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `asking_rate_fees` (object `kpi_rolling_window_bidirectional`, nullable): Asking Rate (+ Estimated Fees) per period: current average price of bookable nights, including estimated fees derived from past reservations. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `asking_rate_highest` (object `kpi_rolling_window_bidirectional`, nullable): Highest asking rate within the period. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `asking_rate_lowest` (object `kpi_rolling_window_bidirectional`, nullable): Lowest asking rate within the period. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `bookings` (object `kpi_rolling_window_bidirectional`, nullable): Number of reservations (booking count, not night count) whose stay dates fall within the period. Corresponds to the 'Bookings' metric in the Wheelhouse platform. Available in both past (`'N_0'`) and future (`'0_N'`) period windows. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `comp_set_count` (integer, nullable): Number of listings in the listing's default comp set. - `comp_set_occupancy` (object `kpi_rolling_window_comp_set`, nullable): Comp-set occupancy rate (booked / calendar nights) per forward-looking period (7, 30, 60 days). Forward-looking keys only (`0_N` = next N days): `0_7`, `0_30`, `0_60`. - Fields: see `kpi_rolling_window_comp_set` under Schemas. - `comp_set_occupancy_adjusted` (object `kpi_rolling_window_comp_set`, nullable): Comp-set open occupancy rate (booked / bookable nights) per forward-looking period (7, 30, 60 days). Forward-looking keys only (`0_N` = next N days): `0_7`, `0_30`, `0_60`. - Fields: see `kpi_rolling_window_comp_set` under Schemas. - `comp_set_revenue` (object `kpi_rolling_window_comp_set`, nullable): Comp-set average revenue per listing per forward-looking period (7, 30, 60 days). Forward-looking keys only (`0_N` = next N days): `0_7`, `0_30`, `0_60`. - Fields: see `kpi_rolling_window_comp_set` under Schemas. - `last_booked_days` (object `kpi_rolling_window_bidirectional`, nullable): Last Booked (Days) per period: number of days since the most recent booking whose stay dates overlap the period. Null when no booking affects the period. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `lead_time` (object `kpi_rolling_window_bidirectional`, nullable): Lead Time (Average) per period: average number of days before the stay date that bookings occurred. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `length_of_stay` (object `kpi_rolling_window_bidirectional`, nullable): Length of Stay (Average) per period: average number of nights booked per reservation. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `min_price_occurrence` (object `kpi_rolling_window_bidirectional`, nullable): Minimum Price Occurrence per period: number of days (regardless of booking status) where the observed price is equal to, or less than, the listing's minimum price. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `nights_available` (object `kpi_rolling_window_bidirectional`, nullable): Nights (Available) per period: number of nights currently available within the period. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `nights_blocked` (object `kpi_rolling_window_bidirectional`, nullable): Nights (Blocked) per period: number of nights currently blocked within the period. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `nights_bookable` (object `kpi_rolling_window_bidirectional`, nullable): Nights (Bookable) per period: available plus booked nights, excluding blocked nights. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `nights_booked` (object `kpi_rolling_window_bidirectional`, nullable): Nights (Booked) per period: number of nights currently booked within the period. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `nights_calendar` (object `kpi_rolling_window_bidirectional`, nullable): Nights (Calendar) per period: number of nights in the period, irrespective of listing status. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `nights_percent_open` (object `kpi_rolling_window_bidirectional`, nullable): Nights (Bookable %) per period: percentage of Nights (Bookable) within Nights (Calendar). Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `occupancy` (object `kpi_rolling_window_bidirectional`, nullable): Occupancy rate per period (booked nights / calendar nights). Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `occupancy_adjusted` (object `kpi_rolling_window_bidirectional`, nullable): Open occupancy rate per period (booked nights / bookable nights). Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `occupancy_neighborhood` (object `kpi_rolling_window_forward_only`, nullable): Occupancy (Neighborhood) per forward-looking period: occupancy rate of the listing's local neighborhood cluster (comparable nearby properties). Forward-looking keys only (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. - Fields: see `kpi_rolling_window_forward_only` under Schemas. - `occupancy_neighborhood_adjusted` (object `kpi_rolling_window_forward_only`, nullable): Open occupancy rate (booked / bookable) of the listing's neighborhood cluster per forward-looking period. Forward-looking keys only (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. - Fields: see `kpi_rolling_window_forward_only` under Schemas. - `occupancy_neighborhood_adjusted_pp` (object `kpi_rolling_window_forward_only`, nullable): Percentage-point difference between the listing's open occupancy and the neighborhood cluster open occupancy per forward-looking period. Forward-looking keys only (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. - Fields: see `kpi_rolling_window_forward_only` under Schemas. - `occupancy_neighborhood_adjusted_ratio` (object `kpi_rolling_window_forward_only`, nullable): Ratio of the listing's open occupancy to the neighborhood cluster open occupancy per forward-looking period. Forward-looking keys only (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. - Fields: see `kpi_rolling_window_forward_only` under Schemas. - `occupancy_neighborhood_pp` (object `kpi_rolling_window_forward_only`, nullable): Percentage-point difference between the listing's occupancy and the neighborhood cluster occupancy per forward-looking period (listing − cluster, expressed in percentage points). Forward-looking keys only (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. - Fields: see `kpi_rolling_window_forward_only` under Schemas. - `occupancy_neighborhood_ratio` (object `kpi_rolling_window_forward_only`, nullable): Ratio of the listing's occupancy to the neighborhood cluster occupancy per forward-looking period (listing / cluster). Forward-looking keys only (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. - Fields: see `kpi_rolling_window_forward_only` under Schemas. - `pickup` (object `kpi_rolling_window_trailing_only`, nullable): Pickup (Booked Nights) per backward-looking period: number of new nights booked within the past N days (by booking creation date, not stay date). Backward-looking keys only (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_trailing_only` under Schemas. - `pickup_bookings` (object `kpi_rolling_window_trailing_only`, nullable): Pickup (Bookings) per backward-looking period: number of distinct bookings picked up within the past N days (one per reservation, by booking creation date). Backward-looking keys only (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_trailing_only` under Schemas. - `revenue` (object `kpi_rolling_window_bidirectional`, nullable): Revenue per period: sum of prices (rent only) for booked nights. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `revenue_available` (object `kpi_rolling_window_bidirectional`, nullable): Revenue (Available) per period: sum of the current asking rates for available nights. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `revenue_blocked` (object `kpi_rolling_window_bidirectional`, nullable): Revenue (Blocked) per period: sum of the current asking rates for blocked nights (opportunity cost of blocked nights). Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `revenue_fees` (object `kpi_rolling_window_bidirectional`, nullable): Revenue (+ Fees) per period: sum of prices (rent plus fees) for booked nights. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `revenue_fees_taxes` (object `kpi_rolling_window_bidirectional`, nullable): Revenue (+ Fees, Taxes) per period: sum of prices (rent plus fees plus taxes) for booked nights. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `revenue_score` (object `kpi_rolling_window_forward_only`, nullable): Revenue Score per cumulative forward-looking period (next 7 through next 365 days). Scores are on a 0–100 scale; higher values indicate the listing is capturing more of its expected revenue and outperforming its market segment. Null for periods beyond the listing's recommendation horizon. Forward-looking keys only (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. - Fields: see `kpi_rolling_window_forward_only` under Schemas. - `revpar` (object `kpi_rolling_window_bidirectional`, nullable): Revenue per available room night per period. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `revpar_adjusted_occupancy` (object `kpi_rolling_window_bidirectional`, nullable): RevPAR excluding blocked nights per period. Canonical name: 'RevPAR (Adjusted Occupancy)'. Previously called 'Adjusted Nightly RevPAR' in the Wheelhouse platform. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `revpar_adjusted_occupancy_fees` (object `kpi_rolling_window_bidirectional`, nullable): RevPAR including fees, excluding blocked nights per period. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. - `revpar_fees` (object `kpi_rolling_window_bidirectional`, nullable): RevPAR including fees per period. Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - Fields: see `kpi_rolling_window_bidirectional` under Schemas. Example shape (generated from the schema; placeholder values, not a real response): ```json { "currency": "USD", "model_date": "2026-01-01", "adr": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "adr_fees": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "asking_rate": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "asking_rate_available": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "asking_rate_fees": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "asking_rate_highest": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "asking_rate_lowest": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "bookings": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "comp_set_count": 0, "comp_set_occupancy": { "0_7": 0, "0_30": 0, "0_60": 0 }, "comp_set_occupancy_adjusted": { "0_7": 0, "0_30": 0, "0_60": 0 }, "comp_set_revenue": { "0_7": 0, "0_30": 0, "0_60": 0 }, "last_booked_days": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "lead_time": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "length_of_stay": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "min_price_occurrence": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "nights_available": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "nights_blocked": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "nights_bookable": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "nights_booked": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "nights_calendar": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "nights_percent_open": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "occupancy": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "occupancy_adjusted": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "occupancy_neighborhood": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0 }, "occupancy_neighborhood_adjusted": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0 }, "occupancy_neighborhood_adjusted_pp": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0 }, "occupancy_neighborhood_adjusted_ratio": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0 }, "occupancy_neighborhood_pp": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0 }, "occupancy_neighborhood_ratio": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0 }, "pickup": { "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "pickup_bookings": { "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "revenue": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "revenue_available": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "revenue_blocked": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "revenue_fees": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "revenue_fees_taxes": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "revenue_score": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0 }, "revpar": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "revpar_adjusted_occupancy": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "revpar_adjusted_occupancy_fees": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 }, "revpar_fees": { "0_7": 0, "0_14": 0, "0_21": 0, "0_30": 0, "0_60": 0, "0_90": 0, "0_180": 0, "0_365": 0, "7_0": 0, "14_0": 0, "21_0": 0, "30_0": 0, "60_0": 0, "90_0": 0, "180_0": 0, "365_0": 0 } } ``` ### 401 API key authorization failed. ### 403 Listing authorization failed, or `basis=stly` was requested by an account without early access to it. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` ## Schemas Shared by more than one field above. ### `kpi_rolling_window_bidirectional` Type: object `kpi_rolling_window_bidirectional` Forward-looking keys (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. Backward-looking keys (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - `0_7` (number, nullable): Next 7 days. - `0_14` (number, nullable): Next 14 days. - `0_21` (number, nullable): Next 21 days. - `0_30` (number, nullable): Next 30 days. - `0_60` (number, nullable): Next 60 days. - `0_90` (number, nullable): Next 90 days. - `0_180` (number, nullable): Next 180 days. - `0_365` (number, nullable): Next 365 days. - `7_0` (number, nullable): Past 7 days. - `14_0` (number, nullable): Past 14 days. - `21_0` (number, nullable): Past 21 days. - `30_0` (number, nullable): Past 30 days. - `60_0` (number, nullable): Past 60 days. - `90_0` (number, nullable): Past 90 days. - `180_0` (number, nullable): Past 180 days. - `365_0` (number, nullable): Past 365 days. ### `kpi_rolling_window_comp_set` Type: object `kpi_rolling_window_comp_set` Forward-looking keys only (`0_N` = next N days): `0_7`, `0_30`, `0_60`. - `0_7` (number, nullable): Next 7 days. - `0_30` (number, nullable): Next 30 days. - `0_60` (number, nullable): Next 60 days. ### `kpi_rolling_window_forward_only` Type: object `kpi_rolling_window_forward_only` Forward-looking keys only (`0_N` = next N days): `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`. - `0_7` (number, nullable): Next 7 days. - `0_14` (number, nullable): Next 14 days. - `0_21` (number, nullable): Next 21 days. - `0_30` (number, nullable): Next 30 days. - `0_60` (number, nullable): Next 60 days. - `0_90` (number, nullable): Next 90 days. - `0_180` (number, nullable): Next 180 days. - `0_365` (number, nullable): Next 365 days. ### `kpi_rolling_window_trailing_only` Type: object `kpi_rolling_window_trailing_only` Backward-looking keys only (`N_0` = past N days): `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`. - `7_0` (number, nullable): Past 7 days. - `14_0` (number, nullable): Past 14 days. - `21_0` (number, nullable): Past 21 days. - `30_0` (number, nullable): Past 30 days. - `60_0` (number, nullable): Past 60 days. - `90_0` (number, nullable): Past 90 days. - `180_0` (number, nullable): Past 180 days. - `365_0` (number, nullable): Past 365 days. --- # Get monthly stats for a listing. `GET /listings/{listing_id}/kpis/monthly` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-listing-kpis-monthly · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetListingKpisMonthly` · Tag: Listings Returns per-month performance stats, ordered oldest-to-newest. Includes comp-set metrics. **Covers both past and future months** — up to 15 months back and forward through the month containing the maximum calendar horizon (1.5 years from today), subject to the months Wheelhouse holds data for. That last month includes only the nights up to the horizon, so its nights and revenue cover part of the month. Months from the current one onward are forward-looking: they reflect the bookings on the books so far plus asking rates for nights that are still open, so they are not final and will change as bookings come in. Compare a month's `month` value against today's date to tell which side of the line it falls on. **Same time last year.** Pass `basis=stly` to get each month as it stood at the same time last year. The row under a `month` holds that month a year earlier, as it stood 52 weeks ago, so a month that was still ahead then counts only the bookings on the books at the time. Rows sit under the current `month` they compare with, so the two bases can be joined on `month`. `revenue_blocked` and the `comp_set_*` fields are `null`. Months with no stats for last year are absent. `basis=stly` is in early access; accounts without early access get a 403. All monetary values are in the listing's `currency`. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/kpis/monthly` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | | `basis` | string | no | Return today's values (`current`) or the values as they stood at the same time last year (`stly`). See the description above for what `stly` returns. (one of: `current`, `stly`, default: `current`) | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/kpis/monthly?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Monthly KPIs. Body (`application/json`): object - `currency` (string, example: `USD`): ISO-4217 currency code for all monetary values in this response. - `data` (array of object `listing_stats_monthly_response`): Past and future months, ordered oldest-to-newest. - Each item: Performance stats for a single calendar month. The month may be in the past or in the future; future months are forward-looking (bookings on the books plus asking rates for open nights) rather than settled results. - `month` (string (date)): First day of the month these stats cover (ISO-8601 date). Compare against today's date to tell whether the month is complete, in progress, or still ahead. - `adr` (number, nullable): Average daily rate (average nightly rate of booked stays). - `adr_fees` (number, nullable): Average daily rate including fees. - `asking_rate` (number, nullable): Asking Rate (Booked + Available Nights): average nightly price across booked and available nights, excluding fees. A booked night counts at the rate it was booked for, an available night at its current price. Blocked nights are left out. `null` when no night qualifies. See `asking_rate_available` for available nights only. - `asking_rate_available` (number, nullable): Asking Rate (Available Nights): sum of nightly prices on available nights / number of available nights, excluding fees. Booked and blocked nights, and nights without a price, count in neither. `null`, not `0`, when no available night has a price. - `asking_rate_highest` (number, nullable): Asking Rate (Highest): highest nightly asking price on any night in the period, whether open, booked or blocked. `null` when no night has a price. - `asking_rate_lowest` (number, nullable): Asking Rate (Lowest): lowest nightly asking price on any night in the period, whether open, booked or blocked. `null` when no night has a price. - `bookings` (integer, nullable): Bookings: reservations with at least one night in the period. `null`, not `0`, when no reservation overlaps the period. - `lead_time` (number, nullable): Average days between booking and check-in. - `los` (number, nullable): Average length of stay in nights. - `nights_available` (number, nullable): Currently unbooked, bookable nights. - `nights_blocked` (number, nullable): Owner-blocked nights preventing bookings. - `nights_bookable` (number, nullable): Bookable nights (available plus booked, excluding blocked). - `nights_booked` (number, nullable): Currently reserved nights. - `nights_calendar` (number, nullable): Nights (Calendar): nights in the period, irrespective of listing status. For a listing with several units, counts the nights of each currently active unit. - `nights_percent_open` (number, nullable): Nights (Bookable %): bookable nights as a share of calendar nights. - `occupancy` (number, nullable): Occupancy rate (booked nights / calendar nights). - `occupancy_adjusted` (number, nullable): Open occupancy rate (booked nights / bookable nights). - `revenue` (number, nullable): Total revenue (rent only). - `revenue_available` (number, nullable): Potential earnings from currently available nights at current asking rates. - `revenue_blocked` (number, nullable): Unrealized revenue from blocked nights at current asking rates. - `revenue_fees` (number, nullable): Revenue including fees (rent plus fees) for booked nights. - `revenue_fees_taxes` (number, nullable): Revenue including fees and taxes for booked nights. - `revpar` (number, nullable): Revenue per available room night. - `revpar_fees` (number, nullable): RevPAR including fees. - `revpar_adjusted_occupancy_fees` (number, nullable): RevPAR including fees, excluding blocked nights. - `revpar_adjusted_occupancy` (number, nullable): RevPAR excluding blocked nights. - `comp_set_adr` (number, nullable): Comp-set average daily rate. - `comp_set_lead_time` (number, nullable): Comp-set average booking lead time. - `comp_set_occupancy` (number, nullable): Comp-set occupancy rate. - `comp_set_occupancy_adjusted` (number, nullable): Comp-set open occupancy rate. - `comp_set_revpar` (number, nullable): Comp-set RevPAR. - `comp_set_revenue` (number, nullable): Comp-set average revenue per unit. - `comp_set_revpar_adjusted_occupancy` (number, nullable): Comp-set RevPAR excluding blocked nights. - `comp_set_los` (number, nullable): Comp-set average length of stay. Example shape (generated from the schema; placeholder values, not a real response): ```json { "currency": "USD", "data": [ { "month": "2026-01-01", "adr": 0, "adr_fees": 0, "asking_rate": 0, "asking_rate_available": 0, "asking_rate_highest": 0, "asking_rate_lowest": 0, "bookings": 0, "lead_time": 0, "los": 0, "nights_available": 0, "nights_blocked": 0, "nights_bookable": 0, "nights_booked": 0, "nights_calendar": 0, "nights_percent_open": 0, "occupancy": 0, "occupancy_adjusted": 0, "revenue": 0, "revenue_available": 0, "revenue_blocked": 0, "revenue_fees": 0, "revenue_fees_taxes": 0, "revpar": 0, "revpar_fees": 0, "revpar_adjusted_occupancy_fees": 0, "revpar_adjusted_occupancy": 0, "comp_set_adr": 0, "comp_set_lead_time": 0, "comp_set_occupancy": 0, "comp_set_occupancy_adjusted": 0, "comp_set_revpar": 0, "comp_set_revenue": 0, "comp_set_revpar_adjusted_occupancy": 0, "comp_set_los": 0 } ] } ``` ### 401 API key authorization failed. ### 403 Listing authorization failed, or `basis=stly` was requested by an account without early access to it. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get quarterly stats for a listing. `GET /listings/{listing_id}/kpis/quarterly` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-listing-kpis-quarterly · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetListingKpisQuarterly` · Tag: Listings Returns per-quarter performance stats, ordered oldest-to-newest. **Covers both past and future quarters** — from the quarter containing the date 15 months ago through the quarter containing the maximum calendar horizon (1.5 years from now), subject to the quarters Wheelhouse holds data for. That last quarter includes only the nights up to the horizon, so its nights and revenue cover part of the quarter. The current quarter and any that follow are forward-looking: they reflect the bookings on the books so far plus asking rates for nights that are still open, so they are not final and will change as bookings come in. Compare a quarter's `quarter` value against today's date to tell which side of the line it falls on. **Same time last year.** Pass `basis=stly` to get each quarter as it stood at the same time last year. The row under a `quarter` holds that quarter a year earlier, as it stood 52 weeks ago, so a quarter that was still ahead then counts only the bookings on the books at the time. Rows sit under the current `quarter` they compare with, so the two bases can be joined on `quarter`. `revenue_blocked` is `null`. Quarters with no stats for last year are absent. `basis=stly` is in early access; accounts without early access get a 403. All monetary values are in the listing's `currency`. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/kpis/quarterly` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | | `basis` | string | no | Return today's values (`current`) or the values as they stood at the same time last year (`stly`). See the description above for what `stly` returns. (one of: `current`, `stly`, default: `current`) | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/kpis/quarterly?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Quarterly KPIs. Body (`application/json`): object - `currency` (string, example: `USD`): ISO-4217 currency code for all monetary values in this response. - `data` (array of object `listing_stats_quarterly_response`): Past and future quarters, ordered oldest-to-newest. - Each item: Performance stats for a single calendar quarter. The quarter may be in the past or in the future; future quarters are forward-looking (bookings on the books plus asking rates for open nights) rather than settled results. - `quarter` (string (date)): First day of the quarter these stats cover (ISO-8601 date). Compare against today's date to tell whether the quarter is complete, in progress, or still ahead. - `adr` (number, nullable): Average daily rate. - `adr_fees` (number, nullable): Average daily rate including fees. - `asking_rate` (number, nullable): Asking Rate (Booked + Available Nights): average nightly price across booked and available nights, excluding fees. A booked night counts at the rate it was booked for, an available night at its current price. Blocked nights are left out. `null` when no night qualifies. See `asking_rate_available` for available nights only. - `asking_rate_available` (number, nullable): Asking Rate (Available Nights): sum of nightly prices on available nights / number of available nights, excluding fees. Booked and blocked nights, and nights without a price, count in neither. `null`, not `0`, when no available night has a price. - `asking_rate_highest` (number, nullable): Asking Rate (Highest): highest nightly asking price on any night in the period, whether open, booked or blocked. `null` when no night has a price. - `asking_rate_lowest` (number, nullable): Asking Rate (Lowest): lowest nightly asking price on any night in the period, whether open, booked or blocked. `null` when no night has a price. - `bookings` (integer, nullable): Bookings: reservations with at least one night in the period. `null`, not `0`, when no reservation overlaps the period. Adds up the months in the period, so a stay that spans months counts once in each month it touches. - `lead_time` (number, nullable): Average days between booking and check-in. - `los` (number, nullable): Average length of stay in nights. - `nights_available` (number, nullable): Currently unbooked, bookable nights. - `nights_blocked` (number, nullable): Owner-blocked nights preventing bookings. - `nights_bookable` (number, nullable): Bookable nights (available plus booked, excluding blocked). - `nights_booked` (number, nullable): Currently reserved nights. - `nights_calendar` (number, nullable): Nights (Calendar): nights in the period, irrespective of listing status. For a listing with several units, counts the nights of each currently active unit. - `nights_percent_open` (number, nullable): Nights (Bookable %): bookable nights as a share of calendar nights. - `occupancy` (number, nullable): Occupancy rate (booked nights / calendar nights). - `occupancy_adjusted` (number, nullable): Open occupancy rate (booked nights / bookable nights). - `revenue` (number, nullable): Total revenue (rent only). - `revenue_available` (number, nullable): Potential earnings from currently available nights at current asking rates. - `revenue_blocked` (number, nullable): Unrealized revenue from blocked nights at current asking rates. - `revenue_fees` (number, nullable): Revenue including fees (rent plus fees) for booked nights. - `revenue_fees_taxes` (number, nullable): Revenue including fees and taxes for booked nights. - `revpar` (number, nullable): Revenue per available room night. - `revpar_fees` (number, nullable): RevPAR including fees. - `revpar_adjusted_occupancy_fees` (number, nullable): RevPAR including fees, excluding blocked nights. - `revpar_adjusted_occupancy` (number, nullable): RevPAR excluding blocked nights. Example shape (generated from the schema; placeholder values, not a real response): ```json { "currency": "USD", "data": [ { "quarter": "2026-01-01", "adr": 0, "adr_fees": 0, "asking_rate": 0, "asking_rate_available": 0, "asking_rate_highest": 0, "asking_rate_lowest": 0, "bookings": 0, "lead_time": 0, "los": 0, "nights_available": 0, "nights_blocked": 0, "nights_bookable": 0, "nights_booked": 0, "nights_calendar": 0, "nights_percent_open": 0, "occupancy": 0, "occupancy_adjusted": 0, "revenue": 0, "revenue_available": 0, "revenue_blocked": 0, "revenue_fees": 0, "revenue_fees_taxes": 0, "revpar": 0, "revpar_fees": 0, "revpar_adjusted_occupancy_fees": 0, "revpar_adjusted_occupancy": 0 } ] } ``` ### 401 API key authorization failed. ### 403 Listing authorization failed, or `basis=stly` was requested by an account without early access to it. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get yearly stats for a listing. `GET /listings/{listing_id}/kpis/yearly` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-listing-kpis-yearly · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetListingKpisYearly` · Tag: Listings Returns per-year performance stats, ordered oldest-to-newest. **Covers both past and future years** — from 5 calendar years ago through the year containing the maximum calendar horizon (1.5 years from now), subject to the years Wheelhouse holds data for. That last year includes only the nights up to the horizon, so its nights and revenue cover part of the year. The current year and any that follow are forward-looking: they reflect the bookings on the books so far plus asking rates for nights that are still open, so they are not final and will change as bookings come in. Compare a year's `year` value against today's date to tell which side of the line it falls on. **Same time last year.** Pass `basis=stly` to get each year as it stood at the same time last year. The row under a `year` holds the year before, as it stood 52 weeks ago, so a year that was still ahead then counts only the bookings on the books at the time. Rows sit under the current `year` they compare with, so the two bases can be joined on `year`. `revenue_blocked` is `null`. Years with no stats for last year are absent. `basis=stly` is in early access; accounts without early access get a 403. All monetary values are in the listing's `currency`. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/kpis/yearly` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | | `basis` | string | no | Return today's values (`current`) or the values as they stood at the same time last year (`stly`). See the description above for what `stly` returns. (one of: `current`, `stly`, default: `current`) | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/kpis/yearly?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Yearly KPIs. Body (`application/json`): object - `currency` (string, example: `USD`): ISO-4217 currency code for all monetary values in this response. - `data` (array of object `listing_stats_yearly_response`): Past and future years, ordered oldest-to-newest. - Each item: Performance stats for a single calendar year. The year may be in the past or in the future; future years are forward-looking (bookings on the books plus asking rates for open nights) rather than settled results. - `year` (string (date)): First day of the year these stats cover (ISO-8601 date). Compare against today's date to tell whether the year is complete, in progress, or still ahead. - `adr` (number, nullable): Average daily rate. - `adr_fees` (number, nullable): Average daily rate including fees. - `asking_rate` (number, nullable): Asking Rate (Booked + Available Nights): average nightly price across booked and available nights, excluding fees. A booked night counts at the rate it was booked for, an available night at its current price. Blocked nights are left out. `null` when no night qualifies. See `asking_rate_available` for available nights only. - `asking_rate_available` (number, nullable): Asking Rate (Available Nights): sum of nightly prices on available nights / number of available nights, excluding fees. Booked and blocked nights, and nights without a price, count in neither. `null`, not `0`, when no available night has a price. - `asking_rate_highest` (number, nullable): Asking Rate (Highest): highest nightly asking price on any night in the period, whether open, booked or blocked. `null` when no night has a price. - `asking_rate_lowest` (number, nullable): Asking Rate (Lowest): lowest nightly asking price on any night in the period, whether open, booked or blocked. `null` when no night has a price. - `bookings` (integer, nullable): Bookings: reservations with at least one night in the period. `null`, not `0`, when no reservation overlaps the period. Adds up the months in the period, so a stay that spans months counts once in each month it touches. - `lead_time` (number, nullable): Average days between booking and check-in. - `los` (number, nullable): Average length of stay in nights. - `nights_available` (number, nullable): Currently unbooked, bookable nights. - `nights_blocked` (number, nullable): Owner-blocked nights preventing bookings. - `nights_bookable` (number, nullable): Bookable nights (available plus booked, excluding blocked). - `nights_booked` (number, nullable): Currently reserved nights. - `nights_calendar` (number, nullable): Nights (Calendar): nights in the period, irrespective of listing status. For a listing with several units, counts the nights of each currently active unit. - `nights_percent_open` (number, nullable): Nights (Bookable %): bookable nights as a share of calendar nights. - `occupancy` (number, nullable): Occupancy rate (booked nights / calendar nights). - `occupancy_adjusted` (number, nullable): Open occupancy rate (booked nights / bookable nights). - `revenue` (number, nullable): Total revenue (rent only). - `revenue_available` (number, nullable): Potential earnings from currently available nights at current asking rates. - `revenue_blocked` (number, nullable): Unrealized revenue from blocked nights at current asking rates. - `revenue_fees` (number, nullable): Revenue including fees (rent plus fees) for booked nights. - `revenue_fees_taxes` (number, nullable): Revenue including fees and taxes for booked nights. - `revpar` (number, nullable): Revenue per available room night. - `revpar_fees` (number, nullable): RevPAR including fees. - `revpar_adjusted_occupancy_fees` (number, nullable): RevPAR including fees, excluding blocked nights. - `revpar_adjusted_occupancy` (number, nullable): RevPAR excluding blocked nights. Example shape (generated from the schema; placeholder values, not a real response): ```json { "currency": "USD", "data": [ { "year": "2026-01-01", "adr": 0, "adr_fees": 0, "asking_rate": 0, "asking_rate_available": 0, "asking_rate_highest": 0, "asking_rate_lowest": 0, "bookings": 0, "lead_time": 0, "los": 0, "nights_available": 0, "nights_blocked": 0, "nights_bookable": 0, "nights_booked": 0, "nights_calendar": 0, "nights_percent_open": 0, "occupancy": 0, "occupancy_adjusted": 0, "revenue": 0, "revenue_available": 0, "revenue_blocked": 0, "revenue_fees": 0, "revenue_fees_taxes": 0, "revpar": 0, "revpar_fees": 0, "revpar_adjusted_occupancy_fees": 0, "revpar_adjusted_occupancy": 0 } ] } ``` ### 401 API key authorization failed. ### 403 Listing authorization failed, or `basis=stly` was requested by an account without early access to it. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get daily price recommendations for a listing. `GET /listings/{listing_id}/price_recommendations` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-price-recommendations · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetPriceRecommendations` · Tag: Recommendations Returns most up-to-date price recommendations for the listing. The horizon of the price recommendations depends on the pricing tier this listing is in and can be queried using the [pricing tier](https://docs.usewheelhouse.com/rm/reference/rm-get-listing-pricing-tier.md) endpoint. By default, `Free` listings get a preview horizon of 30 days, and every other tier, including `Pro Trial` and `Pro Onboarding`, gets 545 days (18 months). Some channels and listings differ. See [Pricing Tiers](https://docs.usewheelhouse.com/rm/concepts/pricing-tiers.md). The `data` array starts from today's date and is returned in chronological order. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/price_recommendations` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | | `currency` | string | no | ISO-4217 3-letter currency code (e.g. 'USD', 'GBP') to convert prices to. Uses listing's currency by default. | | `attribution` | boolean | no | When true, includes detailed per-factor price attribution fields (`attr_*`) in each day's recommendation. (default: `false`) | | `price_model` | string | no | The price model version to use. `current` is the model the listing gets without a pick of its own. `opt_in` is the opt-in model, and returns `400` when there are several; pass `price_model_id` instead. With no opt-in model, `opt_in` uses the price model currently active for the listing, as does omitting the parameter. (one of: `current`, `opt_in`) | | `price_model_id` | integer | no | The ID of a price model to use, instead of `price_model`, from [GET /price_models](https://docs.usewheelhouse.com/rm/reference/rm-get-price-models.md). It must be one the listing can use and that has run for the listing's market, or the request returns `400`. | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/price_recommendations?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Daily price recommendations. Body (`application/json`): object `recommendations_response` Daily price recommendations for a listing. - `data` (array of object `recommendations_response_data_item`): Daily recommendations for prices. Includes min stays as configured by settings. - Each item: One day of price recommendations. The `attr_*` and `historical_anchor_*` fields are present only when the request sets `attribution=true`. - `stay_date` (string (date), required): The date of the given price info (YYYY-MM-DD). - `price` (number, required): The recommended nightly price for this day. - `currency` (string, required): The ISO-4217 3-letter currency code of the price. - `min_stay` (integer, nullable): The minimum stay applied to reservations overlapping this day. Omitted unless min stays are configured. This is the final value after every rule in `minimum_stay_rules_v3` and the `min_min_stay` floor. It does not say which rule set it. See [How minimum stay rules combine](https://docs.usewheelhouse.com/rm/concepts/preferences-rules.md#how-minimum-stay-rules-combine) for the precedence and a worked example. - `min_price` (integer, nullable): The minimum price applied to this day, in `currency`: the higher of the listing's minimum price rule for the date and its absolute minimum price (`min_min_price`). On a day with a fixed custom rate the minimum price rules do not apply, so only the absolute minimum price counts. `price` is never below it. In a preview, it reflects the previewed preferences. `null` when no minimum applies to the day. - `custom_type` (string, nullable, one of: `adjusted`, `fixed`): Reflects if this price is based on a custom rate. `null` means this is the Wheelhouse recommendation; `fixed` means a fixed custom price; `adjusted` means a percentage adjustment. Note: the `adjusted` value here corresponds to `rate_type: "adjustment"` when writing via `PUT /listings/{listing_id}/custom_rates` — the form differs between write (`adjustment`) and read (`adjusted`). - `events` (array of object): The events in the listing's market that run over this date. An empty array means no event runs over the date. Several events can run over one date. Only returned by `GET /listings/{listing_id}/price_recommendations`, not by `POST /preferences/{listing_id}/preview`. - `title` (string, required, example: `Jazz Festival`): The name of the event. - `start_date` (string (date), required): The first date of the event (YYYY-MM-DD). - `end_date` (string (date), required): The last date of the event (YYYY-MM-DD), inclusive. - `attr_seasonality` (integer): Seasonality attribution. Only present if `attribution=true`. - `attr_local_demand` (integer): Local demand attribution. Only present if `attribution=true`. - `attr_availability` (integer): Availability/gap night attribution. Only present if `attribution=true`. - `attr_time` (integer): Time-based attribution. Only present if `attribution=true`. - `attr_custom_weekend` (integer): Day of week attribution. Only present if `attribution=true`. - `attr_scarcity` (integer): Scarcity attribution. Only present if `attribution=true`. - `attr_occupancy_pacing` (integer): Occupancy pacing attribution. Only present if `attribution=true`. - `attr_historical_anchoring` (integer): Historical anchoring attribution. Only present if `attribution=true`. - `attr_restriction` (integer): Min/max restriction attribution. Only present if `attribution=true`. - `attr_user_adjustment` (integer): User customization attribution. Only present if `attribution=true`. - `historical_anchor_date` (string (date)): The earlier date whose price historical anchoring held this date's recommendation up to: the same day of the week, in the same week a year earlier, or two years earlier when that date has no price. Only present if `attribution=true` and historical anchoring raised this date's price, with `attr_historical_anchoring` saying by how much. - `historical_anchor_pct` (number): The historical anchoring percentage in effect for this date, from the listing's `historical_anchoring_rules`, applied as `historical_anchoring_mode` describes. Present with `historical_anchor_date`. - `historical_anchor_price` (integer): The price on `historical_anchor_date` that anchoring weighed in, in this response's `currency`. Present with `historical_anchor_date`. - `historical_anchor_source` (string, one of: `observed`, `posted`): Where `historical_anchor_price` comes from: `observed`, the listing's price as Wheelhouse saw it on the channel once the date booked, or `posted`, the price Wheelhouse last posted for the date before it booked. Present with `historical_anchor_date`. - `base_price` (integer): The base price the recommendations in `data` are computed from. This is the manual `base_price` from `GET /preferences/{listing_id}` when one is set, otherwise `base_price_recommended` multiplied by the preference `base_price_adjustment` and rounded. It is in the same currency as the prices in `data`, so a manual base price is converted and rounded when the requested `currency` differs from the preferences currency. Read the base price in use here, because the preferences and listing endpoints return `base_price` as `null` when the listing follows the recommendation. Same as `base_price_selected` on `GET /listings/{listing_id}/base_price_recommendation`. Never `null`. - `base_price_recommended` (integer, nullable): The Wheelhouse data-driven recommended base price. - `base_price_conservative` (integer, nullable): The Wheelhouse data-driven conservative base price. - `base_price_aggressive` (integer, nullable): The Wheelhouse data-driven aggressive base price. - `global_min_stay` (integer, nullable): The value from the global minimum stay rule — the default minimum stay applied when no higher-priority rule matches a date. Not the same as `min_min_stay` in preferences, which is the absolute floor that overrides all rules. - `automatic_rate_posting_enabled` (boolean): Whether Wheelhouse automatically posts its price recommendations to the channel calendar. When `false`, recommendations are computed but not pushed to the channel. This setting does not affect custom rates set via the API — those are posted independently. Example shape (generated from the schema; placeholder values, not a real response): ```json { "data": [ { "stay_date": "2026-01-01", "price": 0, "currency": "string", "min_stay": 0, "min_price": 0, "custom_type": "adjusted", "events": [ { "title": "Jazz Festival", "start_date": "2026-01-01", "end_date": "2026-01-01" } ], "attr_seasonality": 0, "attr_local_demand": 0, "attr_availability": 0, "attr_time": 0, "attr_custom_weekend": 0, "attr_scarcity": 0, "attr_occupancy_pacing": 0, "attr_historical_anchoring": 0, "attr_restriction": 0, "attr_user_adjustment": 0, "historical_anchor_date": "2026-01-01", "historical_anchor_pct": 0, "historical_anchor_price": 0, "historical_anchor_source": "observed" } ], "base_price": 0, "base_price_recommended": 0, "base_price_conservative": 0, "base_price_aggressive": 0, "global_min_stay": 0, "automatic_rate_posting_enabled": true } ``` ### 400 The requested price model cannot be used for this listing, or `price_model=opt_in` is ambiguous. ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 422 Listing is not covered by a Wheelhouse market. ### 423 Price recommendations are still being generated. Retry after a brief delay. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # List the price models customers can pick from. `GET /price_models` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-price-models · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetPriceModels` · Tag: Recommendations Returns the price models customers can pick from, the current one first. The current model prices every listing that has not picked another one, unless its channel or market is set to a different model. Pass a model's `id` as `price_model_id` to [GET /listings/{listing_id}/price_recommendations](https://docs.usewheelhouse.com/rm/reference/rm-get-price-recommendations.md) or [POST /preferences/{listing_id}/preview](https://docs.usewheelhouse.com/rm/reference/rm-preview-preferences.md) to price with it; a model that has not run for a listing's market returns `400` there. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/price_models` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/price_models' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Available price models. Body (`application/json`): array of object - `id` (integer): Price model ID, to pass as `price_model_id`. - `name` (string) - `version` (number) - `display_name` (string): Name and version, e.g. `Blended model v9.0`. - `status` (string, one of: `current`, `opt_in`): `current` for the model listings get when nothing else is set, `opt_in` for an alternative. - `description` (string, nullable): How the model prices, in plain language. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "id": 0, "name": "string", "version": 0, "display_name": "string", "status": "current", "description": "string" } ] ``` ### 401 API key authorization failed. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Preview price recommendations for a listing with hypothetical preference changes. `POST /preferences/{listing_id}/preview` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-preview-preferences · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPreviewPreferences` · Tag: Recommendations Returns price recommendations as if the provided preferences were applied to the listing, without actually saving any changes. The response format is identical to `GET /listings/{listing_id}/price_recommendations`, except that `global_min_stay` and `automatic_rate_posting_enabled` are not included. ## Request `POST https://api.usewheelhouse.com/ss_api/v1/preferences/{listing_id}/preview` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Does not modify data; read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | | `attribution` | boolean | no | When true, includes detailed per-factor price attribution fields (`attr_*`, plus `historical_anchor_*` on dates historical anchoring raised) in each day's recommendation, as on `GET /listings/{listing_id}/price_recommendations`. Compare the two responses to see which factors a preference change moves. (default: `false`) | ### Request body (`application/json`, required) The pricing preferences to set for a listing. All fields are optional; only provided fields will be updated. This partial-update behavior applies at the top level only — omitting a field (e.g. `minimum_stay_rules_v3`) leaves it unchanged, but providing a field that holds an array of rules (e.g. `minimum_price_rules_v3`) will **completely replace** the existing rule set for that field; individual rules within an array cannot be merged or patched. - `automatic_rate_posting_enabled` (boolean): Whether Wheelhouse automatically posts its price recommendations to the channel calendar. When `false`, recommendations are computed but not pushed to the channel. This setting does not affect custom rates set via the API — those are posted independently. - `base_price` (integer, nullable, min: 1): The manually set base price. If set, overrides Wheelhouse's data-driven recommendation. Must be a whole number of at least 1. - `base_price_adjustment` (number, nullable): A multiplier on the Wheelhouse recommended base price, for example `0.9` for 10% below it. Only used if `base_price` is not set. Sending a non-null value without `base_price` clears a manual `base_price`. Sending `null` leaves a manual `base_price` in place. To clear it, send `null` for `base_price`. Cannot be `0`. - `monthly_discount` (integer, nullable, default: `0`): Monthly discount percentage as an integer in the range 0–100 (e.g. `5` = 5%). On listings that accept length-of-stay premiums (every listing whose `supported_settings.long_term_discount_type` is `complex`, and some with `rules`), values are signed instead, so `-10` is a 10% discount and `10` a 10% premium. Applied to bookings ≥ 28 nights. Kept in sync with the global rule in `long_term_discounts.rules['28']` — setting one automatically updates the other. When both are sent in the same PUT, `long_term_discounts` takes precedence. - `weekly_discount` (integer, nullable, default: `0`): Weekly discount percentage as an integer in the range 0–100 (e.g. `5` = 5%). On listings that accept length-of-stay premiums (every listing whose `supported_settings.long_term_discount_type` is `complex`, and some with `rules`), values are signed instead, so `-10` is a 10% discount and `10` a 10% premium. Applied to bookings ≥ 7 nights. Kept in sync with the global rule in `long_term_discounts.rules['7']` — setting one automatically updates the other. When both are sent in the same PUT, `long_term_discounts` takes precedence. - `nickname` (string, nullable): Listing nickname. Overrides the listing's default nickname. - `last_minute_discount` (object, nullable): UI: 'Last minute' — Last-minute discount configuration. - `type` (string, one of: `CON`, `REC`, `AGG`, `CUS`) - `rules` (array of object `calendar_rule_time_based` | object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly_simple` | object `calendar_rule_day_of_week` | object `calendar_rule_custom`): Calendar rules when `type` is `CUS`. Valid rule types: `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_time_based**: see `calendar_rule_time_based` under Schemas. - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly_simple**: see `calendar_rule_monthly_simple` under Schemas. - **calendar_rule_day_of_week**: see `calendar_rule_day_of_week` under Schemas. - **calendar_rule_custom**: see `calendar_rule_custom` under Schemas. - `smooth` (boolean, default: `false`): UI: 'Smooth' — Only used when `type` is `CUS`. When `true`, the adjustment eases gradually from one rule to the next instead of jumping at each rule's edge. `custom` rules still apply exactly. Defaults to `false` (stepped). - `far_future_premium` (object, nullable): UI: 'Far future' — Far-future premium configuration. - `type` (string, one of: `CON`, `REC`, `AGG`, `CUS`) - `rules` (array of object `calendar_rule_time_based` | object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly_simple` | object `calendar_rule_day_of_week` | object `calendar_rule_custom`): Calendar rules when `type` is `CUS`. Valid rule types: `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_time_based**: see `calendar_rule_time_based` under Schemas. - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly_simple**: see `calendar_rule_monthly_simple` under Schemas. - **calendar_rule_day_of_week**: see `calendar_rule_day_of_week` under Schemas. - **calendar_rule_custom**: see `calendar_rule_custom` under Schemas. - `smooth` (boolean, default: `false`): UI: 'Smooth' — Only used when `type` is `CUS`. When `true`, the adjustment eases gradually from one rule to the next instead of jumping at each rule's edge. `custom` rules still apply exactly. Defaults to `false` (stepped). - `seasonality_adjustment` (object, nullable): UI: 'Seasonality' — Seasonality adjustment configuration. - `type` (string, one of: `CON`, `REC`, `AGG`, `CUS`) - `rules` (array of object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly`): Calendar rules when `type` is `CUS`. Valid rule types: `seasonal`, `event`, `monthly`. - One of: - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly** (object `calendar_rule_monthly`): **monthly** — Limited to specific `months`. Provide `value` or `day_of_week_values`, not both. For linear interpolation (`step: false`), set `start_value` and `end_value` with the peak in `value`. Linear interpolation is only honored in the `seasonality_adjustment` setting, and not when `smooth` is `true`. - `type` (string, required, one of: `monthly`) - `months` (array of integer, required, min items: 1, each item min: 1, max: 12): Month ordinals (1–12); at least one. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `end_value` (number): Value at month end for linear interpolation when `step` is false. - `start_value` (number): Value at month start for linear interpolation when `step` is false. - `step` (boolean): When true, stepped monthly values; when false, linear interpolation using `start_value`, `value` (peak), and `end_value`. Ignored in `seasonality_adjustment` when `smooth` is `true`. - `value` (number): Single value for the month or peak value when interpolating. - `smooth` (boolean, default: `false`): UI: 'Smooth' — Only used when `type` is `CUS`. When `true`, the adjustment eases gradually from one rule to the next instead of jumping at each rule's edge, and monthly rules' `step`, `start_value` and `end_value` are ignored. Defaults to `false` (stepped). - `day_of_week` (object, nullable): Day-of-week pricing factor configuration. - `REC` applies the market's day-of-week pattern. - `CON` and `AGG` adjust that pattern conservatively or aggressively. Sent without `rules`, they store the matching preset `day_of_week` rule. - `ADJ` applies the market's pattern and multiplies your own `rules` on top of it. - `CUS` replaces the market's pattern with your own `rules`, whose values are price multipliers (`1.1` is 10% higher). `CUS` without `rules` prices every day the same. - `type` (string, one of: `CON`, `REC`, `AGG`, `ADJ`, `CUS`) - `rules` (array of object `calendar_rule_global` | object `calendar_rule_time_based` | object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly_simple` | object `calendar_rule_day_of_week` | object `calendar_rule_custom`): Calendar rules when `type` is `ADJ` or `CUS`. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global** (object `calendar_rule_global`): **global** — Single default for the calendar in this rule set. Must not set `day_of_week_values`. UI: 'Default' or 'Minimum price default' (label varies by setting). - `type` (string, required, one of: `global`) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `value` (number, required): Default value (non-negative). - **calendar_rule_time_based**: see `calendar_rule_time_based` under Schemas. - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly_simple**: see `calendar_rule_monthly_simple` under Schemas. - **calendar_rule_day_of_week**: see `calendar_rule_day_of_week` under Schemas. - **calendar_rule_custom**: see `calendar_rule_custom` under Schemas. - `gap_night` (object `gap_night`, nullable): Gap night pricing strategy (UI: 'Gaps & Adjacencies' in the Pricing Engine panel). Controls the price multiplier for gap nights between bookings. When `type` is `CUS`, provide `custom` rules; the server rejects `CUS` without `custom`. This is a **pricing-only** setting. It is unrelated to the `gap` and `adjacency`/`one_sided_gap` rule types in `minimum_stay_rules_v3`, which control minimum stay behavior for gap nights. In a request the `custom` array replaces the stored one. Gap night pricing does not apply to listings with more than one unit. The setting is still accepted, and the response carries a `not_supported_for_multi_unit` warning. - `custom` (array of object `gap_night_custom_rule`): Per-gap custom rules. Required when `type` is `CUS` (may be an empty array). Each entry targets a gap length, weekday set, and optional one-sided adjacency (`left` / `right`). - Each item: One custom gap-night rule. `adjustment` is a price multiplier greater than 0 and at most 10 (`0.8` is a 20% discount). `day_of_week` uses 0 = Sunday through 6 = Saturday, unique values only, length 1–7. When several rules match a night, rules without `adjacent` are checked first, then `left`, then `right`. Within those, the rule with the smallest `gap` that still covers the gap wins, and among rules sharing that `gap` the largest `adjustment` wins. - `adjacent` (string, one of: `left`, `right`): Omit to match open nights with an unavailable night on both sides ("In between"). `left` matches the first `gap` open nights after an unavailable night ("Only after"); `right` matches the last `gap` open nights before one ("Only before"). - `adjustment` (number, required): Price multiplier; greater than 0 and at most 10. `0.8` is a 20% discount. - `day_of_week` (array of integer, required, min items: 1, max items: 7, each item min: 0, max: 6): Weekdays this rule applies to (0–6, each at most once). - `gap` (integer, required): Applies to gaps of this many nights or fewer. - `type` (string, required, one of: `CON`, `REC`, `AGG`, `CUS`): Preset strategy (`CON`, `REC`, `AGG`) or custom (`CUS`) gap-night rules. - `minimum_stay_rules_v3` (array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`, default: `[]`): UI: 'Minimum stays' — minimum stay rules. The `_v3` suffix is a stable historical identifier; this field name is not expected to change. - Fields: see `integer_calendar_rule` under Schemas. - `min_stays_enabled` (boolean): Whether minimum stay rules are enabled. - `minimum_price_rules_v3` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): UI: 'Minimum prices' — Minimum price rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. The `_v3` suffix is a stable historical identifier; this field name is not expected to change. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `maximum_price_rules_v3` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): UI: 'Maximum prices' — Maximum price rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. The `_v3` suffix is a stable historical identifier; this field name is not expected to change. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `checkin_checkout` (object, nullable): Which days guests may check in and check out. Rule values are allow flags: `1` allows the day and `0` blocks it. A `day_of_week` rule's `day_of_week_values` has 7 entries, index 0 = Sunday. Where rules overlap, the more specific rule type wins (for example a date-specific `custom` rule over a `day_of_week` rule); between rules of the same type, the later one in the array wins. In a request the object replaces the stored one as a whole: send `active` and both `check_in_rules` and `check_out_rules` (a request missing either array is rejected with 400). An empty `check_out_rules` leaves check-out unrestricted. Example, check-in on Friday and Saturday only, check-out any day: ```json { "active": true, "auto_adjust": false, "check_in_rules": [{"type": "day_of_week", "day_of_week_values": [0, 0, 0, 0, 0, 1, 1]}], "check_out_rules": [{"type": "day_of_week", "day_of_week_values": [1, 1, 1, 1, 1, 1, 1]}] } ``` - `active` (boolean): Whether the check-in/check-out rules are enforced. Stored as `false` when omitted. - `auto_adjust` (boolean): When `true`, Wheelhouse opens additional check-in and check-out days around unavailable nights so that open stretches between bookings can still be booked, even on days the rules would otherwise block. - `check_in_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`): Allowed check-in rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `check_out_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`): Allowed check-out rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `long_term_discounts` (object, default: `{"active":false,"weekly_rules":[],"monthly_rules":[],"rules":{}}`): Rule-based long-term discount configuration. - `active` (boolean) - `weekly_rules` (array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`, **deprecated**): Weekly discount rules (integer calendar rules). - Fields: see `integer_calendar_rule` under Schemas. - `monthly_rules` (array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`, **deprecated**): Monthly discount rules (integer calendar rules). - Fields: see `integer_calendar_rule` under Schemas. - `rules` (map of string to array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`): LOS-keyed rules (integer calendar rules). Keys are length-of-stay thresholds (e.g. "7", "28"); values are arrays of integer calendar rules holding whole percentages (`10` is a 10% discount). On listings that accept length-of-stay premiums (every listing whose `supported_settings.long_term_discount_type` is `complex`, and some with `rules`), values are signed instead, so `-10` is a 10% discount and `10` a 10% premium. - Fields: see `integer_calendar_rule` under Schemas. - `occupancy_pacing` (object `occupancy_pacing`, nullable, default: `{}`): Occupancy pacing configuration. When `occupancy_pacing` is sent as a non-empty object, both `adjusted` and `pacing` are required. Occupancy pacing matrix configuration. `{}` means pacing is off, which is the default for a new listing. When `occupancy_pacing` is sent as a non-empty object, `adjusted` and `pacing` are required, and `pacing` must include a matrix with `type` `global` (otherwise the request is rejected with 400). In a request the object replaces the stored one as a whole; omit it to leave pacing unchanged. For each lead-time column, occupancy is measured across that whole window and the matching row's percentage is applied to every date in it. A row covers occupancy above `min` up to and including `max` (`min` `0` includes 0%); the first matching row wins, and dates outside every column or row are unchanged. The adjusted price still respects the listing's minimum and maximum price rules. - `adjusted` (boolean): When true, occupancy is computed as booked nights divided by bookable (unblocked) nights; when false, against calendar days × units. - `pacing` (array of object `occupancy_pacing_matrix`): Pacing matrices. Must include one with `type` `global`, which is the one applied; others are ignored. - Each item: One pacing matrix (rows × columns of adjustment percentages). - `columns` (array of object `occupancy_pacing_column`, required): Lead-time column definitions; count must match each row in `values`. - Each item: Lead-time window (days from today) for one column of the pacing matrix. - `days_max` (integer, required, min: 0, max: 1000): Inclusive end of lead-time window (0–1000). Must be greater than or equal to `days_min`. - `days_min` (integer, required, min: 0, max: 1000): Inclusive start of lead-time window (0–1000). - `rows` (array of object `occupancy_pacing_row`, required): Occupancy (or revenue) percentage band rows; each `min`/`max` is 0–100 for occupancy pacing. - Each item: Occupancy percentage band for one row of the pacing matrix. - `max` (integer, required, min: 0, max: 100): Upper bound of the band (0–100 inclusive). - `min` (integer, required, min: 0, max: 100): Lower bound of the band (0–100 inclusive). - `type` (string, required): Rule discriminator; `global` is used for the active pacing matrix. - `values` (array of array of integer, required): Price adjustments as whole percentages (`-10` is a 10% decrease, `10` a 10% increase), each ≥ -100. One array per entry in `rows`, each holding one value per entry in `columns`; any other shape is rejected with 400. - `fee_adjustments` (object `fee_adjustments`, nullable): Estimated fee share applied on top of the nightly rate. `null` when nothing is configured, otherwise both keys are present; in a request the object replaces the stored one as a whole, and `null` clears it. UI: 'Asking Rate (+Est. Fees)' — The estimated share of fees guests pay on top of the nightly rate, as a percentage of that rate. It is what `GET /listings/{listing_id}/fee_impact_calendar` returns as a per-date multiplier. A response carries `null` when nothing is configured, otherwise both keys. In a request the object replaces the stored one as a whole, so send both keys; `null` clears the setting. - `total_fee_percentage` (number): Fees as a percentage of the nightly rate, `-100` or more. `15` means guests pay about 15% on top of the nightly rate in fees; there is no upper bound, since fees can exceed the nightly rate on short stays. Omitted means `0`. - `auto_update` (boolean): When `true`, `total_fee_percentage` is recalculated weekly from the fees on the listing's recent reservations, replacing whatever was set. Defaults to `false` when omitted. - `demand_sensitivity_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): Local events rules. Shown as Demand sensitivity before day of week became its own setting; the field name is unchanged. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `historical_anchoring_price_source` (string, one of: `observed`, `posted`, `posted_with_fallback`): Which historical price historical anchoring weighs in. `observed`, the default, is the listing's price as Wheelhouse saw it on the channel once the date booked. `posted` is the price Wheelhouse last posted for the date before it booked, so dates Wheelhouse never posted a price for are not anchored. `posted_with_fallback` uses the posted price where there is one and the observed price otherwise. - `historical_anchoring_mode` (string, one of: `blended`, `anchor_only`): How a historical anchoring percentage turns the historical price into a floor for the recommendation. `blended` averages the historical price with the recommendation, using the percentage as the weight on the historical price: at 50%, a $1,200 historical price and a $400 recommendation give $800. `anchor_only` takes the percentage of the historical price alone, so at 50% the floor is $600: a $400 recommendation rises to $600 and a $700 one stays at $700. Either only ever raises a price, and from 100% up both give the same price. - `historical_anchoring_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): Historical anchoring rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `custom_date_ranges` (array of object `custom_date_range`, default: `[]`): Represents an Event or Season entry used by the Wheelhouse Events & Seasons feature. Calendar rules reference these entries by `id` to apply settings (e.g. min stay, pricing) over named date windows. Each listing stores its own copy of every Event or Season it belongs to. Entries for the same event or season share the same `id` across listings — this shared `id` is what enables bulk adjustments in the Wheelhouse UI. If you write a `custom_date_ranges` entry with a new or changed `id`, that listing's entry is no longer linked to the others and will not be included in future bulk edits of the original Event or Season. To safely modify an event or season's definition (dates or name) on one listing without affecting others, omit the `id` field — the server assigns a new independent ID scoped to that listing. To update only a rule value (e.g. raise the minimum price) without changing dates, include the existing `id` unchanged. A new `custom_date_ranges` entry and a rule referencing it can be submitted in the same PUT request. Manually assign an `id` on the new entry so that the referencing rule can use it in the same payload. Alternatively, use two sequential PUTs: the first PUT creates the entry without an `id` (the server assigns one, returned in the response); the second PUT adds the rule referencing that server-assigned `id`. - Each item: Represents an Event or Season entry used by the Wheelhouse Events & Seasons feature. Calendar rules reference these entries by `id` to apply settings (e.g. min stay, pricing) over named date windows. Each listing stores its own copy of every Event or Season it belongs to. Entries for the same event or season share the same `id` across listings — this shared `id` is what enables bulk adjustments in the Wheelhouse UI. If you write a `custom_date_ranges` entry with a new or changed `id`, that listing's entry is no longer linked to the others and will not be included in future bulk edits of the original Event or Season. To safely modify an event or season's definition (dates or name) on one listing without affecting others, omit the `id` field — the server assigns a new independent ID scoped to that listing. To update only a rule value (e.g. raise the minimum price) without changing dates, include the existing `id` unchanged. - `date_ranges` (array of object `custom_date_range_segment`, required): One or more inclusive calendar spans. Each span must include `start_date` and `end_date`, and `start_date` must be on or before `end_date`. - Each item: Inclusive calendar span within a custom date range. - `end_date` (string (date), required): Inclusive end (ISO-8601 date). - `start_date` (string (date), required): Inclusive start (ISO-8601 date). - `id` (string): Stable identifier for this range, referenced by calendar rules. Listings that share the same `id` for an entry are considered part of the same Event or Season and can be bulk-edited together. Preserve the existing `id` when updating an entry to keep it linked; omit only when creating a new range (one will be assigned). The server always returns this field as a string. Calendar rule `id` fields accept both string and integer for backward compatibility, but the canonical type is string — use string comparisons when matching rule `id` values against `custom_date_ranges` entries. - `name` (string, required): Display name for the season or event. - `type` (string, required, one of: `event`, `seasonal`): Whether this range represents a recurring season or a dated event. - `yearly` (boolean, required): When true, the date spans repeat each calendar year (same month/day pattern). - `min_min_price` (integer, default: `0`): UI: 'Absolute minimum price' — Hard lower bound that overrides all pricing rules. No recommended price will fall below this value regardless of any rule configuration. Distinct from a `global` rule in `minimum_price_rules_v3`, which can be overridden by higher-priority rules. Must be an integer (whole currency units). - `min_min_stay` (integer, default: `0`): UI: 'Absolute minimum stay' — Hard lower bound that overrides all minimum stay rules. No minimum stay will be set below this value regardless of any rule configuration. Distinct from both a `global` rule in `minimum_stay_rules_v3` (which can be overridden by higher-priority rules) and from `global_min_stay` in the price recommendations response (which reflects the current effective default rule value, not a hard floor). - `apply_gap_night_rules_to_overrides` (boolean): UI: 'Apply Gap Night Rules to Overrides' — When `true`, gap-night minimum stay rules take priority over custom (date override) rules. When `false` (default), custom rules win over gap-night rules. - `price_model` (string, one of: `current`, `opt_in`): The price model version to use. `current` is the model the listing gets without a pick of its own. `opt_in` is the opt-in model, and returns `400` when there are several; pass `price_model_id` instead. With no opt-in model, `opt_in` uses the price model currently active for the listing, as does omitting the parameter. - `price_model_id` (integer): The ID of a price model to use, instead of `price_model`, from [GET /price_models](https://docs.usewheelhouse.com/rm/reference/rm-get-price-models.md). It must be one the listing can use and that has run for the listing's market, or the request returns `400`. ### Example request ```bash curl -X POST 'https://api.usewheelhouse.com/ss_api/v1/preferences/{listing_id}/preview?channel=' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{}' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 201 Preview price recommendations. Body (`application/json`): object - `data` (array of object `recommendations_response_data_item`): Daily recommendations with the same structure as `GET /listings/{listing_id}/price_recommendations`. `min_stay` comes from the listing's min stay settings with the request's changes applied, so a min stay change shows up here. - Each item: One day of price recommendations. The `attr_*` and `historical_anchor_*` fields are present only when the request sets `attribution=true`. - `stay_date` (string (date), required): The date of the given price info (YYYY-MM-DD). - `price` (number, required): The recommended nightly price for this day. - `currency` (string, required): The ISO-4217 3-letter currency code of the price. - `min_stay` (integer, nullable): The minimum stay applied to reservations overlapping this day. Omitted unless min stays are configured. This is the final value after every rule in `minimum_stay_rules_v3` and the `min_min_stay` floor. It does not say which rule set it. See [How minimum stay rules combine](https://docs.usewheelhouse.com/rm/concepts/preferences-rules.md#how-minimum-stay-rules-combine) for the precedence and a worked example. - `min_price` (integer, nullable): The minimum price applied to this day, in `currency`: the higher of the listing's minimum price rule for the date and its absolute minimum price (`min_min_price`). On a day with a fixed custom rate the minimum price rules do not apply, so only the absolute minimum price counts. `price` is never below it. In a preview, it reflects the previewed preferences. `null` when no minimum applies to the day. - `custom_type` (string, nullable, one of: `adjusted`, `fixed`): Reflects if this price is based on a custom rate. `null` means this is the Wheelhouse recommendation; `fixed` means a fixed custom price; `adjusted` means a percentage adjustment. Note: the `adjusted` value here corresponds to `rate_type: "adjustment"` when writing via `PUT /listings/{listing_id}/custom_rates` — the form differs between write (`adjustment`) and read (`adjusted`). - `events` (array of object): The events in the listing's market that run over this date. An empty array means no event runs over the date. Several events can run over one date. Only returned by `GET /listings/{listing_id}/price_recommendations`, not by `POST /preferences/{listing_id}/preview`. - `title` (string, required, example: `Jazz Festival`): The name of the event. - `start_date` (string (date), required): The first date of the event (YYYY-MM-DD). - `end_date` (string (date), required): The last date of the event (YYYY-MM-DD), inclusive. - `attr_seasonality` (integer): Seasonality attribution. Only present if `attribution=true`. - `attr_local_demand` (integer): Local demand attribution. Only present if `attribution=true`. - `attr_availability` (integer): Availability/gap night attribution. Only present if `attribution=true`. - `attr_time` (integer): Time-based attribution. Only present if `attribution=true`. - `attr_custom_weekend` (integer): Day of week attribution. Only present if `attribution=true`. - `attr_scarcity` (integer): Scarcity attribution. Only present if `attribution=true`. - `attr_occupancy_pacing` (integer): Occupancy pacing attribution. Only present if `attribution=true`. - `attr_historical_anchoring` (integer): Historical anchoring attribution. Only present if `attribution=true`. - `attr_restriction` (integer): Min/max restriction attribution. Only present if `attribution=true`. - `attr_user_adjustment` (integer): User customization attribution. Only present if `attribution=true`. - `historical_anchor_date` (string (date)): The earlier date whose price historical anchoring held this date's recommendation up to: the same day of the week, in the same week a year earlier, or two years earlier when that date has no price. Only present if `attribution=true` and historical anchoring raised this date's price, with `attr_historical_anchoring` saying by how much. - `historical_anchor_pct` (number): The historical anchoring percentage in effect for this date, from the listing's `historical_anchoring_rules`, applied as `historical_anchoring_mode` describes. Present with `historical_anchor_date`. - `historical_anchor_price` (integer): The price on `historical_anchor_date` that anchoring weighed in, in this response's `currency`. Present with `historical_anchor_date`. - `historical_anchor_source` (string, one of: `observed`, `posted`): Where `historical_anchor_price` comes from: `observed`, the listing's price as Wheelhouse saw it on the channel once the date booked, or `posted`, the price Wheelhouse last posted for the date before it booked. Present with `historical_anchor_date`. - `base_price` (integer, nullable): The base price the preview recommendations are computed from, given the preference changes in the request body. This is the manual `base_price` when one is set, otherwise `base_price_recommended` multiplied by `base_price_adjustment`. - `base_price_recommended` (integer, nullable): The Wheelhouse-recommended base price given the hypothetical preference changes in the request body. - `base_price_conservative` (integer, nullable): Conservative base price variant (10% below `base_price_recommended`). - `base_price_aggressive` (integer, nullable): Aggressive base price variant (10% above `base_price_recommended`). - `supported_settings` (object `supported_settings`, read-only): Which listing preference settings this listing's channel can act on. A setting reported `false` is discarded on write rather than posted to the channel, so check this before sending it. Reflects any per-account early access, so two listings on the same channel can differ. - `checkin_checkout` (boolean): Whether `checkin_checkout` rules can be set. - `min_stays` (boolean): Whether minimum stay settings (`min_min_stay`, `min_stays_enabled`, `minimum_stay_rules`) can be set. - `long_term_discounts` (boolean): Whether long-term discounts (`long_term_discounts`, `weekly_discount`, `monthly_discount`) can be set at all. - `long_term_discount_type` (string, one of: `disabled`, `simple`, `rules`, `complex`): The form of long-term discount the channel accepts. `disabled` takes none; `simple` takes only flat `weekly_discount` and `monthly_discount` values and ignores a `rules` object; `rules` additionally takes the 7 and 28 night tiers; `complex` takes arbitrary tiers. - `warnings` (array of object `preference_warning`, each item read-only): Settings in the request this listing's channel cannot act on. They were excluded from the preview as well as from writes, so the recommendations above reflect what the channel would actually do. Empty when everything applied. See the [Listing Preferences](https://docs.usewheelhouse.com/rm/concepts/preferences.md) section. - Each item: One setting in the request that was not applied, or that has no effect on this listing. - `setting` (string, one of: `checkin_checkout`, `gap_night`, `min_stays`, `long_term_discounts`): The setting group the warning is about. - `reason` (string, one of: `not_supported_by_channel`, `partially_supported_by_channel`, `not_supported_for_multi_unit`): `not_supported_by_channel` — the channel has no such feature and everything sent for it was dropped. `partially_supported_by_channel` — the channel has the feature but accepts a narrower form than what was sent, and only the excess was dropped. `not_supported_for_multi_unit` — the setting is stored but has no effect on price, because the listing has more than one unit. - `message` (string): A human-readable explanation of what was ignored and why. - `attributes` (array of string): The request attributes this warning covers, in dot notation for nested ones (e.g. `long_term_discounts.rules.14`). Example shape (generated from the schema; placeholder values, not a real response): ```json { "data": [ { "stay_date": "2026-01-01", "price": 0, "currency": "string", "min_stay": 0, "min_price": 0, "custom_type": "adjusted", "events": [ { "title": "Jazz Festival", "start_date": "2026-01-01", "end_date": "2026-01-01" } ], "attr_seasonality": 0, "attr_local_demand": 0, "attr_availability": 0, "attr_time": 0, "attr_custom_weekend": 0, "attr_scarcity": 0, "attr_occupancy_pacing": 0, "attr_historical_anchoring": 0, "attr_restriction": 0, "attr_user_adjustment": 0, "historical_anchor_date": "2026-01-01", "historical_anchor_pct": 0, "historical_anchor_price": 0, "historical_anchor_source": "observed" } ], "base_price": 0, "base_price_recommended": 0, "base_price_conservative": 0, "base_price_aggressive": 0, "supported_settings": { "checkin_checkout": true, "min_stays": true, "long_term_discounts": true, "long_term_discount_type": "disabled" }, "warnings": [ { "setting": "checkin_checkout", "reason": "not_supported_by_channel", "message": "string", "attributes": [ "string" ] } ] } ``` ### 400 A setting in the request has the wrong shape; the message names the field. ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 422 Listing is not covered by a Wheelhouse market. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` ## Schemas Shared by more than one field above. ### `calendar_rule_time_based` Type: object `calendar_rule_time_based` **time_based** — Relative to "today" for the listing. At least one of `days_before` or `days_after` must be set. Provide `value` or `day_of_week_values`, not both. Optional `months` scopes by calendar month. When only `days_before` is set, the rule applies to dates within that many days of today (last-minute window). When only `days_after` is set, the rule applies to dates at least that many days away (far-future window). When both are set, the rule applies to dates that satisfy both conditions simultaneously — at least `days_after` days away AND within `days_before` days — creating a mid-booking-window band. `days_before` must be greater than or equal to `days_after` when both are provided. **time_based** — Relative to “today” for the listing. At least one of `days_before` or `days_after` must be set. Provide `value` or `day_of_week_values`, not both. Optional `months` scopes by calendar month. When only `days_before` is set, the rule applies to dates within that many days of today (last-minute window). When only `days_after` is set, the rule applies to dates at least that many days away (far-future window). When both are set, the rule applies to dates that satisfy both conditions simultaneously — at least `days_after` days away AND within `days_before` days — creating a mid-booking-window band. `days_before` must be greater than or equal to `days_after` when both are provided. - `type` (string, required, one of: `time_based`) - `days_after` (integer, nullable): Applies on/after “today + days_after”. When combined with `days_before`, creates a mid-window band (see rule description). `null` when this side of the window is unset. - `days_before` (integer, nullable): Applies within “today + days_before”. Must be >= `days_after` when both are set. `null` when this side of the window is unset. - `months` (array of integer, min items: 1, each item min: 1, max: 12): When set, restrict to these month ordinals (1–12). - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number) ### `calendar_rule_seasonal` Type: object `calendar_rule_seasonal` **seasonal** — Tied to a custom seasonal date range. Set `id` to the custom range. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `seasonal`) - `id` (integer | string, required): Custom seasonal date-range identifier. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number) ### `calendar_rule_event` Type: object `calendar_rule_event` **event** — Tied to a custom event date range. Set `id` to the custom range. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `event`) - `id` (integer | string, required): Custom event / date-range identifier. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number) ### `calendar_rule_monthly_simple` Type: object `calendar_rule_monthly_simple` **monthly** — Limited to specific `months`. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `monthly`) - `months` (array of integer, required, min items: 1, each item min: 1, max: 12): Month ordinals (1–12); at least one. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number) ### `calendar_rule_day_of_week` Type: object `calendar_rule_day_of_week` **day_of_week** — Per weekday (7 values, Sunday-first). Optional `months` limits to those month ordinals. Must not combine with `days_before` / `days_after` (use `time_based` for that). - `type` (string, required, one of: `day_of_week`) - `months` (array of integer, min items: 1, each item min: 1, max: 12): When set, restrict to these month ordinals (1–12). - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, required, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. ### `calendar_rule_custom` Type: object `calendar_rule_custom` **custom** — Fixed calendar date range. `start_date` and `end_date` inclusive; optional `yearly` repeats each year. Provide `value` or `day_of_week_values`, not both. UI: 'Date-specific overrides.' Not related to `custom_date_ranges` (Events & Seasons), Custom Rates, or the `CUS` preset type. - `type` (string, required, one of: `custom`) - `end_date` (string (date), required): Inclusive end (ISO-8601 date). - `id` (integer | string): Server-assigned identifier, returned as a string when present. On `checkin_checkout` rules it pairs a check-in rule with its check-out rule and is derived from the rule's contents, so it changes when the rule changes (on `seasonal` and `event` rules it is the season or event id instead). Requests don't use it to identify a rule, so don't store it as a stable key. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `start_date` (string (date), required): Inclusive start (ISO-8601 date). - `yearly` (boolean): When true, repeat the same month/day span every year. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number): Single value for dates in range when `day_of_week_values` is not used. ### `integer_calendar_rule` Type: object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule` Integer calendar rules (minimum stay, min/max price caps, local events, check-in/out, long-term discounts, etc.). - One of: - **calendar_rule_adjacency_int** (object `calendar_rule_adjacency_int`): Integer-valued adjacency / one-sided gap rule (same semantics as `calendar_rule_adjacency`). Only used in `minimum_stay_rules_v3` (MLOS behavior). Not related to the `gap_night` pricing setting. - `type` (string, required, one of: `adjacency`, `one_sided_gap`): Use `adjacency` or legacy `one_sided_gap` (same behavior). - `adjustment` (integer): Add to the existing calendar value instead of replacing it. - `day_of_week_adjustments` (array of integer, min items: 7, max items: 7, each item nullable): Per-day adjustments (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `days_adjacent` (integer, required): Window of adjacent days (negative = prior side, positive = subsequent side). To match both sides, use two separate rules — one with a negative value and one with a positive value. When both rules fire on the same date, the negative rule's value takes precedence (it is evaluated last and overwrites the positive rule's result). - `days_after` (integer): Legacy alias retained on some stored adjacency rules. Prefer `days_adjacent`. - `days_one_sided_gap` (integer): Legacy alias retained on some stored adjacency rules. Prefer `days_adjacent`. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day minimums (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer): Single minimum when `day_of_week_values` is not used. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_gap_int** (object `calendar_rule_gap_int`): **gap** — When `gap_enabled` is true, applies a minimum stay only for "gap" nights that cannot fit the normal min stay. Provide `value` or `day_of_week_values` for the gap minimum. Optional `days_before` / `days_after` scope the rule in time. Only used in `minimum_stay_rules_v3` (MLOS behavior). Not related to the `gap_night` pricing setting. **gap** — When `gap_enabled` is true, applies a minimum stay only for “gap” nights that cannot fit the normal min stay. Provide `value` or `day_of_week_values` for the gap minimum. Optional `days_before` / `days_after` scope the rule in time. - `type` (string, required, one of: `gap`) - `days_after` (integer) - `days_before` (integer) - `gap_enabled` (boolean, required, one of: `true`) - `gap_flexibility` (integer): Reduces effective min stay in the gap by this many nights. It will never drop below `value`. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day gap minimums (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer): Gap minimum stay (integer in typical min-stay rules). - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. ### `calendar_rule_global_int` Type: object `calendar_rule_global_int` **global** — Single default for the calendar in this rule set. Must not set `day_of_week_values`. UI: 'Default' or 'Minimum price default' (label varies by setting). - `type` (string, required, one of: `global`) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `value` (integer, required): Default value (non-negative). ### `calendar_rule_time_based_int` Type: object `calendar_rule_time_based_int` **time_based** — Relative to "today" for the listing. At least one of `days_before` or `days_after` must be set. Provide `value` or `day_of_week_values`, not both. Optional `months` scopes by calendar month. When only `days_before` is set, the rule applies to dates within that many days of today (last-minute window). When only `days_after` is set, the rule applies to dates at least that many days away (far-future window). When both are set, the rule applies to dates that satisfy both conditions simultaneously — at least `days_after` days away AND within `days_before` days — creating a mid-booking-window band. `days_before` must be greater than or equal to `days_after` when both are provided. **time_based** — Relative to “today” for the listing. At least one of `days_before` or `days_after` must be set. Provide `value` or `day_of_week_values`, not both. Optional `months` scopes by calendar month. When only `days_before` is set, the rule applies to dates within that many days of today (last-minute window). When only `days_after` is set, the rule applies to dates at least that many days away (far-future window). When both are set, the rule applies to dates that satisfy both conditions simultaneously — at least `days_after` days away AND within `days_before` days — creating a mid-booking-window band. `days_before` must be greater than or equal to `days_after` when both are provided. - `type` (string, required, one of: `time_based`) - `days_after` (integer, nullable): Applies on/after “today + days_after”. When combined with `days_before`, creates a mid-window band (see rule description). `null` when this side of the window is unset. - `days_before` (integer, nullable): Applies within “today + days_before”. Must be >= `days_after` when both are set. `null` when this side of the window is unset. - `months` (array of integer, min items: 1, each item min: 1, max: 12): When set, restrict to these month ordinals (1–12). - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer) ### `calendar_rule_seasonal_int` Type: object `calendar_rule_seasonal_int` **seasonal** — Tied to a custom seasonal date range. Set `id` to the custom range. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `seasonal`) - `id` (integer | string, required): Custom seasonal date-range identifier. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer) ### `calendar_rule_event_int` Type: object `calendar_rule_event_int` **event** — Tied to a custom event date range. Set `id` to the custom range. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `event`) - `id` (integer | string, required): Custom event / date-range identifier. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer) ### `calendar_rule_monthly_int` Type: object `calendar_rule_monthly_int` **monthly** — Limited to specific `months`. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `monthly`) - `months` (array of integer, required, min items: 1, each item min: 1, max: 12): Month ordinals (1–12); at least one. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer): Single value for the month. ### `calendar_rule_day_of_week_int` Type: object `calendar_rule_day_of_week_int` **day_of_week** — Per weekday (7 values, Sunday-first). Optional `months` limits to those month ordinals. Must not combine with `days_before` / `days_after` (use `time_based` for that). - `type` (string, required, one of: `day_of_week`) - `months` (array of integer, min items: 1, each item min: 1, max: 12): When set, restrict to these month ordinals (1–12). - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, required, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. ### `calendar_rule_custom_int` Type: object `calendar_rule_custom_int` **custom** — Fixed calendar date range. `start_date` and `end_date` inclusive; optional `yearly` repeats each year. Provide `value` or `day_of_week_values`, not both. UI: 'Date-specific overrides.' Not related to `custom_date_ranges` (Events & Seasons), Custom Rates, or the `CUS` preset type. - `type` (string, required, one of: `custom`) - `end_date` (string (date), required): Inclusive end (ISO-8601 date). - `id` (integer | string): Server-assigned identifier, returned as a string when present. On `checkin_checkout` rules it pairs a check-in rule with its check-out rule and is derived from the rule's contents, so it changes when the rule changes (on `seasonal` and `event` rules it is the season or event id instead). Requests don't use it to identify a rule, so don't store it as a stable key. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `start_date` (string (date), required): Inclusive start (ISO-8601 date). - `yearly` (boolean): When true, repeat the same month/day span every year. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer): Single value for dates in range when `day_of_week_values` is not used. --- # Get base price recommendation options for a listing. `GET /listings/{listing_id}/base_price_recommendation` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-base-price-recommendation · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetBasePriceRecommendation` · Tag: Recommendations Returns recommended, conservative, and aggressive base prices, the listing's active base price, anchoring fields (`anchor_price`, `anchor_credibility`), and a consolidated `base_price_attribution` object aligned with the Wheelhouse app Recommended Breakdown. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/base_price_recommendation` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | | `currency` | string | no | ISO-4217 3-letter currency code (e.g. 'USD', 'GBP') to convert prices to. Uses listing's currency by default. | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/base_price_recommendation?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Base price recommendation options and breakdown. Body (`application/json`): object `base_price_recommendation` Recommended and selected base prices, anchoring context, and a consolidated attribution breakdown. Monetary fields use the response `currency` (listing currency by default, or the `currency` query parameter); amounts are converted from the listing market currency inside Wheelhouse. - `base_price_recommended` (integer, required): Recommended base nightly price. - `base_price_conservative` (integer, required): Conservative variant. - `base_price_aggressive` (integer, required): Aggressive variant. - `base_price_selected` (integer, required): The base price in use for the listing, which its price recommendations are computed from. This is the manual `base_price` from `GET /preferences/{listing_id}` when one is set (converted to this response's `currency` when that differs), otherwise `base_price_recommended` multiplied by the preference `base_price_adjustment`. Unlike the preference `base_price`, it is never `null`. - `anchor_credibility` (number, required, min: 0, max: 100): Effective anchoring strength as a percentage. Reflects how much observed booking history is incorporated into the base price recommendation (aligns with "credibility" in the Wheelhouse app). - **0%**: No usable booking data — new listing, no qualifying bookings in the past 2 years, or anchoring disabled. - **~90% (typical maximum)**: Full booking history available. - **Intermediate values**: Ramps linearly with booking volume (approaching full weight around 30 effective booked nights over 2 years) and booking distribution uniformity across the calendar year. Higher values mean the base price is more influenced by the listing's own historical booking prices and less by the market model. See `base_price_attribution.observed_bookings` for the dollar-amount contribution anchoring adds to the recommendation. - `anchor_price` (integer, required, nullable): Median observed booking price used in anchoring, when available. - `base_price_attribution` (object `base_price_attribution`, required): Consolidated signed amounts (in the response `currency`) for the Wheelhouse recommended base price breakdown, grouped to match the in-app "Recommended Breakdown" rows. Values are integers (rounded). - `market_baseline` (integer, required): Market-wide average listing price. - `bedrooms_bathrooms` (integer, required): Combined impact of bedroom and bathroom count. - `room_type` (integer, required): Room / listing type impact. - `guests` (integer, required): Combined impact of sleeps, extra guest fee, and included-guests positioning. - `location` (integer, required): Location specific impact. - `amenities_fees` (integer, required): Combined impact of amenities, cleaning fee, photo count, and security deposit. - `occupancy` (integer, required): Impact of occupancy positioning vs market. - `observed_bookings` (integer, required): Effect of observed median booking price vs the pure model price. - `currency` (string, required): ISO-4217 code all monetary amounts are expressed in. Example shape (generated from the schema; placeholder values, not a real response): ```json { "base_price_recommended": 0, "base_price_conservative": 0, "base_price_aggressive": 0, "base_price_selected": 0, "anchor_credibility": 0, "anchor_price": 0, "base_price_attribution": { "market_baseline": 0, "bedrooms_bathrooms": 0, "room_type": 0, "guests": 0, "location": 0, "amenities_fees": 0, "occupancy": 0, "observed_bookings": 0 }, "currency": "string" } ``` ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 422 Listing is not covered by a Wheelhouse market. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get check-in/check-out calendar for a listing. `GET /listings/{listing_id}/checkin_checkout` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-checkin-checkout · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetCheckinCheckout` · Tag: Recommendations Returns a daily calendar of check-in and check-out rules. Returns 204 if check-in/check-out rules are not configured for the listing. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/checkin_checkout` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/checkin_checkout?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Check-in/check-out calendar. Body (`application/json`): object `checkin_checkout_response` Daily check-in and check-out rules. - `data` (array of object `checkin_checkout_day`, required): Daily check-in/check-out rules. - `stay_date` (string (date), required): The date of the given price info (YYYY-MM-DD). - `check_in` (boolean, required): Value of `true` if check-in is allowed. - `check_out` (boolean, required): Value of `true` if check-out is allowed. Example shape (generated from the schema; placeholder values, not a real response): ```json { "data": [ { "stay_date": "2026-01-01", "check_in": true, "check_out": true } ] } ``` ### 204 Check-in/check-out is not configured for this listing. ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get minimum and maximum price calendar for a listing. `GET /listings/{listing_id}/min_max_prices` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-min-max-prices · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetMinMaxPrices` · Tag: Recommendations ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/min_max_prices` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/min_max_prices?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Min/max price calendar. Body (`application/json`): object `min_max_prices_response` Daily minimum and maximum prices. - `data` (array of object `min_max_price_day`, required) - `stay_date` (string (date), required): The stay date (YYYY-MM-DD). - `min_price` (number, nullable): The minimum price for this date. - `max_price` (number, nullable): The maximum price for this date. Example shape (generated from the schema; placeholder values, not a real response): ```json { "data": [ { "stay_date": "2026-01-01", "min_price": 0, "max_price": 0 } ] } ``` ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get recommended monthly seasonality adjustment factors for a listing. `GET /listings/{listing_id}/monthly_seasonality` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-monthly-seasonality · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetMonthlySeasonality` · Tag: Recommendations Returns conservative (CON), recommended (REC), and aggressive (AGG) seasonality multipliers grouped by month number (1–12). The factors represent the average seasonality multiplier for each month based on market data and can be used to understand seasonal pricing patterns. A factor of 1.0 means no seasonal adjustment, values above 1.0 indicate higher demand periods, and values below 1.0 indicate lower demand periods. The three levels differ in how much they amplify the seasonality signal: - CON: 80% of the base seasonality variation - REC: 100% of the base seasonality variation - AGG: 120% of the base seasonality variation ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/monthly_seasonality` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/monthly_seasonality?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Monthly seasonality factors. Body (`application/json`): object Object with keys `CON`, `REC`, and `AGG`, each mapping month numbers (as strings, "1"–"12") to a seasonality multiplier. - `CON` (object `monthly_seasonality_factors`): Conservative seasonality factors by month number. Seasonality factor multipliers by calendar month (string keys "1" through "12"). - Fields: see `monthly_seasonality_factors` under Schemas. - `REC` (object `monthly_seasonality_factors`): Recommended seasonality factors by month number. Seasonality factor multipliers by calendar month (string keys "1" through "12"). - Fields: see `monthly_seasonality_factors` under Schemas. - `AGG` (object `monthly_seasonality_factors`): Aggressive seasonality factors by month number. Seasonality factor multipliers by calendar month (string keys "1" through "12"). - Fields: see `monthly_seasonality_factors` under Schemas. Example shape (generated from the schema; placeholder values, not a real response): ```json { "CON": { "1": 0, "2": 0, "3": 0, "4": 0, "5": 0, "6": 0, "7": 0, "8": 0, "9": 0, "10": 0, "11": 0, "12": 0 }, "REC": { "1": 0, "2": 0, "3": 0, "4": 0, "5": 0, "6": 0, "7": 0, "8": 0, "9": 0, "10": 0, "11": 0, "12": 0 }, "AGG": { "1": 0, "2": 0, "3": 0, "4": 0, "5": 0, "6": 0, "7": 0, "8": 0, "9": 0, "10": 0, "11": 0, "12": 0 } } ``` ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` ## Schemas Shared by more than one field above. ### `monthly_seasonality_factors` Type: object `monthly_seasonality_factors` Seasonality factor multipliers by calendar month (string keys "1" through "12"). - `1` (number): The seasonality factor for January. - `2` (number): The seasonality factor for February. - `3` (number): The seasonality factor for March. - `4` (number): The seasonality factor for April. - `5` (number): The seasonality factor for May. - `6` (number): The seasonality factor for June. - `7` (number): The seasonality factor for July. - `8` (number): The seasonality factor for August. - `9` (number): The seasonality factor for September. - `10` (number): The seasonality factor for October. - `11` (number): The seasonality factor for November. - `12` (number): The seasonality factor for December. --- # Retrieve preferences for a batch of listings. `GET /preferences` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-preferences-batch · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetPreferencesBatch` · Tag: Listing Preferences ## Request `GET https://api.usewheelhouse.com/ss_api/v1/preferences` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | | `listing_ids` | array of string | no | Array of channel listing IDs to retrieve preferences for, or Wheelhouse listing IDs when `channel` is `wheelhouse`. Send more than one in brackets (`?listing_ids[]=A&listing_ids[]=B`); a key repeated without brackets keeps only its last value. If omitted, returns an empty array — it does not default to all listings. Always provide explicit listing IDs. This endpoint has no pagination; all matched preferences are returned in a single response. | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/preferences?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of listing preferences. Body (`application/json`): array of object `listing_preference_response` The full set of pricing preferences for a listing. - `listing_id` (integer, read-only): The Wheelhouse internal listing ID. - `partner_listing_id` (string, read-only): The channel's listing ID. - `currency` (string, nullable, read-only): The currency used for prices in this listing's preferences. - `automatic_rate_posting_enabled` (boolean): Whether Wheelhouse automatically posts prices to the channel calendar. When `false`, recommendations are computed but nothing is pushed to the channel. - `base_price` (number, nullable): The base price the user set by hand, in the preferences `currency`. When set, the pricing engine uses it instead of the Wheelhouse recommendation, and `base_price_adjustment` is `null`. `null` does **not** mean the listing has no base price. It means the base price follows the Wheelhouse recommendation, multiplied by `base_price_adjustment` (or by `1.0` when that is also `null`). To read the base price in use, call `GET /listings/{listing_id}/price_recommendations` and read its top-level `base_price`. Set to `null` to go back to the Wheelhouse recommendation, or set a preset with `PUT /preferences/{listing_id}/base_price_adjustment` and `type` `CON`, `REC`, or `AGG`. - `base_price_adjustment` (number, nullable): The multiplier the pricing engine applies to the Wheelhouse recommended base price (`base_price_recommended` on `GET /listings/{listing_id}/price_recommendations`) when `base_price` is `null`. The presets are `0.9` (conservative, `CON`), `1.0` (recommended, `REC`), and `1.1` (aggressive, `AGG`). Any other value is a custom adjustment, for example `1.05` for 5% above the recommendation. For example, with `base_price_recommended` 200 and `base_price_adjustment` `0.9`, the base price in use is 180, and `base_price` here is `null`. `null` when `base_price` is set, because the manual base price applies instead. Both fields can also be `null`, for example after a manual base price is cleared. The pricing engine then uses `1.0`, the recommended preset. - `monthly_discount` (integer, nullable, default: `0`): Monthly discount percentage as an integer in the range 0–100 (e.g. `5` = 5%). On listings that accept length-of-stay premiums (every listing whose `supported_settings.long_term_discount_type` is `complex`, and some with `rules`), values are signed instead, so `-10` is a 10% discount and `10` a 10% premium. Applied to bookings ≥ 28 nights. Kept in sync with the global rule in `long_term_discounts.rules['28']` — setting one automatically updates the other. When both are sent in the same PUT, `long_term_discounts` takes precedence. - `weekly_discount` (integer, nullable, default: `0`): Weekly discount percentage as an integer in the range 0–100 (e.g. `5` = 5%). On listings that accept length-of-stay premiums (every listing whose `supported_settings.long_term_discount_type` is `complex`, and some with `rules`), values are signed instead, so `-10` is a 10% discount and `10` a 10% premium. Applied to bookings ≥ 7 nights. Kept in sync with the global rule in `long_term_discounts.rules['7']` — setting one automatically updates the other. When both are sent in the same PUT, `long_term_discounts` takes precedence. - `nickname` (string, nullable): Listing nickname. - `last_minute_discount` (object, nullable): UI: 'Last minute' — Last-minute discount configuration. - `type` (string, one of: `CON`, `REC`, `AGG`, `CUS`) - `rules` (array of object `calendar_rule_time_based` | object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly_simple` | object `calendar_rule_day_of_week` | object `calendar_rule_custom`): Calendar rules when `type` is `CUS`. Valid rule types: `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_time_based**: see `calendar_rule_time_based` under Schemas. - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly_simple**: see `calendar_rule_monthly_simple` under Schemas. - **calendar_rule_day_of_week**: see `calendar_rule_day_of_week` under Schemas. - **calendar_rule_custom**: see `calendar_rule_custom` under Schemas. - `smooth` (boolean, default: `false`): UI: 'Smooth' — Only used when `type` is `CUS`. When `true`, the adjustment eases gradually from one rule to the next instead of jumping at each rule's edge. `custom` rules still apply exactly. Defaults to `false` (stepped). - `far_future_premium` (object, nullable): UI: 'Far future' — Far-future premium configuration. - `type` (string, one of: `CON`, `REC`, `AGG`, `CUS`) - `rules` (array of object `calendar_rule_time_based` | object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly_simple` | object `calendar_rule_day_of_week` | object `calendar_rule_custom`): Calendar rules when `type` is `CUS`. Valid rule types: `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_time_based**: see `calendar_rule_time_based` under Schemas. - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly_simple**: see `calendar_rule_monthly_simple` under Schemas. - **calendar_rule_day_of_week**: see `calendar_rule_day_of_week` under Schemas. - **calendar_rule_custom**: see `calendar_rule_custom` under Schemas. - `smooth` (boolean, default: `false`): UI: 'Smooth' — Only used when `type` is `CUS`. When `true`, the adjustment eases gradually from one rule to the next instead of jumping at each rule's edge. `custom` rules still apply exactly. Defaults to `false` (stepped). - `seasonality_adjustment` (object, nullable): UI: 'Seasonality' — Seasonality adjustment configuration. - `type` (string, one of: `CON`, `REC`, `AGG`, `CUS`) - `rules` (array of object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly`): Calendar rules when `type` is `CUS`. Valid rule types: `seasonal`, `event`, `monthly`. - One of: - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly** (object `calendar_rule_monthly`): **monthly** — Limited to specific `months`. Provide `value` or `day_of_week_values`, not both. For linear interpolation (`step: false`), set `start_value` and `end_value` with the peak in `value`. Linear interpolation is only honored in the `seasonality_adjustment` setting, and not when `smooth` is `true`. - `type` (string, required, one of: `monthly`) - `months` (array of integer, required, min items: 1, each item min: 1, max: 12): Month ordinals (1–12); at least one. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `end_value` (number): Value at month end for linear interpolation when `step` is false. - `start_value` (number): Value at month start for linear interpolation when `step` is false. - `step` (boolean): When true, stepped monthly values; when false, linear interpolation using `start_value`, `value` (peak), and `end_value`. Ignored in `seasonality_adjustment` when `smooth` is `true`. - `value` (number): Single value for the month or peak value when interpolating. - `smooth` (boolean, default: `false`): UI: 'Smooth' — Only used when `type` is `CUS`. When `true`, the adjustment eases gradually from one rule to the next instead of jumping at each rule's edge, and monthly rules' `step`, `start_value` and `end_value` are ignored. Defaults to `false` (stepped). - `day_of_week` (object, nullable): Day-of-week pricing factor configuration. - `REC` applies the market's day-of-week pattern. - `CON` and `AGG` adjust that pattern conservatively or aggressively. Sent without `rules`, they store the matching preset `day_of_week` rule. - `ADJ` applies the market's pattern and multiplies your own `rules` on top of it. - `CUS` replaces the market's pattern with your own `rules`, whose values are price multipliers (`1.1` is 10% higher). `CUS` without `rules` prices every day the same. A `CUS` setting saved before the day-of-week and local events split is returned as `ADJ`, since that is how it has priced since the split. - `type` (string, one of: `CON`, `REC`, `AGG`, `ADJ`, `CUS`) - `rules` (array of object `calendar_rule_global` | object `calendar_rule_time_based` | object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly_simple` | object `calendar_rule_day_of_week` | object `calendar_rule_custom`): Calendar rules when `type` is `ADJ` or `CUS`. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global** (object `calendar_rule_global`): **global** — Single default for the calendar in this rule set. Must not set `day_of_week_values`. UI: 'Default' or 'Minimum price default' (label varies by setting). - `type` (string, required, one of: `global`) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `value` (number, required): Default value (non-negative). - **calendar_rule_time_based**: see `calendar_rule_time_based` under Schemas. - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly_simple**: see `calendar_rule_monthly_simple` under Schemas. - **calendar_rule_day_of_week**: see `calendar_rule_day_of_week` under Schemas. - **calendar_rule_custom**: see `calendar_rule_custom` under Schemas. - `gap_night` (object `gap_night`, nullable): Gap night pricing strategy (UI: 'Gaps & Adjacencies' in the Pricing Engine panel). Controls the price multiplier for gap nights between bookings. When `type` is `CUS`, provide `custom` rules; the server rejects `CUS` without `custom`. This is a **pricing-only** setting. It is unrelated to the `gap` and `adjacency`/`one_sided_gap` rule types in `minimum_stay_rules_v3`, which control minimum stay behavior for gap nights. In a request the `custom` array replaces the stored one. Gap night pricing does not apply to listings with more than one unit. The setting is still accepted, and the response carries a `not_supported_for_multi_unit` warning. - `custom` (array of object `gap_night_custom_rule`): Per-gap custom rules. Required when `type` is `CUS` (may be an empty array). Each entry targets a gap length, weekday set, and optional one-sided adjacency (`left` / `right`). - Each item: One custom gap-night rule. `adjustment` is a price multiplier greater than 0 and at most 10 (`0.8` is a 20% discount). `day_of_week` uses 0 = Sunday through 6 = Saturday, unique values only, length 1–7. When several rules match a night, rules without `adjacent` are checked first, then `left`, then `right`. Within those, the rule with the smallest `gap` that still covers the gap wins, and among rules sharing that `gap` the largest `adjustment` wins. - `adjacent` (string, one of: `left`, `right`): Omit to match open nights with an unavailable night on both sides ("In between"). `left` matches the first `gap` open nights after an unavailable night ("Only after"); `right` matches the last `gap` open nights before one ("Only before"). - `adjustment` (number, required): Price multiplier; greater than 0 and at most 10. `0.8` is a 20% discount. - `day_of_week` (array of integer, required, min items: 1, max items: 7, each item min: 0, max: 6): Weekdays this rule applies to (0–6, each at most once). - `gap` (integer, required): Applies to gaps of this many nights or fewer. - `type` (string, required, one of: `CON`, `REC`, `AGG`, `CUS`): Preset strategy (`CON`, `REC`, `AGG`) or custom (`CUS`) gap-night rules. - `minimum_stay_rules_v3` (array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`, default: `[]`): UI: 'Minimum stays' — minimum stay rules. The `_v3` suffix is a stable historical identifier; this field name is not expected to change. - Fields: see `integer_calendar_rule` under Schemas. - `min_stays_enabled` (boolean): Whether minimum stay rules are enabled. - `minimum_price_rules_v3` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): UI: 'Minimum prices' — Minimum price rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. The `_v3` suffix is a stable historical identifier; this field name is not expected to change. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `maximum_price_rules_v3` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): UI: 'Maximum prices' — Maximum price rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. The `_v3` suffix is a stable historical identifier; this field name is not expected to change. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `checkin_checkout` (object, nullable): Which days guests may check in and check out. Rule values are allow flags: `1` allows the day and `0` blocks it. A `day_of_week` rule's `day_of_week_values` has 7 entries, index 0 = Sunday. Where rules overlap, the more specific rule type wins (for example a date-specific `custom` rule over a `day_of_week` rule); between rules of the same type, the later one in the array wins. In a request the object replaces the stored one as a whole: send `active` and both `check_in_rules` and `check_out_rules` (a request missing either array is rejected with 400). An empty `check_out_rules` leaves check-out unrestricted. Example, check-in on Friday and Saturday only, check-out any day: ```json { "active": true, "auto_adjust": false, "check_in_rules": [{"type": "day_of_week", "day_of_week_values": [0, 0, 0, 0, 0, 1, 1]}], "check_out_rules": [{"type": "day_of_week", "day_of_week_values": [1, 1, 1, 1, 1, 1, 1]}] } ``` - `active` (boolean): Whether the check-in/check-out rules are enforced. Stored as `false` when omitted. - `auto_adjust` (boolean): When `true`, Wheelhouse opens additional check-in and check-out days around unavailable nights so that open stretches between bookings can still be booked, even on days the rules would otherwise block. - `check_in_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`): Allowed check-in rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `check_out_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`): Allowed check-out rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `long_term_discounts` (object, default: `{"active":false,"weekly_rules":[],"monthly_rules":[],"rules":{}}`): Rule-based long-term discount configuration. - `active` (boolean) - `weekly_rules` (array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`, **deprecated**): Weekly discount rules (integer calendar rules). - Fields: see `integer_calendar_rule` under Schemas. - `monthly_rules` (array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`, **deprecated**): Monthly discount rules (integer calendar rules). - Fields: see `integer_calendar_rule` under Schemas. - `rules` (map of string to array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`): LOS-keyed rules (integer calendar rules). Keys are length-of-stay thresholds (e.g. "7", "28"); values are arrays of integer calendar rules holding whole percentages (`10` is a 10% discount). On listings that accept length-of-stay premiums (every listing whose `supported_settings.long_term_discount_type` is `complex`, and some with `rules`), values are signed instead, so `-10` is a 10% discount and `10` a 10% premium. - Fields: see `integer_calendar_rule` under Schemas. - `occupancy_pacing` (object `occupancy_pacing`, nullable, default: `{}`): Occupancy pacing configuration. When `occupancy_pacing` is sent as a non-empty object, both `adjusted` and `pacing` are required. Occupancy pacing matrix configuration. `{}` means pacing is off, which is the default for a new listing. When `occupancy_pacing` is sent as a non-empty object, `adjusted` and `pacing` are required, and `pacing` must include a matrix with `type` `global` (otherwise the request is rejected with 400). In a request the object replaces the stored one as a whole; omit it to leave pacing unchanged. For each lead-time column, occupancy is measured across that whole window and the matching row's percentage is applied to every date in it. A row covers occupancy above `min` up to and including `max` (`min` `0` includes 0%); the first matching row wins, and dates outside every column or row are unchanged. The adjusted price still respects the listing's minimum and maximum price rules. - `adjusted` (boolean): When true, occupancy is computed as booked nights divided by bookable (unblocked) nights; when false, against calendar days × units. - `pacing` (array of object `occupancy_pacing_matrix`): Pacing matrices. Must include one with `type` `global`, which is the one applied; others are ignored. - Each item: One pacing matrix (rows × columns of adjustment percentages). - `columns` (array of object `occupancy_pacing_column`, required): Lead-time column definitions; count must match each row in `values`. - Each item: Lead-time window (days from today) for one column of the pacing matrix. - `days_max` (integer, required, min: 0, max: 1000): Inclusive end of lead-time window (0–1000). Must be greater than or equal to `days_min`. - `days_min` (integer, required, min: 0, max: 1000): Inclusive start of lead-time window (0–1000). - `rows` (array of object `occupancy_pacing_row`, required): Occupancy (or revenue) percentage band rows; each `min`/`max` is 0–100 for occupancy pacing. - Each item: Occupancy percentage band for one row of the pacing matrix. - `max` (integer, required, min: 0, max: 100): Upper bound of the band (0–100 inclusive). - `min` (integer, required, min: 0, max: 100): Lower bound of the band (0–100 inclusive). - `type` (string, required): Rule discriminator; `global` is used for the active pacing matrix. - `values` (array of array of integer, required): Price adjustments as whole percentages (`-10` is a 10% decrease, `10` a 10% increase), each ≥ -100. One array per entry in `rows`, each holding one value per entry in `columns`; any other shape is rejected with 400. - `fee_adjustments` (object `fee_adjustments`, nullable): Estimated fee share applied on top of the nightly rate. `null` when nothing is configured, otherwise both keys are present; in a request the object replaces the stored one as a whole, and `null` clears it. UI: 'Asking Rate (+Est. Fees)' — The estimated share of fees guests pay on top of the nightly rate, as a percentage of that rate. It is what `GET /listings/{listing_id}/fee_impact_calendar` returns as a per-date multiplier. A response carries `null` when nothing is configured, otherwise both keys. In a request the object replaces the stored one as a whole, so send both keys; `null` clears the setting. - `total_fee_percentage` (number): Fees as a percentage of the nightly rate, `-100` or more. `15` means guests pay about 15% on top of the nightly rate in fees; there is no upper bound, since fees can exceed the nightly rate on short stays. Omitted means `0`. - `auto_update` (boolean): When `true`, `total_fee_percentage` is recalculated weekly from the fees on the listing's recent reservations, replacing whatever was set. Defaults to `false` when omitted. - `demand_sensitivity_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): Local events rules. Shown as Demand sensitivity before day of week became its own setting; the field name is unchanged. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `historical_anchoring_price_source` (string, one of: `observed`, `posted`, `posted_with_fallback`, default: `observed`): Which historical price historical anchoring weighs in. `observed`, the default, is the listing's price as Wheelhouse saw it on the channel once the date booked. `posted` is the price Wheelhouse last posted for the date before it booked, so dates Wheelhouse never posted a price for are not anchored. `posted_with_fallback` uses the posted price where there is one and the observed price otherwise. - `historical_anchoring_mode` (string, one of: `blended`, `anchor_only`, default: `blended`): How a historical anchoring percentage turns the historical price into a floor for the recommendation. `blended` averages the historical price with the recommendation, using the percentage as the weight on the historical price: at 50%, a $1,200 historical price and a $400 recommendation give $800. `anchor_only` takes the percentage of the historical price alone, so at 50% the floor is $600: a $400 recommendation rises to $600 and a $700 one stays at $700. Either only ever raises a price, and from 100% up both give the same price. - `historical_anchoring_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): Historical anchoring rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `custom_date_ranges` (array of object `custom_date_range`, default: `[]`): Represents an Event or Season entry used by the Wheelhouse Events & Seasons feature. Calendar rules reference these entries by `id` to apply settings (e.g. min stay, pricing) over named date windows. Each listing stores its own copy of every Event or Season it belongs to. Entries for the same event or season share the same `id` across listings — this shared `id` is what enables bulk adjustments in the Wheelhouse UI. If you write a `custom_date_ranges` entry with a new or changed `id`, that listing's entry is no longer linked to the others and will not be included in future bulk edits of the original Event or Season. To safely modify an event or season's definition (dates or name) on one listing without affecting others, omit the `id` field — the server assigns a new independent ID scoped to that listing. To update only a rule value (e.g. raise the minimum price) without changing dates, include the existing `id` unchanged. A new `custom_date_ranges` entry and a rule referencing it can be submitted in the same PUT request. Manually assign an `id` on the new entry so that the referencing rule can use it in the same payload. Alternatively, use two sequential PUTs: the first PUT creates the entry without an `id` (the server assigns one, returned in the response); the second PUT adds the rule referencing that server-assigned `id`. - Each item: Represents an Event or Season entry used by the Wheelhouse Events & Seasons feature. Calendar rules reference these entries by `id` to apply settings (e.g. min stay, pricing) over named date windows. Each listing stores its own copy of every Event or Season it belongs to. Entries for the same event or season share the same `id` across listings — this shared `id` is what enables bulk adjustments in the Wheelhouse UI. If you write a `custom_date_ranges` entry with a new or changed `id`, that listing's entry is no longer linked to the others and will not be included in future bulk edits of the original Event or Season. To safely modify an event or season's definition (dates or name) on one listing without affecting others, omit the `id` field — the server assigns a new independent ID scoped to that listing. To update only a rule value (e.g. raise the minimum price) without changing dates, include the existing `id` unchanged. - `date_ranges` (array of object `custom_date_range_segment`, required): One or more inclusive calendar spans. Each span must include `start_date` and `end_date`, and `start_date` must be on or before `end_date`. - Each item: Inclusive calendar span within a custom date range. - `end_date` (string (date), required): Inclusive end (ISO-8601 date). - `start_date` (string (date), required): Inclusive start (ISO-8601 date). - `id` (string): Stable identifier for this range, referenced by calendar rules. Listings that share the same `id` for an entry are considered part of the same Event or Season and can be bulk-edited together. Preserve the existing `id` when updating an entry to keep it linked; omit only when creating a new range (one will be assigned). The server always returns this field as a string. Calendar rule `id` fields accept both string and integer for backward compatibility, but the canonical type is string — use string comparisons when matching rule `id` values against `custom_date_ranges` entries. - `name` (string, required): Display name for the season or event. - `type` (string, required, one of: `event`, `seasonal`): Whether this range represents a recurring season or a dated event. - `yearly` (boolean, required): When true, the date spans repeat each calendar year (same month/day pattern). - `min_min_price` (integer, default: `0`): UI: 'Absolute minimum price' — Hard lower bound that overrides all pricing rules. No recommended price will fall below this value regardless of any rule configuration. Distinct from a `global` rule in `minimum_price_rules_v3`, which can be overridden by higher-priority rules. Must be an integer (whole currency units). - `min_min_stay` (integer, default: `0`): UI: 'Absolute minimum stay' — Hard lower bound that overrides all minimum stay rules. No minimum stay will be set below this value regardless of any rule configuration. Distinct from both a `global` rule in `minimum_stay_rules_v3` (which can be overridden by higher-priority rules) and from `global_min_stay` in the price recommendations response (which reflects the current effective default rule value, not a hard floor). - `apply_gap_night_rules_to_overrides` (boolean): UI: 'Apply Gap Night Rules to Overrides' — When `true`, gap-night minimum stay rules take priority over custom (date override) rules. When `false` (default), custom rules win over gap-night rules. - `update_from` (string, read-only): The source used when the preferences were last updated. - `update_from_id` (integer, nullable, read-only): The ID of the entity used when preferences were last updated. - `created_at` (string, nullable, read-only): When the listing preferences were created (Rails-style timestamp). - `updated_at` (string, nullable, read-only): When the listing preferences were last updated (Rails-style timestamp). - `supported_settings` (object `supported_settings`, read-only): Which listing preference settings this listing's channel can act on. A setting reported `false` is discarded on write rather than posted to the channel, so check this before sending it. Reflects any per-account early access, so two listings on the same channel can differ. - `checkin_checkout` (boolean): Whether `checkin_checkout` rules can be set. - `min_stays` (boolean): Whether minimum stay settings (`min_min_stay`, `min_stays_enabled`, `minimum_stay_rules`) can be set. - `long_term_discounts` (boolean): Whether long-term discounts (`long_term_discounts`, `weekly_discount`, `monthly_discount`) can be set at all. - `long_term_discount_type` (string, one of: `disabled`, `simple`, `rules`, `complex`): The form of long-term discount the channel accepts. `disabled` takes none; `simple` takes only flat `weekly_discount` and `monthly_discount` values and ignores a `rules` object; `rules` additionally takes the 7 and 28 night tiers; `complex` takes arbitrary tiers. - `warnings` (array of object `preference_warning`, read-only, each item read-only): Settings in the request this listing's channel cannot act on, and which were therefore not applied. Present on write responses and empty when everything applied, so it can be read unconditionally; absent on reads, where nothing was being set. - Each item: One setting in the request that was not applied, or that has no effect on this listing. - `setting` (string, one of: `checkin_checkout`, `gap_night`, `min_stays`, `long_term_discounts`): The setting group the warning is about. - `reason` (string, one of: `not_supported_by_channel`, `partially_supported_by_channel`, `not_supported_for_multi_unit`): `not_supported_by_channel` — the channel has no such feature and everything sent for it was dropped. `partially_supported_by_channel` — the channel has the feature but accepts a narrower form than what was sent, and only the excess was dropped. `not_supported_for_multi_unit` — the setting is stored but has no effect on price, because the listing has more than one unit. - `message` (string): A human-readable explanation of what was ignored and why. - `attributes` (array of string): The request attributes this warning covers, in dot notation for nested ones (e.g. `long_term_discounts.rules.14`). Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "listing_id": 0, "partner_listing_id": "string", "currency": "string", "automatic_rate_posting_enabled": true, "base_price": 0, "base_price_adjustment": 0, "monthly_discount": 0, "weekly_discount": 0, "nickname": "string", "last_minute_discount": { "type": "CON", "rules": [ { "type": "time_based", "days_after": 0, "days_before": 0, "months": [ 1 ], "priority": 0, "day_of_week_values": [ 0, 0, 0, 0, 0, 0, 0 ], "value": 0 } ], "smooth": false }, "far_future_premium": { "type": "CON", "rules": [ { "type": "time_based", "days_after": 0, "days_before": 0, "months": [ 1 ], "priority": 0, "day_of_week_values": [ 0, 0, 0, 0, 0, 0, 0 ], "value": 0 } ], "smooth": false }, "seasonality_adjustment": { "type": "CON", "rules": [ { "type": "seasonal", "id": 0, "priority": 0, "day_of_week_values": [ 0, 0, 0, 0, 0, 0, 0 ], "value": 0 } ], "smooth": false }, "day_of_week": { "type": "CON", "rules": [ { "type": "global", "priority": 0, "value": 0 } ] }, "gap_night": { "custom": [ { "adjacent": "left", "adjustment": 0, "day_of_week": [ 0 ], "gap": 0 } ], "type": "CON" }, "minimum_stay_rules_v3": [], "min_stays_enabled": true, "minimum_price_rules_v3": [], "maximum_price_rules_v3": [], "checkin_checkout": { "active": true, "auto_adjust": true, "check_in_rules": [ { "type": "global", "priority": 0, "value": 0 } ], "check_out_rules": [ { "type": "global", "priority": 0, "value": 0 } ] }, "long_term_discounts": { "active": false, "weekly_rules": [], "monthly_rules": [], "rules": {} }, "occupancy_pacing": {}, "fee_adjustments": { "total_fee_percentage": 0, "auto_update": true }, "demand_sensitivity_rules": [], "historical_anchoring_price_source": "observed", "historical_anchoring_mode": "blended", "historical_anchoring_rules": [], "custom_date_ranges": [], "min_min_price": 0, "min_min_stay": 0, "apply_gap_night_rules_to_overrides": true, "update_from": "string", "update_from_id": 0, "created_at": "string", "updated_at": "string", "supported_settings": { "checkin_checkout": true, "min_stays": true, "long_term_discounts": true, "long_term_discount_type": "disabled" }, "warnings": [ { "setting": "checkin_checkout", "reason": "not_supported_by_channel", "message": "string", "attributes": [ "string" ] } ] } ] ``` ### 401 API key authorization failed. ### 422 Missing `channel` query parameter while the request has no integration channel context (see `channel` parameter description). ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` ## Schemas Shared by more than one field above. ### `calendar_rule_time_based` Type: object `calendar_rule_time_based` **time_based** — Relative to "today" for the listing. At least one of `days_before` or `days_after` must be set. Provide `value` or `day_of_week_values`, not both. Optional `months` scopes by calendar month. When only `days_before` is set, the rule applies to dates within that many days of today (last-minute window). When only `days_after` is set, the rule applies to dates at least that many days away (far-future window). When both are set, the rule applies to dates that satisfy both conditions simultaneously — at least `days_after` days away AND within `days_before` days — creating a mid-booking-window band. `days_before` must be greater than or equal to `days_after` when both are provided. **time_based** — Relative to “today” for the listing. At least one of `days_before` or `days_after` must be set. Provide `value` or `day_of_week_values`, not both. Optional `months` scopes by calendar month. When only `days_before` is set, the rule applies to dates within that many days of today (last-minute window). When only `days_after` is set, the rule applies to dates at least that many days away (far-future window). When both are set, the rule applies to dates that satisfy both conditions simultaneously — at least `days_after` days away AND within `days_before` days — creating a mid-booking-window band. `days_before` must be greater than or equal to `days_after` when both are provided. - `type` (string, required, one of: `time_based`) - `days_after` (integer, nullable): Applies on/after “today + days_after”. When combined with `days_before`, creates a mid-window band (see rule description). `null` when this side of the window is unset. - `days_before` (integer, nullable): Applies within “today + days_before”. Must be >= `days_after` when both are set. `null` when this side of the window is unset. - `months` (array of integer, min items: 1, each item min: 1, max: 12): When set, restrict to these month ordinals (1–12). - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number) ### `calendar_rule_seasonal` Type: object `calendar_rule_seasonal` **seasonal** — Tied to a custom seasonal date range. Set `id` to the custom range. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `seasonal`) - `id` (integer | string, required): Custom seasonal date-range identifier. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number) ### `calendar_rule_event` Type: object `calendar_rule_event` **event** — Tied to a custom event date range. Set `id` to the custom range. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `event`) - `id` (integer | string, required): Custom event / date-range identifier. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number) ### `calendar_rule_monthly_simple` Type: object `calendar_rule_monthly_simple` **monthly** — Limited to specific `months`. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `monthly`) - `months` (array of integer, required, min items: 1, each item min: 1, max: 12): Month ordinals (1–12); at least one. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number) ### `calendar_rule_day_of_week` Type: object `calendar_rule_day_of_week` **day_of_week** — Per weekday (7 values, Sunday-first). Optional `months` limits to those month ordinals. Must not combine with `days_before` / `days_after` (use `time_based` for that). - `type` (string, required, one of: `day_of_week`) - `months` (array of integer, min items: 1, each item min: 1, max: 12): When set, restrict to these month ordinals (1–12). - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, required, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. ### `calendar_rule_custom` Type: object `calendar_rule_custom` **custom** — Fixed calendar date range. `start_date` and `end_date` inclusive; optional `yearly` repeats each year. Provide `value` or `day_of_week_values`, not both. UI: 'Date-specific overrides.' Not related to `custom_date_ranges` (Events & Seasons), Custom Rates, or the `CUS` preset type. - `type` (string, required, one of: `custom`) - `end_date` (string (date), required): Inclusive end (ISO-8601 date). - `id` (integer | string): Server-assigned identifier, returned as a string when present. On `checkin_checkout` rules it pairs a check-in rule with its check-out rule and is derived from the rule's contents, so it changes when the rule changes (on `seasonal` and `event` rules it is the season or event id instead). Requests don't use it to identify a rule, so don't store it as a stable key. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `start_date` (string (date), required): Inclusive start (ISO-8601 date). - `yearly` (boolean): When true, repeat the same month/day span every year. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number): Single value for dates in range when `day_of_week_values` is not used. ### `integer_calendar_rule` Type: object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule` Integer calendar rules (minimum stay, min/max price caps, local events, check-in/out, long-term discounts, etc.). - One of: - **calendar_rule_adjacency_int** (object `calendar_rule_adjacency_int`): Integer-valued adjacency / one-sided gap rule (same semantics as `calendar_rule_adjacency`). Only used in `minimum_stay_rules_v3` (MLOS behavior). Not related to the `gap_night` pricing setting. - `type` (string, required, one of: `adjacency`, `one_sided_gap`): Use `adjacency` or legacy `one_sided_gap` (same behavior). - `adjustment` (integer): Add to the existing calendar value instead of replacing it. - `day_of_week_adjustments` (array of integer, min items: 7, max items: 7, each item nullable): Per-day adjustments (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `days_adjacent` (integer, required): Window of adjacent days (negative = prior side, positive = subsequent side). To match both sides, use two separate rules — one with a negative value and one with a positive value. When both rules fire on the same date, the negative rule's value takes precedence (it is evaluated last and overwrites the positive rule's result). - `days_after` (integer): Legacy alias retained on some stored adjacency rules. Prefer `days_adjacent`. - `days_one_sided_gap` (integer): Legacy alias retained on some stored adjacency rules. Prefer `days_adjacent`. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day minimums (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer): Single minimum when `day_of_week_values` is not used. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_gap_int** (object `calendar_rule_gap_int`): **gap** — When `gap_enabled` is true, applies a minimum stay only for "gap" nights that cannot fit the normal min stay. Provide `value` or `day_of_week_values` for the gap minimum. Optional `days_before` / `days_after` scope the rule in time. Only used in `minimum_stay_rules_v3` (MLOS behavior). Not related to the `gap_night` pricing setting. **gap** — When `gap_enabled` is true, applies a minimum stay only for “gap” nights that cannot fit the normal min stay. Provide `value` or `day_of_week_values` for the gap minimum. Optional `days_before` / `days_after` scope the rule in time. - `type` (string, required, one of: `gap`) - `days_after` (integer) - `days_before` (integer) - `gap_enabled` (boolean, required, one of: `true`) - `gap_flexibility` (integer): Reduces effective min stay in the gap by this many nights. It will never drop below `value`. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day gap minimums (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer): Gap minimum stay (integer in typical min-stay rules). - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. ### `calendar_rule_global_int` Type: object `calendar_rule_global_int` **global** — Single default for the calendar in this rule set. Must not set `day_of_week_values`. UI: 'Default' or 'Minimum price default' (label varies by setting). - `type` (string, required, one of: `global`) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `value` (integer, required): Default value (non-negative). ### `calendar_rule_time_based_int` Type: object `calendar_rule_time_based_int` **time_based** — Relative to "today" for the listing. At least one of `days_before` or `days_after` must be set. Provide `value` or `day_of_week_values`, not both. Optional `months` scopes by calendar month. When only `days_before` is set, the rule applies to dates within that many days of today (last-minute window). When only `days_after` is set, the rule applies to dates at least that many days away (far-future window). When both are set, the rule applies to dates that satisfy both conditions simultaneously — at least `days_after` days away AND within `days_before` days — creating a mid-booking-window band. `days_before` must be greater than or equal to `days_after` when both are provided. **time_based** — Relative to “today” for the listing. At least one of `days_before` or `days_after` must be set. Provide `value` or `day_of_week_values`, not both. Optional `months` scopes by calendar month. When only `days_before` is set, the rule applies to dates within that many days of today (last-minute window). When only `days_after` is set, the rule applies to dates at least that many days away (far-future window). When both are set, the rule applies to dates that satisfy both conditions simultaneously — at least `days_after` days away AND within `days_before` days — creating a mid-booking-window band. `days_before` must be greater than or equal to `days_after` when both are provided. - `type` (string, required, one of: `time_based`) - `days_after` (integer, nullable): Applies on/after “today + days_after”. When combined with `days_before`, creates a mid-window band (see rule description). `null` when this side of the window is unset. - `days_before` (integer, nullable): Applies within “today + days_before”. Must be >= `days_after` when both are set. `null` when this side of the window is unset. - `months` (array of integer, min items: 1, each item min: 1, max: 12): When set, restrict to these month ordinals (1–12). - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer) ### `calendar_rule_seasonal_int` Type: object `calendar_rule_seasonal_int` **seasonal** — Tied to a custom seasonal date range. Set `id` to the custom range. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `seasonal`) - `id` (integer | string, required): Custom seasonal date-range identifier. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer) ### `calendar_rule_event_int` Type: object `calendar_rule_event_int` **event** — Tied to a custom event date range. Set `id` to the custom range. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `event`) - `id` (integer | string, required): Custom event / date-range identifier. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer) ### `calendar_rule_monthly_int` Type: object `calendar_rule_monthly_int` **monthly** — Limited to specific `months`. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `monthly`) - `months` (array of integer, required, min items: 1, each item min: 1, max: 12): Month ordinals (1–12); at least one. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer): Single value for the month. ### `calendar_rule_day_of_week_int` Type: object `calendar_rule_day_of_week_int` **day_of_week** — Per weekday (7 values, Sunday-first). Optional `months` limits to those month ordinals. Must not combine with `days_before` / `days_after` (use `time_based` for that). - `type` (string, required, one of: `day_of_week`) - `months` (array of integer, min items: 1, each item min: 1, max: 12): When set, restrict to these month ordinals (1–12). - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, required, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. ### `calendar_rule_custom_int` Type: object `calendar_rule_custom_int` **custom** — Fixed calendar date range. `start_date` and `end_date` inclusive; optional `yearly` repeats each year. Provide `value` or `day_of_week_values`, not both. UI: 'Date-specific overrides.' Not related to `custom_date_ranges` (Events & Seasons), Custom Rates, or the `CUS` preset type. - `type` (string, required, one of: `custom`) - `end_date` (string (date), required): Inclusive end (ISO-8601 date). - `id` (integer | string): Server-assigned identifier, returned as a string when present. On `checkin_checkout` rules it pairs a check-in rule with its check-out rule and is derived from the rule's contents, so it changes when the rule changes (on `seasonal` and `event` rules it is the season or event id instead). Requests don't use it to identify a rule, so don't store it as a stable key. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `start_date` (string (date), required): Inclusive start (ISO-8601 date). - `yearly` (boolean): When true, repeat the same month/day span every year. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer): Single value for dates in range when `day_of_week_values` is not used. --- # Update preferences for a batch of listings. `PUT /preferences` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-put-preferences-batch · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPutPreferencesBatch` · Tag: Listing Preferences Updates pricing preferences for multiple listings in one request. Returns status `207` if some updates failed, `424` if all updates failed. This is a bulk update, which a user with *restricted editor* access to a shared listing may not make: such a listing is reported in `errors` with status `403`, however many listings the request names. Use [PUT /preferences/{listing_id}](https://docs.usewheelhouse.com/rm/reference/rm-put-preferences.md) for it instead. All fields are optional; only provided fields will be updated. This partial-update behavior applies at the top level only — omitting a field (e.g. `minimum_stay_rules_v3`) leaves it unchanged, but providing a field that holds an array of rules (e.g. `minimum_price_rules_v3`) will **completely replace** the existing rule set for that field; individual rules within an array cannot be merged or patched. Always fetch the current preferences before writing and include every rule you wish to retain — any rules omitted from an array will be permanently deleted. ## Request `PUT https://api.usewheelhouse.com/ss_api/v1/preferences` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listings are on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_ids` as Wheelhouse listing IDs instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Request body (`application/json`, required) - `listing_preferences` (array of object, required) - Each item: The pricing preferences to set for a listing. All fields are optional; only provided fields will be updated. This partial-update behavior applies at the top level only — omitting a field (e.g. `minimum_stay_rules_v3`) leaves it unchanged, but providing a field that holds an array of rules (e.g. `minimum_price_rules_v3`) will **completely replace** the existing rule set for that field; individual rules within an array cannot be merged or patched. - `listing_id` (string, required): The channel's listing ID to update. - `automatic_rate_posting_enabled` (boolean): Whether Wheelhouse automatically posts its price recommendations to the channel calendar. When `false`, recommendations are computed but not pushed to the channel. This setting does not affect custom rates set via the API — those are posted independently. - `base_price` (integer, nullable, min: 1): The manually set base price. If set, overrides Wheelhouse's data-driven recommendation. Must be a whole number of at least 1. - `base_price_adjustment` (number, nullable): A multiplier on the Wheelhouse recommended base price, for example `0.9` for 10% below it. Only used if `base_price` is not set. Sending a non-null value without `base_price` clears a manual `base_price`. Sending `null` leaves a manual `base_price` in place. To clear it, send `null` for `base_price`. Cannot be `0`. - `monthly_discount` (integer, nullable, default: `0`): Monthly discount percentage as an integer in the range 0–100 (e.g. `5` = 5%). On listings that accept length-of-stay premiums (every listing whose `supported_settings.long_term_discount_type` is `complex`, and some with `rules`), values are signed instead, so `-10` is a 10% discount and `10` a 10% premium. Applied to bookings ≥ 28 nights. Kept in sync with the global rule in `long_term_discounts.rules['28']` — setting one automatically updates the other. When both are sent in the same PUT, `long_term_discounts` takes precedence. - `weekly_discount` (integer, nullable, default: `0`): Weekly discount percentage as an integer in the range 0–100 (e.g. `5` = 5%). On listings that accept length-of-stay premiums (every listing whose `supported_settings.long_term_discount_type` is `complex`, and some with `rules`), values are signed instead, so `-10` is a 10% discount and `10` a 10% premium. Applied to bookings ≥ 7 nights. Kept in sync with the global rule in `long_term_discounts.rules['7']` — setting one automatically updates the other. When both are sent in the same PUT, `long_term_discounts` takes precedence. - `nickname` (string, nullable): Listing nickname. Overrides the listing's default nickname. - `last_minute_discount` (object, nullable): UI: 'Last minute' — Last-minute discount configuration. - `type` (string, one of: `CON`, `REC`, `AGG`, `CUS`) - `rules` (array of object `calendar_rule_time_based` | object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly_simple` | object `calendar_rule_day_of_week` | object `calendar_rule_custom`): Calendar rules when `type` is `CUS`. Valid rule types: `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_time_based**: see `calendar_rule_time_based` under Schemas. - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly_simple**: see `calendar_rule_monthly_simple` under Schemas. - **calendar_rule_day_of_week**: see `calendar_rule_day_of_week` under Schemas. - **calendar_rule_custom**: see `calendar_rule_custom` under Schemas. - `smooth` (boolean, default: `false`): UI: 'Smooth' — Only used when `type` is `CUS`. When `true`, the adjustment eases gradually from one rule to the next instead of jumping at each rule's edge. `custom` rules still apply exactly. Defaults to `false` (stepped). - `far_future_premium` (object, nullable): UI: 'Far future' — Far-future premium configuration. - `type` (string, one of: `CON`, `REC`, `AGG`, `CUS`) - `rules` (array of object `calendar_rule_time_based` | object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly_simple` | object `calendar_rule_day_of_week` | object `calendar_rule_custom`): Calendar rules when `type` is `CUS`. Valid rule types: `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_time_based**: see `calendar_rule_time_based` under Schemas. - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly_simple**: see `calendar_rule_monthly_simple` under Schemas. - **calendar_rule_day_of_week**: see `calendar_rule_day_of_week` under Schemas. - **calendar_rule_custom**: see `calendar_rule_custom` under Schemas. - `smooth` (boolean, default: `false`): UI: 'Smooth' — Only used when `type` is `CUS`. When `true`, the adjustment eases gradually from one rule to the next instead of jumping at each rule's edge. `custom` rules still apply exactly. Defaults to `false` (stepped). - `seasonality_adjustment` (object, nullable): UI: 'Seasonality' — Seasonality adjustment configuration. - `type` (string, one of: `CON`, `REC`, `AGG`, `CUS`) - `rules` (array of object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly`): Calendar rules when `type` is `CUS`. Valid rule types: `seasonal`, `event`, `monthly`. - One of: - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly**: see `calendar_rule_monthly` under Schemas. - `smooth` (boolean, default: `false`): UI: 'Smooth' — Only used when `type` is `CUS`. When `true`, the adjustment eases gradually from one rule to the next instead of jumping at each rule's edge, and monthly rules' `step`, `start_value` and `end_value` are ignored. Defaults to `false` (stepped). - `day_of_week` (object, nullable): Day-of-week pricing factor configuration. - `REC` applies the market's day-of-week pattern. - `CON` and `AGG` adjust that pattern conservatively or aggressively. Sent without `rules`, they store the matching preset `day_of_week` rule. - `ADJ` applies the market's pattern and multiplies your own `rules` on top of it. - `CUS` replaces the market's pattern with your own `rules`, whose values are price multipliers (`1.1` is 10% higher). `CUS` without `rules` prices every day the same. - `type` (string, one of: `CON`, `REC`, `AGG`, `ADJ`, `CUS`) - `rules` (array of object `calendar_rule_global` | object `calendar_rule_time_based` | object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly_simple` | object `calendar_rule_day_of_week` | object `calendar_rule_custom`): Calendar rules when `type` is `ADJ` or `CUS`. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global**: see `calendar_rule_global` under Schemas. - **calendar_rule_time_based**: see `calendar_rule_time_based` under Schemas. - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly_simple**: see `calendar_rule_monthly_simple` under Schemas. - **calendar_rule_day_of_week**: see `calendar_rule_day_of_week` under Schemas. - **calendar_rule_custom**: see `calendar_rule_custom` under Schemas. - `gap_night` (object `gap_night`, nullable): Gap night pricing strategy (UI: 'Gaps & Adjacencies' in the Pricing Engine panel). Controls the price multiplier for gap nights between bookings. When `type` is `CUS`, provide `custom` rules; the server rejects `CUS` without `custom`. This is a **pricing-only** setting. It is unrelated to the `gap` and `adjacency`/`one_sided_gap` rule types in `minimum_stay_rules_v3`, which control minimum stay behavior for gap nights. In a request the `custom` array replaces the stored one. Gap night pricing does not apply to listings with more than one unit. The setting is still accepted, and the response carries a `not_supported_for_multi_unit` warning. - Fields: see `gap_night` under Schemas. - `minimum_stay_rules_v3` (array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`, default: `[]`): UI: 'Minimum stays' — minimum stay rules. The `_v3` suffix is a stable historical identifier; this field name is not expected to change. - Fields: see `integer_calendar_rule` under Schemas. - `min_stays_enabled` (boolean): Whether minimum stay rules are enabled. - `minimum_price_rules_v3` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): UI: 'Minimum prices' — Minimum price rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. The `_v3` suffix is a stable historical identifier; this field name is not expected to change. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `maximum_price_rules_v3` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): UI: 'Maximum prices' — Maximum price rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. The `_v3` suffix is a stable historical identifier; this field name is not expected to change. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `checkin_checkout` (object, nullable): Which days guests may check in and check out. Rule values are allow flags: `1` allows the day and `0` blocks it. A `day_of_week` rule's `day_of_week_values` has 7 entries, index 0 = Sunday. Where rules overlap, the more specific rule type wins (for example a date-specific `custom` rule over a `day_of_week` rule); between rules of the same type, the later one in the array wins. In a request the object replaces the stored one as a whole: send `active` and both `check_in_rules` and `check_out_rules` (a request missing either array is rejected with 400). An empty `check_out_rules` leaves check-out unrestricted. Example, check-in on Friday and Saturday only, check-out any day: ```json { "active": true, "auto_adjust": false, "check_in_rules": [{"type": "day_of_week", "day_of_week_values": [0, 0, 0, 0, 0, 1, 1]}], "check_out_rules": [{"type": "day_of_week", "day_of_week_values": [1, 1, 1, 1, 1, 1, 1]}] } ``` - `active` (boolean): Whether the check-in/check-out rules are enforced. Stored as `false` when omitted. - `auto_adjust` (boolean): When `true`, Wheelhouse opens additional check-in and check-out days around unavailable nights so that open stretches between bookings can still be booked, even on days the rules would otherwise block. - `check_in_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`): Allowed check-in rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `check_out_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`): Allowed check-out rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `long_term_discounts` (object, default: `{"active":false,"weekly_rules":[],"monthly_rules":[],"rules":{}}`): Rule-based long-term discount configuration. - `active` (boolean) - `weekly_rules` (array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`, **deprecated**): Weekly discount rules (integer calendar rules). - Fields: see `integer_calendar_rule` under Schemas. - `monthly_rules` (array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`, **deprecated**): Monthly discount rules (integer calendar rules). - Fields: see `integer_calendar_rule` under Schemas. - `rules` (map of string to array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`): LOS-keyed rules (integer calendar rules). Keys are length-of-stay thresholds (e.g. "7", "28"); values are arrays of integer calendar rules holding whole percentages (`10` is a 10% discount). On listings that accept length-of-stay premiums (every listing whose `supported_settings.long_term_discount_type` is `complex`, and some with `rules`), values are signed instead, so `-10` is a 10% discount and `10` a 10% premium. - Fields: see `integer_calendar_rule` under Schemas. - `occupancy_pacing` (object `occupancy_pacing`, nullable, default: `{}`): Occupancy pacing configuration. When `occupancy_pacing` is sent as a non-empty object, both `adjusted` and `pacing` are required. Occupancy pacing matrix configuration. `{}` means pacing is off, which is the default for a new listing. When `occupancy_pacing` is sent as a non-empty object, `adjusted` and `pacing` are required, and `pacing` must include a matrix with `type` `global` (otherwise the request is rejected with 400). In a request the object replaces the stored one as a whole; omit it to leave pacing unchanged. For each lead-time column, occupancy is measured across that whole window and the matching row's percentage is applied to every date in it. A row covers occupancy above `min` up to and including `max` (`min` `0` includes 0%); the first matching row wins, and dates outside every column or row are unchanged. The adjusted price still respects the listing's minimum and maximum price rules. - Fields: see `occupancy_pacing` under Schemas. - `fee_adjustments` (object `fee_adjustments`, nullable): Estimated fee share applied on top of the nightly rate. `null` when nothing is configured, otherwise both keys are present; in a request the object replaces the stored one as a whole, and `null` clears it. UI: 'Asking Rate (+Est. Fees)' — The estimated share of fees guests pay on top of the nightly rate, as a percentage of that rate. It is what `GET /listings/{listing_id}/fee_impact_calendar` returns as a per-date multiplier. A response carries `null` when nothing is configured, otherwise both keys. In a request the object replaces the stored one as a whole, so send both keys; `null` clears the setting. - Fields: see `fee_adjustments` under Schemas. - `demand_sensitivity_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): Local events rules. Shown as Demand sensitivity before day of week became its own setting; the field name is unchanged. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `historical_anchoring_price_source` (string, one of: `observed`, `posted`, `posted_with_fallback`): Which historical price historical anchoring weighs in. `observed`, the default, is the listing's price as Wheelhouse saw it on the channel once the date booked. `posted` is the price Wheelhouse last posted for the date before it booked, so dates Wheelhouse never posted a price for are not anchored. `posted_with_fallback` uses the posted price where there is one and the observed price otherwise. - `historical_anchoring_mode` (string, one of: `blended`, `anchor_only`): How a historical anchoring percentage turns the historical price into a floor for the recommendation. `blended` averages the historical price with the recommendation, using the percentage as the weight on the historical price: at 50%, a $1,200 historical price and a $400 recommendation give $800. `anchor_only` takes the percentage of the historical price alone, so at 50% the floor is $600: a $400 recommendation rises to $600 and a $700 one stays at $700. Either only ever raises a price, and from 100% up both give the same price. - `historical_anchoring_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): Historical anchoring rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `custom_date_ranges` (array of object `custom_date_range`, default: `[]`): Represents an Event or Season entry used by the Wheelhouse Events & Seasons feature. Calendar rules reference these entries by `id` to apply settings (e.g. min stay, pricing) over named date windows. Each listing stores its own copy of every Event or Season it belongs to. Entries for the same event or season share the same `id` across listings — this shared `id` is what enables bulk adjustments in the Wheelhouse UI. If you write a `custom_date_ranges` entry with a new or changed `id`, that listing's entry is no longer linked to the others and will not be included in future bulk edits of the original Event or Season. To safely modify an event or season's definition (dates or name) on one listing without affecting others, omit the `id` field — the server assigns a new independent ID scoped to that listing. To update only a rule value (e.g. raise the minimum price) without changing dates, include the existing `id` unchanged. A new `custom_date_ranges` entry and a rule referencing it can be submitted in the same PUT request. Manually assign an `id` on the new entry so that the referencing rule can use it in the same payload. Alternatively, use two sequential PUTs: the first PUT creates the entry without an `id` (the server assigns one, returned in the response); the second PUT adds the rule referencing that server-assigned `id`. - Fields: see `custom_date_range` under Schemas. - `min_min_price` (integer, default: `0`): UI: 'Absolute minimum price' — Hard lower bound that overrides all pricing rules. No recommended price will fall below this value regardless of any rule configuration. Distinct from a `global` rule in `minimum_price_rules_v3`, which can be overridden by higher-priority rules. Must be an integer (whole currency units). - `min_min_stay` (integer, default: `0`): UI: 'Absolute minimum stay' — Hard lower bound that overrides all minimum stay rules. No minimum stay will be set below this value regardless of any rule configuration. Distinct from both a `global` rule in `minimum_stay_rules_v3` (which can be overridden by higher-priority rules) and from `global_min_stay` in the price recommendations response (which reflects the current effective default rule value, not a hard floor). - `apply_gap_night_rules_to_overrides` (boolean): UI: 'Apply Gap Night Rules to Overrides' — When `true`, gap-night minimum stay rules take priority over custom (date override) rules. When `false` (default), custom rules win over gap-night rules. ### Example request ```bash curl -X PUT 'https://api.usewheelhouse.com/ss_api/v1/preferences?channel=' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{ "listing_preferences": [ { "listing_id": "string" } ] }' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 All updates succeeded. Body (`application/json`): object - `updated_preferences` (array of object `listing_preference_response`) - Fields: see `listing_preference_response` under Schemas. Example shape (generated from the schema; placeholder values, not a real response): ```json { "updated_preferences": [ { "listing_id": 0, "partner_listing_id": "string", "currency": "string", "automatic_rate_posting_enabled": true, "base_price": 0, "base_price_adjustment": 0, "monthly_discount": 0, "weekly_discount": 0, "nickname": "string", "last_minute_discount": { "type": "CON", "rules": [ { "type": "time_based", "days_after": 0, "days_before": 0, "months": [ 1 ], "priority": 0, "day_of_week_values": [ 0, 0, 0, 0, 0, 0, 0 ], "value": 0 } ], "smooth": false }, "far_future_premium": { "type": "CON", "rules": [ { "type": "time_based", "days_after": 0, "days_before": 0, "months": [ 1 ], "priority": 0, "day_of_week_values": [ 0, 0, 0, 0, 0, 0, 0 ], "value": 0 } ], "smooth": false }, "seasonality_adjustment": { "type": "CON", "rules": [ { "type": "seasonal", "id": 0, "priority": 0, "day_of_week_values": [ 0, 0, 0, 0, 0, 0, 0 ], "value": 0 } ], "smooth": false }, "day_of_week": { "type": "CON", "rules": [ { "type": "global", "priority": 0, "value": 0 } ] }, "gap_night": { "custom": [ { "adjacent": "left", "adjustment": 0, "day_of_week": [ 0 ], "gap": 0 } ], "type": "CON" }, "minimum_stay_rules_v3": [], "min_stays_enabled": true, "minimum_price_rules_v3": [], "maximum_price_rules_v3": [], "checkin_checkout": { "active": true, "auto_adjust": true, "check_in_rules": [ { "type": "global", "priority": 0, "value": 0 } ], "check_out_rules": [ { "type": "global", "priority": 0, "value": 0 } ] }, "long_term_discounts": { "active": false, "weekly_rules": [], "monthly_rules": [], "rules": {} }, "occupancy_pacing": {}, "fee_adjustments": { "total_fee_percentage": 0, "auto_update": true }, "demand_sensitivity_rules": [], "historical_anchoring_price_source": "observed", "historical_anchoring_mode": "blended", "historical_anchoring_rules": [], "custom_date_ranges": [], "min_min_price": 0, "min_min_stay": 0, "apply_gap_night_rules_to_overrides": true, "update_from": "string", "update_from_id": 0, "created_at": "string", "updated_at": "string", "supported_settings": { "checkin_checkout": true, "min_stays": true, "long_term_discounts": true, "long_term_discount_type": "disabled" }, "warnings": [ { "setting": "checkin_checkout", "reason": "not_supported_by_channel", "message": "string", "attributes": [ "string" ] } ] } ] } ``` ### 207 Some updates succeeded and some failed. Body (`application/json`): object - `updated_preferences` (array of object `listing_preference_response`) - Fields: see `listing_preference_response` under Schemas. - `errors` (array of array of string | integer, each item min items: 3, max items: 3): List of per-listing errors. - Fields: see `preference_error` under Schemas. Example shape (generated from the schema; placeholder values, not a real response): ```json { "updated_preferences": [ { "listing_id": 0, "partner_listing_id": "string", "currency": "string", "automatic_rate_posting_enabled": true, "base_price": 0, "base_price_adjustment": 0, "monthly_discount": 0, "weekly_discount": 0, "nickname": "string", "last_minute_discount": { "type": "CON", "rules": [ { "type": "time_based", "days_after": 0, "days_before": 0, "months": [ 1 ], "priority": 0, "day_of_week_values": [ 0, 0, 0, 0, 0, 0, 0 ], "value": 0 } ], "smooth": false }, "far_future_premium": { "type": "CON", "rules": [ { "type": "time_based", "days_after": 0, "days_before": 0, "months": [ 1 ], "priority": 0, "day_of_week_values": [ 0, 0, 0, 0, 0, 0, 0 ], "value": 0 } ], "smooth": false }, "seasonality_adjustment": { "type": "CON", "rules": [ { "type": "seasonal", "id": 0, "priority": 0, "day_of_week_values": [ 0, 0, 0, 0, 0, 0, 0 ], "value": 0 } ], "smooth": false }, "day_of_week": { "type": "CON", "rules": [ { "type": "global", "priority": 0, "value": 0 } ] }, "gap_night": { "custom": [ { "adjacent": "left", "adjustment": 0, "day_of_week": [ 0 ], "gap": 0 } ], "type": "CON" }, "minimum_stay_rules_v3": [], "min_stays_enabled": true, "minimum_price_rules_v3": [], "maximum_price_rules_v3": [], "checkin_checkout": { "active": true, "auto_adjust": true, "check_in_rules": [ { "type": "global", "priority": 0, "value": 0 } ], "check_out_rules": [ { "type": "global", "priority": 0, "value": 0 } ] }, "long_term_discounts": { "active": false, "weekly_rules": [], "monthly_rules": [], "rules": {} }, "occupancy_pacing": {}, "fee_adjustments": { "total_fee_percentage": 0, "auto_update": true }, "demand_sensitivity_rules": [], "historical_anchoring_price_source": "observed", "historical_anchoring_mode": "blended", "historical_anchoring_rules": [], "custom_date_ranges": [], "min_min_price": 0, "min_min_stay": 0, "apply_gap_night_rules_to_overrides": true, "update_from": "string", "update_from_id": 0, "created_at": "string", "updated_at": "string", "supported_settings": { "checkin_checkout": true, "min_stays": true, "long_term_discounts": true, "long_term_discount_type": "disabled" }, "warnings": [ { "setting": "checkin_checkout", "reason": "not_supported_by_channel", "message": "string", "attributes": [ "string" ] } ] } ], "errors": [ [ "1234567890", "Listing not found", 404 ] ] } ``` ### 401 API key authorization failed. ### 403 The API key is read-only and may not be used with PUT. ### 424 All updates failed. Body: same as `207` above. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` ## Schemas Shared by more than one field above. ### `calendar_rule_time_based` Type: object `calendar_rule_time_based` **time_based** — Relative to "today" for the listing. At least one of `days_before` or `days_after` must be set. Provide `value` or `day_of_week_values`, not both. Optional `months` scopes by calendar month. When only `days_before` is set, the rule applies to dates within that many days of today (last-minute window). When only `days_after` is set, the rule applies to dates at least that many days away (far-future window). When both are set, the rule applies to dates that satisfy both conditions simultaneously — at least `days_after` days away AND within `days_before` days — creating a mid-booking-window band. `days_before` must be greater than or equal to `days_after` when both are provided. **time_based** — Relative to “today” for the listing. At least one of `days_before` or `days_after` must be set. Provide `value` or `day_of_week_values`, not both. Optional `months` scopes by calendar month. When only `days_before` is set, the rule applies to dates within that many days of today (last-minute window). When only `days_after` is set, the rule applies to dates at least that many days away (far-future window). When both are set, the rule applies to dates that satisfy both conditions simultaneously — at least `days_after` days away AND within `days_before` days — creating a mid-booking-window band. `days_before` must be greater than or equal to `days_after` when both are provided. - `type` (string, required, one of: `time_based`) - `days_after` (integer, nullable): Applies on/after “today + days_after”. When combined with `days_before`, creates a mid-window band (see rule description). `null` when this side of the window is unset. - `days_before` (integer, nullable): Applies within “today + days_before”. Must be >= `days_after` when both are set. `null` when this side of the window is unset. - `months` (array of integer, min items: 1, each item min: 1, max: 12): When set, restrict to these month ordinals (1–12). - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number) ### `calendar_rule_seasonal` Type: object `calendar_rule_seasonal` **seasonal** — Tied to a custom seasonal date range. Set `id` to the custom range. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `seasonal`) - `id` (integer | string, required): Custom seasonal date-range identifier. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number) ### `calendar_rule_event` Type: object `calendar_rule_event` **event** — Tied to a custom event date range. Set `id` to the custom range. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `event`) - `id` (integer | string, required): Custom event / date-range identifier. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number) ### `calendar_rule_monthly_simple` Type: object `calendar_rule_monthly_simple` **monthly** — Limited to specific `months`. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `monthly`) - `months` (array of integer, required, min items: 1, each item min: 1, max: 12): Month ordinals (1–12); at least one. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number) ### `calendar_rule_day_of_week` Type: object `calendar_rule_day_of_week` **day_of_week** — Per weekday (7 values, Sunday-first). Optional `months` limits to those month ordinals. Must not combine with `days_before` / `days_after` (use `time_based` for that). - `type` (string, required, one of: `day_of_week`) - `months` (array of integer, min items: 1, each item min: 1, max: 12): When set, restrict to these month ordinals (1–12). - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, required, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. ### `calendar_rule_custom` Type: object `calendar_rule_custom` **custom** — Fixed calendar date range. `start_date` and `end_date` inclusive; optional `yearly` repeats each year. Provide `value` or `day_of_week_values`, not both. UI: 'Date-specific overrides.' Not related to `custom_date_ranges` (Events & Seasons), Custom Rates, or the `CUS` preset type. - `type` (string, required, one of: `custom`) - `end_date` (string (date), required): Inclusive end (ISO-8601 date). - `id` (integer | string): Server-assigned identifier, returned as a string when present. On `checkin_checkout` rules it pairs a check-in rule with its check-out rule and is derived from the rule's contents, so it changes when the rule changes (on `seasonal` and `event` rules it is the season or event id instead). Requests don't use it to identify a rule, so don't store it as a stable key. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `start_date` (string (date), required): Inclusive start (ISO-8601 date). - `yearly` (boolean): When true, repeat the same month/day span every year. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number): Single value for dates in range when `day_of_week_values` is not used. ### `calendar_rule_monthly` Type: object `calendar_rule_monthly` **monthly** — Limited to specific `months`. Provide `value` or `day_of_week_values`, not both. For linear interpolation (`step: false`), set `start_value` and `end_value` with the peak in `value`. Linear interpolation is only honored in the `seasonality_adjustment` setting, and not when `smooth` is `true`. - `type` (string, required, one of: `monthly`) - `months` (array of integer, required, min items: 1, each item min: 1, max: 12): Month ordinals (1–12); at least one. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `end_value` (number): Value at month end for linear interpolation when `step` is false. - `start_value` (number): Value at month start for linear interpolation when `step` is false. - `step` (boolean): When true, stepped monthly values; when false, linear interpolation using `start_value`, `value` (peak), and `end_value`. Ignored in `seasonality_adjustment` when `smooth` is `true`. - `value` (number): Single value for the month or peak value when interpolating. ### `calendar_rule_global` Type: object `calendar_rule_global` **global** — Single default for the calendar in this rule set. Must not set `day_of_week_values`. UI: 'Default' or 'Minimum price default' (label varies by setting). - `type` (string, required, one of: `global`) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `value` (number, required): Default value (non-negative). ### `gap_night` Type: object `gap_night` Gap night pricing strategy (UI: 'Gaps & Adjacencies' in the Pricing Engine panel). Controls the price multiplier for gap nights between bookings. When `type` is `CUS`, provide `custom` rules; the server rejects `CUS` without `custom`. This is a **pricing-only** setting. It is unrelated to the `gap` and `adjacency`/`one_sided_gap` rule types in `minimum_stay_rules_v3`, which control minimum stay behavior for gap nights. In a request the `custom` array replaces the stored one. Gap night pricing does not apply to listings with more than one unit. The setting is still accepted, and the response carries a `not_supported_for_multi_unit` warning. - `custom` (array of object `gap_night_custom_rule`): Per-gap custom rules. Required when `type` is `CUS` (may be an empty array). Each entry targets a gap length, weekday set, and optional one-sided adjacency (`left` / `right`). - Each item: One custom gap-night rule. `adjustment` is a price multiplier greater than 0 and at most 10 (`0.8` is a 20% discount). `day_of_week` uses 0 = Sunday through 6 = Saturday, unique values only, length 1–7. When several rules match a night, rules without `adjacent` are checked first, then `left`, then `right`. Within those, the rule with the smallest `gap` that still covers the gap wins, and among rules sharing that `gap` the largest `adjustment` wins. - `adjacent` (string, one of: `left`, `right`): Omit to match open nights with an unavailable night on both sides ("In between"). `left` matches the first `gap` open nights after an unavailable night ("Only after"); `right` matches the last `gap` open nights before one ("Only before"). - `adjustment` (number, required): Price multiplier; greater than 0 and at most 10. `0.8` is a 20% discount. - `day_of_week` (array of integer, required, min items: 1, max items: 7, each item min: 0, max: 6): Weekdays this rule applies to (0–6, each at most once). - `gap` (integer, required): Applies to gaps of this many nights or fewer. - `type` (string, required, one of: `CON`, `REC`, `AGG`, `CUS`): Preset strategy (`CON`, `REC`, `AGG`) or custom (`CUS`) gap-night rules. ### `integer_calendar_rule` Type: object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule` Integer calendar rules (minimum stay, min/max price caps, local events, check-in/out, long-term discounts, etc.). - One of: - **calendar_rule_adjacency_int** (object `calendar_rule_adjacency_int`): Integer-valued adjacency / one-sided gap rule (same semantics as `calendar_rule_adjacency`). Only used in `minimum_stay_rules_v3` (MLOS behavior). Not related to the `gap_night` pricing setting. - `type` (string, required, one of: `adjacency`, `one_sided_gap`): Use `adjacency` or legacy `one_sided_gap` (same behavior). - `adjustment` (integer): Add to the existing calendar value instead of replacing it. - `day_of_week_adjustments` (array of integer, min items: 7, max items: 7, each item nullable): Per-day adjustments (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `days_adjacent` (integer, required): Window of adjacent days (negative = prior side, positive = subsequent side). To match both sides, use two separate rules — one with a negative value and one with a positive value. When both rules fire on the same date, the negative rule's value takes precedence (it is evaluated last and overwrites the positive rule's result). - `days_after` (integer): Legacy alias retained on some stored adjacency rules. Prefer `days_adjacent`. - `days_one_sided_gap` (integer): Legacy alias retained on some stored adjacency rules. Prefer `days_adjacent`. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day minimums (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer): Single minimum when `day_of_week_values` is not used. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_gap_int** (object `calendar_rule_gap_int`): **gap** — When `gap_enabled` is true, applies a minimum stay only for "gap" nights that cannot fit the normal min stay. Provide `value` or `day_of_week_values` for the gap minimum. Optional `days_before` / `days_after` scope the rule in time. Only used in `minimum_stay_rules_v3` (MLOS behavior). Not related to the `gap_night` pricing setting. **gap** — When `gap_enabled` is true, applies a minimum stay only for “gap” nights that cannot fit the normal min stay. Provide `value` or `day_of_week_values` for the gap minimum. Optional `days_before` / `days_after` scope the rule in time. - `type` (string, required, one of: `gap`) - `days_after` (integer) - `days_before` (integer) - `gap_enabled` (boolean, required, one of: `true`) - `gap_flexibility` (integer): Reduces effective min stay in the gap by this many nights. It will never drop below `value`. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day gap minimums (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer): Gap minimum stay (integer in typical min-stay rules). - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. ### `calendar_rule_global_int` Type: object `calendar_rule_global_int` **global** — Single default for the calendar in this rule set. Must not set `day_of_week_values`. UI: 'Default' or 'Minimum price default' (label varies by setting). - `type` (string, required, one of: `global`) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `value` (integer, required): Default value (non-negative). ### `calendar_rule_time_based_int` Type: object `calendar_rule_time_based_int` **time_based** — Relative to "today" for the listing. At least one of `days_before` or `days_after` must be set. Provide `value` or `day_of_week_values`, not both. Optional `months` scopes by calendar month. When only `days_before` is set, the rule applies to dates within that many days of today (last-minute window). When only `days_after` is set, the rule applies to dates at least that many days away (far-future window). When both are set, the rule applies to dates that satisfy both conditions simultaneously — at least `days_after` days away AND within `days_before` days — creating a mid-booking-window band. `days_before` must be greater than or equal to `days_after` when both are provided. **time_based** — Relative to “today” for the listing. At least one of `days_before` or `days_after` must be set. Provide `value` or `day_of_week_values`, not both. Optional `months` scopes by calendar month. When only `days_before` is set, the rule applies to dates within that many days of today (last-minute window). When only `days_after` is set, the rule applies to dates at least that many days away (far-future window). When both are set, the rule applies to dates that satisfy both conditions simultaneously — at least `days_after` days away AND within `days_before` days — creating a mid-booking-window band. `days_before` must be greater than or equal to `days_after` when both are provided. - `type` (string, required, one of: `time_based`) - `days_after` (integer, nullable): Applies on/after “today + days_after”. When combined with `days_before`, creates a mid-window band (see rule description). `null` when this side of the window is unset. - `days_before` (integer, nullable): Applies within “today + days_before”. Must be >= `days_after` when both are set. `null` when this side of the window is unset. - `months` (array of integer, min items: 1, each item min: 1, max: 12): When set, restrict to these month ordinals (1–12). - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer) ### `calendar_rule_seasonal_int` Type: object `calendar_rule_seasonal_int` **seasonal** — Tied to a custom seasonal date range. Set `id` to the custom range. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `seasonal`) - `id` (integer | string, required): Custom seasonal date-range identifier. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer) ### `calendar_rule_event_int` Type: object `calendar_rule_event_int` **event** — Tied to a custom event date range. Set `id` to the custom range. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `event`) - `id` (integer | string, required): Custom event / date-range identifier. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer) ### `calendar_rule_monthly_int` Type: object `calendar_rule_monthly_int` **monthly** — Limited to specific `months`. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `monthly`) - `months` (array of integer, required, min items: 1, each item min: 1, max: 12): Month ordinals (1–12); at least one. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer): Single value for the month. ### `calendar_rule_day_of_week_int` Type: object `calendar_rule_day_of_week_int` **day_of_week** — Per weekday (7 values, Sunday-first). Optional `months` limits to those month ordinals. Must not combine with `days_before` / `days_after` (use `time_based` for that). - `type` (string, required, one of: `day_of_week`) - `months` (array of integer, min items: 1, each item min: 1, max: 12): When set, restrict to these month ordinals (1–12). - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, required, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. ### `calendar_rule_custom_int` Type: object `calendar_rule_custom_int` **custom** — Fixed calendar date range. `start_date` and `end_date` inclusive; optional `yearly` repeats each year. Provide `value` or `day_of_week_values`, not both. UI: 'Date-specific overrides.' Not related to `custom_date_ranges` (Events & Seasons), Custom Rates, or the `CUS` preset type. - `type` (string, required, one of: `custom`) - `end_date` (string (date), required): Inclusive end (ISO-8601 date). - `id` (integer | string): Server-assigned identifier, returned as a string when present. On `checkin_checkout` rules it pairs a check-in rule with its check-out rule and is derived from the rule's contents, so it changes when the rule changes (on `seasonal` and `event` rules it is the season or event id instead). Requests don't use it to identify a rule, so don't store it as a stable key. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `start_date` (string (date), required): Inclusive start (ISO-8601 date). - `yearly` (boolean): When true, repeat the same month/day span every year. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer): Single value for dates in range when `day_of_week_values` is not used. ### `occupancy_pacing` Type: object `occupancy_pacing` Occupancy pacing matrix configuration. `{}` means pacing is off, which is the default for a new listing. When `occupancy_pacing` is sent as a non-empty object, `adjusted` and `pacing` are required, and `pacing` must include a matrix with `type` `global` (otherwise the request is rejected with 400). In a request the object replaces the stored one as a whole; omit it to leave pacing unchanged. For each lead-time column, occupancy is measured across that whole window and the matching row's percentage is applied to every date in it. A row covers occupancy above `min` up to and including `max` (`min` `0` includes 0%); the first matching row wins, and dates outside every column or row are unchanged. The adjusted price still respects the listing's minimum and maximum price rules. - `adjusted` (boolean): When true, occupancy is computed as booked nights divided by bookable (unblocked) nights; when false, against calendar days × units. - `pacing` (array of object `occupancy_pacing_matrix`): Pacing matrices. Must include one with `type` `global`, which is the one applied; others are ignored. - Each item: One pacing matrix (rows × columns of adjustment percentages). - `columns` (array of object `occupancy_pacing_column`, required): Lead-time column definitions; count must match each row in `values`. - Each item: Lead-time window (days from today) for one column of the pacing matrix. - `days_max` (integer, required, min: 0, max: 1000): Inclusive end of lead-time window (0–1000). Must be greater than or equal to `days_min`. - `days_min` (integer, required, min: 0, max: 1000): Inclusive start of lead-time window (0–1000). - `rows` (array of object `occupancy_pacing_row`, required): Occupancy (or revenue) percentage band rows; each `min`/`max` is 0–100 for occupancy pacing. - Each item: Occupancy percentage band for one row of the pacing matrix. - `max` (integer, required, min: 0, max: 100): Upper bound of the band (0–100 inclusive). - `min` (integer, required, min: 0, max: 100): Lower bound of the band (0–100 inclusive). - `type` (string, required): Rule discriminator; `global` is used for the active pacing matrix. - `values` (array of array of integer, required): Price adjustments as whole percentages (`-10` is a 10% decrease, `10` a 10% increase), each ≥ -100. One array per entry in `rows`, each holding one value per entry in `columns`; any other shape is rejected with 400. ### `fee_adjustments` Type: object `fee_adjustments` UI: 'Asking Rate (+Est. Fees)' — The estimated share of fees guests pay on top of the nightly rate, as a percentage of that rate. It is what `GET /listings/{listing_id}/fee_impact_calendar` returns as a per-date multiplier. A response carries `null` when nothing is configured, otherwise both keys. In a request the object replaces the stored one as a whole, so send both keys; `null` clears the setting. - `total_fee_percentage` (number): Fees as a percentage of the nightly rate, `-100` or more. `15` means guests pay about 15% on top of the nightly rate in fees; there is no upper bound, since fees can exceed the nightly rate on short stays. Omitted means `0`. - `auto_update` (boolean): When `true`, `total_fee_percentage` is recalculated weekly from the fees on the listing's recent reservations, replacing whatever was set. Defaults to `false` when omitted. ### `custom_date_range` Type: object `custom_date_range` Represents an Event or Season entry used by the Wheelhouse Events & Seasons feature. Calendar rules reference these entries by `id` to apply settings (e.g. min stay, pricing) over named date windows. Each listing stores its own copy of every Event or Season it belongs to. Entries for the same event or season share the same `id` across listings — this shared `id` is what enables bulk adjustments in the Wheelhouse UI. If you write a `custom_date_ranges` entry with a new or changed `id`, that listing's entry is no longer linked to the others and will not be included in future bulk edits of the original Event or Season. To safely modify an event or season's definition (dates or name) on one listing without affecting others, omit the `id` field — the server assigns a new independent ID scoped to that listing. To update only a rule value (e.g. raise the minimum price) without changing dates, include the existing `id` unchanged. - `date_ranges` (array of object `custom_date_range_segment`, required): One or more inclusive calendar spans. Each span must include `start_date` and `end_date`, and `start_date` must be on or before `end_date`. - Each item: Inclusive calendar span within a custom date range. - `end_date` (string (date), required): Inclusive end (ISO-8601 date). - `start_date` (string (date), required): Inclusive start (ISO-8601 date). - `id` (string): Stable identifier for this range, referenced by calendar rules. Listings that share the same `id` for an entry are considered part of the same Event or Season and can be bulk-edited together. Preserve the existing `id` when updating an entry to keep it linked; omit only when creating a new range (one will be assigned). The server always returns this field as a string. Calendar rule `id` fields accept both string and integer for backward compatibility, but the canonical type is string — use string comparisons when matching rule `id` values against `custom_date_ranges` entries. - `name` (string, required): Display name for the season or event. - `type` (string, required, one of: `event`, `seasonal`): Whether this range represents a recurring season or a dated event. - `yearly` (boolean, required): When true, the date spans repeat each calendar year (same month/day pattern). ### `listing_preference_response` Type: object `listing_preference_response` The full set of pricing preferences for a listing. - `listing_id` (integer, read-only): The Wheelhouse internal listing ID. - `partner_listing_id` (string, read-only): The channel's listing ID. - `currency` (string, nullable, read-only): The currency used for prices in this listing's preferences. - `automatic_rate_posting_enabled` (boolean): Whether Wheelhouse automatically posts prices to the channel calendar. When `false`, recommendations are computed but nothing is pushed to the channel. - `base_price` (number, nullable): The base price the user set by hand, in the preferences `currency`. When set, the pricing engine uses it instead of the Wheelhouse recommendation, and `base_price_adjustment` is `null`. `null` does **not** mean the listing has no base price. It means the base price follows the Wheelhouse recommendation, multiplied by `base_price_adjustment` (or by `1.0` when that is also `null`). To read the base price in use, call `GET /listings/{listing_id}/price_recommendations` and read its top-level `base_price`. Set to `null` to go back to the Wheelhouse recommendation, or set a preset with `PUT /preferences/{listing_id}/base_price_adjustment` and `type` `CON`, `REC`, or `AGG`. - `base_price_adjustment` (number, nullable): The multiplier the pricing engine applies to the Wheelhouse recommended base price (`base_price_recommended` on `GET /listings/{listing_id}/price_recommendations`) when `base_price` is `null`. The presets are `0.9` (conservative, `CON`), `1.0` (recommended, `REC`), and `1.1` (aggressive, `AGG`). Any other value is a custom adjustment, for example `1.05` for 5% above the recommendation. For example, with `base_price_recommended` 200 and `base_price_adjustment` `0.9`, the base price in use is 180, and `base_price` here is `null`. `null` when `base_price` is set, because the manual base price applies instead. Both fields can also be `null`, for example after a manual base price is cleared. The pricing engine then uses `1.0`, the recommended preset. - `monthly_discount` (integer, nullable, default: `0`): Monthly discount percentage as an integer in the range 0–100 (e.g. `5` = 5%). On listings that accept length-of-stay premiums (every listing whose `supported_settings.long_term_discount_type` is `complex`, and some with `rules`), values are signed instead, so `-10` is a 10% discount and `10` a 10% premium. Applied to bookings ≥ 28 nights. Kept in sync with the global rule in `long_term_discounts.rules['28']` — setting one automatically updates the other. When both are sent in the same PUT, `long_term_discounts` takes precedence. - `weekly_discount` (integer, nullable, default: `0`): Weekly discount percentage as an integer in the range 0–100 (e.g. `5` = 5%). On listings that accept length-of-stay premiums (every listing whose `supported_settings.long_term_discount_type` is `complex`, and some with `rules`), values are signed instead, so `-10` is a 10% discount and `10` a 10% premium. Applied to bookings ≥ 7 nights. Kept in sync with the global rule in `long_term_discounts.rules['7']` — setting one automatically updates the other. When both are sent in the same PUT, `long_term_discounts` takes precedence. - `nickname` (string, nullable): Listing nickname. - `last_minute_discount` (object, nullable): UI: 'Last minute' — Last-minute discount configuration. - `type` (string, one of: `CON`, `REC`, `AGG`, `CUS`) - `rules` (array of object `calendar_rule_time_based` | object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly_simple` | object `calendar_rule_day_of_week` | object `calendar_rule_custom`): Calendar rules when `type` is `CUS`. Valid rule types: `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_time_based**: see `calendar_rule_time_based` under Schemas. - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly_simple**: see `calendar_rule_monthly_simple` under Schemas. - **calendar_rule_day_of_week**: see `calendar_rule_day_of_week` under Schemas. - **calendar_rule_custom**: see `calendar_rule_custom` under Schemas. - `smooth` (boolean, default: `false`): UI: 'Smooth' — Only used when `type` is `CUS`. When `true`, the adjustment eases gradually from one rule to the next instead of jumping at each rule's edge. `custom` rules still apply exactly. Defaults to `false` (stepped). - `far_future_premium` (object, nullable): UI: 'Far future' — Far-future premium configuration. - `type` (string, one of: `CON`, `REC`, `AGG`, `CUS`) - `rules` (array of object `calendar_rule_time_based` | object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly_simple` | object `calendar_rule_day_of_week` | object `calendar_rule_custom`): Calendar rules when `type` is `CUS`. Valid rule types: `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_time_based**: see `calendar_rule_time_based` under Schemas. - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly_simple**: see `calendar_rule_monthly_simple` under Schemas. - **calendar_rule_day_of_week**: see `calendar_rule_day_of_week` under Schemas. - **calendar_rule_custom**: see `calendar_rule_custom` under Schemas. - `smooth` (boolean, default: `false`): UI: 'Smooth' — Only used when `type` is `CUS`. When `true`, the adjustment eases gradually from one rule to the next instead of jumping at each rule's edge. `custom` rules still apply exactly. Defaults to `false` (stepped). - `seasonality_adjustment` (object, nullable): UI: 'Seasonality' — Seasonality adjustment configuration. - `type` (string, one of: `CON`, `REC`, `AGG`, `CUS`) - `rules` (array of object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly`): Calendar rules when `type` is `CUS`. Valid rule types: `seasonal`, `event`, `monthly`. - One of: - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly**: see `calendar_rule_monthly` under Schemas. - `smooth` (boolean, default: `false`): UI: 'Smooth' — Only used when `type` is `CUS`. When `true`, the adjustment eases gradually from one rule to the next instead of jumping at each rule's edge, and monthly rules' `step`, `start_value` and `end_value` are ignored. Defaults to `false` (stepped). - `day_of_week` (object, nullable): Day-of-week pricing factor configuration. - `REC` applies the market's day-of-week pattern. - `CON` and `AGG` adjust that pattern conservatively or aggressively. Sent without `rules`, they store the matching preset `day_of_week` rule. - `ADJ` applies the market's pattern and multiplies your own `rules` on top of it. - `CUS` replaces the market's pattern with your own `rules`, whose values are price multipliers (`1.1` is 10% higher). `CUS` without `rules` prices every day the same. A `CUS` setting saved before the day-of-week and local events split is returned as `ADJ`, since that is how it has priced since the split. - `type` (string, one of: `CON`, `REC`, `AGG`, `ADJ`, `CUS`) - `rules` (array of object `calendar_rule_global` | object `calendar_rule_time_based` | object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly_simple` | object `calendar_rule_day_of_week` | object `calendar_rule_custom`): Calendar rules when `type` is `ADJ` or `CUS`. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global**: see `calendar_rule_global` under Schemas. - **calendar_rule_time_based**: see `calendar_rule_time_based` under Schemas. - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly_simple**: see `calendar_rule_monthly_simple` under Schemas. - **calendar_rule_day_of_week**: see `calendar_rule_day_of_week` under Schemas. - **calendar_rule_custom**: see `calendar_rule_custom` under Schemas. - `gap_night` (object `gap_night`, nullable): Gap night pricing strategy (UI: 'Gaps & Adjacencies' in the Pricing Engine panel). Controls the price multiplier for gap nights between bookings. When `type` is `CUS`, provide `custom` rules; the server rejects `CUS` without `custom`. This is a **pricing-only** setting. It is unrelated to the `gap` and `adjacency`/`one_sided_gap` rule types in `minimum_stay_rules_v3`, which control minimum stay behavior for gap nights. In a request the `custom` array replaces the stored one. Gap night pricing does not apply to listings with more than one unit. The setting is still accepted, and the response carries a `not_supported_for_multi_unit` warning. - Fields: see `gap_night` under Schemas. - `minimum_stay_rules_v3` (array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`, default: `[]`): UI: 'Minimum stays' — minimum stay rules. The `_v3` suffix is a stable historical identifier; this field name is not expected to change. - Fields: see `integer_calendar_rule` under Schemas. - `min_stays_enabled` (boolean): Whether minimum stay rules are enabled. - `minimum_price_rules_v3` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): UI: 'Minimum prices' — Minimum price rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. The `_v3` suffix is a stable historical identifier; this field name is not expected to change. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `maximum_price_rules_v3` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): UI: 'Maximum prices' — Maximum price rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. The `_v3` suffix is a stable historical identifier; this field name is not expected to change. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `checkin_checkout` (object, nullable): Which days guests may check in and check out. Rule values are allow flags: `1` allows the day and `0` blocks it. A `day_of_week` rule's `day_of_week_values` has 7 entries, index 0 = Sunday. Where rules overlap, the more specific rule type wins (for example a date-specific `custom` rule over a `day_of_week` rule); between rules of the same type, the later one in the array wins. In a request the object replaces the stored one as a whole: send `active` and both `check_in_rules` and `check_out_rules` (a request missing either array is rejected with 400). An empty `check_out_rules` leaves check-out unrestricted. Example, check-in on Friday and Saturday only, check-out any day: ```json { "active": true, "auto_adjust": false, "check_in_rules": [{"type": "day_of_week", "day_of_week_values": [0, 0, 0, 0, 0, 1, 1]}], "check_out_rules": [{"type": "day_of_week", "day_of_week_values": [1, 1, 1, 1, 1, 1, 1]}] } ``` - `active` (boolean): Whether the check-in/check-out rules are enforced. Stored as `false` when omitted. - `auto_adjust` (boolean): When `true`, Wheelhouse opens additional check-in and check-out days around unavailable nights so that open stretches between bookings can still be booked, even on days the rules would otherwise block. - `check_in_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`): Allowed check-in rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `check_out_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`): Allowed check-out rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `long_term_discounts` (object, default: `{"active":false,"weekly_rules":[],"monthly_rules":[],"rules":{}}`): Rule-based long-term discount configuration. - `active` (boolean) - `weekly_rules` (array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`, **deprecated**): Weekly discount rules (integer calendar rules). - Fields: see `integer_calendar_rule` under Schemas. - `monthly_rules` (array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`, **deprecated**): Monthly discount rules (integer calendar rules). - Fields: see `integer_calendar_rule` under Schemas. - `rules` (map of string to array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`): LOS-keyed rules (integer calendar rules). Keys are length-of-stay thresholds (e.g. "7", "28"); values are arrays of integer calendar rules holding whole percentages (`10` is a 10% discount). On listings that accept length-of-stay premiums (every listing whose `supported_settings.long_term_discount_type` is `complex`, and some with `rules`), values are signed instead, so `-10` is a 10% discount and `10` a 10% premium. - Fields: see `integer_calendar_rule` under Schemas. - `occupancy_pacing` (object `occupancy_pacing`, nullable, default: `{}`): Occupancy pacing configuration. When `occupancy_pacing` is sent as a non-empty object, both `adjusted` and `pacing` are required. Occupancy pacing matrix configuration. `{}` means pacing is off, which is the default for a new listing. When `occupancy_pacing` is sent as a non-empty object, `adjusted` and `pacing` are required, and `pacing` must include a matrix with `type` `global` (otherwise the request is rejected with 400). In a request the object replaces the stored one as a whole; omit it to leave pacing unchanged. For each lead-time column, occupancy is measured across that whole window and the matching row's percentage is applied to every date in it. A row covers occupancy above `min` up to and including `max` (`min` `0` includes 0%); the first matching row wins, and dates outside every column or row are unchanged. The adjusted price still respects the listing's minimum and maximum price rules. - Fields: see `occupancy_pacing` under Schemas. - `fee_adjustments` (object `fee_adjustments`, nullable): Estimated fee share applied on top of the nightly rate. `null` when nothing is configured, otherwise both keys are present; in a request the object replaces the stored one as a whole, and `null` clears it. UI: 'Asking Rate (+Est. Fees)' — The estimated share of fees guests pay on top of the nightly rate, as a percentage of that rate. It is what `GET /listings/{listing_id}/fee_impact_calendar` returns as a per-date multiplier. A response carries `null` when nothing is configured, otherwise both keys. In a request the object replaces the stored one as a whole, so send both keys; `null` clears the setting. - Fields: see `fee_adjustments` under Schemas. - `demand_sensitivity_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): Local events rules. Shown as Demand sensitivity before day of week became its own setting; the field name is unchanged. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `historical_anchoring_price_source` (string, one of: `observed`, `posted`, `posted_with_fallback`, default: `observed`): Which historical price historical anchoring weighs in. `observed`, the default, is the listing's price as Wheelhouse saw it on the channel once the date booked. `posted` is the price Wheelhouse last posted for the date before it booked, so dates Wheelhouse never posted a price for are not anchored. `posted_with_fallback` uses the posted price where there is one and the observed price otherwise. - `historical_anchoring_mode` (string, one of: `blended`, `anchor_only`, default: `blended`): How a historical anchoring percentage turns the historical price into a floor for the recommendation. `blended` averages the historical price with the recommendation, using the percentage as the weight on the historical price: at 50%, a $1,200 historical price and a $400 recommendation give $800. `anchor_only` takes the percentage of the historical price alone, so at 50% the floor is $600: a $400 recommendation rises to $600 and a $700 one stays at $700. Either only ever raises a price, and from 100% up both give the same price. - `historical_anchoring_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): Historical anchoring rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `custom_date_ranges` (array of object `custom_date_range`, default: `[]`): Represents an Event or Season entry used by the Wheelhouse Events & Seasons feature. Calendar rules reference these entries by `id` to apply settings (e.g. min stay, pricing) over named date windows. Each listing stores its own copy of every Event or Season it belongs to. Entries for the same event or season share the same `id` across listings — this shared `id` is what enables bulk adjustments in the Wheelhouse UI. If you write a `custom_date_ranges` entry with a new or changed `id`, that listing's entry is no longer linked to the others and will not be included in future bulk edits of the original Event or Season. To safely modify an event or season's definition (dates or name) on one listing without affecting others, omit the `id` field — the server assigns a new independent ID scoped to that listing. To update only a rule value (e.g. raise the minimum price) without changing dates, include the existing `id` unchanged. A new `custom_date_ranges` entry and a rule referencing it can be submitted in the same PUT request. Manually assign an `id` on the new entry so that the referencing rule can use it in the same payload. Alternatively, use two sequential PUTs: the first PUT creates the entry without an `id` (the server assigns one, returned in the response); the second PUT adds the rule referencing that server-assigned `id`. - Fields: see `custom_date_range` under Schemas. - `min_min_price` (integer, default: `0`): UI: 'Absolute minimum price' — Hard lower bound that overrides all pricing rules. No recommended price will fall below this value regardless of any rule configuration. Distinct from a `global` rule in `minimum_price_rules_v3`, which can be overridden by higher-priority rules. Must be an integer (whole currency units). - `min_min_stay` (integer, default: `0`): UI: 'Absolute minimum stay' — Hard lower bound that overrides all minimum stay rules. No minimum stay will be set below this value regardless of any rule configuration. Distinct from both a `global` rule in `minimum_stay_rules_v3` (which can be overridden by higher-priority rules) and from `global_min_stay` in the price recommendations response (which reflects the current effective default rule value, not a hard floor). - `apply_gap_night_rules_to_overrides` (boolean): UI: 'Apply Gap Night Rules to Overrides' — When `true`, gap-night minimum stay rules take priority over custom (date override) rules. When `false` (default), custom rules win over gap-night rules. - `update_from` (string, read-only): The source used when the preferences were last updated. - `update_from_id` (integer, nullable, read-only): The ID of the entity used when preferences were last updated. - `created_at` (string, nullable, read-only): When the listing preferences were created (Rails-style timestamp). - `updated_at` (string, nullable, read-only): When the listing preferences were last updated (Rails-style timestamp). - `supported_settings` (object `supported_settings`, read-only): Which listing preference settings this listing's channel can act on. A setting reported `false` is discarded on write rather than posted to the channel, so check this before sending it. Reflects any per-account early access, so two listings on the same channel can differ. - `checkin_checkout` (boolean): Whether `checkin_checkout` rules can be set. - `min_stays` (boolean): Whether minimum stay settings (`min_min_stay`, `min_stays_enabled`, `minimum_stay_rules`) can be set. - `long_term_discounts` (boolean): Whether long-term discounts (`long_term_discounts`, `weekly_discount`, `monthly_discount`) can be set at all. - `long_term_discount_type` (string, one of: `disabled`, `simple`, `rules`, `complex`): The form of long-term discount the channel accepts. `disabled` takes none; `simple` takes only flat `weekly_discount` and `monthly_discount` values and ignores a `rules` object; `rules` additionally takes the 7 and 28 night tiers; `complex` takes arbitrary tiers. - `warnings` (array of object `preference_warning`, read-only, each item read-only): Settings in the request this listing's channel cannot act on, and which were therefore not applied. Present on write responses and empty when everything applied, so it can be read unconditionally; absent on reads, where nothing was being set. - Each item: One setting in the request that was not applied, or that has no effect on this listing. - `setting` (string, one of: `checkin_checkout`, `gap_night`, `min_stays`, `long_term_discounts`): The setting group the warning is about. - `reason` (string, one of: `not_supported_by_channel`, `partially_supported_by_channel`, `not_supported_for_multi_unit`): `not_supported_by_channel` — the channel has no such feature and everything sent for it was dropped. `partially_supported_by_channel` — the channel has the feature but accepts a narrower form than what was sent, and only the excess was dropped. `not_supported_for_multi_unit` — the setting is stored but has no effect on price, because the listing has more than one unit. - `message` (string): A human-readable explanation of what was ignored and why. - `attributes` (array of string): The request attributes this warning covers, in dot notation for nested ones (e.g. `long_term_discounts.rules.14`). ### `preference_error` Type: array of string | integer An error that occurred when processing a listing preference update, returned as a positional tuple in the order `[listing_id, message, http_code]`. The first two elements are strings; the third is an integer HTTP status code (e.g. 404, 403, 423, 406, 409, 500). --- # Get preferences for a listing. `GET /preferences/{listing_id}` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-preferences · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetPreferences` · Tag: Listing Preferences `base_price: null` does not mean the listing has no base price. It means the base price follows the Wheelhouse recommendation, multiplied by `base_price_adjustment` (or by `1.0` when that is also `null`). To read the base price in use, call `GET /listings/{listing_id}/price_recommendations` and read its top-level `base_price`. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/preferences/{listing_id}` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/preferences/{listing_id}?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The listing preferences. Body (`application/json`): object `listing_preference_response` The full set of pricing preferences for a listing. - `listing_id` (integer, read-only): The Wheelhouse internal listing ID. - `partner_listing_id` (string, read-only): The channel's listing ID. - `currency` (string, nullable, read-only): The currency used for prices in this listing's preferences. - `automatic_rate_posting_enabled` (boolean): Whether Wheelhouse automatically posts prices to the channel calendar. When `false`, recommendations are computed but nothing is pushed to the channel. - `base_price` (number, nullable): The base price the user set by hand, in the preferences `currency`. When set, the pricing engine uses it instead of the Wheelhouse recommendation, and `base_price_adjustment` is `null`. `null` does **not** mean the listing has no base price. It means the base price follows the Wheelhouse recommendation, multiplied by `base_price_adjustment` (or by `1.0` when that is also `null`). To read the base price in use, call `GET /listings/{listing_id}/price_recommendations` and read its top-level `base_price`. Set to `null` to go back to the Wheelhouse recommendation, or set a preset with `PUT /preferences/{listing_id}/base_price_adjustment` and `type` `CON`, `REC`, or `AGG`. - `base_price_adjustment` (number, nullable): The multiplier the pricing engine applies to the Wheelhouse recommended base price (`base_price_recommended` on `GET /listings/{listing_id}/price_recommendations`) when `base_price` is `null`. The presets are `0.9` (conservative, `CON`), `1.0` (recommended, `REC`), and `1.1` (aggressive, `AGG`). Any other value is a custom adjustment, for example `1.05` for 5% above the recommendation. For example, with `base_price_recommended` 200 and `base_price_adjustment` `0.9`, the base price in use is 180, and `base_price` here is `null`. `null` when `base_price` is set, because the manual base price applies instead. Both fields can also be `null`, for example after a manual base price is cleared. The pricing engine then uses `1.0`, the recommended preset. - `monthly_discount` (integer, nullable, default: `0`): Monthly discount percentage as an integer in the range 0–100 (e.g. `5` = 5%). On listings that accept length-of-stay premiums (every listing whose `supported_settings.long_term_discount_type` is `complex`, and some with `rules`), values are signed instead, so `-10` is a 10% discount and `10` a 10% premium. Applied to bookings ≥ 28 nights. Kept in sync with the global rule in `long_term_discounts.rules['28']` — setting one automatically updates the other. When both are sent in the same PUT, `long_term_discounts` takes precedence. - `weekly_discount` (integer, nullable, default: `0`): Weekly discount percentage as an integer in the range 0–100 (e.g. `5` = 5%). On listings that accept length-of-stay premiums (every listing whose `supported_settings.long_term_discount_type` is `complex`, and some with `rules`), values are signed instead, so `-10` is a 10% discount and `10` a 10% premium. Applied to bookings ≥ 7 nights. Kept in sync with the global rule in `long_term_discounts.rules['7']` — setting one automatically updates the other. When both are sent in the same PUT, `long_term_discounts` takes precedence. - `nickname` (string, nullable): Listing nickname. - `last_minute_discount` (object, nullable): UI: 'Last minute' — Last-minute discount configuration. - `type` (string, one of: `CON`, `REC`, `AGG`, `CUS`) - `rules` (array of object `calendar_rule_time_based` | object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly_simple` | object `calendar_rule_day_of_week` | object `calendar_rule_custom`): Calendar rules when `type` is `CUS`. Valid rule types: `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_time_based**: see `calendar_rule_time_based` under Schemas. - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly_simple**: see `calendar_rule_monthly_simple` under Schemas. - **calendar_rule_day_of_week**: see `calendar_rule_day_of_week` under Schemas. - **calendar_rule_custom**: see `calendar_rule_custom` under Schemas. - `smooth` (boolean, default: `false`): UI: 'Smooth' — Only used when `type` is `CUS`. When `true`, the adjustment eases gradually from one rule to the next instead of jumping at each rule's edge. `custom` rules still apply exactly. Defaults to `false` (stepped). - `far_future_premium` (object, nullable): UI: 'Far future' — Far-future premium configuration. - `type` (string, one of: `CON`, `REC`, `AGG`, `CUS`) - `rules` (array of object `calendar_rule_time_based` | object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly_simple` | object `calendar_rule_day_of_week` | object `calendar_rule_custom`): Calendar rules when `type` is `CUS`. Valid rule types: `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_time_based**: see `calendar_rule_time_based` under Schemas. - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly_simple**: see `calendar_rule_monthly_simple` under Schemas. - **calendar_rule_day_of_week**: see `calendar_rule_day_of_week` under Schemas. - **calendar_rule_custom**: see `calendar_rule_custom` under Schemas. - `smooth` (boolean, default: `false`): UI: 'Smooth' — Only used when `type` is `CUS`. When `true`, the adjustment eases gradually from one rule to the next instead of jumping at each rule's edge. `custom` rules still apply exactly. Defaults to `false` (stepped). - `seasonality_adjustment` (object, nullable): UI: 'Seasonality' — Seasonality adjustment configuration. - `type` (string, one of: `CON`, `REC`, `AGG`, `CUS`) - `rules` (array of object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly`): Calendar rules when `type` is `CUS`. Valid rule types: `seasonal`, `event`, `monthly`. - One of: - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly** (object `calendar_rule_monthly`): **monthly** — Limited to specific `months`. Provide `value` or `day_of_week_values`, not both. For linear interpolation (`step: false`), set `start_value` and `end_value` with the peak in `value`. Linear interpolation is only honored in the `seasonality_adjustment` setting, and not when `smooth` is `true`. - `type` (string, required, one of: `monthly`) - `months` (array of integer, required, min items: 1, each item min: 1, max: 12): Month ordinals (1–12); at least one. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `end_value` (number): Value at month end for linear interpolation when `step` is false. - `start_value` (number): Value at month start for linear interpolation when `step` is false. - `step` (boolean): When true, stepped monthly values; when false, linear interpolation using `start_value`, `value` (peak), and `end_value`. Ignored in `seasonality_adjustment` when `smooth` is `true`. - `value` (number): Single value for the month or peak value when interpolating. - `smooth` (boolean, default: `false`): UI: 'Smooth' — Only used when `type` is `CUS`. When `true`, the adjustment eases gradually from one rule to the next instead of jumping at each rule's edge, and monthly rules' `step`, `start_value` and `end_value` are ignored. Defaults to `false` (stepped). - `day_of_week` (object, nullable): Day-of-week pricing factor configuration. - `REC` applies the market's day-of-week pattern. - `CON` and `AGG` adjust that pattern conservatively or aggressively. Sent without `rules`, they store the matching preset `day_of_week` rule. - `ADJ` applies the market's pattern and multiplies your own `rules` on top of it. - `CUS` replaces the market's pattern with your own `rules`, whose values are price multipliers (`1.1` is 10% higher). `CUS` without `rules` prices every day the same. A `CUS` setting saved before the day-of-week and local events split is returned as `ADJ`, since that is how it has priced since the split. - `type` (string, one of: `CON`, `REC`, `AGG`, `ADJ`, `CUS`) - `rules` (array of object `calendar_rule_global` | object `calendar_rule_time_based` | object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly_simple` | object `calendar_rule_day_of_week` | object `calendar_rule_custom`): Calendar rules when `type` is `ADJ` or `CUS`. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global** (object `calendar_rule_global`): **global** — Single default for the calendar in this rule set. Must not set `day_of_week_values`. UI: 'Default' or 'Minimum price default' (label varies by setting). - `type` (string, required, one of: `global`) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `value` (number, required): Default value (non-negative). - **calendar_rule_time_based**: see `calendar_rule_time_based` under Schemas. - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly_simple**: see `calendar_rule_monthly_simple` under Schemas. - **calendar_rule_day_of_week**: see `calendar_rule_day_of_week` under Schemas. - **calendar_rule_custom**: see `calendar_rule_custom` under Schemas. - `gap_night` (object `gap_night`, nullable): Gap night pricing strategy (UI: 'Gaps & Adjacencies' in the Pricing Engine panel). Controls the price multiplier for gap nights between bookings. When `type` is `CUS`, provide `custom` rules; the server rejects `CUS` without `custom`. This is a **pricing-only** setting. It is unrelated to the `gap` and `adjacency`/`one_sided_gap` rule types in `minimum_stay_rules_v3`, which control minimum stay behavior for gap nights. In a request the `custom` array replaces the stored one. Gap night pricing does not apply to listings with more than one unit. The setting is still accepted, and the response carries a `not_supported_for_multi_unit` warning. - `custom` (array of object `gap_night_custom_rule`): Per-gap custom rules. Required when `type` is `CUS` (may be an empty array). Each entry targets a gap length, weekday set, and optional one-sided adjacency (`left` / `right`). - Each item: One custom gap-night rule. `adjustment` is a price multiplier greater than 0 and at most 10 (`0.8` is a 20% discount). `day_of_week` uses 0 = Sunday through 6 = Saturday, unique values only, length 1–7. When several rules match a night, rules without `adjacent` are checked first, then `left`, then `right`. Within those, the rule with the smallest `gap` that still covers the gap wins, and among rules sharing that `gap` the largest `adjustment` wins. - `adjacent` (string, one of: `left`, `right`): Omit to match open nights with an unavailable night on both sides ("In between"). `left` matches the first `gap` open nights after an unavailable night ("Only after"); `right` matches the last `gap` open nights before one ("Only before"). - `adjustment` (number, required): Price multiplier; greater than 0 and at most 10. `0.8` is a 20% discount. - `day_of_week` (array of integer, required, min items: 1, max items: 7, each item min: 0, max: 6): Weekdays this rule applies to (0–6, each at most once). - `gap` (integer, required): Applies to gaps of this many nights or fewer. - `type` (string, required, one of: `CON`, `REC`, `AGG`, `CUS`): Preset strategy (`CON`, `REC`, `AGG`) or custom (`CUS`) gap-night rules. - `minimum_stay_rules_v3` (array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`, default: `[]`): UI: 'Minimum stays' — minimum stay rules. The `_v3` suffix is a stable historical identifier; this field name is not expected to change. - Fields: see `integer_calendar_rule` under Schemas. - `min_stays_enabled` (boolean): Whether minimum stay rules are enabled. - `minimum_price_rules_v3` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): UI: 'Minimum prices' — Minimum price rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. The `_v3` suffix is a stable historical identifier; this field name is not expected to change. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `maximum_price_rules_v3` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): UI: 'Maximum prices' — Maximum price rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. The `_v3` suffix is a stable historical identifier; this field name is not expected to change. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `checkin_checkout` (object, nullable): Which days guests may check in and check out. Rule values are allow flags: `1` allows the day and `0` blocks it. A `day_of_week` rule's `day_of_week_values` has 7 entries, index 0 = Sunday. Where rules overlap, the more specific rule type wins (for example a date-specific `custom` rule over a `day_of_week` rule); between rules of the same type, the later one in the array wins. In a request the object replaces the stored one as a whole: send `active` and both `check_in_rules` and `check_out_rules` (a request missing either array is rejected with 400). An empty `check_out_rules` leaves check-out unrestricted. Example, check-in on Friday and Saturday only, check-out any day: ```json { "active": true, "auto_adjust": false, "check_in_rules": [{"type": "day_of_week", "day_of_week_values": [0, 0, 0, 0, 0, 1, 1]}], "check_out_rules": [{"type": "day_of_week", "day_of_week_values": [1, 1, 1, 1, 1, 1, 1]}] } ``` - `active` (boolean): Whether the check-in/check-out rules are enforced. Stored as `false` when omitted. - `auto_adjust` (boolean): When `true`, Wheelhouse opens additional check-in and check-out days around unavailable nights so that open stretches between bookings can still be booked, even on days the rules would otherwise block. - `check_in_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`): Allowed check-in rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `check_out_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`): Allowed check-out rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `long_term_discounts` (object, default: `{"active":false,"weekly_rules":[],"monthly_rules":[],"rules":{}}`): Rule-based long-term discount configuration. - `active` (boolean) - `weekly_rules` (array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`, **deprecated**): Weekly discount rules (integer calendar rules). - Fields: see `integer_calendar_rule` under Schemas. - `monthly_rules` (array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`, **deprecated**): Monthly discount rules (integer calendar rules). - Fields: see `integer_calendar_rule` under Schemas. - `rules` (map of string to array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`): LOS-keyed rules (integer calendar rules). Keys are length-of-stay thresholds (e.g. "7", "28"); values are arrays of integer calendar rules holding whole percentages (`10` is a 10% discount). On listings that accept length-of-stay premiums (every listing whose `supported_settings.long_term_discount_type` is `complex`, and some with `rules`), values are signed instead, so `-10` is a 10% discount and `10` a 10% premium. - Fields: see `integer_calendar_rule` under Schemas. - `occupancy_pacing` (object `occupancy_pacing`, nullable, default: `{}`): Occupancy pacing configuration. When `occupancy_pacing` is sent as a non-empty object, both `adjusted` and `pacing` are required. Occupancy pacing matrix configuration. `{}` means pacing is off, which is the default for a new listing. When `occupancy_pacing` is sent as a non-empty object, `adjusted` and `pacing` are required, and `pacing` must include a matrix with `type` `global` (otherwise the request is rejected with 400). In a request the object replaces the stored one as a whole; omit it to leave pacing unchanged. For each lead-time column, occupancy is measured across that whole window and the matching row's percentage is applied to every date in it. A row covers occupancy above `min` up to and including `max` (`min` `0` includes 0%); the first matching row wins, and dates outside every column or row are unchanged. The adjusted price still respects the listing's minimum and maximum price rules. - `adjusted` (boolean): When true, occupancy is computed as booked nights divided by bookable (unblocked) nights; when false, against calendar days × units. - `pacing` (array of object `occupancy_pacing_matrix`): Pacing matrices. Must include one with `type` `global`, which is the one applied; others are ignored. - Each item: One pacing matrix (rows × columns of adjustment percentages). - `columns` (array of object `occupancy_pacing_column`, required): Lead-time column definitions; count must match each row in `values`. - Each item: Lead-time window (days from today) for one column of the pacing matrix. - `days_max` (integer, required, min: 0, max: 1000): Inclusive end of lead-time window (0–1000). Must be greater than or equal to `days_min`. - `days_min` (integer, required, min: 0, max: 1000): Inclusive start of lead-time window (0–1000). - `rows` (array of object `occupancy_pacing_row`, required): Occupancy (or revenue) percentage band rows; each `min`/`max` is 0–100 for occupancy pacing. - Each item: Occupancy percentage band for one row of the pacing matrix. - `max` (integer, required, min: 0, max: 100): Upper bound of the band (0–100 inclusive). - `min` (integer, required, min: 0, max: 100): Lower bound of the band (0–100 inclusive). - `type` (string, required): Rule discriminator; `global` is used for the active pacing matrix. - `values` (array of array of integer, required): Price adjustments as whole percentages (`-10` is a 10% decrease, `10` a 10% increase), each ≥ -100. One array per entry in `rows`, each holding one value per entry in `columns`; any other shape is rejected with 400. - `fee_adjustments` (object `fee_adjustments`, nullable): Estimated fee share applied on top of the nightly rate. `null` when nothing is configured, otherwise both keys are present; in a request the object replaces the stored one as a whole, and `null` clears it. UI: 'Asking Rate (+Est. Fees)' — The estimated share of fees guests pay on top of the nightly rate, as a percentage of that rate. It is what `GET /listings/{listing_id}/fee_impact_calendar` returns as a per-date multiplier. A response carries `null` when nothing is configured, otherwise both keys. In a request the object replaces the stored one as a whole, so send both keys; `null` clears the setting. - `total_fee_percentage` (number): Fees as a percentage of the nightly rate, `-100` or more. `15` means guests pay about 15% on top of the nightly rate in fees; there is no upper bound, since fees can exceed the nightly rate on short stays. Omitted means `0`. - `auto_update` (boolean): When `true`, `total_fee_percentage` is recalculated weekly from the fees on the listing's recent reservations, replacing whatever was set. Defaults to `false` when omitted. - `demand_sensitivity_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): Local events rules. Shown as Demand sensitivity before day of week became its own setting; the field name is unchanged. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `historical_anchoring_price_source` (string, one of: `observed`, `posted`, `posted_with_fallback`, default: `observed`): Which historical price historical anchoring weighs in. `observed`, the default, is the listing's price as Wheelhouse saw it on the channel once the date booked. `posted` is the price Wheelhouse last posted for the date before it booked, so dates Wheelhouse never posted a price for are not anchored. `posted_with_fallback` uses the posted price where there is one and the observed price otherwise. - `historical_anchoring_mode` (string, one of: `blended`, `anchor_only`, default: `blended`): How a historical anchoring percentage turns the historical price into a floor for the recommendation. `blended` averages the historical price with the recommendation, using the percentage as the weight on the historical price: at 50%, a $1,200 historical price and a $400 recommendation give $800. `anchor_only` takes the percentage of the historical price alone, so at 50% the floor is $600: a $400 recommendation rises to $600 and a $700 one stays at $700. Either only ever raises a price, and from 100% up both give the same price. - `historical_anchoring_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): Historical anchoring rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `custom_date_ranges` (array of object `custom_date_range`, default: `[]`): Represents an Event or Season entry used by the Wheelhouse Events & Seasons feature. Calendar rules reference these entries by `id` to apply settings (e.g. min stay, pricing) over named date windows. Each listing stores its own copy of every Event or Season it belongs to. Entries for the same event or season share the same `id` across listings — this shared `id` is what enables bulk adjustments in the Wheelhouse UI. If you write a `custom_date_ranges` entry with a new or changed `id`, that listing's entry is no longer linked to the others and will not be included in future bulk edits of the original Event or Season. To safely modify an event or season's definition (dates or name) on one listing without affecting others, omit the `id` field — the server assigns a new independent ID scoped to that listing. To update only a rule value (e.g. raise the minimum price) without changing dates, include the existing `id` unchanged. A new `custom_date_ranges` entry and a rule referencing it can be submitted in the same PUT request. Manually assign an `id` on the new entry so that the referencing rule can use it in the same payload. Alternatively, use two sequential PUTs: the first PUT creates the entry without an `id` (the server assigns one, returned in the response); the second PUT adds the rule referencing that server-assigned `id`. - Each item: Represents an Event or Season entry used by the Wheelhouse Events & Seasons feature. Calendar rules reference these entries by `id` to apply settings (e.g. min stay, pricing) over named date windows. Each listing stores its own copy of every Event or Season it belongs to. Entries for the same event or season share the same `id` across listings — this shared `id` is what enables bulk adjustments in the Wheelhouse UI. If you write a `custom_date_ranges` entry with a new or changed `id`, that listing's entry is no longer linked to the others and will not be included in future bulk edits of the original Event or Season. To safely modify an event or season's definition (dates or name) on one listing without affecting others, omit the `id` field — the server assigns a new independent ID scoped to that listing. To update only a rule value (e.g. raise the minimum price) without changing dates, include the existing `id` unchanged. - `date_ranges` (array of object `custom_date_range_segment`, required): One or more inclusive calendar spans. Each span must include `start_date` and `end_date`, and `start_date` must be on or before `end_date`. - Each item: Inclusive calendar span within a custom date range. - `end_date` (string (date), required): Inclusive end (ISO-8601 date). - `start_date` (string (date), required): Inclusive start (ISO-8601 date). - `id` (string): Stable identifier for this range, referenced by calendar rules. Listings that share the same `id` for an entry are considered part of the same Event or Season and can be bulk-edited together. Preserve the existing `id` when updating an entry to keep it linked; omit only when creating a new range (one will be assigned). The server always returns this field as a string. Calendar rule `id` fields accept both string and integer for backward compatibility, but the canonical type is string — use string comparisons when matching rule `id` values against `custom_date_ranges` entries. - `name` (string, required): Display name for the season or event. - `type` (string, required, one of: `event`, `seasonal`): Whether this range represents a recurring season or a dated event. - `yearly` (boolean, required): When true, the date spans repeat each calendar year (same month/day pattern). - `min_min_price` (integer, default: `0`): UI: 'Absolute minimum price' — Hard lower bound that overrides all pricing rules. No recommended price will fall below this value regardless of any rule configuration. Distinct from a `global` rule in `minimum_price_rules_v3`, which can be overridden by higher-priority rules. Must be an integer (whole currency units). - `min_min_stay` (integer, default: `0`): UI: 'Absolute minimum stay' — Hard lower bound that overrides all minimum stay rules. No minimum stay will be set below this value regardless of any rule configuration. Distinct from both a `global` rule in `minimum_stay_rules_v3` (which can be overridden by higher-priority rules) and from `global_min_stay` in the price recommendations response (which reflects the current effective default rule value, not a hard floor). - `apply_gap_night_rules_to_overrides` (boolean): UI: 'Apply Gap Night Rules to Overrides' — When `true`, gap-night minimum stay rules take priority over custom (date override) rules. When `false` (default), custom rules win over gap-night rules. - `update_from` (string, read-only): The source used when the preferences were last updated. - `update_from_id` (integer, nullable, read-only): The ID of the entity used when preferences were last updated. - `created_at` (string, nullable, read-only): When the listing preferences were created (Rails-style timestamp). - `updated_at` (string, nullable, read-only): When the listing preferences were last updated (Rails-style timestamp). - `supported_settings` (object `supported_settings`, read-only): Which listing preference settings this listing's channel can act on. A setting reported `false` is discarded on write rather than posted to the channel, so check this before sending it. Reflects any per-account early access, so two listings on the same channel can differ. - `checkin_checkout` (boolean): Whether `checkin_checkout` rules can be set. - `min_stays` (boolean): Whether minimum stay settings (`min_min_stay`, `min_stays_enabled`, `minimum_stay_rules`) can be set. - `long_term_discounts` (boolean): Whether long-term discounts (`long_term_discounts`, `weekly_discount`, `monthly_discount`) can be set at all. - `long_term_discount_type` (string, one of: `disabled`, `simple`, `rules`, `complex`): The form of long-term discount the channel accepts. `disabled` takes none; `simple` takes only flat `weekly_discount` and `monthly_discount` values and ignores a `rules` object; `rules` additionally takes the 7 and 28 night tiers; `complex` takes arbitrary tiers. - `warnings` (array of object `preference_warning`, read-only, each item read-only): Settings in the request this listing's channel cannot act on, and which were therefore not applied. Present on write responses and empty when everything applied, so it can be read unconditionally; absent on reads, where nothing was being set. - Each item: One setting in the request that was not applied, or that has no effect on this listing. - `setting` (string, one of: `checkin_checkout`, `gap_night`, `min_stays`, `long_term_discounts`): The setting group the warning is about. - `reason` (string, one of: `not_supported_by_channel`, `partially_supported_by_channel`, `not_supported_for_multi_unit`): `not_supported_by_channel` — the channel has no such feature and everything sent for it was dropped. `partially_supported_by_channel` — the channel has the feature but accepts a narrower form than what was sent, and only the excess was dropped. `not_supported_for_multi_unit` — the setting is stored but has no effect on price, because the listing has more than one unit. - `message` (string): A human-readable explanation of what was ignored and why. - `attributes` (array of string): The request attributes this warning covers, in dot notation for nested ones (e.g. `long_term_discounts.rules.14`). Example shape (generated from the schema; placeholder values, not a real response): ```json { "listing_id": 0, "partner_listing_id": "string", "currency": "string", "automatic_rate_posting_enabled": true, "base_price": 0, "base_price_adjustment": 0, "monthly_discount": 0, "weekly_discount": 0, "nickname": "string", "last_minute_discount": { "type": "CON", "rules": [ { "type": "time_based", "days_after": 0, "days_before": 0, "months": [ 1 ], "priority": 0, "day_of_week_values": [ 0, 0, 0, 0, 0, 0, 0 ], "value": 0 } ], "smooth": false }, "far_future_premium": { "type": "CON", "rules": [ { "type": "time_based", "days_after": 0, "days_before": 0, "months": [ 1 ], "priority": 0, "day_of_week_values": [ 0, 0, 0, 0, 0, 0, 0 ], "value": 0 } ], "smooth": false }, "seasonality_adjustment": { "type": "CON", "rules": [ { "type": "seasonal", "id": 0, "priority": 0, "day_of_week_values": [ 0, 0, 0, 0, 0, 0, 0 ], "value": 0 } ], "smooth": false }, "day_of_week": { "type": "CON", "rules": [ { "type": "global", "priority": 0, "value": 0 } ] }, "gap_night": { "custom": [ { "adjacent": "left", "adjustment": 0, "day_of_week": [ 0 ], "gap": 0 } ], "type": "CON" }, "minimum_stay_rules_v3": [], "min_stays_enabled": true, "minimum_price_rules_v3": [], "maximum_price_rules_v3": [], "checkin_checkout": { "active": true, "auto_adjust": true, "check_in_rules": [ { "type": "global", "priority": 0, "value": 0 } ], "check_out_rules": [ { "type": "global", "priority": 0, "value": 0 } ] }, "long_term_discounts": { "active": false, "weekly_rules": [], "monthly_rules": [], "rules": {} }, "occupancy_pacing": {}, "fee_adjustments": { "total_fee_percentage": 0, "auto_update": true }, "demand_sensitivity_rules": [], "historical_anchoring_price_source": "observed", "historical_anchoring_mode": "blended", "historical_anchoring_rules": [], "custom_date_ranges": [], "min_min_price": 0, "min_min_stay": 0, "apply_gap_night_rules_to_overrides": true, "update_from": "string", "update_from_id": 0, "created_at": "string", "updated_at": "string", "supported_settings": { "checkin_checkout": true, "min_stays": true, "long_term_discounts": true, "long_term_discount_type": "disabled" }, "warnings": [ { "setting": "checkin_checkout", "reason": "not_supported_by_channel", "message": "string", "attributes": [ "string" ] } ] } ``` ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` ## Schemas Shared by more than one field above. ### `calendar_rule_time_based` Type: object `calendar_rule_time_based` **time_based** — Relative to "today" for the listing. At least one of `days_before` or `days_after` must be set. Provide `value` or `day_of_week_values`, not both. Optional `months` scopes by calendar month. When only `days_before` is set, the rule applies to dates within that many days of today (last-minute window). When only `days_after` is set, the rule applies to dates at least that many days away (far-future window). When both are set, the rule applies to dates that satisfy both conditions simultaneously — at least `days_after` days away AND within `days_before` days — creating a mid-booking-window band. `days_before` must be greater than or equal to `days_after` when both are provided. **time_based** — Relative to “today” for the listing. At least one of `days_before` or `days_after` must be set. Provide `value` or `day_of_week_values`, not both. Optional `months` scopes by calendar month. When only `days_before` is set, the rule applies to dates within that many days of today (last-minute window). When only `days_after` is set, the rule applies to dates at least that many days away (far-future window). When both are set, the rule applies to dates that satisfy both conditions simultaneously — at least `days_after` days away AND within `days_before` days — creating a mid-booking-window band. `days_before` must be greater than or equal to `days_after` when both are provided. - `type` (string, required, one of: `time_based`) - `days_after` (integer, nullable): Applies on/after “today + days_after”. When combined with `days_before`, creates a mid-window band (see rule description). `null` when this side of the window is unset. - `days_before` (integer, nullable): Applies within “today + days_before”. Must be >= `days_after` when both are set. `null` when this side of the window is unset. - `months` (array of integer, min items: 1, each item min: 1, max: 12): When set, restrict to these month ordinals (1–12). - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number) ### `calendar_rule_seasonal` Type: object `calendar_rule_seasonal` **seasonal** — Tied to a custom seasonal date range. Set `id` to the custom range. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `seasonal`) - `id` (integer | string, required): Custom seasonal date-range identifier. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number) ### `calendar_rule_event` Type: object `calendar_rule_event` **event** — Tied to a custom event date range. Set `id` to the custom range. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `event`) - `id` (integer | string, required): Custom event / date-range identifier. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number) ### `calendar_rule_monthly_simple` Type: object `calendar_rule_monthly_simple` **monthly** — Limited to specific `months`. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `monthly`) - `months` (array of integer, required, min items: 1, each item min: 1, max: 12): Month ordinals (1–12); at least one. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number) ### `calendar_rule_day_of_week` Type: object `calendar_rule_day_of_week` **day_of_week** — Per weekday (7 values, Sunday-first). Optional `months` limits to those month ordinals. Must not combine with `days_before` / `days_after` (use `time_based` for that). - `type` (string, required, one of: `day_of_week`) - `months` (array of integer, min items: 1, each item min: 1, max: 12): When set, restrict to these month ordinals (1–12). - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, required, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. ### `calendar_rule_custom` Type: object `calendar_rule_custom` **custom** — Fixed calendar date range. `start_date` and `end_date` inclusive; optional `yearly` repeats each year. Provide `value` or `day_of_week_values`, not both. UI: 'Date-specific overrides.' Not related to `custom_date_ranges` (Events & Seasons), Custom Rates, or the `CUS` preset type. - `type` (string, required, one of: `custom`) - `end_date` (string (date), required): Inclusive end (ISO-8601 date). - `id` (integer | string): Server-assigned identifier, returned as a string when present. On `checkin_checkout` rules it pairs a check-in rule with its check-out rule and is derived from the rule's contents, so it changes when the rule changes (on `seasonal` and `event` rules it is the season or event id instead). Requests don't use it to identify a rule, so don't store it as a stable key. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `start_date` (string (date), required): Inclusive start (ISO-8601 date). - `yearly` (boolean): When true, repeat the same month/day span every year. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number): Single value for dates in range when `day_of_week_values` is not used. ### `integer_calendar_rule` Type: object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule` Integer calendar rules (minimum stay, min/max price caps, local events, check-in/out, long-term discounts, etc.). - One of: - **calendar_rule_adjacency_int** (object `calendar_rule_adjacency_int`): Integer-valued adjacency / one-sided gap rule (same semantics as `calendar_rule_adjacency`). Only used in `minimum_stay_rules_v3` (MLOS behavior). Not related to the `gap_night` pricing setting. - `type` (string, required, one of: `adjacency`, `one_sided_gap`): Use `adjacency` or legacy `one_sided_gap` (same behavior). - `adjustment` (integer): Add to the existing calendar value instead of replacing it. - `day_of_week_adjustments` (array of integer, min items: 7, max items: 7, each item nullable): Per-day adjustments (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `days_adjacent` (integer, required): Window of adjacent days (negative = prior side, positive = subsequent side). To match both sides, use two separate rules — one with a negative value and one with a positive value. When both rules fire on the same date, the negative rule's value takes precedence (it is evaluated last and overwrites the positive rule's result). - `days_after` (integer): Legacy alias retained on some stored adjacency rules. Prefer `days_adjacent`. - `days_one_sided_gap` (integer): Legacy alias retained on some stored adjacency rules. Prefer `days_adjacent`. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day minimums (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer): Single minimum when `day_of_week_values` is not used. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_gap_int** (object `calendar_rule_gap_int`): **gap** — When `gap_enabled` is true, applies a minimum stay only for "gap" nights that cannot fit the normal min stay. Provide `value` or `day_of_week_values` for the gap minimum. Optional `days_before` / `days_after` scope the rule in time. Only used in `minimum_stay_rules_v3` (MLOS behavior). Not related to the `gap_night` pricing setting. **gap** — When `gap_enabled` is true, applies a minimum stay only for “gap” nights that cannot fit the normal min stay. Provide `value` or `day_of_week_values` for the gap minimum. Optional `days_before` / `days_after` scope the rule in time. - `type` (string, required, one of: `gap`) - `days_after` (integer) - `days_before` (integer) - `gap_enabled` (boolean, required, one of: `true`) - `gap_flexibility` (integer): Reduces effective min stay in the gap by this many nights. It will never drop below `value`. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day gap minimums (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer): Gap minimum stay (integer in typical min-stay rules). - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. ### `calendar_rule_global_int` Type: object `calendar_rule_global_int` **global** — Single default for the calendar in this rule set. Must not set `day_of_week_values`. UI: 'Default' or 'Minimum price default' (label varies by setting). - `type` (string, required, one of: `global`) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `value` (integer, required): Default value (non-negative). ### `calendar_rule_time_based_int` Type: object `calendar_rule_time_based_int` **time_based** — Relative to "today" for the listing. At least one of `days_before` or `days_after` must be set. Provide `value` or `day_of_week_values`, not both. Optional `months` scopes by calendar month. When only `days_before` is set, the rule applies to dates within that many days of today (last-minute window). When only `days_after` is set, the rule applies to dates at least that many days away (far-future window). When both are set, the rule applies to dates that satisfy both conditions simultaneously — at least `days_after` days away AND within `days_before` days — creating a mid-booking-window band. `days_before` must be greater than or equal to `days_after` when both are provided. **time_based** — Relative to “today” for the listing. At least one of `days_before` or `days_after` must be set. Provide `value` or `day_of_week_values`, not both. Optional `months` scopes by calendar month. When only `days_before` is set, the rule applies to dates within that many days of today (last-minute window). When only `days_after` is set, the rule applies to dates at least that many days away (far-future window). When both are set, the rule applies to dates that satisfy both conditions simultaneously — at least `days_after` days away AND within `days_before` days — creating a mid-booking-window band. `days_before` must be greater than or equal to `days_after` when both are provided. - `type` (string, required, one of: `time_based`) - `days_after` (integer, nullable): Applies on/after “today + days_after”. When combined with `days_before`, creates a mid-window band (see rule description). `null` when this side of the window is unset. - `days_before` (integer, nullable): Applies within “today + days_before”. Must be >= `days_after` when both are set. `null` when this side of the window is unset. - `months` (array of integer, min items: 1, each item min: 1, max: 12): When set, restrict to these month ordinals (1–12). - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer) ### `calendar_rule_seasonal_int` Type: object `calendar_rule_seasonal_int` **seasonal** — Tied to a custom seasonal date range. Set `id` to the custom range. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `seasonal`) - `id` (integer | string, required): Custom seasonal date-range identifier. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer) ### `calendar_rule_event_int` Type: object `calendar_rule_event_int` **event** — Tied to a custom event date range. Set `id` to the custom range. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `event`) - `id` (integer | string, required): Custom event / date-range identifier. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer) ### `calendar_rule_monthly_int` Type: object `calendar_rule_monthly_int` **monthly** — Limited to specific `months`. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `monthly`) - `months` (array of integer, required, min items: 1, each item min: 1, max: 12): Month ordinals (1–12); at least one. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer): Single value for the month. ### `calendar_rule_day_of_week_int` Type: object `calendar_rule_day_of_week_int` **day_of_week** — Per weekday (7 values, Sunday-first). Optional `months` limits to those month ordinals. Must not combine with `days_before` / `days_after` (use `time_based` for that). - `type` (string, required, one of: `day_of_week`) - `months` (array of integer, min items: 1, each item min: 1, max: 12): When set, restrict to these month ordinals (1–12). - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, required, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. ### `calendar_rule_custom_int` Type: object `calendar_rule_custom_int` **custom** — Fixed calendar date range. `start_date` and `end_date` inclusive; optional `yearly` repeats each year. Provide `value` or `day_of_week_values`, not both. UI: 'Date-specific overrides.' Not related to `custom_date_ranges` (Events & Seasons), Custom Rates, or the `CUS` preset type. - `type` (string, required, one of: `custom`) - `end_date` (string (date), required): Inclusive end (ISO-8601 date). - `id` (integer | string): Server-assigned identifier, returned as a string when present. On `checkin_checkout` rules it pairs a check-in rule with its check-out rule and is derived from the rule's contents, so it changes when the rule changes (on `seasonal` and `event` rules it is the season or event id instead). Requests don't use it to identify a rule, so don't store it as a stable key. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `start_date` (string (date), required): Inclusive start (ISO-8601 date). - `yearly` (boolean): When true, repeat the same month/day span every year. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer): Single value for dates in range when `day_of_week_values` is not used. --- # Update preferences for a listing. `PUT /preferences/{listing_id}` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-put-preferences · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPutPreferences` · Tag: Listing Preferences Updates pricing preferences for a listing. All fields are optional; only provided fields will be updated. This partial-update behavior applies at the top level only — omitting a field (e.g. `minimum_stay_rules_v3`) leaves it unchanged, but providing a field that holds an array of rules (e.g. `minimum_price_rules_v3`) will **completely replace** the existing rule set for that field; individual rules within an array cannot be merged or patched. Always fetch the current preferences before writing and include every rule you wish to retain — any rules omitted from an array will be permanently deleted. ## Request `PUT https://api.usewheelhouse.com/ss_api/v1/preferences/{listing_id}` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Request body (`application/json`, required) The pricing preferences to set for a listing. All fields are optional; only provided fields will be updated. This partial-update behavior applies at the top level only — omitting a field (e.g. `minimum_stay_rules_v3`) leaves it unchanged, but providing a field that holds an array of rules (e.g. `minimum_price_rules_v3`) will **completely replace** the existing rule set for that field; individual rules within an array cannot be merged or patched. - `automatic_rate_posting_enabled` (boolean): Whether Wheelhouse automatically posts its price recommendations to the channel calendar. When `false`, recommendations are computed but not pushed to the channel. This setting does not affect custom rates set via the API — those are posted independently. - `base_price` (integer, nullable, min: 1): The manually set base price. If set, overrides Wheelhouse's data-driven recommendation. Must be a whole number of at least 1. - `base_price_adjustment` (number, nullable): A multiplier on the Wheelhouse recommended base price, for example `0.9` for 10% below it. Only used if `base_price` is not set. Sending a non-null value without `base_price` clears a manual `base_price`. Sending `null` leaves a manual `base_price` in place. To clear it, send `null` for `base_price`. Cannot be `0`. - `monthly_discount` (integer, nullable, default: `0`): Monthly discount percentage as an integer in the range 0–100 (e.g. `5` = 5%). On listings that accept length-of-stay premiums (every listing whose `supported_settings.long_term_discount_type` is `complex`, and some with `rules`), values are signed instead, so `-10` is a 10% discount and `10` a 10% premium. Applied to bookings ≥ 28 nights. Kept in sync with the global rule in `long_term_discounts.rules['28']` — setting one automatically updates the other. When both are sent in the same PUT, `long_term_discounts` takes precedence. - `weekly_discount` (integer, nullable, default: `0`): Weekly discount percentage as an integer in the range 0–100 (e.g. `5` = 5%). On listings that accept length-of-stay premiums (every listing whose `supported_settings.long_term_discount_type` is `complex`, and some with `rules`), values are signed instead, so `-10` is a 10% discount and `10` a 10% premium. Applied to bookings ≥ 7 nights. Kept in sync with the global rule in `long_term_discounts.rules['7']` — setting one automatically updates the other. When both are sent in the same PUT, `long_term_discounts` takes precedence. - `nickname` (string, nullable): Listing nickname. Overrides the listing's default nickname. - `last_minute_discount` (object, nullable): UI: 'Last minute' — Last-minute discount configuration. - `type` (string, one of: `CON`, `REC`, `AGG`, `CUS`) - `rules` (array of object `calendar_rule_time_based` | object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly_simple` | object `calendar_rule_day_of_week` | object `calendar_rule_custom`): Calendar rules when `type` is `CUS`. Valid rule types: `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_time_based**: see `calendar_rule_time_based` under Schemas. - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly_simple**: see `calendar_rule_monthly_simple` under Schemas. - **calendar_rule_day_of_week**: see `calendar_rule_day_of_week` under Schemas. - **calendar_rule_custom**: see `calendar_rule_custom` under Schemas. - `smooth` (boolean, default: `false`): UI: 'Smooth' — Only used when `type` is `CUS`. When `true`, the adjustment eases gradually from one rule to the next instead of jumping at each rule's edge. `custom` rules still apply exactly. Defaults to `false` (stepped). - `far_future_premium` (object, nullable): UI: 'Far future' — Far-future premium configuration. - `type` (string, one of: `CON`, `REC`, `AGG`, `CUS`) - `rules` (array of object `calendar_rule_time_based` | object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly_simple` | object `calendar_rule_day_of_week` | object `calendar_rule_custom`): Calendar rules when `type` is `CUS`. Valid rule types: `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_time_based**: see `calendar_rule_time_based` under Schemas. - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly_simple**: see `calendar_rule_monthly_simple` under Schemas. - **calendar_rule_day_of_week**: see `calendar_rule_day_of_week` under Schemas. - **calendar_rule_custom**: see `calendar_rule_custom` under Schemas. - `smooth` (boolean, default: `false`): UI: 'Smooth' — Only used when `type` is `CUS`. When `true`, the adjustment eases gradually from one rule to the next instead of jumping at each rule's edge. `custom` rules still apply exactly. Defaults to `false` (stepped). - `seasonality_adjustment` (object, nullable): UI: 'Seasonality' — Seasonality adjustment configuration. - `type` (string, one of: `CON`, `REC`, `AGG`, `CUS`) - `rules` (array of object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly`): Calendar rules when `type` is `CUS`. Valid rule types: `seasonal`, `event`, `monthly`. - One of: - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly**: see `calendar_rule_monthly` under Schemas. - `smooth` (boolean, default: `false`): UI: 'Smooth' — Only used when `type` is `CUS`. When `true`, the adjustment eases gradually from one rule to the next instead of jumping at each rule's edge, and monthly rules' `step`, `start_value` and `end_value` are ignored. Defaults to `false` (stepped). - `day_of_week` (object, nullable): Day-of-week pricing factor configuration. - `REC` applies the market's day-of-week pattern. - `CON` and `AGG` adjust that pattern conservatively or aggressively. Sent without `rules`, they store the matching preset `day_of_week` rule. - `ADJ` applies the market's pattern and multiplies your own `rules` on top of it. - `CUS` replaces the market's pattern with your own `rules`, whose values are price multipliers (`1.1` is 10% higher). `CUS` without `rules` prices every day the same. - `type` (string, one of: `CON`, `REC`, `AGG`, `ADJ`, `CUS`) - `rules` (array of object `calendar_rule_global` | object `calendar_rule_time_based` | object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly_simple` | object `calendar_rule_day_of_week` | object `calendar_rule_custom`): Calendar rules when `type` is `ADJ` or `CUS`. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global**: see `calendar_rule_global` under Schemas. - **calendar_rule_time_based**: see `calendar_rule_time_based` under Schemas. - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly_simple**: see `calendar_rule_monthly_simple` under Schemas. - **calendar_rule_day_of_week**: see `calendar_rule_day_of_week` under Schemas. - **calendar_rule_custom**: see `calendar_rule_custom` under Schemas. - `gap_night` (object `gap_night`, nullable): Gap night pricing strategy (UI: 'Gaps & Adjacencies' in the Pricing Engine panel). Controls the price multiplier for gap nights between bookings. When `type` is `CUS`, provide `custom` rules; the server rejects `CUS` without `custom`. This is a **pricing-only** setting. It is unrelated to the `gap` and `adjacency`/`one_sided_gap` rule types in `minimum_stay_rules_v3`, which control minimum stay behavior for gap nights. In a request the `custom` array replaces the stored one. Gap night pricing does not apply to listings with more than one unit. The setting is still accepted, and the response carries a `not_supported_for_multi_unit` warning. - Fields: see `gap_night` under Schemas. - `minimum_stay_rules_v3` (array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`, default: `[]`): UI: 'Minimum stays' — minimum stay rules. The `_v3` suffix is a stable historical identifier; this field name is not expected to change. - Fields: see `integer_calendar_rule` under Schemas. - `min_stays_enabled` (boolean): Whether minimum stay rules are enabled. - `minimum_price_rules_v3` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): UI: 'Minimum prices' — Minimum price rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. The `_v3` suffix is a stable historical identifier; this field name is not expected to change. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `maximum_price_rules_v3` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): UI: 'Maximum prices' — Maximum price rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. The `_v3` suffix is a stable historical identifier; this field name is not expected to change. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `checkin_checkout` (object, nullable): Which days guests may check in and check out. Rule values are allow flags: `1` allows the day and `0` blocks it. A `day_of_week` rule's `day_of_week_values` has 7 entries, index 0 = Sunday. Where rules overlap, the more specific rule type wins (for example a date-specific `custom` rule over a `day_of_week` rule); between rules of the same type, the later one in the array wins. In a request the object replaces the stored one as a whole: send `active` and both `check_in_rules` and `check_out_rules` (a request missing either array is rejected with 400). An empty `check_out_rules` leaves check-out unrestricted. Example, check-in on Friday and Saturday only, check-out any day: ```json { "active": true, "auto_adjust": false, "check_in_rules": [{"type": "day_of_week", "day_of_week_values": [0, 0, 0, 0, 0, 1, 1]}], "check_out_rules": [{"type": "day_of_week", "day_of_week_values": [1, 1, 1, 1, 1, 1, 1]}] } ``` - `active` (boolean): Whether the check-in/check-out rules are enforced. Stored as `false` when omitted. - `auto_adjust` (boolean): When `true`, Wheelhouse opens additional check-in and check-out days around unavailable nights so that open stretches between bookings can still be booked, even on days the rules would otherwise block. - `check_in_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`): Allowed check-in rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `check_out_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`): Allowed check-out rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `long_term_discounts` (object, default: `{"active":false,"weekly_rules":[],"monthly_rules":[],"rules":{}}`): Rule-based long-term discount configuration. - `active` (boolean) - `weekly_rules` (array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`, **deprecated**): Weekly discount rules (integer calendar rules). - Fields: see `integer_calendar_rule` under Schemas. - `monthly_rules` (array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`, **deprecated**): Monthly discount rules (integer calendar rules). - Fields: see `integer_calendar_rule` under Schemas. - `rules` (map of string to array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`): LOS-keyed rules (integer calendar rules). Keys are length-of-stay thresholds (e.g. "7", "28"); values are arrays of integer calendar rules holding whole percentages (`10` is a 10% discount). On listings that accept length-of-stay premiums (every listing whose `supported_settings.long_term_discount_type` is `complex`, and some with `rules`), values are signed instead, so `-10` is a 10% discount and `10` a 10% premium. - Fields: see `integer_calendar_rule` under Schemas. - `occupancy_pacing` (object `occupancy_pacing`, nullable, default: `{}`): Occupancy pacing configuration. When `occupancy_pacing` is sent as a non-empty object, both `adjusted` and `pacing` are required. Occupancy pacing matrix configuration. `{}` means pacing is off, which is the default for a new listing. When `occupancy_pacing` is sent as a non-empty object, `adjusted` and `pacing` are required, and `pacing` must include a matrix with `type` `global` (otherwise the request is rejected with 400). In a request the object replaces the stored one as a whole; omit it to leave pacing unchanged. For each lead-time column, occupancy is measured across that whole window and the matching row's percentage is applied to every date in it. A row covers occupancy above `min` up to and including `max` (`min` `0` includes 0%); the first matching row wins, and dates outside every column or row are unchanged. The adjusted price still respects the listing's minimum and maximum price rules. - Fields: see `occupancy_pacing` under Schemas. - `fee_adjustments` (object `fee_adjustments`, nullable): Estimated fee share applied on top of the nightly rate. `null` when nothing is configured, otherwise both keys are present; in a request the object replaces the stored one as a whole, and `null` clears it. UI: 'Asking Rate (+Est. Fees)' — The estimated share of fees guests pay on top of the nightly rate, as a percentage of that rate. It is what `GET /listings/{listing_id}/fee_impact_calendar` returns as a per-date multiplier. A response carries `null` when nothing is configured, otherwise both keys. In a request the object replaces the stored one as a whole, so send both keys; `null` clears the setting. - Fields: see `fee_adjustments` under Schemas. - `demand_sensitivity_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): Local events rules. Shown as Demand sensitivity before day of week became its own setting; the field name is unchanged. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `historical_anchoring_price_source` (string, one of: `observed`, `posted`, `posted_with_fallback`): Which historical price historical anchoring weighs in. `observed`, the default, is the listing's price as Wheelhouse saw it on the channel once the date booked. `posted` is the price Wheelhouse last posted for the date before it booked, so dates Wheelhouse never posted a price for are not anchored. `posted_with_fallback` uses the posted price where there is one and the observed price otherwise. - `historical_anchoring_mode` (string, one of: `blended`, `anchor_only`): How a historical anchoring percentage turns the historical price into a floor for the recommendation. `blended` averages the historical price with the recommendation, using the percentage as the weight on the historical price: at 50%, a $1,200 historical price and a $400 recommendation give $800. `anchor_only` takes the percentage of the historical price alone, so at 50% the floor is $600: a $400 recommendation rises to $600 and a $700 one stays at $700. Either only ever raises a price, and from 100% up both give the same price. - `historical_anchoring_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): Historical anchoring rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `custom_date_ranges` (array of object `custom_date_range`, default: `[]`): Represents an Event or Season entry used by the Wheelhouse Events & Seasons feature. Calendar rules reference these entries by `id` to apply settings (e.g. min stay, pricing) over named date windows. Each listing stores its own copy of every Event or Season it belongs to. Entries for the same event or season share the same `id` across listings — this shared `id` is what enables bulk adjustments in the Wheelhouse UI. If you write a `custom_date_ranges` entry with a new or changed `id`, that listing's entry is no longer linked to the others and will not be included in future bulk edits of the original Event or Season. To safely modify an event or season's definition (dates or name) on one listing without affecting others, omit the `id` field — the server assigns a new independent ID scoped to that listing. To update only a rule value (e.g. raise the minimum price) without changing dates, include the existing `id` unchanged. A new `custom_date_ranges` entry and a rule referencing it can be submitted in the same PUT request. Manually assign an `id` on the new entry so that the referencing rule can use it in the same payload. Alternatively, use two sequential PUTs: the first PUT creates the entry without an `id` (the server assigns one, returned in the response); the second PUT adds the rule referencing that server-assigned `id`. - Fields: see `custom_date_range` under Schemas. - `min_min_price` (integer, default: `0`): UI: 'Absolute minimum price' — Hard lower bound that overrides all pricing rules. No recommended price will fall below this value regardless of any rule configuration. Distinct from a `global` rule in `minimum_price_rules_v3`, which can be overridden by higher-priority rules. Must be an integer (whole currency units). - `min_min_stay` (integer, default: `0`): UI: 'Absolute minimum stay' — Hard lower bound that overrides all minimum stay rules. No minimum stay will be set below this value regardless of any rule configuration. Distinct from both a `global` rule in `minimum_stay_rules_v3` (which can be overridden by higher-priority rules) and from `global_min_stay` in the price recommendations response (which reflects the current effective default rule value, not a hard floor). - `apply_gap_night_rules_to_overrides` (boolean): UI: 'Apply Gap Night Rules to Overrides' — When `true`, gap-night minimum stay rules take priority over custom (date override) rules. When `false` (default), custom rules win over gap-night rules. ### Example request ```bash curl -X PUT 'https://api.usewheelhouse.com/ss_api/v1/preferences/{listing_id}?channel=' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{}' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The updated listing preferences. Body (`application/json`): object `listing_preference_response` The full set of pricing preferences for a listing. - `listing_id` (integer, read-only): The Wheelhouse internal listing ID. - `partner_listing_id` (string, read-only): The channel's listing ID. - `currency` (string, nullable, read-only): The currency used for prices in this listing's preferences. - `automatic_rate_posting_enabled` (boolean): Whether Wheelhouse automatically posts prices to the channel calendar. When `false`, recommendations are computed but nothing is pushed to the channel. - `base_price` (number, nullable): The base price the user set by hand, in the preferences `currency`. When set, the pricing engine uses it instead of the Wheelhouse recommendation, and `base_price_adjustment` is `null`. `null` does **not** mean the listing has no base price. It means the base price follows the Wheelhouse recommendation, multiplied by `base_price_adjustment` (or by `1.0` when that is also `null`). To read the base price in use, call `GET /listings/{listing_id}/price_recommendations` and read its top-level `base_price`. Set to `null` to go back to the Wheelhouse recommendation, or set a preset with `PUT /preferences/{listing_id}/base_price_adjustment` and `type` `CON`, `REC`, or `AGG`. - `base_price_adjustment` (number, nullable): The multiplier the pricing engine applies to the Wheelhouse recommended base price (`base_price_recommended` on `GET /listings/{listing_id}/price_recommendations`) when `base_price` is `null`. The presets are `0.9` (conservative, `CON`), `1.0` (recommended, `REC`), and `1.1` (aggressive, `AGG`). Any other value is a custom adjustment, for example `1.05` for 5% above the recommendation. For example, with `base_price_recommended` 200 and `base_price_adjustment` `0.9`, the base price in use is 180, and `base_price` here is `null`. `null` when `base_price` is set, because the manual base price applies instead. Both fields can also be `null`, for example after a manual base price is cleared. The pricing engine then uses `1.0`, the recommended preset. - `monthly_discount` (integer, nullable, default: `0`): Monthly discount percentage as an integer in the range 0–100 (e.g. `5` = 5%). On listings that accept length-of-stay premiums (every listing whose `supported_settings.long_term_discount_type` is `complex`, and some with `rules`), values are signed instead, so `-10` is a 10% discount and `10` a 10% premium. Applied to bookings ≥ 28 nights. Kept in sync with the global rule in `long_term_discounts.rules['28']` — setting one automatically updates the other. When both are sent in the same PUT, `long_term_discounts` takes precedence. - `weekly_discount` (integer, nullable, default: `0`): Weekly discount percentage as an integer in the range 0–100 (e.g. `5` = 5%). On listings that accept length-of-stay premiums (every listing whose `supported_settings.long_term_discount_type` is `complex`, and some with `rules`), values are signed instead, so `-10` is a 10% discount and `10` a 10% premium. Applied to bookings ≥ 7 nights. Kept in sync with the global rule in `long_term_discounts.rules['7']` — setting one automatically updates the other. When both are sent in the same PUT, `long_term_discounts` takes precedence. - `nickname` (string, nullable): Listing nickname. - `last_minute_discount` (object, nullable): UI: 'Last minute' — Last-minute discount configuration. - `type` (string, one of: `CON`, `REC`, `AGG`, `CUS`) - `rules` (array of object `calendar_rule_time_based` | object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly_simple` | object `calendar_rule_day_of_week` | object `calendar_rule_custom`): Calendar rules when `type` is `CUS`. Valid rule types: `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_time_based**: see `calendar_rule_time_based` under Schemas. - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly_simple**: see `calendar_rule_monthly_simple` under Schemas. - **calendar_rule_day_of_week**: see `calendar_rule_day_of_week` under Schemas. - **calendar_rule_custom**: see `calendar_rule_custom` under Schemas. - `smooth` (boolean, default: `false`): UI: 'Smooth' — Only used when `type` is `CUS`. When `true`, the adjustment eases gradually from one rule to the next instead of jumping at each rule's edge. `custom` rules still apply exactly. Defaults to `false` (stepped). - `far_future_premium` (object, nullable): UI: 'Far future' — Far-future premium configuration. - `type` (string, one of: `CON`, `REC`, `AGG`, `CUS`) - `rules` (array of object `calendar_rule_time_based` | object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly_simple` | object `calendar_rule_day_of_week` | object `calendar_rule_custom`): Calendar rules when `type` is `CUS`. Valid rule types: `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_time_based**: see `calendar_rule_time_based` under Schemas. - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly_simple**: see `calendar_rule_monthly_simple` under Schemas. - **calendar_rule_day_of_week**: see `calendar_rule_day_of_week` under Schemas. - **calendar_rule_custom**: see `calendar_rule_custom` under Schemas. - `smooth` (boolean, default: `false`): UI: 'Smooth' — Only used when `type` is `CUS`. When `true`, the adjustment eases gradually from one rule to the next instead of jumping at each rule's edge. `custom` rules still apply exactly. Defaults to `false` (stepped). - `seasonality_adjustment` (object, nullable): UI: 'Seasonality' — Seasonality adjustment configuration. - `type` (string, one of: `CON`, `REC`, `AGG`, `CUS`) - `rules` (array of object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly`): Calendar rules when `type` is `CUS`. Valid rule types: `seasonal`, `event`, `monthly`. - One of: - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly**: see `calendar_rule_monthly` under Schemas. - `smooth` (boolean, default: `false`): UI: 'Smooth' — Only used when `type` is `CUS`. When `true`, the adjustment eases gradually from one rule to the next instead of jumping at each rule's edge, and monthly rules' `step`, `start_value` and `end_value` are ignored. Defaults to `false` (stepped). - `day_of_week` (object, nullable): Day-of-week pricing factor configuration. - `REC` applies the market's day-of-week pattern. - `CON` and `AGG` adjust that pattern conservatively or aggressively. Sent without `rules`, they store the matching preset `day_of_week` rule. - `ADJ` applies the market's pattern and multiplies your own `rules` on top of it. - `CUS` replaces the market's pattern with your own `rules`, whose values are price multipliers (`1.1` is 10% higher). `CUS` without `rules` prices every day the same. A `CUS` setting saved before the day-of-week and local events split is returned as `ADJ`, since that is how it has priced since the split. - `type` (string, one of: `CON`, `REC`, `AGG`, `ADJ`, `CUS`) - `rules` (array of object `calendar_rule_global` | object `calendar_rule_time_based` | object `calendar_rule_seasonal` | object `calendar_rule_event` | object `calendar_rule_monthly_simple` | object `calendar_rule_day_of_week` | object `calendar_rule_custom`): Calendar rules when `type` is `ADJ` or `CUS`. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global**: see `calendar_rule_global` under Schemas. - **calendar_rule_time_based**: see `calendar_rule_time_based` under Schemas. - **calendar_rule_seasonal**: see `calendar_rule_seasonal` under Schemas. - **calendar_rule_event**: see `calendar_rule_event` under Schemas. - **calendar_rule_monthly_simple**: see `calendar_rule_monthly_simple` under Schemas. - **calendar_rule_day_of_week**: see `calendar_rule_day_of_week` under Schemas. - **calendar_rule_custom**: see `calendar_rule_custom` under Schemas. - `gap_night` (object `gap_night`, nullable): Gap night pricing strategy (UI: 'Gaps & Adjacencies' in the Pricing Engine panel). Controls the price multiplier for gap nights between bookings. When `type` is `CUS`, provide `custom` rules; the server rejects `CUS` without `custom`. This is a **pricing-only** setting. It is unrelated to the `gap` and `adjacency`/`one_sided_gap` rule types in `minimum_stay_rules_v3`, which control minimum stay behavior for gap nights. In a request the `custom` array replaces the stored one. Gap night pricing does not apply to listings with more than one unit. The setting is still accepted, and the response carries a `not_supported_for_multi_unit` warning. - Fields: see `gap_night` under Schemas. - `minimum_stay_rules_v3` (array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`, default: `[]`): UI: 'Minimum stays' — minimum stay rules. The `_v3` suffix is a stable historical identifier; this field name is not expected to change. - Fields: see `integer_calendar_rule` under Schemas. - `min_stays_enabled` (boolean): Whether minimum stay rules are enabled. - `minimum_price_rules_v3` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): UI: 'Minimum prices' — Minimum price rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. The `_v3` suffix is a stable historical identifier; this field name is not expected to change. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `maximum_price_rules_v3` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): UI: 'Maximum prices' — Maximum price rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. The `_v3` suffix is a stable historical identifier; this field name is not expected to change. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `checkin_checkout` (object, nullable): Which days guests may check in and check out. Rule values are allow flags: `1` allows the day and `0` blocks it. A `day_of_week` rule's `day_of_week_values` has 7 entries, index 0 = Sunday. Where rules overlap, the more specific rule type wins (for example a date-specific `custom` rule over a `day_of_week` rule); between rules of the same type, the later one in the array wins. In a request the object replaces the stored one as a whole: send `active` and both `check_in_rules` and `check_out_rules` (a request missing either array is rejected with 400). An empty `check_out_rules` leaves check-out unrestricted. Example, check-in on Friday and Saturday only, check-out any day: ```json { "active": true, "auto_adjust": false, "check_in_rules": [{"type": "day_of_week", "day_of_week_values": [0, 0, 0, 0, 0, 1, 1]}], "check_out_rules": [{"type": "day_of_week", "day_of_week_values": [1, 1, 1, 1, 1, 1, 1]}] } ``` - `active` (boolean): Whether the check-in/check-out rules are enforced. Stored as `false` when omitted. - `auto_adjust` (boolean): When `true`, Wheelhouse opens additional check-in and check-out days around unavailable nights so that open stretches between bookings can still be booked, even on days the rules would otherwise block. - `check_in_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`): Allowed check-in rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `check_out_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`): Allowed check-out rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `long_term_discounts` (object, default: `{"active":false,"weekly_rules":[],"monthly_rules":[],"rules":{}}`): Rule-based long-term discount configuration. - `active` (boolean) - `weekly_rules` (array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`, **deprecated**): Weekly discount rules (integer calendar rules). - Fields: see `integer_calendar_rule` under Schemas. - `monthly_rules` (array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`, **deprecated**): Monthly discount rules (integer calendar rules). - Fields: see `integer_calendar_rule` under Schemas. - `rules` (map of string to array of object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule`): LOS-keyed rules (integer calendar rules). Keys are length-of-stay thresholds (e.g. "7", "28"); values are arrays of integer calendar rules holding whole percentages (`10` is a 10% discount). On listings that accept length-of-stay premiums (every listing whose `supported_settings.long_term_discount_type` is `complex`, and some with `rules`), values are signed instead, so `-10` is a 10% discount and `10` a 10% premium. - Fields: see `integer_calendar_rule` under Schemas. - `occupancy_pacing` (object `occupancy_pacing`, nullable, default: `{}`): Occupancy pacing configuration. When `occupancy_pacing` is sent as a non-empty object, both `adjusted` and `pacing` are required. Occupancy pacing matrix configuration. `{}` means pacing is off, which is the default for a new listing. When `occupancy_pacing` is sent as a non-empty object, `adjusted` and `pacing` are required, and `pacing` must include a matrix with `type` `global` (otherwise the request is rejected with 400). In a request the object replaces the stored one as a whole; omit it to leave pacing unchanged. For each lead-time column, occupancy is measured across that whole window and the matching row's percentage is applied to every date in it. A row covers occupancy above `min` up to and including `max` (`min` `0` includes 0%); the first matching row wins, and dates outside every column or row are unchanged. The adjusted price still respects the listing's minimum and maximum price rules. - Fields: see `occupancy_pacing` under Schemas. - `fee_adjustments` (object `fee_adjustments`, nullable): Estimated fee share applied on top of the nightly rate. `null` when nothing is configured, otherwise both keys are present; in a request the object replaces the stored one as a whole, and `null` clears it. UI: 'Asking Rate (+Est. Fees)' — The estimated share of fees guests pay on top of the nightly rate, as a percentage of that rate. It is what `GET /listings/{listing_id}/fee_impact_calendar` returns as a per-date multiplier. A response carries `null` when nothing is configured, otherwise both keys. In a request the object replaces the stored one as a whole, so send both keys; `null` clears the setting. - Fields: see `fee_adjustments` under Schemas. - `demand_sensitivity_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): Local events rules. Shown as Demand sensitivity before day of week became its own setting; the field name is unchanged. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `historical_anchoring_price_source` (string, one of: `observed`, `posted`, `posted_with_fallback`, default: `observed`): Which historical price historical anchoring weighs in. `observed`, the default, is the listing's price as Wheelhouse saw it on the channel once the date booked. `posted` is the price Wheelhouse last posted for the date before it booked, so dates Wheelhouse never posted a price for are not anchored. `posted_with_fallback` uses the posted price where there is one and the observed price otherwise. - `historical_anchoring_mode` (string, one of: `blended`, `anchor_only`, default: `blended`): How a historical anchoring percentage turns the historical price into a floor for the recommendation. `blended` averages the historical price with the recommendation, using the percentage as the weight on the historical price: at 50%, a $1,200 historical price and a $400 recommendation give $800. `anchor_only` takes the percentage of the historical price alone, so at 50% the floor is $600: a $400 recommendation rises to $600 and a $700 one stays at $700. Either only ever raises a price, and from 100% up both give the same price. - `historical_anchoring_rules` (array of object `calendar_rule_global_int` | object `calendar_rule_time_based_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_event_int` | object `calendar_rule_monthly_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_custom_int`, default: `[]`): Historical anchoring rules. Valid rule types: `global`, `time_based`, `seasonal`, `event`, `monthly`, `day_of_week`, `custom`. - One of: - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - `custom_date_ranges` (array of object `custom_date_range`, default: `[]`): Represents an Event or Season entry used by the Wheelhouse Events & Seasons feature. Calendar rules reference these entries by `id` to apply settings (e.g. min stay, pricing) over named date windows. Each listing stores its own copy of every Event or Season it belongs to. Entries for the same event or season share the same `id` across listings — this shared `id` is what enables bulk adjustments in the Wheelhouse UI. If you write a `custom_date_ranges` entry with a new or changed `id`, that listing's entry is no longer linked to the others and will not be included in future bulk edits of the original Event or Season. To safely modify an event or season's definition (dates or name) on one listing without affecting others, omit the `id` field — the server assigns a new independent ID scoped to that listing. To update only a rule value (e.g. raise the minimum price) without changing dates, include the existing `id` unchanged. A new `custom_date_ranges` entry and a rule referencing it can be submitted in the same PUT request. Manually assign an `id` on the new entry so that the referencing rule can use it in the same payload. Alternatively, use two sequential PUTs: the first PUT creates the entry without an `id` (the server assigns one, returned in the response); the second PUT adds the rule referencing that server-assigned `id`. - Fields: see `custom_date_range` under Schemas. - `min_min_price` (integer, default: `0`): UI: 'Absolute minimum price' — Hard lower bound that overrides all pricing rules. No recommended price will fall below this value regardless of any rule configuration. Distinct from a `global` rule in `minimum_price_rules_v3`, which can be overridden by higher-priority rules. Must be an integer (whole currency units). - `min_min_stay` (integer, default: `0`): UI: 'Absolute minimum stay' — Hard lower bound that overrides all minimum stay rules. No minimum stay will be set below this value regardless of any rule configuration. Distinct from both a `global` rule in `minimum_stay_rules_v3` (which can be overridden by higher-priority rules) and from `global_min_stay` in the price recommendations response (which reflects the current effective default rule value, not a hard floor). - `apply_gap_night_rules_to_overrides` (boolean): UI: 'Apply Gap Night Rules to Overrides' — When `true`, gap-night minimum stay rules take priority over custom (date override) rules. When `false` (default), custom rules win over gap-night rules. - `update_from` (string, read-only): The source used when the preferences were last updated. - `update_from_id` (integer, nullable, read-only): The ID of the entity used when preferences were last updated. - `created_at` (string, nullable, read-only): When the listing preferences were created (Rails-style timestamp). - `updated_at` (string, nullable, read-only): When the listing preferences were last updated (Rails-style timestamp). - `supported_settings` (object `supported_settings`, read-only): Which listing preference settings this listing's channel can act on. A setting reported `false` is discarded on write rather than posted to the channel, so check this before sending it. Reflects any per-account early access, so two listings on the same channel can differ. - `checkin_checkout` (boolean): Whether `checkin_checkout` rules can be set. - `min_stays` (boolean): Whether minimum stay settings (`min_min_stay`, `min_stays_enabled`, `minimum_stay_rules`) can be set. - `long_term_discounts` (boolean): Whether long-term discounts (`long_term_discounts`, `weekly_discount`, `monthly_discount`) can be set at all. - `long_term_discount_type` (string, one of: `disabled`, `simple`, `rules`, `complex`): The form of long-term discount the channel accepts. `disabled` takes none; `simple` takes only flat `weekly_discount` and `monthly_discount` values and ignores a `rules` object; `rules` additionally takes the 7 and 28 night tiers; `complex` takes arbitrary tiers. - `warnings` (array of object `preference_warning`, read-only, each item read-only): Settings in the request this listing's channel cannot act on, and which were therefore not applied. Present on write responses and empty when everything applied, so it can be read unconditionally; absent on reads, where nothing was being set. - Each item: One setting in the request that was not applied, or that has no effect on this listing. - `setting` (string, one of: `checkin_checkout`, `gap_night`, `min_stays`, `long_term_discounts`): The setting group the warning is about. - `reason` (string, one of: `not_supported_by_channel`, `partially_supported_by_channel`, `not_supported_for_multi_unit`): `not_supported_by_channel` — the channel has no such feature and everything sent for it was dropped. `partially_supported_by_channel` — the channel has the feature but accepts a narrower form than what was sent, and only the excess was dropped. `not_supported_for_multi_unit` — the setting is stored but has no effect on price, because the listing has more than one unit. - `message` (string): A human-readable explanation of what was ignored and why. - `attributes` (array of string): The request attributes this warning covers, in dot notation for nested ones (e.g. `long_term_discounts.rules.14`). Example shape (generated from the schema; placeholder values, not a real response): ```json { "listing_id": 0, "partner_listing_id": "string", "currency": "string", "automatic_rate_posting_enabled": true, "base_price": 0, "base_price_adjustment": 0, "monthly_discount": 0, "weekly_discount": 0, "nickname": "string", "last_minute_discount": { "type": "CON", "rules": [ { "type": "time_based", "days_after": 0, "days_before": 0, "months": [ 1 ], "priority": 0, "day_of_week_values": [ 0, 0, 0, 0, 0, 0, 0 ], "value": 0 } ], "smooth": false }, "far_future_premium": { "type": "CON", "rules": [ { "type": "time_based", "days_after": 0, "days_before": 0, "months": [ 1 ], "priority": 0, "day_of_week_values": [ 0, 0, 0, 0, 0, 0, 0 ], "value": 0 } ], "smooth": false }, "seasonality_adjustment": { "type": "CON", "rules": [ { "type": "seasonal", "id": 0, "priority": 0, "day_of_week_values": [ 0, 0, 0, 0, 0, 0, 0 ], "value": 0 } ], "smooth": false }, "day_of_week": { "type": "CON", "rules": [ { "type": "global", "priority": 0, "value": 0 } ] }, "gap_night": { "custom": [ { "adjacent": "left", "adjustment": 0, "day_of_week": [ 0 ], "gap": 0 } ], "type": "CON" }, "minimum_stay_rules_v3": [], "min_stays_enabled": true, "minimum_price_rules_v3": [], "maximum_price_rules_v3": [], "checkin_checkout": { "active": true, "auto_adjust": true, "check_in_rules": [ { "type": "global", "priority": 0, "value": 0 } ], "check_out_rules": [ { "type": "global", "priority": 0, "value": 0 } ] }, "long_term_discounts": { "active": false, "weekly_rules": [], "monthly_rules": [], "rules": {} }, "occupancy_pacing": {}, "fee_adjustments": { "total_fee_percentage": 0, "auto_update": true }, "demand_sensitivity_rules": [], "historical_anchoring_price_source": "observed", "historical_anchoring_mode": "blended", "historical_anchoring_rules": [], "custom_date_ranges": [], "min_min_price": 0, "min_min_stay": 0, "apply_gap_night_rules_to_overrides": true, "update_from": "string", "update_from_id": 0, "created_at": "string", "updated_at": "string", "supported_settings": { "checkin_checkout": true, "min_stays": true, "long_term_discounts": true, "long_term_discount_type": "disabled" }, "warnings": [ { "setting": "checkin_checkout", "reason": "not_supported_by_channel", "message": "string", "attributes": [ "string" ] } ] } ``` ### 400 A setting in the request has the wrong shape; the message names the field. ### 401 API key authorization failed. ### 403 Listing authorization failed, or the API key is read-only and may not be used with PUT. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 409 Another request is already in progress for this listing. Retry after the concurrent request completes. ### 423 Listing preferences not yet initialized. Retry after a brief delay. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` ## Schemas Shared by more than one field above. ### `calendar_rule_time_based` Type: object `calendar_rule_time_based` **time_based** — Relative to "today" for the listing. At least one of `days_before` or `days_after` must be set. Provide `value` or `day_of_week_values`, not both. Optional `months` scopes by calendar month. When only `days_before` is set, the rule applies to dates within that many days of today (last-minute window). When only `days_after` is set, the rule applies to dates at least that many days away (far-future window). When both are set, the rule applies to dates that satisfy both conditions simultaneously — at least `days_after` days away AND within `days_before` days — creating a mid-booking-window band. `days_before` must be greater than or equal to `days_after` when both are provided. **time_based** — Relative to “today” for the listing. At least one of `days_before` or `days_after` must be set. Provide `value` or `day_of_week_values`, not both. Optional `months` scopes by calendar month. When only `days_before` is set, the rule applies to dates within that many days of today (last-minute window). When only `days_after` is set, the rule applies to dates at least that many days away (far-future window). When both are set, the rule applies to dates that satisfy both conditions simultaneously — at least `days_after` days away AND within `days_before` days — creating a mid-booking-window band. `days_before` must be greater than or equal to `days_after` when both are provided. - `type` (string, required, one of: `time_based`) - `days_after` (integer, nullable): Applies on/after “today + days_after”. When combined with `days_before`, creates a mid-window band (see rule description). `null` when this side of the window is unset. - `days_before` (integer, nullable): Applies within “today + days_before”. Must be >= `days_after` when both are set. `null` when this side of the window is unset. - `months` (array of integer, min items: 1, each item min: 1, max: 12): When set, restrict to these month ordinals (1–12). - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number) ### `calendar_rule_seasonal` Type: object `calendar_rule_seasonal` **seasonal** — Tied to a custom seasonal date range. Set `id` to the custom range. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `seasonal`) - `id` (integer | string, required): Custom seasonal date-range identifier. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number) ### `calendar_rule_event` Type: object `calendar_rule_event` **event** — Tied to a custom event date range. Set `id` to the custom range. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `event`) - `id` (integer | string, required): Custom event / date-range identifier. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number) ### `calendar_rule_monthly_simple` Type: object `calendar_rule_monthly_simple` **monthly** — Limited to specific `months`. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `monthly`) - `months` (array of integer, required, min items: 1, each item min: 1, max: 12): Month ordinals (1–12); at least one. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number) ### `calendar_rule_day_of_week` Type: object `calendar_rule_day_of_week` **day_of_week** — Per weekday (7 values, Sunday-first). Optional `months` limits to those month ordinals. Must not combine with `days_before` / `days_after` (use `time_based` for that). - `type` (string, required, one of: `day_of_week`) - `months` (array of integer, min items: 1, each item min: 1, max: 12): When set, restrict to these month ordinals (1–12). - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, required, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. ### `calendar_rule_custom` Type: object `calendar_rule_custom` **custom** — Fixed calendar date range. `start_date` and `end_date` inclusive; optional `yearly` repeats each year. Provide `value` or `day_of_week_values`, not both. UI: 'Date-specific overrides.' Not related to `custom_date_ranges` (Events & Seasons), Custom Rates, or the `CUS` preset type. - `type` (string, required, one of: `custom`) - `end_date` (string (date), required): Inclusive end (ISO-8601 date). - `id` (integer | string): Server-assigned identifier, returned as a string when present. On `checkin_checkout` rules it pairs a check-in rule with its check-out rule and is derived from the rule's contents, so it changes when the rule changes (on `seasonal` and `event` rules it is the season or event id instead). Requests don't use it to identify a rule, so don't store it as a stable key. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `start_date` (string (date), required): Inclusive start (ISO-8601 date). - `yearly` (boolean): When true, repeat the same month/day span every year. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (number): Single value for dates in range when `day_of_week_values` is not used. ### `calendar_rule_monthly` Type: object `calendar_rule_monthly` **monthly** — Limited to specific `months`. Provide `value` or `day_of_week_values`, not both. For linear interpolation (`step: false`), set `start_value` and `end_value` with the peak in `value`. Linear interpolation is only honored in the `seasonality_adjustment` setting, and not when `smooth` is `true`. - `type` (string, required, one of: `monthly`) - `months` (array of integer, required, min items: 1, each item min: 1, max: 12): Month ordinals (1–12); at least one. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of number, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `end_value` (number): Value at month end for linear interpolation when `step` is false. - `start_value` (number): Value at month start for linear interpolation when `step` is false. - `step` (boolean): When true, stepped monthly values; when false, linear interpolation using `start_value`, `value` (peak), and `end_value`. Ignored in `seasonality_adjustment` when `smooth` is `true`. - `value` (number): Single value for the month or peak value when interpolating. ### `calendar_rule_global` Type: object `calendar_rule_global` **global** — Single default for the calendar in this rule set. Must not set `day_of_week_values`. UI: 'Default' or 'Minimum price default' (label varies by setting). - `type` (string, required, one of: `global`) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `value` (number, required): Default value (non-negative). ### `gap_night` Type: object `gap_night` Gap night pricing strategy (UI: 'Gaps & Adjacencies' in the Pricing Engine panel). Controls the price multiplier for gap nights between bookings. When `type` is `CUS`, provide `custom` rules; the server rejects `CUS` without `custom`. This is a **pricing-only** setting. It is unrelated to the `gap` and `adjacency`/`one_sided_gap` rule types in `minimum_stay_rules_v3`, which control minimum stay behavior for gap nights. In a request the `custom` array replaces the stored one. Gap night pricing does not apply to listings with more than one unit. The setting is still accepted, and the response carries a `not_supported_for_multi_unit` warning. - `custom` (array of object `gap_night_custom_rule`): Per-gap custom rules. Required when `type` is `CUS` (may be an empty array). Each entry targets a gap length, weekday set, and optional one-sided adjacency (`left` / `right`). - Each item: One custom gap-night rule. `adjustment` is a price multiplier greater than 0 and at most 10 (`0.8` is a 20% discount). `day_of_week` uses 0 = Sunday through 6 = Saturday, unique values only, length 1–7. When several rules match a night, rules without `adjacent` are checked first, then `left`, then `right`. Within those, the rule with the smallest `gap` that still covers the gap wins, and among rules sharing that `gap` the largest `adjustment` wins. - `adjacent` (string, one of: `left`, `right`): Omit to match open nights with an unavailable night on both sides ("In between"). `left` matches the first `gap` open nights after an unavailable night ("Only after"); `right` matches the last `gap` open nights before one ("Only before"). - `adjustment` (number, required): Price multiplier; greater than 0 and at most 10. `0.8` is a 20% discount. - `day_of_week` (array of integer, required, min items: 1, max items: 7, each item min: 0, max: 6): Weekdays this rule applies to (0–6, each at most once). - `gap` (integer, required): Applies to gaps of this many nights or fewer. - `type` (string, required, one of: `CON`, `REC`, `AGG`, `CUS`): Preset strategy (`CON`, `REC`, `AGG`) or custom (`CUS`) gap-night rules. ### `integer_calendar_rule` Type: object `calendar_rule_adjacency_int` | object `calendar_rule_custom_int` | object `calendar_rule_day_of_week_int` | object `calendar_rule_event_int` | object `calendar_rule_gap_int` | object `calendar_rule_global_int` | object `calendar_rule_monthly_int` | object `calendar_rule_seasonal_int` | object `calendar_rule_time_based_int` `integer_calendar_rule` Integer calendar rules (minimum stay, min/max price caps, local events, check-in/out, long-term discounts, etc.). - One of: - **calendar_rule_adjacency_int** (object `calendar_rule_adjacency_int`): Integer-valued adjacency / one-sided gap rule (same semantics as `calendar_rule_adjacency`). Only used in `minimum_stay_rules_v3` (MLOS behavior). Not related to the `gap_night` pricing setting. - `type` (string, required, one of: `adjacency`, `one_sided_gap`): Use `adjacency` or legacy `one_sided_gap` (same behavior). - `adjustment` (integer): Add to the existing calendar value instead of replacing it. - `day_of_week_adjustments` (array of integer, min items: 7, max items: 7, each item nullable): Per-day adjustments (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `days_adjacent` (integer, required): Window of adjacent days (negative = prior side, positive = subsequent side). To match both sides, use two separate rules — one with a negative value and one with a positive value. When both rules fire on the same date, the negative rule's value takes precedence (it is evaluated last and overwrites the positive rule's result). - `days_after` (integer): Legacy alias retained on some stored adjacency rules. Prefer `days_adjacent`. - `days_one_sided_gap` (integer): Legacy alias retained on some stored adjacency rules. Prefer `days_adjacent`. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day minimums (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer): Single minimum when `day_of_week_values` is not used. - **calendar_rule_custom_int**: see `calendar_rule_custom_int` under Schemas. - **calendar_rule_day_of_week_int**: see `calendar_rule_day_of_week_int` under Schemas. - **calendar_rule_event_int**: see `calendar_rule_event_int` under Schemas. - **calendar_rule_gap_int** (object `calendar_rule_gap_int`): **gap** — When `gap_enabled` is true, applies a minimum stay only for "gap" nights that cannot fit the normal min stay. Provide `value` or `day_of_week_values` for the gap minimum. Optional `days_before` / `days_after` scope the rule in time. Only used in `minimum_stay_rules_v3` (MLOS behavior). Not related to the `gap_night` pricing setting. **gap** — When `gap_enabled` is true, applies a minimum stay only for “gap” nights that cannot fit the normal min stay. Provide `value` or `day_of_week_values` for the gap minimum. Optional `days_before` / `days_after` scope the rule in time. - `type` (string, required, one of: `gap`) - `days_after` (integer) - `days_before` (integer) - `gap_enabled` (boolean, required, one of: `true`) - `gap_flexibility` (integer): Reduces effective min stay in the gap by this many nights. It will never drop below `value`. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day gap minimums (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer): Gap minimum stay (integer in typical min-stay rules). - **calendar_rule_global_int**: see `calendar_rule_global_int` under Schemas. - **calendar_rule_monthly_int**: see `calendar_rule_monthly_int` under Schemas. - **calendar_rule_seasonal_int**: see `calendar_rule_seasonal_int` under Schemas. - **calendar_rule_time_based_int**: see `calendar_rule_time_based_int` under Schemas. ### `calendar_rule_global_int` Type: object `calendar_rule_global_int` **global** — Single default for the calendar in this rule set. Must not set `day_of_week_values`. UI: 'Default' or 'Minimum price default' (label varies by setting). - `type` (string, required, one of: `global`) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `value` (integer, required): Default value (non-negative). ### `calendar_rule_time_based_int` Type: object `calendar_rule_time_based_int` **time_based** — Relative to "today" for the listing. At least one of `days_before` or `days_after` must be set. Provide `value` or `day_of_week_values`, not both. Optional `months` scopes by calendar month. When only `days_before` is set, the rule applies to dates within that many days of today (last-minute window). When only `days_after` is set, the rule applies to dates at least that many days away (far-future window). When both are set, the rule applies to dates that satisfy both conditions simultaneously — at least `days_after` days away AND within `days_before` days — creating a mid-booking-window band. `days_before` must be greater than or equal to `days_after` when both are provided. **time_based** — Relative to “today” for the listing. At least one of `days_before` or `days_after` must be set. Provide `value` or `day_of_week_values`, not both. Optional `months` scopes by calendar month. When only `days_before` is set, the rule applies to dates within that many days of today (last-minute window). When only `days_after` is set, the rule applies to dates at least that many days away (far-future window). When both are set, the rule applies to dates that satisfy both conditions simultaneously — at least `days_after` days away AND within `days_before` days — creating a mid-booking-window band. `days_before` must be greater than or equal to `days_after` when both are provided. - `type` (string, required, one of: `time_based`) - `days_after` (integer, nullable): Applies on/after “today + days_after”. When combined with `days_before`, creates a mid-window band (see rule description). `null` when this side of the window is unset. - `days_before` (integer, nullable): Applies within “today + days_before”. Must be >= `days_after` when both are set. `null` when this side of the window is unset. - `months` (array of integer, min items: 1, each item min: 1, max: 12): When set, restrict to these month ordinals (1–12). - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer) ### `calendar_rule_seasonal_int` Type: object `calendar_rule_seasonal_int` **seasonal** — Tied to a custom seasonal date range. Set `id` to the custom range. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `seasonal`) - `id` (integer | string, required): Custom seasonal date-range identifier. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer) ### `calendar_rule_event_int` Type: object `calendar_rule_event_int` **event** — Tied to a custom event date range. Set `id` to the custom range. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `event`) - `id` (integer | string, required): Custom event / date-range identifier. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer) ### `calendar_rule_monthly_int` Type: object `calendar_rule_monthly_int` **monthly** — Limited to specific `months`. Provide `value` or `day_of_week_values`, not both. - `type` (string, required, one of: `monthly`) - `months` (array of integer, required, min items: 1, each item min: 1, max: 12): Month ordinals (1–12); at least one. - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer): Single value for the month. ### `calendar_rule_day_of_week_int` Type: object `calendar_rule_day_of_week_int` **day_of_week** — Per weekday (7 values, Sunday-first). Optional `months` limits to those month ordinals. Must not combine with `days_before` / `days_after` (use `time_based` for that). - `type` (string, required, one of: `day_of_week`) - `months` (array of integer, min items: 1, each item min: 1, max: 12): When set, restrict to these month ordinals (1–12). - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `day_of_week_values` (array of integer, required, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. ### `calendar_rule_custom_int` Type: object `calendar_rule_custom_int` **custom** — Fixed calendar date range. `start_date` and `end_date` inclusive; optional `yearly` repeats each year. Provide `value` or `day_of_week_values`, not both. UI: 'Date-specific overrides.' Not related to `custom_date_ranges` (Events & Seasons), Custom Rates, or the `CUS` preset type. - `type` (string, required, one of: `custom`) - `end_date` (string (date), required): Inclusive end (ISO-8601 date). - `id` (integer | string): Server-assigned identifier, returned as a string when present. On `checkin_checkout` rules it pairs a check-in rule with its check-out rule and is derived from the rule's contents, so it changes when the rule changes (on `seasonal` and `event` rules it is the season or event id instead). Requests don't use it to identify a rule, so don't store it as a stable key. - One of: - **Option 1** (integer) - **Option 2** (string) - `priority` (number, read-only): Read-only. Assigned automatically by the server based on rule type; any value submitted in a request body is ignored. - `start_date` (string (date), required): Inclusive start (ISO-8601 date). - `yearly` (boolean): When true, repeat the same month/day span every year. - `day_of_week_values` (array of integer, min items: 7, max items: 7, each item nullable): Per-day values (length 7; index 0 = Sunday). A null element means this rule does not apply for that weekday — the date falls through to the next applicable rule in the hierarchy. Use `0` to explicitly apply a zero value. - `value` (integer): Single value for dates in range when `day_of_week_values` is not used. ### `occupancy_pacing` Type: object `occupancy_pacing` Occupancy pacing matrix configuration. `{}` means pacing is off, which is the default for a new listing. When `occupancy_pacing` is sent as a non-empty object, `adjusted` and `pacing` are required, and `pacing` must include a matrix with `type` `global` (otherwise the request is rejected with 400). In a request the object replaces the stored one as a whole; omit it to leave pacing unchanged. For each lead-time column, occupancy is measured across that whole window and the matching row's percentage is applied to every date in it. A row covers occupancy above `min` up to and including `max` (`min` `0` includes 0%); the first matching row wins, and dates outside every column or row are unchanged. The adjusted price still respects the listing's minimum and maximum price rules. - `adjusted` (boolean): When true, occupancy is computed as booked nights divided by bookable (unblocked) nights; when false, against calendar days × units. - `pacing` (array of object `occupancy_pacing_matrix`): Pacing matrices. Must include one with `type` `global`, which is the one applied; others are ignored. - Each item: One pacing matrix (rows × columns of adjustment percentages). - `columns` (array of object `occupancy_pacing_column`, required): Lead-time column definitions; count must match each row in `values`. - Each item: Lead-time window (days from today) for one column of the pacing matrix. - `days_max` (integer, required, min: 0, max: 1000): Inclusive end of lead-time window (0–1000). Must be greater than or equal to `days_min`. - `days_min` (integer, required, min: 0, max: 1000): Inclusive start of lead-time window (0–1000). - `rows` (array of object `occupancy_pacing_row`, required): Occupancy (or revenue) percentage band rows; each `min`/`max` is 0–100 for occupancy pacing. - Each item: Occupancy percentage band for one row of the pacing matrix. - `max` (integer, required, min: 0, max: 100): Upper bound of the band (0–100 inclusive). - `min` (integer, required, min: 0, max: 100): Lower bound of the band (0–100 inclusive). - `type` (string, required): Rule discriminator; `global` is used for the active pacing matrix. - `values` (array of array of integer, required): Price adjustments as whole percentages (`-10` is a 10% decrease, `10` a 10% increase), each ≥ -100. One array per entry in `rows`, each holding one value per entry in `columns`; any other shape is rejected with 400. ### `fee_adjustments` Type: object `fee_adjustments` UI: 'Asking Rate (+Est. Fees)' — The estimated share of fees guests pay on top of the nightly rate, as a percentage of that rate. It is what `GET /listings/{listing_id}/fee_impact_calendar` returns as a per-date multiplier. A response carries `null` when nothing is configured, otherwise both keys. In a request the object replaces the stored one as a whole, so send both keys; `null` clears the setting. - `total_fee_percentage` (number): Fees as a percentage of the nightly rate, `-100` or more. `15` means guests pay about 15% on top of the nightly rate in fees; there is no upper bound, since fees can exceed the nightly rate on short stays. Omitted means `0`. - `auto_update` (boolean): When `true`, `total_fee_percentage` is recalculated weekly from the fees on the listing's recent reservations, replacing whatever was set. Defaults to `false` when omitted. ### `custom_date_range` Type: object `custom_date_range` Represents an Event or Season entry used by the Wheelhouse Events & Seasons feature. Calendar rules reference these entries by `id` to apply settings (e.g. min stay, pricing) over named date windows. Each listing stores its own copy of every Event or Season it belongs to. Entries for the same event or season share the same `id` across listings — this shared `id` is what enables bulk adjustments in the Wheelhouse UI. If you write a `custom_date_ranges` entry with a new or changed `id`, that listing's entry is no longer linked to the others and will not be included in future bulk edits of the original Event or Season. To safely modify an event or season's definition (dates or name) on one listing without affecting others, omit the `id` field — the server assigns a new independent ID scoped to that listing. To update only a rule value (e.g. raise the minimum price) without changing dates, include the existing `id` unchanged. - `date_ranges` (array of object `custom_date_range_segment`, required): One or more inclusive calendar spans. Each span must include `start_date` and `end_date`, and `start_date` must be on or before `end_date`. - Each item: Inclusive calendar span within a custom date range. - `end_date` (string (date), required): Inclusive end (ISO-8601 date). - `start_date` (string (date), required): Inclusive start (ISO-8601 date). - `id` (string): Stable identifier for this range, referenced by calendar rules. Listings that share the same `id` for an entry are considered part of the same Event or Season and can be bulk-edited together. Preserve the existing `id` when updating an entry to keep it linked; omit only when creating a new range (one will be assigned). The server always returns this field as a string. Calendar rule `id` fields accept both string and integer for backward compatibility, but the canonical type is string — use string comparisons when matching rule `id` values against `custom_date_ranges` entries. - `name` (string, required): Display name for the season or event. - `type` (string, required, one of: `event`, `seasonal`): Whether this range represents a recurring season or a dated event. - `yearly` (boolean, required): When true, the date spans repeat each calendar year (same month/day pattern). --- # Copy preferences from one listing to another. `PUT /preferences/{listing_id}/copy` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-copy-preferences · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmCopyPreferences` · Tag: Listing Preferences Copies the preferences (and optionally custom rates) from a source listing to the target listing. **This is a destructive action** — it will overwrite the target listing's existing preferences. The **source** listing is identified in the request body by `copy_preferences_from`. The **target** listing is identified by the `listing_id` path parameter. ## Request `PUT https://api.usewheelhouse.com/ss_api/v1/preferences/{listing_id}/copy` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier of the **target** listing (the one to copy preferences **to**), or its Wheelhouse listing ID when the top-level `channel` is `wheelhouse`. | ### Request body (`application/json`, required) - `copy_custom_rates` (boolean, default: `true`): If true, also copies the source listing's custom rates to the target. - `channel` (string, required): Channel name the **target** listing is on (see return value of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) endpoint), or the literal `wheelhouse` to read the path `listing_id` as a Wheelhouse listing ID instead. - `copy_preferences_from` (object, required): Identifies the **source** listing to copy preferences from. - `channel` (string): Channel name for the **source** listing (same values as elsewhere in this API, e.g. from `/listings`), or the literal `wheelhouse` to read the source `listing_id` as a Wheelhouse listing ID instead. Resolved independently of the top-level `channel`, so the source and target listing may each be identified their own way. - `listing_id` (string, required): The channel's unique listing identifier of the **source** listing (the listing to copy **from**), or its Wheelhouse listing ID when `copy_preferences_from.channel` is `wheelhouse`. ### Example request ```bash curl -X PUT 'https://api.usewheelhouse.com/ss_api/v1/preferences/{listing_id}/copy' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{ "channel": "string", "copy_preferences_from": { "listing_id": "string" } }' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Successfully copied preferences and/or custom rates. Body (`application/json`): object - `warnings` (array of object `preference_warning`, each item read-only): Settings the source listing carries that the **target** listing's channel cannot act on, and which were therefore not copied. Empty when everything copied. Only settings the source actually set are considered — a value left at its default is not treated as something the copy is applying. See the [Listing Preferences](https://docs.usewheelhouse.com/rm/concepts/preferences.md) section. - Each item: One setting in the request that was not applied, or that has no effect on this listing. - `setting` (string, one of: `checkin_checkout`, `gap_night`, `min_stays`, `long_term_discounts`): The setting group the warning is about. - `reason` (string, one of: `not_supported_by_channel`, `partially_supported_by_channel`, `not_supported_for_multi_unit`): `not_supported_by_channel` — the channel has no such feature and everything sent for it was dropped. `partially_supported_by_channel` — the channel has the feature but accepts a narrower form than what was sent, and only the excess was dropped. `not_supported_for_multi_unit` — the setting is stored but has no effect on price, because the listing has more than one unit. - `message` (string): A human-readable explanation of what was ignored and why. - `attributes` (array of string): The request attributes this warning covers, in dot notation for nested ones (e.g. `long_term_discounts.rules.14`). Example shape (generated from the schema; placeholder values, not a real response): ```json { "warnings": [ { "setting": "checkin_checkout", "reason": "not_supported_by_channel", "message": "string", "attributes": [ "string" ] } ] } ``` ### 401 API key authorization failed. ### 403 Listing authorization failed, or the API key is read-only and may not be used with PUT. ### 404 Source or target listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 409 Another request is already in progress for this listing. Retry after the concurrent request completes. ### 422 Validation failed (e.g. source channel could not be determined). ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` ## Notes for AI agents The Wheelhouse MCP server gives agents these instructions for this operation. They apply equally when calling the API directly. ⚠️ **Requires user confirmation before calling — this is destructive.** This overwrites the target listing's entire preference set (and custom rates, if `copy_custom_rates` is true) with the source listing's settings. Before calling, state to the user: the source and target listings, and whether custom rates will also be copied. Do not call until the user has explicitly confirmed both listings and the custom-rate scope. --- # Update a single pricing setting for a listing. `PUT /preferences/{listing_id}/{setting}` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-put-preference-setting · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPutPreferenceSetting` · Tag: Listing Preferences Updates one of the following settings to a preset level (conservative/recommended/aggressive), or toggles automatic rate posting on/off. | Setting | Accepted parameters | |---|---| | `base_price_adjustment` | `type`: `CON`, `REC`, or `AGG` | | `day_of_week` | `type`: `CON`, `REC`, or `AGG` | | `seasonality_adjustment` | `type`: `CON`, `REC`, or `AGG` | | `last_minute_discount` | `type`: `CON`, `REC`, or `AGG` | | `far_future_premium` | `type`: `CON`, `REC`, or `AGG` | | `automatic_rate_posting` | `enabled`: `true` or `false` | ## Request `PUT https://api.usewheelhouse.com/ss_api/v1/preferences/{listing_id}/{setting}` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | | `setting` | string | yes | The setting to update. (one of: `base_price_adjustment`, `day_of_week`, `seasonality_adjustment`, `last_minute_discount`, `far_future_premium`, `automatic_rate_posting`) | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Request body (`application/json`, required) - `type` (string, one of: `CON`, `REC`, `AGG`): The preset level to apply. Required for all settings except `automatic_rate_posting`. - `enabled` (boolean): The enabled state. Required for `automatic_rate_posting` only. ### Example request ```bash curl -X PUT 'https://api.usewheelhouse.com/ss_api/v1/preferences/{listing_id}/{setting}?channel=' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{}' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 204 The setting was updated successfully. No content is returned. ### 400 Invalid or missing parameter. ### 401 API key authorization failed. ### 403 Listing authorization failed, or the API key is read-only and may not be used with PUT. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 409 Another request is already in progress for this listing. Retry after the concurrent request completes. ### 423 Listing preferences not yet initialized. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` ## Notes for AI agents The Wheelhouse MCP server gives agents these instructions for this operation. They apply equally when calling the API directly. ⚠️ **Requires user confirmation before calling.** This changes a live pricing setting for the listing, which affects the rates Wheelhouse recommends and may post going forward. Before calling, state to the user: the listing, the setting being changed, the current value (fetch via `rmGetPreferences` first if unknown), and the new value. Do not call until the user has explicitly confirmed. --- # Get the long-term discount settings for a listing. `GET /preferences/{listing_id}/long_term_discounts` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-long-term-discounts · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetLongTermDiscounts` · Tag: Listing Preferences This endpoint can be used to fetch weekly and monthly discounts set up through Wheelhouse for a listing. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/preferences/{listing_id}/long_term_discounts` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/preferences/{listing_id}/long_term_discounts?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Long-term discount settings. Body (`application/json`): object - `weekly_discount` (integer, nullable): The weekly discount as an integer percentage (e.g. `5` = 5%). Same value as `weekly_discount` in `GET /preferences/{listing_id}`. - `monthly_discount` (integer, nullable): The monthly discount as an integer percentage (e.g. `10` = 10%). Same value as `monthly_discount` in `GET /preferences/{listing_id}`. Example shape (generated from the schema; placeholder values, not a real response): ```json { "weekly_discount": 0, "monthly_discount": 0 } ``` ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get the changelog of all changes to a listing. `GET /preferences/{listing_id}/changelog` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-preferences-changelog · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetPreferencesChangelog` · Tag: Listing Preferences Returns a list of recent change events for the listing, most recent first. Despite sitting under `/preferences`, the changelog is not limited to preference changes: it is the single history of everything recorded against the listing. It covers changes to the pricing settings, prices posted to the channel and any post or calendar sync that failed, custom rates added, split or removed, a change of pricing engine, and reservations imported for the listing. Read `event` on each entry to tell them apart. Custom rate history is therefore read from here rather than from the Custom Rates endpoints, which report the rates currently in force. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/preferences/{listing_id}/changelog` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | | `start_date` | string (date) | no | Start of the date range to retrieve changes for. Defaults to 30 days ago. A request returns at most one year, so a `start_date` more than a year before `end_date` is moved forward to one year before `end_date` (no error is returned). To read older history, move `end_date` back as well, e.g. `start_date=2024-01-01&end_date=2025-01-01`, then `start_date=2023-01-01&end_date=2024-01-01`. | | `end_date` | string (date) | no | End of the date range to retrieve changes for. Defaults to tomorrow. Clamped to the range [`start_date` + 1 day, tomorrow] (no error is returned). | | `event` | array of string | no | Return only events of these types (the `event` field of each entry). Defaults to every type. Leaving out `Prices posted` drops the automatic price posts, which outnumber everything else on a listing that posts daily, e.g. `?event[]=Settings changed&event[]=Custom rates` for setting and custom rate changes only. Send more than one comma-separated (`?event=Settings changed,Custom rates`) or in brackets; a key repeated without brackets keeps only its last value. (each item one of: `Prices posted`, `Calendar synced`, `Settings changed`, `Custom rates`, `Reservations imported`) | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/preferences/{listing_id}/changelog?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 List of changelog events. Body (`application/json`): object - `events` (array of object) - `time` (string (date-time)): When the change occurred (ISO-8601). - `source` (string): Who triggered the change. Known values: `'Wheelhouse'` (system-generated — auto price posting, internal adjustments, migrations); `'User'` or `'User '` (user-initiated); `'API'` (updated via API); `'Customer Support'` (Wheelhouse support staff); `'Wheelhouse team'` or `'Wheelhouse team '` (reservation imports). - `event` (string): The type of event. Known values: `'Prices posted'`, `'Calendar synced'`, `'Settings changed'`, `'Custom rates'`, `'Reservations imported'`. - `status` (string): The outcome of the event. Known values: `'success'`, `'warning'` (partial success: e.g. some prices posted, but the channel rejected some dates; `msg` says what to fix), `'error'`. - `msg` (string): A human-readable description of the change. Example shape (generated from the schema; placeholder values, not a real response): ```json { "events": [ { "time": "2026-01-01T00:00:00Z", "source": "string", "event": "string", "status": "string", "msg": "string" } ] } ``` ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get all active and upcoming custom rates for a listing. `GET /listings/{listing_id}/custom_rates` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-custom-rates · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetCustomRates` · Tag: Custom Rates Returns all custom rate periods that are currently active and affect future stay dates. Expired rate periods (those whose `expires_at` timestamp has passed) are excluded. This is the state of the listing's custom rates now, not their history. For a record of when custom rates were added, split or removed, and by whom, read the listing's [changelog](https://docs.usewheelhouse.com/rm/reference/rm-get-preferences-changelog.md) and look for `Custom rates` events. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/custom_rates` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/custom_rates?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The list of active and upcoming custom rate periods. Body (`application/json`): array of object `rate_period_response` A custom rate period. - `id` (integer): The Wheelhouse internal rate period ID. - `listing_id` (integer): The Wheelhouse internal listing ID. - `rate_type` (string, one of: `fixed`, `adjustment`): The type of custom rate. `fixed` means a fixed nightly price; `adjustment` means a percentage adjustment to the Wheelhouse recommendation. Note: when reading prices via `GET /listings/{listing_id}/price_recommendations`, an `adjustment` rate appears as `custom_type: "adjusted"` (past-tense form). - `currency` (string, nullable): The currency of the fixed rate (ISO-4217). Only present for `fixed` type rates. - `start_date` (string (date)): The first date of the rate period (YYYY-MM-DD). - `end_date` (string (date)): The last date of the rate period (YYYY-MM-DD). - `sunday` (number, nullable): Sunday price or adjustment value. - `monday` (number, nullable): Monday price or adjustment value. - `tuesday` (number, nullable): Tuesday price or adjustment value. - `wednesday` (number, nullable): Wednesday price or adjustment value. - `thursday` (number, nullable): Thursday price or adjustment value. - `friday` (number, nullable): Friday price or adjustment value. - `saturday` (number, nullable): Saturday price or adjustment value. - `created_user_id` (integer): The ID of the user who created this rate period. - `split_user_id` (integer, nullable): When a PUT or DELETE operation partially overlaps this rate period, causing it to be shortened or split, this field records the ID of the user whose request triggered the split. Null if the period has never been split. - `expires_at` (string (date-time), nullable): The date-time after which this rate period is considered expired and no longer applies. Null if the period does not expire automatically. - `valid_until` (string (date-time), nullable): Internal archival timestamp. Null means this is the currently active rate period. Non-null means this period has been replaced or deleted — the replacement took effect at this time. - `created_at` (string (date-time)): When this rate period was created (ISO-8601). - `updated_at` (string (date-time)): When this rate period was last updated (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "id": 0, "listing_id": 0, "rate_type": "fixed", "currency": "string", "start_date": "2026-01-01", "end_date": "2026-01-01", "sunday": 0, "monday": 0, "tuesday": 0, "wednesday": 0, "thursday": 0, "friday": 0, "saturday": 0, "created_user_id": 0, "split_user_id": 0, "expires_at": "2026-01-01T00:00:00Z", "valid_until": "2026-01-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ] ``` ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Set a custom rate for a listing. `PUT /listings/{listing_id}/custom_rates` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-put-custom-rate · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPutCustomRate` · Tag: Custom Rates Creates or replaces a custom rate for a date range. Setting a `fixed` rate applies an absolute nightly price; setting an `adjustment` rate applies a percentage multiplier to the Wheelhouse recommendation. For `adjustment` rates, per-day values are percentages where 100 = no adjustment, 110 = +10%, and 90 = −10%. If the specified date range overlaps an existing custom rate, the existing rate is shortened or split so the new rate takes precedence for the overlapping dates. Custom rates are not stacked — a new adjustment rate replaces rather than compounds with any existing adjustment for the same dates. To combine adjustments, compute the target multiplier explicitly and submit the combined value. ## Request `PUT https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/custom_rates` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Request body (`application/json`, required) A custom rate to set for a date range. - `start_date` (string (date), required): The first date of the custom rate period (YYYY-MM-DD). - `end_date` (string (date), required): The last date of the custom rate period (YYYY-MM-DD). - `rate_type` (string, required, one of: `fixed`, `adjustment`): The type of custom rate. - `fixed`: A fixed nightly price. Requires `currency`. Per-day values (`sunday`–`saturday`) are absolute prices. - `adjustment`: A percentage adjustment to the Wheelhouse recommendation. Per-day values are percentages where 100 = no adjustment, 110 = +10%, and 90 = −10%. **Minimum price interactions:** Fixed rates are constrained only by `min_min_price` (the absolute floor) — they bypass `minimum_price_rules_v3` entirely. Adjustment rates are additionally constrained by per-date `minimum_price_rules_v3` floors; the resulting dollar price after applying the multiplier must meet or exceed the effective minimum price rule for each date. **Read-side representation:** When reading prices via `GET /listings/{listing_id}/price_recommendations`, an `adjustment` rate appears as `custom_type: "adjusted"` (past-tense form). The write value (`adjustment`) and the read value (`adjusted`) differ in form; match them accordingly when reconciling written rates against recommendation responses. - `currency` (string): The ISO-4217 3-letter currency code. Required for `fixed` type. - `sunday` (number, min: 1): Price or adjustment value for Sundays. - `monday` (number, min: 1): Price or adjustment value for Mondays. - `tuesday` (number, min: 1): Price or adjustment value for Tuesdays. - `wednesday` (number, min: 1): Price or adjustment value for Wednesdays. - `thursday` (number, min: 1): Price or adjustment value for Thursdays. - `friday` (number, min: 1): Price or adjustment value for Fridays. - `saturday` (number, min: 1): Price or adjustment value for Saturdays. - `expires_at` (string (date-time)): When the custom rate expires (ISO-8601). Once past this timestamp the rate is no longer applied. Omit to create a rate that never expires. ### Example request ```bash curl -X PUT 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/custom_rates?channel=' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{ "start_date": "2026-01-01", "end_date": "2026-01-01", "rate_type": "fixed" }' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The created custom rate period. Body (`application/json`): object `rate_period_response` A custom rate period. - `id` (integer): The Wheelhouse internal rate period ID. - `listing_id` (integer): The Wheelhouse internal listing ID. - `rate_type` (string, one of: `fixed`, `adjustment`): The type of custom rate. `fixed` means a fixed nightly price; `adjustment` means a percentage adjustment to the Wheelhouse recommendation. Note: when reading prices via `GET /listings/{listing_id}/price_recommendations`, an `adjustment` rate appears as `custom_type: "adjusted"` (past-tense form). - `currency` (string, nullable): The currency of the fixed rate (ISO-4217). Only present for `fixed` type rates. - `start_date` (string (date)): The first date of the rate period (YYYY-MM-DD). - `end_date` (string (date)): The last date of the rate period (YYYY-MM-DD). - `sunday` (number, nullable): Sunday price or adjustment value. - `monday` (number, nullable): Monday price or adjustment value. - `tuesday` (number, nullable): Tuesday price or adjustment value. - `wednesday` (number, nullable): Wednesday price or adjustment value. - `thursday` (number, nullable): Thursday price or adjustment value. - `friday` (number, nullable): Friday price or adjustment value. - `saturday` (number, nullable): Saturday price or adjustment value. - `created_user_id` (integer): The ID of the user who created this rate period. - `split_user_id` (integer, nullable): When a PUT or DELETE operation partially overlaps this rate period, causing it to be shortened or split, this field records the ID of the user whose request triggered the split. Null if the period has never been split. - `expires_at` (string (date-time), nullable): The date-time after which this rate period is considered expired and no longer applies. Null if the period does not expire automatically. - `valid_until` (string (date-time), nullable): Internal archival timestamp. Null means this is the currently active rate period. Non-null means this period has been replaced or deleted — the replacement took effect at this time. - `created_at` (string (date-time)): When this rate period was created (ISO-8601). - `updated_at` (string (date-time)): When this rate period was last updated (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json { "id": 0, "listing_id": 0, "rate_type": "fixed", "currency": "string", "start_date": "2026-01-01", "end_date": "2026-01-01", "sunday": 0, "monday": 0, "tuesday": 0, "wednesday": 0, "thursday": 0, "friday": 0, "saturday": 0, "created_user_id": 0, "split_user_id": 0, "expires_at": "2026-01-01T00:00:00Z", "valid_until": "2026-01-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ``` ### 400 Validation failed. ### 401 API key authorization failed. ### 403 Listing authorization failed, or the API key is read-only and may not be used with PUT. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 409 Another request is already in progress for this listing. Retry after the concurrent request completes. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` ## Notes for AI agents The Wheelhouse MCP server gives agents these instructions for this operation. They apply equally when calling the API directly. ⚠️ **Requires user confirmation before calling.** This writes a live custom rate that will be posted to the channel, and will silently shorten or split any existing custom rate that overlaps the given date range(s). **Step 1 — Check for an existing rate first.** Before writing any rate for a listing/date range, check for an existing overlapping custom rate (`rmGetCustomRates`). Do not assume intent based on the existing rate's presence. **Step 2 — If an existing rate is found, ask the user to choose:** * **(a) Adjust existing** — compound the requested change on top of what's already there, or * **(b) Replace** — discard the existing rate and set only the new value **Step 3 — If "adjust existing" is chosen, compute the combined value before calling this tool** — this tool does not compound automatically; whatever value is submitted is treated as the final value. * `adjustment` type rates: the combination is **additive on percentage-points**, not multiplicative. * Example: existing rate is 110 (+10%). User requests +10% more. → Submit **120** (+20% total), *not* 110 × 1.10 = 121. * Formula: `new_value = existing_value + requested_delta_points` * `fixed` type rates: the combination is **multiplicative on the dollar value**. * Example: existing rate is $100. User requests +10%. → Submit **$110** (100 × 1.10). * Formula: `new_value = round(existing_value × (1 + requested_delta_pct / 100))` **Step 4 — Before calling, state to the user:** the listing, the exact date range(s), the rate type (fixed/adjustment), the existing value (if any), the computed new value, which mode was used (adjust/replace), and flag if this overlaps an existing rate. Do not call until the user has explicitly confirmed the specific dates and values. --- # Delete custom rates for a date range on a listing. `DELETE /listings/{listing_id}/custom_rates` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-delete-custom-rate · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmDeleteCustomRate` · Tag: Custom Rates Removes all custom rates overlapping the specified date range. If a custom rate period extends beyond the deleted range on one side only, it is truncated to the non-overlapping portion. If the deleted range falls in the middle of an existing rate period, that period is split into two — one before and one after the deleted range. The deleted dates revert to the Wheelhouse recommended price. ## Request `DELETE https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/custom_rates` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | | `start_date` | string (date) | yes | The start date of the range to delete (YYYY-MM-DD). This date is inclusive. | | `end_date` | string (date) | yes | The end date of the range to delete (YYYY-MM-DD). This date is inclusive. | ### Example request ```bash curl -X DELETE 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/custom_rates?channel=&start_date=&end_date=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 204 Custom rates deleted successfully. No content is returned. ### 400 Validation failed (e.g. start_date > end_date). ### 401 API key authorization failed. ### 403 Listing authorization failed, or the API key is read-only and may not be used with DELETE. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Set multiple custom rates for a listing in bulk. `PUT /listings/{listing_id}/bulk_custom_rates` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-bulk-put-custom-rates · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmBulkPutCustomRates` · Tag: Custom Rates Creates or replaces multiple custom rates in a single request. Partially successful requests return status `207`; fully failed requests return `424`. For `adjustment` rates, per-day values are percentages where 100 = no adjustment, 110 = +10%, and 90 = −10%. If a specified date range overlaps an existing custom rate, the existing rate is shortened or split so the new rate takes precedence for the overlapping dates. Custom rates are not stacked — a new adjustment rate replaces rather than compounds with any existing adjustment for the same dates. To combine adjustments, compute the target multiplier explicitly and submit the combined value. ## Request `PUT https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/bulk_custom_rates` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Request body (`application/json`, required) - `custom_rates` (array of object `custom_rate_input`, required) - Each item: A custom rate to set for a date range. - `start_date` (string (date), required): The first date of the custom rate period (YYYY-MM-DD). - `end_date` (string (date), required): The last date of the custom rate period (YYYY-MM-DD). - `rate_type` (string, required, one of: `fixed`, `adjustment`): The type of custom rate. - `fixed`: A fixed nightly price. Requires `currency`. Per-day values (`sunday`–`saturday`) are absolute prices. - `adjustment`: A percentage adjustment to the Wheelhouse recommendation. Per-day values are percentages where 100 = no adjustment, 110 = +10%, and 90 = −10%. **Minimum price interactions:** Fixed rates are constrained only by `min_min_price` (the absolute floor) — they bypass `minimum_price_rules_v3` entirely. Adjustment rates are additionally constrained by per-date `minimum_price_rules_v3` floors; the resulting dollar price after applying the multiplier must meet or exceed the effective minimum price rule for each date. **Read-side representation:** When reading prices via `GET /listings/{listing_id}/price_recommendations`, an `adjustment` rate appears as `custom_type: "adjusted"` (past-tense form). The write value (`adjustment`) and the read value (`adjusted`) differ in form; match them accordingly when reconciling written rates against recommendation responses. - `currency` (string): The ISO-4217 3-letter currency code. Required for `fixed` type. - `sunday` (number, min: 1): Price or adjustment value for Sundays. - `monday` (number, min: 1): Price or adjustment value for Mondays. - `tuesday` (number, min: 1): Price or adjustment value for Tuesdays. - `wednesday` (number, min: 1): Price or adjustment value for Wednesdays. - `thursday` (number, min: 1): Price or adjustment value for Thursdays. - `friday` (number, min: 1): Price or adjustment value for Fridays. - `saturday` (number, min: 1): Price or adjustment value for Saturdays. - `expires_at` (string (date-time)): When the custom rate expires (ISO-8601). Once past this timestamp the rate is no longer applied. Omit to create a rate that never expires. ### Example request ```bash curl -X PUT 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/bulk_custom_rates?channel=' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{ "custom_rates": [ { "start_date": "2026-01-01", "end_date": "2026-01-01", "rate_type": "fixed" } ] }' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 All custom rates set successfully. An empty `custom_rates` array is accepted and returns an empty `updated_custom_rates`; nothing is changed. Body (`application/json`): object - `updated_custom_rates` (array of object `rate_period_response`) - Fields: see `rate_period_response` under Schemas. Example shape (generated from the schema; placeholder values, not a real response): ```json { "updated_custom_rates": [ { "id": 0, "listing_id": 0, "rate_type": "fixed", "currency": "string", "start_date": "2026-01-01", "end_date": "2026-01-01", "sunday": 0, "monday": 0, "tuesday": 0, "wednesday": 0, "thursday": 0, "friday": 0, "saturday": 0, "created_user_id": 0, "split_user_id": 0, "expires_at": "2026-01-01T00:00:00Z", "valid_until": "2026-01-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ] } ``` ### 207 Some custom rates succeeded and some failed. Body (`application/json`): object - `updated_custom_rates` (array of object `rate_period_response`) - Fields: see `rate_period_response` under Schemas. - `errors` (array of object `custom_rate_error`) - Fields: see `custom_rate_error` under Schemas. Example shape (generated from the schema; placeholder values, not a real response): ```json { "updated_custom_rates": [ { "id": 0, "listing_id": 0, "rate_type": "fixed", "currency": "string", "start_date": "2026-01-01", "end_date": "2026-01-01", "sunday": 0, "monday": 0, "tuesday": 0, "wednesday": 0, "thursday": 0, "friday": 0, "saturday": 0, "created_user_id": 0, "split_user_id": 0, "expires_at": "2026-01-01T00:00:00Z", "valid_until": "2026-01-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ], "errors": [ { "start_date": "2026-01-01", "end_date": "2026-01-01", "http_code": 0, "message": "string" } ] } ``` ### 401 API key authorization failed. ### 403 Listing authorization failed, or the API key is read-only and may not be used with PUT. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 424 All custom rates failed. Body: same as `207` above. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` ## Schemas Shared by more than one field above. ### `rate_period_response` Type: object `rate_period_response` A custom rate period. - `id` (integer): The Wheelhouse internal rate period ID. - `listing_id` (integer): The Wheelhouse internal listing ID. - `rate_type` (string, one of: `fixed`, `adjustment`): The type of custom rate. `fixed` means a fixed nightly price; `adjustment` means a percentage adjustment to the Wheelhouse recommendation. Note: when reading prices via `GET /listings/{listing_id}/price_recommendations`, an `adjustment` rate appears as `custom_type: "adjusted"` (past-tense form). - `currency` (string, nullable): The currency of the fixed rate (ISO-4217). Only present for `fixed` type rates. - `start_date` (string (date)): The first date of the rate period (YYYY-MM-DD). - `end_date` (string (date)): The last date of the rate period (YYYY-MM-DD). - `sunday` (number, nullable): Sunday price or adjustment value. - `monday` (number, nullable): Monday price or adjustment value. - `tuesday` (number, nullable): Tuesday price or adjustment value. - `wednesday` (number, nullable): Wednesday price or adjustment value. - `thursday` (number, nullable): Thursday price or adjustment value. - `friday` (number, nullable): Friday price or adjustment value. - `saturday` (number, nullable): Saturday price or adjustment value. - `created_user_id` (integer): The ID of the user who created this rate period. - `split_user_id` (integer, nullable): When a PUT or DELETE operation partially overlaps this rate period, causing it to be shortened or split, this field records the ID of the user whose request triggered the split. Null if the period has never been split. - `expires_at` (string (date-time), nullable): The date-time after which this rate period is considered expired and no longer applies. Null if the period does not expire automatically. - `valid_until` (string (date-time), nullable): Internal archival timestamp. Null means this is the currently active rate period. Non-null means this period has been replaced or deleted — the replacement took effect at this time. - `created_at` (string (date-time)): When this rate period was created (ISO-8601). - `updated_at` (string (date-time)): When this rate period was last updated (ISO-8601). ### `custom_rate_error` Type: object `custom_rate_error` An error that occurred when processing a custom rate. - `start_date` (string (date)) - `end_date` (string (date)) - `http_code` (integer) - `message` (string) ## Notes for AI agents The Wheelhouse MCP server gives agents these instructions for this operation. They apply equally when calling the API directly. ⚠️ **Requires user confirmation before calling.** This writes live custom rates that will be posted to the channel, and will silently shorten or split any existing custom rates that overlap the given date range(s). **Step 1 — Check for an existing rate first.** Before writing any rate for a listing/date range, check for an existing overlapping custom rate (`rmGetCustomRates`). Do not assume intent based on the existing rate's presence. **Step 2 — If an existing rate is found, ask the user to choose:** * **(a) Adjust existing** — compound the requested change on top of what's already there, or * **(b) Replace** — discard the existing rate and set only the new value **Step 3 — If "adjust existing" is chosen, compute the combined value before calling this tool** — this tool does not compound automatically; whatever value is submitted is treated as the final value. * `adjustment` type rates: the combination is **additive on percentage-points**, not multiplicative. * Example: existing rate is 110 (+10%). User requests +10% more. → Submit **120** (+20% total), *not* 110 × 1.10 = 121. * Formula: `new_value = existing_value + requested_delta_points` * `fixed` type rates: the combination is **multiplicative on the dollar value**. * Example: existing rate is $100. User requests +10%. → Submit **$110** (100 × 1.10). * Formula: `new_value = round(existing_value × (1 + requested_delta_pct / 100))` **Step 4 — Before calling, state to the user:** the listing, the exact date range(s), the rate type (fixed/adjustment), the existing value (if any), the computed new value, which mode was used (adjust/replace), and flag if this overlaps an existing rate. Do not call until the user has explicitly confirmed the specific dates and values. --- # Delete multiple custom rate ranges for a listing in bulk. `DELETE /listings/{listing_id}/bulk_custom_rates` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-bulk-delete-custom-rates · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmBulkDeleteCustomRates` · Tag: Custom Rates Removes custom rates for multiple date ranges in a single request. Partially successful requests return status `207`; fully failed requests return `424`. ## Request `DELETE https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/bulk_custom_rates` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Request body (`application/json`, required) - `channel` (string): Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). - `delete_ranges` (array of object, required) - `start_date` (string (date), required): The start date of the range to delete (YYYY-MM-DD). This date is inclusive. - `end_date` (string (date), required): The end date of the range to delete (YYYY-MM-DD). This date is inclusive. ### Example request ```bash curl -X DELETE 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/bulk_custom_rates' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{ "delete_ranges": [ { "start_date": "2026-01-01", "end_date": "2026-01-01" } ] }' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 204 All ranges deleted successfully. No content is returned. ### 207 Some ranges deleted and some failed. Body (`application/json`): object - `errors` (array of object `custom_rate_error`) - Fields: see `custom_rate_error` under Schemas. Example shape (generated from the schema; placeholder values, not a real response): ```json { "errors": [ { "start_date": "2026-01-01", "end_date": "2026-01-01", "http_code": 0, "message": "string" } ] } ``` ### 401 API key authorization failed. ### 403 Listing authorization failed, or the API key is read-only and may not be used with DELETE. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 424 All ranges failed to delete. Body: same as `207` above. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` ## Schemas Shared by more than one field above. ### `custom_rate_error` Type: object `custom_rate_error` An error that occurred when processing a custom rate. - `start_date` (string (date)) - `end_date` (string (date)) - `http_code` (integer) - `message` (string) --- # Get reservations for a listing. `GET /listings/{listing_id}/reservations` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-reservations · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetReservations` · Tag: Reservations Returns a list of reservations for a listing. **Fetching only what changed:** Use `date_filter_type=updated_at` with timestamps, e.g. `start_date=2026-09-01T00:00:00Z&end_date=2026-09-02T00:00:00Z`, to get the reservations created, amended or cancelled in that window rather than every reservation in a stay range. **Deriving pickup metrics:** Use `date_filter_type=booked_at` to filter by booking date rather than stay date: - **Pickup (Booked Nights)** — new nights booked in a time window — sum `end_date − start_date` (in days) across returned reservations. - **Pickup (Bookings)** — new reservations created in a time window — count the number of reservation records returned. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/reservations` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | | `start_date` | string | no | Filter start, as a date (YYYY-MM-DD) or, for `updated_at`, an ISO 8601 timestamp. Behavior depends on `date_filter_type`: - `stay_date` (default): returns reservations whose stay period overlaps with this date (i.e. `end_date > start_date`). - `booked_at`: returns reservations booked on or after the start of this date. - `updated_at`: returns reservations last changed at or after this time. A date alone means midnight UTC. (example: `2026-09-01`) | | `end_date` | string | no | Filter end, as a date (YYYY-MM-DD) or, for `updated_at`, an ISO 8601 timestamp. Behavior depends on `date_filter_type`: - `stay_date` (default): returns reservations whose stay period overlaps with this date (i.e. `start_date <= end_date`). - `booked_at`: returns reservations booked before the end of this date. - `updated_at`: returns reservations last changed before this time. A date alone means midnight UTC, so that day itself is not included. (example: `2026-09-10`) | | `date_filter_type` | string | no | Controls which date field is used for filtering: - `stay_date` (default): filter by the reservation's stay dates. - `booked_at`: filter by the date the reservation was booked. - `updated_at`: filter by when Wheelhouse last recorded a change to the reservation (the `updated_at` field), for example a new booking, an amendment or a cancellation. Use it to fetch only what changed since your last request: pass the previous request's `end_date` as the next `start_date`. Times are compared exactly, with `start_date` included and `end_date` excluded, so consecutive windows do not overlap. Keep `end_date` a few minutes in the past: a change can take a short while to become visible after the time it is recorded with. A reservation can also be returned when Wheelhouse re-recorded it without a visible change, so treat the result as the reservations to re-read rather than a list of confirmed changes. (one of: `stay_date`, `booked_at`, `updated_at`, default: `stay_date`) | | `per_page` | integer | no | Number of reservations per page. (default: `50`, min: 1, max: 100) | | `page` | integer | no | Page number to retrieve. | | `offset` | integer | no | Number of items to skip before starting to collect the result set. | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/reservations?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of reservations. Body (`application/json`): array of object `reservation_response` A reservation. - `id` (string, required): The reservation ID. - `status` (string, required): The reservation status. Known values: `Accepted`, `Declined`, `Expired`, `Canceled`, `Pending`, `Ignored`. - `start_date` (string (date), required): The check-in date (YYYY-MM-DD). - `end_date` (string (date), required): The check-out date (YYYY-MM-DD). - `booked_at` (string (date-time), nullable): When the reservation was booked (ISO-8601), or `null` if it is unknown. - `canceled_at` (string (date-time), nullable): When the reservation was cancelled (ISO-8601), or `null` if it was not. Set whenever `status` is `Canceled`. Note the single-l spelling, matching the `Canceled` status value; the `PUT` request body uses `cancelled`. - `num_guests` (integer, nullable): Number of guests, or `null` if it was not provided. - `currency` (string, nullable): The ISO-4217 3-letter currency code, or `null` if it is unknown. - `total_price` (number, nullable): Total price of the reservation paid by the guest, or `null` if it is unknown. - `nightly_subtotal` (number, nullable): Sum of all nightly room prices. This is the 'Revenue' metric in the Wheelhouse platform (rent only, excluding fees and taxes). To derive Revenue + Fees, compute `total_price − taxes`. To derive ADR (Average Daily Rate) for this reservation, divide by the number of nights. `null` if it is unknown. - `extra_guest` (number, nullable): Extra guest fee amount, or `null` if it is unknown. - `security_deposit` (number, nullable): Security deposit amount, or `null` if it is unknown. - `extras` (number, nullable): Additional extras charges, or `null` if it is unknown. - `taxes` (number, nullable): Tax amount, or `null` if it is unknown. - `confirmation_code` (string, nullable): The reservation confirmation code from the booking channel, or `null` if none was provided. - `source_name` (string, nullable): The name of the booking source/channel, or `null` if it is unknown. - `comments` (string, nullable): Any comments or notes about the reservation, or `null` if none were provided. - `created_at` (string (date-time), nullable): When the reservation was created in Wheelhouse (ISO-8601), or `null` if it is unknown. - `updated_at` (string (date-time), nullable): When the reservation was last updated in Wheelhouse (ISO-8601), or `null` if it is unknown. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "id": "string", "status": "string", "start_date": "2026-01-01", "end_date": "2026-01-01", "booked_at": "2026-01-01T00:00:00Z", "canceled_at": "2026-01-01T00:00:00Z", "num_guests": 0, "currency": "string", "total_price": 0, "nightly_subtotal": 0, "extra_guest": 0, "security_deposit": 0, "extras": 0, "taxes": 0, "confirmation_code": "string", "source_name": "string", "comments": "string", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ] ``` ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get user-defined tags for a listing. `GET /listings/{listing_id}/tags` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-tags · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetTags` · Tag: Listing Tags ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/tags` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/tags?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of tags. Body (`application/json`): array of object `tag_response` A listing tag. - `id` (integer): The tag ID. - `name` (string): The tag name. - `description` (string, nullable): An optional description of the tag, or `null` when none was set. - `type` (string): The tag type, `UserTag` or `ImportedTag`. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "id": 0, "name": "string", "description": "string", "type": "string" } ] ``` ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Update user-defined tags for a listing. `PUT /listings/{listing_id}/tags` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-put-tags · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPutTags` · Tag: Listing Tags Adds (or overwrites) tags on a listing. If `overwrite` is false, provided tags are merged with existing tags. If `overwrite` is true, existing tags are replaced and all tags that are not in the list are deleted. A user with *restricted editor* access to a shared listing may read its tags but not change them. ## Request `PUT https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/tags` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Request body (`application/json`, required) - `names` (array of string, required): Array of tag names to add (or set if `overwrite` is true). - `overwrite` (boolean, default: `false`): If true, replaces all existing tags with the provided list. If false (default), merges with existing tags. ### Example request ```bash curl -X PUT 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/tags?channel=' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{ "names": [ "string" ] }' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The listing's updated tags. Body (`application/json`): array of object `tag_response` A listing tag. - `id` (integer): The tag ID. - `name` (string): The tag name. - `description` (string, nullable): An optional description of the tag, or `null` when none was set. - `type` (string): The tag type, `UserTag` or `ImportedTag`. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "id": 0, "name": "string", "description": "string", "type": "string" } ] ``` ### 401 API key authorization failed. ### 403 Listing authorization failed (including a restricted editor on a shared listing), or the API key is read-only and may not be used with PUT. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 409 Another request is already in progress for this listing. Retry after the concurrent request completes. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # List a listing's links to other booking platforms. `GET /listings/{listing_id}/ota_links` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-ota-links · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetOtaLinks` · Tag: Listing OTA Links Returns the listing's pages on other booking platforms and its direct booking website, each once with every source that links it, plus the listing's own page on the channel it is connected through when that has a URL. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/ota_links` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/ota_links?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The listing's links. Body (`application/json`): array of object `ota_link_response` A page on another booking platform, or the listing's direct booking website, with every source that links the listing to it. - `platform` (string, required, nullable, one of: `airbnb`, `booking_com`, `direct`, `vrbo`, `null`): The platform the page is on, as `PUT /listings/{listing_id}/ota_links` takes it. `null` only for the listing's own page on a channel that is none of these. - `platform_name` (string, required, nullable): Display name of the platform, e.g. `Airbnb`, `Vrbo`, `Booking.com` or `Direct Website`. - `external_id` (string, required, nullable): The platform's ID for the page, e.g. the Airbnb room ID. For a Booking.com page added by URL it is the country and slug from the URL (`US/cloud-nine`). For `direct`, the URL itself. - `url` (string, required, nullable): The page's URL. `null` when no source gave one and Wheelhouse has no data for the page, e.g. a Booking.com hotel ID from the PMS. - `title` (string, required, nullable): The page's title on that platform, or `null` when Wheelhouse has no data for the page. - `own_listing` (boolean, required): `true` for the listing's own page on the channel it is connected through. It is listed even when no source links it, with an empty `sources`. - `known` (boolean, required): Whether Wheelhouse has data for the page. A newly added page can take a while to become known. Always `true` for `direct`. - `page_active` (boolean, required, nullable): Whether the page is still listed on the platform, or `null` when unknown. - `sources` (array of object `ota_link_source`, required): Every source that links the listing to the page, oldest first. - Each item: One source that links the listing to the page. - `link_id` (integer, required, example: `48213`): Identifies this source's link. Pass it to `DELETE /listings/{listing_id}/ota_links/{link_id}`. - `source` (string, required, one of: `pms`, `user`, `bulk`): `pms` when the listing's PMS sent the link, `user` when a user added it in Wheelhouse or through this API, `bulk` when it came from a bulk upload. - `since` (string (date-time), required): When this source first linked the page. - `removable` (boolean, required): Whether `DELETE /listings/{listing_id}/ota_links/{link_id}` can remove this source's link. Links from the PMS cannot be removed. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "platform": "airbnb", "platform_name": "string", "external_id": "string", "url": "string", "title": "string", "own_listing": true, "known": true, "page_active": true, "sources": [ { "link_id": 48213, "source": "pms", "since": "2026-01-01T00:00:00Z", "removable": true } ] } ] ``` ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Add a link to another booking platform. `PUT /listings/{listing_id}/ota_links` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-put-ota-link · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPutOtaLink` · Tag: Listing OTA Links Links the listing to its page on another booking platform, or sets its direct booking website. The link is recorded as added by the API key's user, with source `user`. For `airbnb`, `vrbo` and `booking_com`, `url` must be a listing page on that platform. Wheelhouse may not have data for the page yet, in which case it is returned with `known: false` and filled in later. Adding a page a user already linked has no effect. Adding a page only the PMS or a bulk upload links adds a `user` source next to it, which keeps the page linked if the PMS stops sending it. For `direct`, `url` replaces the listing's direct booking website. A URL without a scheme gets `http://`. Requires owner, manager or editor access to the listing (restricted editors included); viewers get `403`. ## Request `PUT https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/ota_links` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Request body (`application/json`, required) - `platform` (string, required, one of: `airbnb`, `booking_com`, `direct`, `vrbo`): The platform the URL is on, or `direct` for the listing's direct booking website. - `url` (string, required, example: `https://www.airbnb.com/rooms/12345678`): The listing's page on that platform, or its direct booking website. ### Example request ```bash curl -X PUT 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/ota_links?channel=' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{ "platform": "airbnb", "url": "https://www.airbnb.com/rooms/12345678" }' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 All of the listing's links, including the one added. Body (`application/json`): array of object `ota_link_response` A page on another booking platform, or the listing's direct booking website, with every source that links the listing to it. - `platform` (string, required, nullable, one of: `airbnb`, `booking_com`, `direct`, `vrbo`, `null`): The platform the page is on, as `PUT /listings/{listing_id}/ota_links` takes it. `null` only for the listing's own page on a channel that is none of these. - `platform_name` (string, required, nullable): Display name of the platform, e.g. `Airbnb`, `Vrbo`, `Booking.com` or `Direct Website`. - `external_id` (string, required, nullable): The platform's ID for the page, e.g. the Airbnb room ID. For a Booking.com page added by URL it is the country and slug from the URL (`US/cloud-nine`). For `direct`, the URL itself. - `url` (string, required, nullable): The page's URL. `null` when no source gave one and Wheelhouse has no data for the page, e.g. a Booking.com hotel ID from the PMS. - `title` (string, required, nullable): The page's title on that platform, or `null` when Wheelhouse has no data for the page. - `own_listing` (boolean, required): `true` for the listing's own page on the channel it is connected through. It is listed even when no source links it, with an empty `sources`. - `known` (boolean, required): Whether Wheelhouse has data for the page. A newly added page can take a while to become known. Always `true` for `direct`. - `page_active` (boolean, required, nullable): Whether the page is still listed on the platform, or `null` when unknown. - `sources` (array of object `ota_link_source`, required): Every source that links the listing to the page, oldest first. - Each item: One source that links the listing to the page. - `link_id` (integer, required, example: `48213`): Identifies this source's link. Pass it to `DELETE /listings/{listing_id}/ota_links/{link_id}`. - `source` (string, required, one of: `pms`, `user`, `bulk`): `pms` when the listing's PMS sent the link, `user` when a user added it in Wheelhouse or through this API, `bulk` when it came from a bulk upload. - `since` (string (date-time), required): When this source first linked the page. - `removable` (boolean, required): Whether `DELETE /listings/{listing_id}/ota_links/{link_id}` can remove this source's link. Links from the PMS cannot be removed. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "platform": "airbnb", "platform_name": "string", "external_id": "string", "url": "string", "title": "string", "own_listing": true, "known": true, "page_active": true, "sources": [ { "link_id": 48213, "source": "pms", "since": "2026-01-01T00:00:00Z", "removable": true } ] } ] ``` ### 400 `platform` or `url` is missing, or `platform` is not one of the listed values. ### 401 API key authorization failed. ### 403 Listing authorization failed (including a viewer on a shared listing), or the API key is read-only and may not be used with PUT. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 422 The URL is not valid, or is not a listing page on the given platform. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Remove a link to another booking platform. `DELETE /listings/{listing_id}/ota_links/{link_id}` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-delete-ota-link · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmDeleteOtaLink` · Tag: Listing OTA Links Removes one source's link, named by the `link_id` in the link's `sources`. Only links with `removable: true` can be removed: links from the PMS change only in the PMS, so the page stays listed for as long as the PMS sends it. Only the named source's link ends: the page stays listed for as long as another source still links it, e.g. a `direct` website that was also added by a bulk upload. Requires owner, manager or editor access to the listing (restricted editors included); viewers get `403`. ## Request `DELETE https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/ota_links/{link_id}` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | | `link_id` | integer | yes | The `link_id` of one of the link's `sources`, from `GET /listings/{listing_id}/ota_links`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Example request ```bash curl -X DELETE 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/ota_links/{link_id}?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 204 The link was removed. ### 401 API key authorization failed. ### 403 Listing authorization failed (including a viewer on a shared listing), or the API key is read-only and may not be used with DELETE. ### 404 Listing not found, or the listing has no current link with that `link_id`, e.g. because it was already removed. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 422 The link comes from the listing's PMS and cannot be removed. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get system-defined flags for a listing. `GET /listings/{listing_id}/flags` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-flags · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetFlags` · Tag: Listing Flags Returns system-managed flags (as opposed to user-defined tags) associated with the listing. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/flags` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/flags?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of flags. Body (`application/json`): array of object - `category` (string, nullable, one of: `engine`, `info`, `performance`, `settings`): What the flag means for the listing's pricing: * `engine` — a setup that keeps Wheelhouse from pricing the listing as recommended, such as fixed prices, a minimum price above the base price, or a maximum price below the minimum. * `info` — context about the listing, such as being new to Wheelhouse or having its recommended base price lowered by its booking history. * `performance` — how the listing is booking, such as pacing ahead of or behind last year, or going unbooked. * `settings` — a pricing setting worth reviewing because it is missing, set unusually high or low, or combined with another setting so that their effects compound or cancel out. `null` for an older flag that Wheelhouse no longer raises. New flags can be added to any category, so decide how to treat a flag from its `category` rather than from a list of flag names. - `description` (string): An optional description of the flag. - `name` (string): The flag name. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "category": "engine", "description": "string", "name": "string" } ] ``` ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get the price calendar for a listing. `GET /listings/{listing_id}/price_calendar` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-price-calendar · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetPriceCalendar` · Tag: Calendar Returns the price calendar for a single listing. Each entry represents one stay date and includes the price, availability, and booking state. The data reflects the current state of the calendar as of the time of the request: - **Future dates** — the current price and availability as they stand right now. - **Past dates** — the state the date ended up in (e.g. whether it was booked, blocked, or left available, and the price that was in effect at the time). Defaults to today through the maximum calendar horizon (1.5 years) when `start_date` and `end_date` are omitted. The total date range may not exceed 3 years. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/price_calendar` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | | `start_date` | string (date) | no | First stay date to include (YYYY-MM-DD). Defaults to today. | | `end_date` | string (date) | no | Last stay date to include (YYYY-MM-DD). Defaults to the maximum calendar horizon (1.5 years from today). The total range (`start_date` to `end_date`) may not exceed 3 years. | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/price_calendar?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of calendar day entries ordered by stay date. Body (`application/json`): array of object `calendar_day_response` One stay date of a listing's price calendar. - `stay_date` (string (date), required): The stay date. - `price` (integer, required, nullable): The current observed price for this date, or `null` if none is recorded. For available dates this is the live price. For booked or blocked dates this is the price it booked at. Use `GET /listings/{listing_id}/last_posted_prices` to retrieve the last price posted to the channel. - `currency` (string, nullable): ISO 4217 currency code for the price, or `null` if none is recorded. - `is_available` (boolean, required): Whether the date is available for booking. State matrix: `is_available=true, is_booked=false` = available; `is_available=false, is_booked=true` = booked (confirmed reservation); `is_available=false, is_booked=false` = blocked (owner hold or similar). - `is_booked` (boolean, required): Whether the date has a confirmed booking. See `is_available` for the full state matrix. - `block_time` (string (date), nullable): The date and time (ISO-8601) when this night first became unavailable. Null for available nights. This field applies to both owner-blocked and guest-booked nights using the same column: - **Booked nights** (`is_booked=true`): the date the reservation was first detected as pending or accepted by Wheelhouse. - **Blocked nights** (`is_booked=false, is_available=false`): approximately the date the calendar sync recorded the block. The value is not the check-in date or booking date in the channel sense — it reflects when Wheelhouse's calendar ingestion first observed the night as unavailable. - `reservation_id` (string, nullable): The reservation ID associated with this date, if booked. This is the channel reservation ID (a string), or `null` when the night is not booked. - `unit_number` (integer, required): The unit number, 0 if the listing is single-unit. - `created_at` (string (date-time)): The date and time the data was created. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "stay_date": "2026-01-01", "price": 0, "currency": "string", "is_available": true, "is_booked": true, "block_time": "2026-01-01", "reservation_id": "string", "unit_number": 0, "created_at": "2026-01-01T00:00:00Z" } ] ``` ### 400 Date range exceeds the 3-year maximum. ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get the last posted price per stay date for a listing. `GET /listings/{listing_id}/last_posted_prices` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-last-posted-prices · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetLastPostedPrices` · Tag: Calendar Returns the last price posted to the channel for each stay date in the requested range. - **Available nights**: the most recently posted price for that date. - **Booked nights**: the last price posted at or before `block_time` (when the booking was recorded), reflecting the price that was live when the booking came in. Dates with no posting history return `null` for `last_posted_price`. Defaults to today through the maximum calendar horizon (1.5 years) when `start_date` and `end_date` are omitted. The total date range may not exceed 3 years. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/last_posted_prices` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | | `start_date` | string (date) | no | First stay date to include (YYYY-MM-DD). Defaults to today. | | `end_date` | string (date) | no | Last stay date to include (YYYY-MM-DD). Defaults to the maximum calendar horizon (1.5 years from today). The total range (`start_date` to `end_date`) may not exceed 3 years. | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/last_posted_prices?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of last-posted-price entries ordered by stay date. Body (`application/json`): array of object `last_posted_price_response` The last price posted to the channel for one stay date. - `stay_date` (string (date), required): The stay date. - `unit_number` (integer, required): The unit number, 0 if the listing is single-unit. - `last_posted_price` (integer, required, nullable): The last price posted to the channel for this stay date, or null if no price has been posted yet. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "stay_date": "2026-01-01", "unit_number": 0, "last_posted_price": 0 } ] ``` ### 400 Date range exceeds the 3-year maximum. ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get the base price recommendation history for a listing. `GET /listings/{listing_id}/base_price_history` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-base-price-history · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetBasePriceHistory` · Tag: Recommendations Returns a daily log of Wheelhouse base price recommendations and settings for the listing. Each record reflects the model's recommendation, any adjustments applied, and the effective base price used on that day. Defaults to the last 30 days when `start_date` and `end_date` are omitted. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/base_price_history` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | | `start_date` | string (date) | no | First model date to include (YYYY-MM-DD). Defaults to 30 days before `end_date`. | | `end_date` | string (date) | no | Last model date to include (YYYY-MM-DD). Defaults to today. | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/base_price_history?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of base price history entries ordered by model_date. Body (`application/json`): array of object - `model_date` (string (date)): The date this recommendation was computed. - `raw_recommendation` (integer, nullable): The raw model recommendation before any anchoring adjustments. - `recommendation` (integer, nullable): The anchored base price recommendation. - `adjustment` (number (float), nullable): Multiplicative adjustment factor applied by the user (e.g. 1.1 for +10%). - `fixed` (integer, nullable): The user-set fixed base price, if any. When present, this overrides the recommendation. - `anchor_price` (integer, nullable): The anchor price used to blend the model recommendation. - `anchor_weight` (number (float), nullable): The weight given to the anchor price (0–1). - `effective_base_price` (number (float), nullable): The base price that was actually in effect — equal to `fixed` when set, otherwise `recommendation * adjustment`. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "model_date": "2026-01-01", "raw_recommendation": 0, "recommendation": 0, "adjustment": 0, "fixed": 0, "anchor_price": 0, "anchor_weight": 0, "effective_base_price": 0 } ] ``` ### 400 `end_date` is before `start_date`. ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get the historical snapshots of a calendar day for a listing. `GET /listings/{listing_id}/calendar_day_history` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-calendar-day-history · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetCalendarDayHistory` · Tag: Calendar Returns a history of price postings and calendar state snapshots for a specific stay date. - **`posted_prices`** — each entry records a price that Wheelhouse posted to the channel for this date, in chronological order. - **`calendar_snapshots`** — historical snapshots of the calendar day's state (availability, price, booking, etc.) over time. Requires a Pro tier listing. Returns `402` if the feature is not available. The maximum lookback window is 180 days. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/calendar_day_history` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | | `stay_date` | string (date) | yes | The stay date to retrieve history for (YYYY-MM-DD). | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/calendar_day_history?channel=&stay_date=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Historical price postings and calendar snapshots for the requested stay date. Body (`application/json`): object - `stay_date` (string (date)): The stay date the history is for. - `posted_prices` (array of object): Chronological list of prices posted to the channel for this stay date. - `posted_at` (string (date-time)): When the price was posted. - `posted_price` (integer): The price posted at that time in the listing currency. - `calendar_snapshots` (array of object): Historical snapshots of the calendar day's state over time. - `price` (integer, nullable): The observed price for this date, or `null` if none is recorded. - `currency` (string, nullable): ISO 4217 currency code for the price, or `null` if none is recorded. - `is_available` (boolean): Whether the date is available for booking. State matrix: `is_available=true, is_booked=false` = available; `is_available=false, is_booked=true` = booked (confirmed reservation); `is_available=false, is_booked=false` = blocked (owner hold or similar). - `is_booked` (boolean): Whether the date has a confirmed booking. See `is_available` for the full state matrix. - `block_time` (string (date), nullable): The date and time (ISO-8601) when this night first became unavailable. Null for available nights. This field applies to both owner-blocked and guest-booked nights using the same column: - **Booked nights** (`is_booked=true`): the date the reservation was first detected as pending or accepted by Wheelhouse. - **Blocked nights** (`is_booked=false, is_available=false`): approximately the date the calendar sync recorded the block. The value is not the check-in date or booking date in the channel sense — it reflects when Wheelhouse's calendar ingestion first observed the night as unavailable. - `reservation_id` (string, nullable): The reservation ID associated with this date, if booked. This is the channel reservation ID (a string), or `null` when the night is not booked. - `unit_number` (integer): The unit number, 0 if the listing is single-unit. - `created_at` (string (date-time)): When this snapshot was recorded. Example shape (generated from the schema; placeholder values, not a real response): ```json { "stay_date": "2026-01-01", "posted_prices": [ { "posted_at": "2026-01-01T00:00:00Z", "posted_price": 0 } ], "calendar_snapshots": [ { "price": 0, "currency": "string", "is_available": true, "is_booked": true, "block_time": "2026-01-01", "reservation_id": "string", "unit_number": 0, "created_at": "2026-01-01T00:00:00Z" } ] } ``` ### 400 `stay_date` is missing or beyond the historical lookback limit. ### 401 API key authorization failed. ### 402 The listing does not have access to historical calendar data. Upgrade the plan to unlock this feature. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get the estimated fee multiplier per stay date for a listing. `GET /listings/{listing_id}/fee_impact_calendar` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-fee-impact-calendar · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetFeeImpactCalendar` · Tag: Calendar Returns a per-date fee multiplier derived from the listing's `fee_adjustments` preference (`total_fee_percentage`, see `GET /preferences/{listing_id}`). Multiply any nightly price by `fee_multiplier` to obtain the fee-inclusive price, for example before comparing it with neighborhood prices, which include fees. When no fee adjustment is in effect, `fee_multiplier` is `1.0`. Pass `fallback=estimate` to have it estimated instead from the fees on the listing's recent reservations, the same estimate `auto_update` applies. Each entry's `source` says where the multiplier came from. Currently the multiplier is uniform across all dates. The per-date shape is intentional — future releases will allow fee variation by date range or season, and the response format will remain compatible. Defaults to today through the maximum calendar horizon (1.5 years) when `start_date` and `end_date` are omitted. The total date range may not exceed 3 years. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/fee_impact_calendar` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | | `start_date` | string (date) | no | First stay date to include (YYYY-MM-DD). Defaults to today. | | `end_date` | string (date) | no | Last stay date to include (YYYY-MM-DD). Defaults to the maximum calendar horizon (1.5 years from today). The total range (`start_date` to `end_date`) may not exceed 3 years. | | `fallback` | string | no | What to report when the listing has no fee adjustment in effect. `none` (the default) reports `1.0`. `estimate` estimates the multiplier from the fees on the listing's recent reservations, and still reports `1.0` when none of them carries fee data. (one of: `none`, `estimate`, default: `none`) | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/fee_impact_calendar?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of fee multiplier entries ordered by stay date. Body (`application/json`): array of object - `stay_date` (string (date)): The stay date. - `fee_multiplier` (number): Multiply a nightly price by this value to get the fee-inclusive price. `1.0` means no fee is applied; `1.15` means a 15% estimated fee. - `source` (string, one of: `setting`, `estimate`, `none`): Where `fee_multiplier` came from: `setting` is the listing's fee adjustment, `estimate` is estimated from the listing's recent reservations (only with `fallback=estimate`), and `none` means neither applies, so the multiplier is `1.0`. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "stay_date": "2026-01-01", "fee_multiplier": 0, "source": "setting" } ] ``` ### 400 Date range exceeds the 3-year maximum, or `fallback` is not one of the listed values. ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get the minimum stay calendar for a listing. `GET /listings/{listing_id}/min_stay_calendar` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-min-stay-calendar · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetMinStayCalendar` · Tag: Calendar Returns the per-date minimum stay derived from the listing's minimum stay rules for a given date range. One entry is returned for each date in the range. A `null` value for `min_stay` means no specific rule covers that date. Defaults to today through the maximum calendar horizon (1.5 years) when `start_date` and `end_date` are omitted. The total date range may not exceed 3 years. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/min_stay_calendar` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | | `start_date` | string (date) | no | First stay date to include (YYYY-MM-DD). Defaults to today. | | `end_date` | string (date) | no | Last stay date to include (YYYY-MM-DD). Defaults to the maximum calendar horizon (1.5 years from today). The total range (`start_date` to `end_date`) may not exceed 3 years. | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/min_stay_calendar?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of minimum stay entries ordered by stay date. Body (`application/json`): array of object `min_stay_day_response` The minimum stay in effect for one stay date. - `stay_date` (string (date), required): The stay date. - `min_stay` (integer, required, nullable): The minimum stay in nights for this date, or null if no specific rule covers that date. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "stay_date": "2026-01-01", "min_stay": 0 } ] ``` ### 400 Date range exceeds the 3-year maximum. ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # List markets for a country. `GET /market_report` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-market-report · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetMarketReport` · Tag: Market Reports Returns all active Wheelhouse markets which the authenticated user has at least one Pro tier listing in for the given country. Each market includes the postal codes it covers. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/market_report` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `country_code` | string | yes | ISO-3166 2-letter country code (e.g. `US`, `GB`). | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/market_report?country_code=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of markets. Body (`application/json`): array of object - `market_id` (integer): The Wheelhouse internal market ID. - `market_name` (string): The display name of the market. - `postal_codes` (array of object): Postal codes covered by this market. - `code` (string): The postal code. - `latlong` (string): Latitude/longitude of the postal code centroid. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "market_id": 0, "market_name": "string", "postal_codes": [ { "code": "string", "latlong": "string" } ] } ] ``` ### 401 API key authorization failed. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # List portfolio segments. `GET /segments` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-segments · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetSegments` · Tag: Segments Returns all portfolio segments for the authenticated user. Segments are used in the Wheelhouse UI to group listings by filter criteria; this endpoint provides read-only access to the segment list. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/segments` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/segments' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of portfolio segments. Body (`application/json`): array of object `portfolio_segment_response` A portfolio segment. - `id` (integer, required): The Wheelhouse internal segment ID. - `name` (string): The segment name. - `description` (string, nullable): An optional description of the segment. - `filter_backend` (object `filter_backend_object`): A map that controls which listings belong to a segment. Keys are listing attribute paths with optional operator suffixes; values are the match criteria. All entries are ANDed — a listing must satisfy every condition to be included. **Structure**: `{ "key[_suffix]": value, ... }` --- #### Boolean parameters Accept `true` or `false`. No operator suffixes. | Key | Description | |---|---| | `is_live` | Listing is live on its channel | | `user_removed` | Listing has been marked removed by the user | | `listings.is_active` | Listing is active in Wheelhouse | | `listing_preferences.automatic_rate_posting_enabled` | Automatic rate posting is enabled | | `listing_views.in_market` | Listing is in a Wheelhouse-covered market | --- #### Numeric range parameters Each base key supports six operator suffixes: `key` (=), `key_ne` (≠), `key_lt` (<), `key_gt` (>), `key_lte` (≤), `key_gte` (≥). Values are integers (floats accepted for `bathrooms`). | Key | Description | |---|---| | `bedrooms` | Number of bedrooms | | `bathrooms` | Number of bathrooms | | `sleeps` | Maximum guest capacity | | `beds` | Number of beds | | `guests_included` | Guests included in the base rate | | `number_of_units` | Number of units at the property | | `review_count` | Total guest reviews | | `listings.minimum_stay` | Default minimum stay in nights | | `listings.cleaning_fee` | Cleaning fee amount | | `listings.security_deposit` | Security deposit amount | | `listing_preferences.base_price` | Wheelhouse base price | | `listing_preferences.weekly_discount` | Weekly discount percentage | | `listing_preferences.monthly_discount` | Monthly discount percentage | | `listing_views.number_of_editors` | Co-host editor count | | `listing_views.number_of_restricted_editors` | Restricted editor count | | `listing_views.number_of_viewers` | Viewer-level co-host count | | `listing_views.minimum_stay_rules_count` | Minimum-stay rules configured | | `listing_views.minimum_price_rules_count` | Minimum-price rules configured | Performance stats use scoped keys of the form `listing_stats_rolling:metric:{metric}:{window}` with the same six operator suffixes as other numeric ranges. Windows are `next_N` (forward-looking) and `past_N` (trailing) for N in 7, 14, 21, 30, 60, 90, 180, 365. Metrics include `revenue`, `occupancy`, and `booking_count`. Example: `"listing_stats_rolling:metric:revenue:next_30_gte": 5000`. The most recent booking date remains `listing_stats.last_booked_at` under date ranges. --- #### Enumeration parameters Three operator suffixes: `key` (=), `key_ne` (≠), `key_enum` (returns the distinct values present on the authenticated user's listings — useful for discovering valid values). | Key | Value type | Notes | |---|---|---| | `source` | string | Channel short ID: `"A"` (Airbnb), `"V"` (Vrbo), `"B"` (Booking.com) | | `market_id` | integer | Wheelhouse market ID | | `country_code` | string | ISO 3166-1 alpha-2 (e.g. `"US"`, `"GB"`) | | `room_type` | string | As reported by the channel (e.g. `"Entire place"`) | | `channel_account_id` | integer | Wheelhouse channel connection ID | | `listings.currency` | string | ISO 4217 currency code (e.g. `"USD"`, `"EUR"`) | | `listings.price_model_id` | integer | Active price model ID | | `channel_accounts.status` | string | `"active"`, `"failed"`, `"disabled"`, `"pending"`, `"empty"`, `"invalid_auth"` | | `charge_bee_items.id` | string | Billing plan (e.g. `"Free"`, `"Flex_Plan"`, `"Flat_Plan"`) | | `managed_listings.level` | string | Co-host level: `"editor"`, `"restricted_editor"`, `"viewer"` | | `listings.operating_user_id` | integer | User ID of the operating account | --- #### String match parameters Two operator suffixes: `key` (contains), `key_not` (does not contain). Case-insensitive substring match. Comma-separate multiple values for OR logic: `"listings.title": "Beach,Ocean"` matches titles containing *either* word. | Key | Description | |---|---| | `listings.title` | Listing title | | `listing_views.display_name` | Display name | | `listing_views.display_nickname` | Display nickname | | `source_address` | Source address | --- #### Tag parameters Filter by Wheelhouse tag IDs (integers). Four operator suffixes: | Suffix | Match logic | |---|---| | `tags.id` | Has **any** of the listed tag IDs (OR) | | `tags.id_ne` | Has **none** of the listed tag IDs | | `tags.id_and` | Has **all** of the listed tag IDs (AND) | | `tags.id_and_ne` | Does **not** have all of the listed tag IDs | To combine multiple independent tag conditions in one object, append any unique identifier after the suffix — the system strips it before evaluating. Example: `"tags.id_pool": [12]` and `"tags.id_certified_and": [5, 7]` are treated as two separate filters on the same object. --- #### Date range parameters Six operator suffixes, same as numeric range. Values are either an ISO 8601 date string (`"2025-01-01"`) or an integer for a rolling window relative to today (`30` means "30 days ago"). | Key | Description | |---|---| | `listings.created_at` | When the listing was created in Wheelhouse | | `listing_stats.last_booked_at` | Date of the listing's most recent booking | --- #### Membership parameters | Key | Value type | Description | |---|---|---| | `listings.id_in` | integer[] | Include only listings with these internal IDs | | `listings.id_not_in` | integer[] | Exclude listings with these internal IDs | | `listings.source_not_in` | string[] | Exclude listings from these channels | --- #### Geographic parameter | Key | Value format | Description | |---|---|---| | `latlong_distance_from_lte` | `"latitude,longitude,meters"` | Listings within the radius of the given coordinates | --- **Example** ```json { "is_live": true, "bedrooms_gte": 2, "source": "A", "listings.title": "Beach,Ocean", "tags.id_pool": [12], "listings.created_at_gte": "2025-01-01", "listings.id_in": [101, 102, 103] } ``` - `is_default` (boolean): Whether this is the default segment. - `created_at` (string (date-time), required): When the segment was created (ISO-8601). - `updated_at` (string (date-time), required): When the segment was last updated (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "id": 0, "name": "string", "description": "string", "filter_backend": {}, "is_default": true, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ] ``` ### 401 API key authorization failed. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Create a portfolio segment. `POST /segments` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-post-segments · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPostSegments` · Tag: Segments Creates a new portfolio segment owned by the authenticated user. ## Request `POST https://api.usewheelhouse.com/ss_api/v1/segments` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Request body (`application/json`, required) - `name` (string, required): Name of the segment. - `description` (string): Optional description. - `filter_backend` (object `filter_backend_object`): A map that controls which listings belong to a segment. Keys are listing attribute paths with optional operator suffixes; values are the match criteria. All entries are ANDed — a listing must satisfy every condition to be included. **Structure**: `{ "key[_suffix]": value, ... }` --- #### Boolean parameters Accept `true` or `false`. No operator suffixes. | Key | Description | |---|---| | `is_live` | Listing is live on its channel | | `user_removed` | Listing has been marked removed by the user | | `listings.is_active` | Listing is active in Wheelhouse | | `listing_preferences.automatic_rate_posting_enabled` | Automatic rate posting is enabled | | `listing_views.in_market` | Listing is in a Wheelhouse-covered market | --- #### Numeric range parameters Each base key supports six operator suffixes: `key` (=), `key_ne` (≠), `key_lt` (<), `key_gt` (>), `key_lte` (≤), `key_gte` (≥). Values are integers (floats accepted for `bathrooms`). | Key | Description | |---|---| | `bedrooms` | Number of bedrooms | | `bathrooms` | Number of bathrooms | | `sleeps` | Maximum guest capacity | | `beds` | Number of beds | | `guests_included` | Guests included in the base rate | | `number_of_units` | Number of units at the property | | `review_count` | Total guest reviews | | `listings.minimum_stay` | Default minimum stay in nights | | `listings.cleaning_fee` | Cleaning fee amount | | `listings.security_deposit` | Security deposit amount | | `listing_preferences.base_price` | Wheelhouse base price | | `listing_preferences.weekly_discount` | Weekly discount percentage | | `listing_preferences.monthly_discount` | Monthly discount percentage | | `listing_views.number_of_editors` | Co-host editor count | | `listing_views.number_of_restricted_editors` | Restricted editor count | | `listing_views.number_of_viewers` | Viewer-level co-host count | | `listing_views.minimum_stay_rules_count` | Minimum-stay rules configured | | `listing_views.minimum_price_rules_count` | Minimum-price rules configured | Performance stats use scoped keys of the form `listing_stats_rolling:metric:{metric}:{window}` with the same six operator suffixes as other numeric ranges. Windows are `next_N` (forward-looking) and `past_N` (trailing) for N in 7, 14, 21, 30, 60, 90, 180, 365. Metrics include `revenue`, `occupancy`, and `booking_count`. Example: `"listing_stats_rolling:metric:revenue:next_30_gte": 5000`. The most recent booking date remains `listing_stats.last_booked_at` under date ranges. --- #### Enumeration parameters Three operator suffixes: `key` (=), `key_ne` (≠), `key_enum` (returns the distinct values present on the authenticated user's listings — useful for discovering valid values). | Key | Value type | Notes | |---|---|---| | `source` | string | Channel short ID: `"A"` (Airbnb), `"V"` (Vrbo), `"B"` (Booking.com) | | `market_id` | integer | Wheelhouse market ID | | `country_code` | string | ISO 3166-1 alpha-2 (e.g. `"US"`, `"GB"`) | | `room_type` | string | As reported by the channel (e.g. `"Entire place"`) | | `channel_account_id` | integer | Wheelhouse channel connection ID | | `listings.currency` | string | ISO 4217 currency code (e.g. `"USD"`, `"EUR"`) | | `listings.price_model_id` | integer | Active price model ID | | `channel_accounts.status` | string | `"active"`, `"failed"`, `"disabled"`, `"pending"`, `"empty"`, `"invalid_auth"` | | `charge_bee_items.id` | string | Billing plan (e.g. `"Free"`, `"Flex_Plan"`, `"Flat_Plan"`) | | `managed_listings.level` | string | Co-host level: `"editor"`, `"restricted_editor"`, `"viewer"` | | `listings.operating_user_id` | integer | User ID of the operating account | --- #### String match parameters Two operator suffixes: `key` (contains), `key_not` (does not contain). Case-insensitive substring match. Comma-separate multiple values for OR logic: `"listings.title": "Beach,Ocean"` matches titles containing *either* word. | Key | Description | |---|---| | `listings.title` | Listing title | | `listing_views.display_name` | Display name | | `listing_views.display_nickname` | Display nickname | | `source_address` | Source address | --- #### Tag parameters Filter by Wheelhouse tag IDs (integers). Four operator suffixes: | Suffix | Match logic | |---|---| | `tags.id` | Has **any** of the listed tag IDs (OR) | | `tags.id_ne` | Has **none** of the listed tag IDs | | `tags.id_and` | Has **all** of the listed tag IDs (AND) | | `tags.id_and_ne` | Does **not** have all of the listed tag IDs | To combine multiple independent tag conditions in one object, append any unique identifier after the suffix — the system strips it before evaluating. Example: `"tags.id_pool": [12]` and `"tags.id_certified_and": [5, 7]` are treated as two separate filters on the same object. --- #### Date range parameters Six operator suffixes, same as numeric range. Values are either an ISO 8601 date string (`"2025-01-01"`) or an integer for a rolling window relative to today (`30` means "30 days ago"). | Key | Description | |---|---| | `listings.created_at` | When the listing was created in Wheelhouse | | `listing_stats.last_booked_at` | Date of the listing's most recent booking | --- #### Membership parameters | Key | Value type | Description | |---|---|---| | `listings.id_in` | integer[] | Include only listings with these internal IDs | | `listings.id_not_in` | integer[] | Exclude listings with these internal IDs | | `listings.source_not_in` | string[] | Exclude listings from these channels | --- #### Geographic parameter | Key | Value format | Description | |---|---|---| | `latlong_distance_from_lte` | `"latitude,longitude,meters"` | Listings within the radius of the given coordinates | --- **Example** ```json { "is_live": true, "bedrooms_gte": 2, "source": "A", "listings.title": "Beach,Ocean", "tags.id_pool": [12], "listings.created_at_gte": "2025-01-01", "listings.id_in": [101, 102, 103] } ``` - `is_default` (boolean): Set as the default segment. Any existing default is cleared. ### Example request ```bash curl -X POST 'https://api.usewheelhouse.com/ss_api/v1/segments' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{ "name": "string" }' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 201 The newly created portfolio segment. Body (`application/json`): object `portfolio_segment_response` A portfolio segment. - `id` (integer, required): The Wheelhouse internal segment ID. - `name` (string): The segment name. - `description` (string, nullable): An optional description of the segment. - `filter_backend` (object `filter_backend_object`): A map that controls which listings belong to a segment. Keys are listing attribute paths with optional operator suffixes; values are the match criteria. All entries are ANDed — a listing must satisfy every condition to be included. **Structure**: `{ "key[_suffix]": value, ... }` --- #### Boolean parameters Accept `true` or `false`. No operator suffixes. | Key | Description | |---|---| | `is_live` | Listing is live on its channel | | `user_removed` | Listing has been marked removed by the user | | `listings.is_active` | Listing is active in Wheelhouse | | `listing_preferences.automatic_rate_posting_enabled` | Automatic rate posting is enabled | | `listing_views.in_market` | Listing is in a Wheelhouse-covered market | --- #### Numeric range parameters Each base key supports six operator suffixes: `key` (=), `key_ne` (≠), `key_lt` (<), `key_gt` (>), `key_lte` (≤), `key_gte` (≥). Values are integers (floats accepted for `bathrooms`). | Key | Description | |---|---| | `bedrooms` | Number of bedrooms | | `bathrooms` | Number of bathrooms | | `sleeps` | Maximum guest capacity | | `beds` | Number of beds | | `guests_included` | Guests included in the base rate | | `number_of_units` | Number of units at the property | | `review_count` | Total guest reviews | | `listings.minimum_stay` | Default minimum stay in nights | | `listings.cleaning_fee` | Cleaning fee amount | | `listings.security_deposit` | Security deposit amount | | `listing_preferences.base_price` | Wheelhouse base price | | `listing_preferences.weekly_discount` | Weekly discount percentage | | `listing_preferences.monthly_discount` | Monthly discount percentage | | `listing_views.number_of_editors` | Co-host editor count | | `listing_views.number_of_restricted_editors` | Restricted editor count | | `listing_views.number_of_viewers` | Viewer-level co-host count | | `listing_views.minimum_stay_rules_count` | Minimum-stay rules configured | | `listing_views.minimum_price_rules_count` | Minimum-price rules configured | Performance stats use scoped keys of the form `listing_stats_rolling:metric:{metric}:{window}` with the same six operator suffixes as other numeric ranges. Windows are `next_N` (forward-looking) and `past_N` (trailing) for N in 7, 14, 21, 30, 60, 90, 180, 365. Metrics include `revenue`, `occupancy`, and `booking_count`. Example: `"listing_stats_rolling:metric:revenue:next_30_gte": 5000`. The most recent booking date remains `listing_stats.last_booked_at` under date ranges. --- #### Enumeration parameters Three operator suffixes: `key` (=), `key_ne` (≠), `key_enum` (returns the distinct values present on the authenticated user's listings — useful for discovering valid values). | Key | Value type | Notes | |---|---|---| | `source` | string | Channel short ID: `"A"` (Airbnb), `"V"` (Vrbo), `"B"` (Booking.com) | | `market_id` | integer | Wheelhouse market ID | | `country_code` | string | ISO 3166-1 alpha-2 (e.g. `"US"`, `"GB"`) | | `room_type` | string | As reported by the channel (e.g. `"Entire place"`) | | `channel_account_id` | integer | Wheelhouse channel connection ID | | `listings.currency` | string | ISO 4217 currency code (e.g. `"USD"`, `"EUR"`) | | `listings.price_model_id` | integer | Active price model ID | | `channel_accounts.status` | string | `"active"`, `"failed"`, `"disabled"`, `"pending"`, `"empty"`, `"invalid_auth"` | | `charge_bee_items.id` | string | Billing plan (e.g. `"Free"`, `"Flex_Plan"`, `"Flat_Plan"`) | | `managed_listings.level` | string | Co-host level: `"editor"`, `"restricted_editor"`, `"viewer"` | | `listings.operating_user_id` | integer | User ID of the operating account | --- #### String match parameters Two operator suffixes: `key` (contains), `key_not` (does not contain). Case-insensitive substring match. Comma-separate multiple values for OR logic: `"listings.title": "Beach,Ocean"` matches titles containing *either* word. | Key | Description | |---|---| | `listings.title` | Listing title | | `listing_views.display_name` | Display name | | `listing_views.display_nickname` | Display nickname | | `source_address` | Source address | --- #### Tag parameters Filter by Wheelhouse tag IDs (integers). Four operator suffixes: | Suffix | Match logic | |---|---| | `tags.id` | Has **any** of the listed tag IDs (OR) | | `tags.id_ne` | Has **none** of the listed tag IDs | | `tags.id_and` | Has **all** of the listed tag IDs (AND) | | `tags.id_and_ne` | Does **not** have all of the listed tag IDs | To combine multiple independent tag conditions in one object, append any unique identifier after the suffix — the system strips it before evaluating. Example: `"tags.id_pool": [12]` and `"tags.id_certified_and": [5, 7]` are treated as two separate filters on the same object. --- #### Date range parameters Six operator suffixes, same as numeric range. Values are either an ISO 8601 date string (`"2025-01-01"`) or an integer for a rolling window relative to today (`30` means "30 days ago"). | Key | Description | |---|---| | `listings.created_at` | When the listing was created in Wheelhouse | | `listing_stats.last_booked_at` | Date of the listing's most recent booking | --- #### Membership parameters | Key | Value type | Description | |---|---|---| | `listings.id_in` | integer[] | Include only listings with these internal IDs | | `listings.id_not_in` | integer[] | Exclude listings with these internal IDs | | `listings.source_not_in` | string[] | Exclude listings from these channels | --- #### Geographic parameter | Key | Value format | Description | |---|---|---| | `latlong_distance_from_lte` | `"latitude,longitude,meters"` | Listings within the radius of the given coordinates | --- **Example** ```json { "is_live": true, "bedrooms_gte": 2, "source": "A", "listings.title": "Beach,Ocean", "tags.id_pool": [12], "listings.created_at_gte": "2025-01-01", "listings.id_in": [101, 102, 103] } ``` - `is_default` (boolean): Whether this is the default segment. - `created_at` (string (date-time), required): When the segment was created (ISO-8601). - `updated_at` (string (date-time), required): When the segment was last updated (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json { "id": 0, "name": "string", "description": "string", "filter_backend": {}, "is_default": true, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ``` ### 400 Request body is invalid (e.g. `name` is missing). ### 401 API key authorization failed. ### 403 Read-only API key cannot create segments. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Update a portfolio segment. `PUT /segments/{segment_id}` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-put-segment · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPutSegment` · Tag: Segments Updates the name, description, and/or default status of an existing portfolio segment. All fields are optional; omitted fields are left unchanged. ## Request `PUT https://api.usewheelhouse.com/ss_api/v1/segments/{segment_id}` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `segment_id` | integer | yes | The Wheelhouse internal segment ID. | ### Request body (`application/json`, required) - `name` (string): New name for the segment. - `description` (string): New description for the segment. Omit to leave unchanged. - `filter_backend` (object `filter_backend_object`): A map that controls which listings belong to a segment. Keys are listing attribute paths with optional operator suffixes; values are the match criteria. All entries are ANDed — a listing must satisfy every condition to be included. **Structure**: `{ "key[_suffix]": value, ... }` --- #### Boolean parameters Accept `true` or `false`. No operator suffixes. | Key | Description | |---|---| | `is_live` | Listing is live on its channel | | `user_removed` | Listing has been marked removed by the user | | `listings.is_active` | Listing is active in Wheelhouse | | `listing_preferences.automatic_rate_posting_enabled` | Automatic rate posting is enabled | | `listing_views.in_market` | Listing is in a Wheelhouse-covered market | --- #### Numeric range parameters Each base key supports six operator suffixes: `key` (=), `key_ne` (≠), `key_lt` (<), `key_gt` (>), `key_lte` (≤), `key_gte` (≥). Values are integers (floats accepted for `bathrooms`). | Key | Description | |---|---| | `bedrooms` | Number of bedrooms | | `bathrooms` | Number of bathrooms | | `sleeps` | Maximum guest capacity | | `beds` | Number of beds | | `guests_included` | Guests included in the base rate | | `number_of_units` | Number of units at the property | | `review_count` | Total guest reviews | | `listings.minimum_stay` | Default minimum stay in nights | | `listings.cleaning_fee` | Cleaning fee amount | | `listings.security_deposit` | Security deposit amount | | `listing_preferences.base_price` | Wheelhouse base price | | `listing_preferences.weekly_discount` | Weekly discount percentage | | `listing_preferences.monthly_discount` | Monthly discount percentage | | `listing_views.number_of_editors` | Co-host editor count | | `listing_views.number_of_restricted_editors` | Restricted editor count | | `listing_views.number_of_viewers` | Viewer-level co-host count | | `listing_views.minimum_stay_rules_count` | Minimum-stay rules configured | | `listing_views.minimum_price_rules_count` | Minimum-price rules configured | Performance stats use scoped keys of the form `listing_stats_rolling:metric:{metric}:{window}` with the same six operator suffixes as other numeric ranges. Windows are `next_N` (forward-looking) and `past_N` (trailing) for N in 7, 14, 21, 30, 60, 90, 180, 365. Metrics include `revenue`, `occupancy`, and `booking_count`. Example: `"listing_stats_rolling:metric:revenue:next_30_gte": 5000`. The most recent booking date remains `listing_stats.last_booked_at` under date ranges. --- #### Enumeration parameters Three operator suffixes: `key` (=), `key_ne` (≠), `key_enum` (returns the distinct values present on the authenticated user's listings — useful for discovering valid values). | Key | Value type | Notes | |---|---|---| | `source` | string | Channel short ID: `"A"` (Airbnb), `"V"` (Vrbo), `"B"` (Booking.com) | | `market_id` | integer | Wheelhouse market ID | | `country_code` | string | ISO 3166-1 alpha-2 (e.g. `"US"`, `"GB"`) | | `room_type` | string | As reported by the channel (e.g. `"Entire place"`) | | `channel_account_id` | integer | Wheelhouse channel connection ID | | `listings.currency` | string | ISO 4217 currency code (e.g. `"USD"`, `"EUR"`) | | `listings.price_model_id` | integer | Active price model ID | | `channel_accounts.status` | string | `"active"`, `"failed"`, `"disabled"`, `"pending"`, `"empty"`, `"invalid_auth"` | | `charge_bee_items.id` | string | Billing plan (e.g. `"Free"`, `"Flex_Plan"`, `"Flat_Plan"`) | | `managed_listings.level` | string | Co-host level: `"editor"`, `"restricted_editor"`, `"viewer"` | | `listings.operating_user_id` | integer | User ID of the operating account | --- #### String match parameters Two operator suffixes: `key` (contains), `key_not` (does not contain). Case-insensitive substring match. Comma-separate multiple values for OR logic: `"listings.title": "Beach,Ocean"` matches titles containing *either* word. | Key | Description | |---|---| | `listings.title` | Listing title | | `listing_views.display_name` | Display name | | `listing_views.display_nickname` | Display nickname | | `source_address` | Source address | --- #### Tag parameters Filter by Wheelhouse tag IDs (integers). Four operator suffixes: | Suffix | Match logic | |---|---| | `tags.id` | Has **any** of the listed tag IDs (OR) | | `tags.id_ne` | Has **none** of the listed tag IDs | | `tags.id_and` | Has **all** of the listed tag IDs (AND) | | `tags.id_and_ne` | Does **not** have all of the listed tag IDs | To combine multiple independent tag conditions in one object, append any unique identifier after the suffix — the system strips it before evaluating. Example: `"tags.id_pool": [12]` and `"tags.id_certified_and": [5, 7]` are treated as two separate filters on the same object. --- #### Date range parameters Six operator suffixes, same as numeric range. Values are either an ISO 8601 date string (`"2025-01-01"`) or an integer for a rolling window relative to today (`30` means "30 days ago"). | Key | Description | |---|---| | `listings.created_at` | When the listing was created in Wheelhouse | | `listing_stats.last_booked_at` | Date of the listing's most recent booking | --- #### Membership parameters | Key | Value type | Description | |---|---|---| | `listings.id_in` | integer[] | Include only listings with these internal IDs | | `listings.id_not_in` | integer[] | Exclude listings with these internal IDs | | `listings.source_not_in` | string[] | Exclude listings from these channels | --- #### Geographic parameter | Key | Value format | Description | |---|---|---| | `latlong_distance_from_lte` | `"latitude,longitude,meters"` | Listings within the radius of the given coordinates | --- **Example** ```json { "is_live": true, "bedrooms_gte": 2, "source": "A", "listings.title": "Beach,Ocean", "tags.id_pool": [12], "listings.created_at_gte": "2025-01-01", "listings.id_in": [101, 102, 103] } ``` - `is_default` (boolean): Set as the default segment. Any existing default is cleared. ### Example request ```bash curl -X PUT 'https://api.usewheelhouse.com/ss_api/v1/segments/{segment_id}' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{}' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The updated portfolio segment. Body (`application/json`): object `portfolio_segment_response` A portfolio segment. - `id` (integer, required): The Wheelhouse internal segment ID. - `name` (string): The segment name. - `description` (string, nullable): An optional description of the segment. - `filter_backend` (object `filter_backend_object`): A map that controls which listings belong to a segment. Keys are listing attribute paths with optional operator suffixes; values are the match criteria. All entries are ANDed — a listing must satisfy every condition to be included. **Structure**: `{ "key[_suffix]": value, ... }` --- #### Boolean parameters Accept `true` or `false`. No operator suffixes. | Key | Description | |---|---| | `is_live` | Listing is live on its channel | | `user_removed` | Listing has been marked removed by the user | | `listings.is_active` | Listing is active in Wheelhouse | | `listing_preferences.automatic_rate_posting_enabled` | Automatic rate posting is enabled | | `listing_views.in_market` | Listing is in a Wheelhouse-covered market | --- #### Numeric range parameters Each base key supports six operator suffixes: `key` (=), `key_ne` (≠), `key_lt` (<), `key_gt` (>), `key_lte` (≤), `key_gte` (≥). Values are integers (floats accepted for `bathrooms`). | Key | Description | |---|---| | `bedrooms` | Number of bedrooms | | `bathrooms` | Number of bathrooms | | `sleeps` | Maximum guest capacity | | `beds` | Number of beds | | `guests_included` | Guests included in the base rate | | `number_of_units` | Number of units at the property | | `review_count` | Total guest reviews | | `listings.minimum_stay` | Default minimum stay in nights | | `listings.cleaning_fee` | Cleaning fee amount | | `listings.security_deposit` | Security deposit amount | | `listing_preferences.base_price` | Wheelhouse base price | | `listing_preferences.weekly_discount` | Weekly discount percentage | | `listing_preferences.monthly_discount` | Monthly discount percentage | | `listing_views.number_of_editors` | Co-host editor count | | `listing_views.number_of_restricted_editors` | Restricted editor count | | `listing_views.number_of_viewers` | Viewer-level co-host count | | `listing_views.minimum_stay_rules_count` | Minimum-stay rules configured | | `listing_views.minimum_price_rules_count` | Minimum-price rules configured | Performance stats use scoped keys of the form `listing_stats_rolling:metric:{metric}:{window}` with the same six operator suffixes as other numeric ranges. Windows are `next_N` (forward-looking) and `past_N` (trailing) for N in 7, 14, 21, 30, 60, 90, 180, 365. Metrics include `revenue`, `occupancy`, and `booking_count`. Example: `"listing_stats_rolling:metric:revenue:next_30_gte": 5000`. The most recent booking date remains `listing_stats.last_booked_at` under date ranges. --- #### Enumeration parameters Three operator suffixes: `key` (=), `key_ne` (≠), `key_enum` (returns the distinct values present on the authenticated user's listings — useful for discovering valid values). | Key | Value type | Notes | |---|---|---| | `source` | string | Channel short ID: `"A"` (Airbnb), `"V"` (Vrbo), `"B"` (Booking.com) | | `market_id` | integer | Wheelhouse market ID | | `country_code` | string | ISO 3166-1 alpha-2 (e.g. `"US"`, `"GB"`) | | `room_type` | string | As reported by the channel (e.g. `"Entire place"`) | | `channel_account_id` | integer | Wheelhouse channel connection ID | | `listings.currency` | string | ISO 4217 currency code (e.g. `"USD"`, `"EUR"`) | | `listings.price_model_id` | integer | Active price model ID | | `channel_accounts.status` | string | `"active"`, `"failed"`, `"disabled"`, `"pending"`, `"empty"`, `"invalid_auth"` | | `charge_bee_items.id` | string | Billing plan (e.g. `"Free"`, `"Flex_Plan"`, `"Flat_Plan"`) | | `managed_listings.level` | string | Co-host level: `"editor"`, `"restricted_editor"`, `"viewer"` | | `listings.operating_user_id` | integer | User ID of the operating account | --- #### String match parameters Two operator suffixes: `key` (contains), `key_not` (does not contain). Case-insensitive substring match. Comma-separate multiple values for OR logic: `"listings.title": "Beach,Ocean"` matches titles containing *either* word. | Key | Description | |---|---| | `listings.title` | Listing title | | `listing_views.display_name` | Display name | | `listing_views.display_nickname` | Display nickname | | `source_address` | Source address | --- #### Tag parameters Filter by Wheelhouse tag IDs (integers). Four operator suffixes: | Suffix | Match logic | |---|---| | `tags.id` | Has **any** of the listed tag IDs (OR) | | `tags.id_ne` | Has **none** of the listed tag IDs | | `tags.id_and` | Has **all** of the listed tag IDs (AND) | | `tags.id_and_ne` | Does **not** have all of the listed tag IDs | To combine multiple independent tag conditions in one object, append any unique identifier after the suffix — the system strips it before evaluating. Example: `"tags.id_pool": [12]` and `"tags.id_certified_and": [5, 7]` are treated as two separate filters on the same object. --- #### Date range parameters Six operator suffixes, same as numeric range. Values are either an ISO 8601 date string (`"2025-01-01"`) or an integer for a rolling window relative to today (`30` means "30 days ago"). | Key | Description | |---|---| | `listings.created_at` | When the listing was created in Wheelhouse | | `listing_stats.last_booked_at` | Date of the listing's most recent booking | --- #### Membership parameters | Key | Value type | Description | |---|---|---| | `listings.id_in` | integer[] | Include only listings with these internal IDs | | `listings.id_not_in` | integer[] | Exclude listings with these internal IDs | | `listings.source_not_in` | string[] | Exclude listings from these channels | --- #### Geographic parameter | Key | Value format | Description | |---|---|---| | `latlong_distance_from_lte` | `"latitude,longitude,meters"` | Listings within the radius of the given coordinates | --- **Example** ```json { "is_live": true, "bedrooms_gte": 2, "source": "A", "listings.title": "Beach,Ocean", "tags.id_pool": [12], "listings.created_at_gte": "2025-01-01", "listings.id_in": [101, 102, 103] } ``` - `is_default` (boolean): Whether this is the default segment. - `created_at` (string (date-time), required): When the segment was created (ISO-8601). - `updated_at` (string (date-time), required): When the segment was last updated (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json { "id": 0, "name": "string", "description": "string", "filter_backend": {}, "is_default": true, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ``` ### 401 API key authorization failed. ### 403 Read-only API key cannot update segments. ### 404 Segment not found or does not belong to the authenticated user. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Delete a portfolio segment. `DELETE /segments/{segment_id}` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-delete-segment · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmDeleteSegment` · Tag: Segments Permanently deletes a portfolio segment owned by the authenticated user. Listings matched by the segment's filter are not affected. Deleting the default segment leaves the user with no default segment. A segment assigned to a team member cannot be deleted, because doing so would change which listings that team member can access. Remove it from the team member's assigned segments with `POST /teams/members/{sub_user_id}/assigned_segments` first. ## Request `DELETE https://api.usewheelhouse.com/ss_api/v1/segments/{segment_id}` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `segment_id` | integer | yes | The Wheelhouse internal segment ID. | ### Example request ```bash curl -X DELETE 'https://api.usewheelhouse.com/ss_api/v1/segments/{segment_id}' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 204 Segment deleted. ### 400 The segment is assigned to a team member. Unassign it first. ### 401 API key authorization failed. ### 403 Read-only API key cannot delete segments. ### 404 Segment not found or does not belong to the authenticated user. ### 409 A change to the account's team members is in progress. Retry after it completes. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # List listings in a segment. `GET /segments/{segment_id}/listings` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-segment-listings · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetSegmentListings` · Tag: Segments Returns the listings that belong to the given portfolio segment. The segment's filter criteria are applied to the user's portfolio — for an RM API key that includes listings shared with the user to manage, not just listings they own (see `include_managed_listings`). Supports pagination and optional exclusion of inactive listings. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/segments/{segment_id}/listings` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `segment_id` | integer | yes | The Wheelhouse internal segment ID. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `exclude_inactive` | boolean | no | Exclude inactive listings, and listings not linked to a channel, from the response. Defaults to true. (default: `true`) | | `per_page` | integer | no | Number of listings per page. (default: `50`, min: 1, max: 100) | | `page` | integer | no | Page number to retrieve. | | `offset` | integer | no | Number of items to skip before starting to collect the result set. | | `include_managed_listings` | boolean | no | When true (default for RM API keys), the segment's filter is evaluated against listings the user manages for another Wheelhouse account (valid shared-access grants) as well as listings they own. Set to false to match only owned listings. Channel integration keys default to false, since they act on the one account they connected. (default: `true`) | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/segments/{segment_id}/listings' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of listings within the segment. Body (`application/json`): array of object `listing_response` A listing as returned by the RM API. - `id` (string, required): The channel's unique listing identifier. Always the channel's ID, whichever way the request identified the listing; the Wheelhouse listing ID is the separate `wheelhouse_id` field. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). - `channel` (string, required): The channel name of the listing. - `wheelhouse_id` (integer, nullable): The Wheelhouse internal listing ID. - `title` (string, nullable): The listing's name. - `nickname` (string, nullable): Listing nickname used as a shortened title. - `description` (string, nullable): The listing's description text. - `location` (object, nullable): The listing's location. - `country` (string, nullable): ISO-3166 2-letter country code. - `postal_code` (string, nullable) - `address` (string, nullable) - `latitude` (number, nullable) - `longitude` (number, nullable) - `num_bedrooms` (integer, nullable): Number of bedrooms. - `num_beds` (integer, nullable): Number of beds. - `num_bathrooms` (number, nullable): Number of bathrooms (may be fractional, e.g. 1.5). - `room_type` (string, nullable): The room type of the listing. - `property_type` (string, nullable): The property type of the listing. - `currency` (string, nullable): The ISO-4217 3-letter currency code of the listing. - `star_rating` (number, nullable): Star rating. - `num_reviews` (integer, nullable): Number of reviews. - `num_photos` (integer, nullable): Number of photos. - `thumb_url` (string, nullable): URL of the listing's thumbnail image. - `access_level` (string, nullable, one of: `owner`, `viewer`, `restricted_editor`, `editor`, `manager`): How the authenticated user accesses this listing in the RM API: `owner` for listings on their account, or the delegated role when shared access applies (`viewer`, `restricted_editor`, `editor`, `manager`). **API permissions by level:** - `owner`, `editor`, `manager` — full read and write access (GET, PUT, POST, DELETE). - `restricted_editor` — read and write access to the listing itself, except that `PUT /listings/{listing_id}/tags` returns 403 and the batch `PUT /preferences` reports the listing in `errors` with status 403. - `viewer` — read-only; write endpoints (PUT, POST, DELETE) return 403, except that a viewer may remove the listing from a set with `DELETE /sets/{set_id}/associated_listings`. - `amenities` (array of string, nullable): List of amenities available at the listing. - `owner_name` (string, nullable): The property owner's name, as supplied by the channel. This is display text about the physical property's owner and is unrelated to the Wheelhouse account that holds the listing — see `owner_user` for that. - `owner_user` (object, nullable): The Wheelhouse account this listing belongs to. Use this to tell whose portfolio a listing sits in when a response mixes owned and managed listings — for example `GET /listings?include_managed_listings=true`, or the listings of a portfolio segment or dynamic set. For listings the authenticated user owns (`access_level` of `owner`) this is the authenticated user's own account. For managed listings it is the account that granted the shared access. - `id` (integer): The Wheelhouse internal user ID of the owning account. - `email` (string): Email address of the owning account. - `first_name` (string, nullable): First name of the owning account. - `last_name` (string, nullable): Last name of the owning account. - `source_user_id` (string, nullable): The ID of the listing's host on the source channel, as reported by that channel. This is an identifier in the channel's own namespace, not a Wheelhouse account — see `owner_user` for the Wheelhouse account the listing belongs to. - `channel_ids` (object, nullable): A mapping of channel names to the channel's listing ID. - `airbnb` (string, nullable) - `tripadvisor` (string, nullable) - `vrbo` (string, nullable) - `wheelhouse` (string, nullable) - `links` (object, nullable): Useful links to the Wheelhouse app. - `calendar` (string, nullable): Link to the listing calendar page on Wheelhouse. - `upgrade` (string, nullable): Link to the upgrade flow for this listing on Wheelhouse. - `security_deposit` (number, nullable): Security deposit amount in the listing's currency. - `base_min_night_stay` (integer, nullable): The minimum night stay floor for this listing. - `listing_preferences` (object, nullable): A summary of the listing's pricing preferences and fee configuration. Use `GET /preferences/{listing_id}` for the full structured preference object, including date-specific rules. - `automatic_rate_posting_enabled` (boolean, nullable): Whether recommended prices are posted to the channel automatically. - `base_price` (number, nullable): The base price the user set by hand, in the listing's currency. `null` does not mean the listing has no base price. It means the base price follows the Wheelhouse recommendation, multiplied by `base_price_adjustment` (or by `1.0` when that is also `null`). To read the base price in use, call `GET /listings/{listing_id}/price_recommendations` and read its top-level `base_price`. - `base_price_adjustment` (number, nullable): Multiplier applied to the recommended base price when `base_price` is `null`. The presets are `0.9` (conservative), `1.0` (recommended), and `1.1` (aggressive). Any other value is a custom adjustment. When both fields are `null`, the pricing engine uses `1.0`. - `fees` (array of object): Fees charged when booking the listing. Only fees with a configured value are listed. - `name` (string, required): The name of the fee as it appears on line items. - `type` (string, required, one of: `cleaning`, `extra_guest`): Classification of the fee. - `multiplier` (string, required, one of: `PER_STAY`, `PER_NIGHT`): What the fee is charged per. - `value_type` (string, required, one of: `FIXED`, `PERCENTAGE`): Whether `value` is a fixed amount in the listing's currency or a percentage of the booking value. - `value` (number, required): The fee amount. - `max_price` (integer): The global maximum nightly price for automated pricing. Only present when a maximum price is configured. - `min_price` (integer): The global minimum nightly price for automated pricing. Only present when a minimum price is configured. - `minimum_stay` (integer): The global minimum stay in nights. Only present when a minimum stay is configured. - `monthly_discount_pct` (number, nullable): The percent discount given to bookings of 28 nights or more. - `nickname` (string, nullable): User-editable nickname for the listing. - `num_included_guests` (integer, nullable): The number of guests included in the nightly price. - `num_max_guests` (integer, nullable): The maximum number of guests the listing sleeps. - `weekly_discount_pct` (number, nullable): The percent discount given to bookings of 7 nights or more. - `meta` (object, nullable): Supplementary listing attributes. `photos` is present only where photos are requested, such as `GET /listings` with `include_photos=true`; the other fields repeat the top-level fields of the same name. - `amenities` (array of string, nullable) - `num_beds` (integer, nullable) - `num_photos` (integer, nullable) - `num_reviews` (integer, nullable) - `photos` (array of object, nullable): The listing's photos. - `caption` (string, nullable): The photo's caption. - `regular` (string, nullable): URL of the web-sized photo. - `thumbnail` (string, nullable): URL of the thumbnail-sized photo. - `security_deposit` (number, nullable) - `source_user_id` (string, nullable) - `star_rating` (number, nullable) - `market_id` (integer, nullable): The Wheelhouse market ID for this listing. - `market_name` (string, nullable): The human-readable name of the market identified by `market_id`, e.g. `San Francisco, CA, United States`. It is the same `market_name` that `GET /market_report` returns, so there is no need to look it up there. `null` when the listing has no market. - `is_active` (boolean, nullable): Whether the listing is currently active. - `is_hidden` (boolean): Whether the listing has been hidden in the Wheelhouse app. Hiding a listing does not deactivate or disconnect it, so a hidden listing is still returned with `exclude_inactive=true`; filter on this field to leave hidden listings out. Unrelated to the `hidden` membership status of a listing in a dynamic set. - `wheelhouse_created_at` (string, nullable): The datetime the listing was created in Wheelhouse (Rails-style timestamp, e.g. `2016-09-20 02:07:32 -0700`). - `number_of_active_units` (integer, nullable): The number of independently bookable units under this listing. `null` for standard single-unit listings; a positive integer for multi-unit listings. See the **Multi-Unit Listings** section in the overview. - `supported_settings` (object `supported_settings`, read-only): Which listing preference settings this listing's channel can act on. A setting reported `false` is discarded on write rather than posted to the channel, so check this before sending it. Reflects any per-account early access, so two listings on the same channel can differ. - `checkin_checkout` (boolean): Whether `checkin_checkout` rules can be set. - `min_stays` (boolean): Whether minimum stay settings (`min_min_stay`, `min_stays_enabled`, `minimum_stay_rules`) can be set. - `long_term_discounts` (boolean): Whether long-term discounts (`long_term_discounts`, `weekly_discount`, `monthly_discount`) can be set at all. - `long_term_discount_type` (string, one of: `disabled`, `simple`, `rules`, `complex`): The form of long-term discount the channel accepts. `disabled` takes none; `simple` takes only flat `weekly_discount` and `monthly_discount` values and ignores a `rules` object; `rules` additionally takes the 7 and 28 night tiers; `complex` takes arbitrary tiers. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "id": "string", "channel": "string", "wheelhouse_id": 0, "title": "string", "nickname": "string", "description": "string", "location": { "country": "string", "postal_code": "string", "address": "string", "latitude": 0, "longitude": 0 }, "num_bedrooms": 0, "num_beds": 0, "num_bathrooms": 0, "room_type": "string", "property_type": "string", "currency": "string", "star_rating": 0, "num_reviews": 0, "num_photos": 0, "thumb_url": "string", "access_level": "owner", "amenities": [ "string" ], "owner_name": "string", "owner_user": { "id": 0, "email": "string", "first_name": "string", "last_name": "string" }, "source_user_id": "string", "channel_ids": { "airbnb": "string", "tripadvisor": "string", "vrbo": "string", "wheelhouse": "string" }, "links": { "calendar": "string", "upgrade": "string" }, "security_deposit": 0, "base_min_night_stay": 0, "listing_preferences": { "automatic_rate_posting_enabled": true, "base_price": 0, "base_price_adjustment": 0, "fees": [ { "name": "string", "type": "cleaning", "multiplier": "PER_STAY", "value_type": "FIXED", "value": 0 } ], "max_price": 0, "min_price": 0, "minimum_stay": 0, "monthly_discount_pct": 0, "nickname": "string", "num_included_guests": 0, "num_max_guests": 0, "weekly_discount_pct": 0 }, "meta": { "amenities": [ "string" ], "num_beds": 0, "num_photos": 0, "num_reviews": 0, "photos": [ { "caption": "string", "regular": "string", "thumbnail": "string" } ], "security_deposit": 0, "source_user_id": "string", "star_rating": 0 }, "market_id": 0, "market_name": "string", "is_active": true, "is_hidden": true, "wheelhouse_created_at": "string", "number_of_active_units": 0, "supported_settings": { "checkin_checkout": true, "min_stays": true, "long_term_discounts": true, "long_term_discount_type": "disabled" } } ] ``` ### 401 API key authorization failed. ### 404 Segment not found. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get aggregated metrics for a segment. `GET /segments/{segment_id}/aggregated_metrics` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-segment-aggregated-metrics · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetSegmentAggregatedMetrics` · Tag: Segments Returns monthly performance metrics aggregated across the listings matched by the segment's filter. For an RM API key the filter is evaluated against listings shared with the user to manage as well as listings they own (see `include_managed_listings`). Monetary values are converted to the requested currency. Because a segment has no currency of its own, the default is the currency of the most common market among the segment's listings (falling back to USD). ## Request `GET https://api.usewheelhouse.com/ss_api/v1/segments/{segment_id}/aggregated_metrics` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `segment_id` | integer | yes | The Wheelhouse internal segment ID. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `currency` | string | no | ISO-4217 3-letter currency code to convert monetary metrics to. Defaults to the currency of the most common market among the segment's listings. | | `dates` | array of string (date) | no | Restrict the response to periods starting on these dates (first of month, YYYY-MM-DD). Send more than one in brackets (`?dates[]=2026-05-01&dates[]=2026-06-01`); a key repeated without brackets keeps only its last value. Defaults to all available periods. | | `include_managed_listings` | boolean | no | When true (default for RM API keys), the segment's filter is evaluated against listings the user manages for another Wheelhouse account (valid shared-access grants) as well as listings they own. Set to false to match only owned listings. Channel integration keys default to false, since they act on the one account they connected. (default: `true`) | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/segments/{segment_id}/aggregated_metrics' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Aggregated metrics per period. Body (`application/json`): object - `data` (array of object `segment_aggregated_metric_response`) - Each item: Performance metrics for one month, aggregated across the listings matched by a portfolio segment's filter. Metric names follow the [Wheelhouse metrics definitions](https://www.usewheelhouse.com/research-metrics). Values derive from calendar prices and exclude fees and taxes. Monetary values are converted to the response `currency` and rounded to whole units; ratios are expressed as fractions (0–1). - `start_date` (string (date)): First day of the period (YYYY-MM-DD). - `end_date` (string (date)): Last day of the period (YYYY-MM-DD). - `occupancy` (number, nullable): Booked nights as a share of all calendar nights (`nights_booked / nights_calendar`). - `occupancy_adjusted` (number, nullable): Booked nights as a share of bookable nights, excluding blocked inventory (`nights_booked / nights_bookable`). - `nights_percent_open` (number, nullable): Share of calendar nights that are bookable (`nights_bookable / nights_calendar`), as a fraction. - `revenue` (number, nullable): Sum of rental prices for booked nights, excluding fees and taxes. - `adr` (number, nullable): Average Daily Rate — average price per booked night, excluding fees (`revenue / nights_booked`). - `asking_rate` (number, nullable): Asking Rate (Booked + Available Nights): average nightly price across booked and available nights, excluding fees. A booked night counts at the rate it was booked for, an available night at its current price. Blocked nights are left out. `null` when no night qualifies. See `asking_rate_available` for available nights only. - `asking_rate_available` (number, nullable): Asking Rate (Available Nights): sum of nightly prices on available nights / number of available nights, excluding fees. Booked and blocked nights, and nights without a price, count in neither. `null`, not `0`, when no available night has a price. - `revpar` (number, nullable): Revenue per available night, excluding fees (Average Daily Rate × Occupancy). - `revpar_adjusted` (number, nullable): Revenue per bookable night using adjusted occupancy, excluding fees and blocked inventory. - `revenue_available` (number, nullable): Potential earnings from currently available nights at current asking rates. - `revenue_blocked` (number, nullable): Unrealized revenue from blocked nights at current asking rates. - `lead_time` (number, nullable): Days between booking date and stay start date (median across the segment's listings). - `length_of_stay` (number, nullable): Nights per reservation (median across the segment's listings). - `nights_available` (number, nullable): Currently unbooked, bookable nights. - `nights_blocked` (number, nullable): Owner-blocked nights preventing bookings. - `nights_booked` (number, nullable): Currently reserved nights. - `nights_bookable` (number, nullable): Available plus booked nights, excluding blocked nights. - `nights_calendar` (integer, nullable): All nights in the period regardless of status. - `count_bookings` (integer, nullable): Total number of unique reservations. - `currency` (string): The ISO-4217 3-letter currency code of the monetary metrics. Example shape (generated from the schema; placeholder values, not a real response): ```json { "data": [ { "start_date": "2026-01-01", "end_date": "2026-01-01", "occupancy": 0, "occupancy_adjusted": 0, "nights_percent_open": 0, "revenue": 0, "adr": 0, "asking_rate": 0, "asking_rate_available": 0, "revpar": 0, "revpar_adjusted": 0, "revenue_available": 0, "revenue_blocked": 0, "lead_time": 0, "length_of_stay": 0, "nights_available": 0, "nights_blocked": 0, "nights_booked": 0, "nights_bookable": 0, "nights_calendar": 0, "count_bookings": 0 } ], "currency": "string" } ``` ### 401 API key authorization failed. ### 404 Segment not found. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get the bedroom groups a market is broken down by. `GET /market_report/{market_id}/bedroom_groups` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-market-bedroom-groups · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetMarketBedroomGroups` · Tag: Market Reports Returns the bedroom groups the market's report is broken down by, in ascending order, with the number of listings behind each one. Pass a group's `bedrooms` value to the time-series and distribution endpoints. RM API users can only access markets in which they have at least one Pro tier listing. Groups are derived from the listings in the market, so they differ from market to market and can change when the report is regenerated. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/market_report/{market_id}/bedroom_groups` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `market_id` | integer | yes | The Wheelhouse internal market ID (from `GET /market_report` or `/listings`). | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/market_report/{market_id}/bedroom_groups' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Bedroom groups for the market. Body (`application/json`): object - `bedroom_groups` (array of object): The market's bedroom groups, in ascending order. - `bedrooms` (string, example: `6+`): Value to pass as the `bedrooms` parameter. A trailing `+` marks the top group, which holds every listing with at least that many bedrooms. - `listings` (integer, nullable, example: `23`): Number of listings in the group. Null where the report was generated before the counts were published. - `updated_at` (string, example: `2026-08-30 04:17:22 UTC`): When the market's report was generated. Example shape (generated from the schema; placeholder values, not a real response): ```json { "bedroom_groups": [ { "bedrooms": "6+", "listings": 23 } ], "updated_at": "2026-08-30 04:17:22 UTC" } ``` ### 204 No report has been generated for this market yet. ### 400 Invalid market_id. ### 401 API key authorization failed. ### 404 Market not found or not accessible. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get time-series market metrics. `GET /market_report/{market_id}/time_series` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-market-time-series · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetMarketTimeSeries` · Tag: Market Reports Returns daily time-series data for one or more market-level metrics over a date range. RM API users can only access markets in which they have at least one Pro tier listing. Available metrics: `asking_rate_w_fees`, `occupancy`, `occupancy_adjusted`, `adr_w_fees`, `lead_time`, `revpar_adjusted_w_fees`, `revpar_w_fees`, `revenue_w_fees`, `nights_bookable`. **Same time last year.** Pass `basis=stly` to get each stay date's values as they stood around the same time last year: the market's figures for the stay date 52 weeks earlier, returned under this year's `stay_date` with the same fields, so the rows of both bases can be joined on `stay_date`. `updated_at` is then when last year's figures were generated. A value is `null` where last year has no data for that stay date, and a bedroom group last year's market was not broken down by returns 204. Last year's figures are refreshed weekly, so the last few days of the one-year horizon can be missing from the response, and a range that lies entirely within them returns 204. `basis=stly` is in early access: accounts without early access get a 403, and a market whose last year figures are not available yet returns a 404. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/market_report/{market_id}/time_series` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `market_id` | integer | yes | The Wheelhouse internal market ID (from `GET /market_report` or `/listings`). | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `metric` | array of string | no | Metrics to include. Defaults to all metrics. Send more than one in brackets (`?metric[]=asking_rate_w_fees&metric[]=occupancy`); a key repeated without brackets keeps only its last value. (each item one of: `occupancy`, `occupancy_adjusted`, `nights_bookable`, `asking_rate_w_fees`, `adr_w_fees`, `lead_time`, `revpar_adjusted_w_fees`, `revpar_w_fees`, `revenue_w_fees`) | | `start_date` | string (date) | no | Start of the date range (YYYY-MM-DD). Defaults to today. Must be within 3 years in the past and 1 year in the future. | | `end_date` | string (date) | no | End of the date range (YYYY-MM-DD). Defaults to 1 year from today. Must be after `start_date`. | | `performance` | string | no | Filter to a performance tier. Omit to include all tiers. (one of: `low`, `average`, `high`) | | `bedrooms` | string | no | Filter to this bedroom group. Omit to include all bedroom counts. Which groups a market is broken down by depends on the listings in it, so they differ from market to market: a market with many larger listings is broken down further (`0`, `1`, `2`, `3`, `4`, `5`, `6+`) than one without them (`0`, `1`, `2+`). Read a market's groups from `GET /market_report/{market_id}/bedroom_groups` rather than assuming a fixed set. A group the market has no data for is rejected, and the error names the groups it does have. The top group holds every listing with at least that many bedrooms. A request for a top group is answered from the exact bedroom count it names where the market is broken down past it, so `4+` returns the 4 bedroom group in a market broken down into `4`, `5` and `6+`. (pattern: `^\d{1,2}\+?$`, example: `2`) | | `property_type` | string | no | Filter to a property type. Omit to include all property types. (one of: `apartment`, `bnb`, `boat`, `bus`, `cabin`, `camper`, `camping`, `castle`, `holiday_home`, `hostel`, `hotel`, `house`, `houseboat`, `island`, `mill`, `other`, `room`, `shared`, `tower`) | | `basis` | string | no | Today's values (`current`) or the values as they stood around the same time last year (`stly`). See the description above for what `stly` returns. `stly` is in early access. (one of: `current`, `stly`, default: `current`) | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/market_report/{market_id}/time_series' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Time-series market data. Body (`application/json`): object - `currency` (string): ISO-4217 currency code for monetary metrics. - `updated_at` (string, example: `2026-08-30 04:17:22 UTC`): When the underlying market report was last generated, as a timestamp with a time zone abbreviation rather than ISO-8601. - `data` (array of object): Daily metric values. - `stay_date` (string (date)): Stay date (YYYY-MM-DD). - `occupancy` (number, nullable): Occupancy rate (0–1). Present when `occupancy` is requested. - `occupancy_adjusted` (number, nullable): Occupancy rate over open (non-blocked) nights (0–1). Present when `occupancy_adjusted` is requested. - `nights_bookable` (number, nullable): Number of open (non-blocked) available room-nights. Present when `nights_bookable` is requested. - `asking_rate_w_fees` (number, nullable): Average asking rate including fees. Present when `asking_rate_w_fees` is requested. - `adr_w_fees` (number, nullable): Average daily rate including fees of booked rooms. Present when `adr_w_fees` is requested. - `lead_time` (number, nullable): Average lead time in days. Present when `lead_time` is requested. - `revpar_adjusted_w_fees` (number, nullable): Revenue per open available room-night including fees. Present when `revpar_adjusted_w_fees` is requested. - `revpar_w_fees` (number, nullable): Revenue per available room-night including fees. Present when `revpar_w_fees` is requested. - `revenue_w_fees` (number, nullable): Total revenue including fees. Present when `revenue_w_fees` is requested. Example shape (generated from the schema; placeholder values, not a real response): ```json { "currency": "string", "updated_at": "2026-08-30 04:17:22 UTC", "data": [ { "stay_date": "2026-01-01", "occupancy": 0, "occupancy_adjusted": 0, "nights_bookable": 0, "asking_rate_w_fees": 0, "adr_w_fees": 0, "lead_time": 0, "revpar_adjusted_w_fees": 0, "revpar_w_fees": 0, "revenue_w_fees": 0 } ] } ``` ### 204 Not enough data for the requested parameters. ### 400 Invalid parameter value (e.g. invalid date range, or a `bedrooms` group this market is not broken down by). ### 401 API key authorization failed. ### 403 `basis=stly` was requested by an account without early access to it. ### 404 Market not found or not accessible, or, with `basis=stly`, last year's figures for this market are not available yet. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get market metric distributions for a month. `GET /market_report/{market_id}/distribution` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-market-distribution · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetMarketDistribution` · Tag: Market Reports Returns histogram distributions for one or more market-level metrics for a given calendar month. RM API users can only access markets in which they have at least one Pro tier listing. Available metrics: `occupancy`, `occupancy_adjusted`, `asking_rate_w_fees`, `adr_w_fees`, `lead_time`, `revpar_adjusted_w_fees`, `revpar_w_fees`, `length_of_stay`. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/market_report/{market_id}/distribution` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `market_id` | integer | yes | The Wheelhouse internal market ID (from `GET /market_report`). | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `metric` | array of string | no | Metrics to include. Defaults to all metrics. Send more than one in brackets (`?metric[]=asking_rate_w_fees&metric[]=occupancy`); a key repeated without brackets keeps only its last value. (each item one of: `occupancy`, `occupancy_adjusted`, `asking_rate_w_fees`, `adr_w_fees`, `lead_time`, `revpar_adjusted_w_fees`, `revpar_w_fees`, `length_of_stay`) | | `month` | string (date) | no | The month to retrieve distributions for (YYYY-MM-DD or YYYY-MM, e.g. `2026-05-01` or `2026-05`). Defaults to the start of the current month. (example: `2026-05-01`) | | `performance` | string | no | Filter to a performance tier. Omit to include all tiers. (one of: `low`, `average`, `high`) | | `bedrooms` | string | no | Filter to this bedroom group. Omit to include all bedroom counts. Which groups a market is broken down by depends on the listings in it, so they differ from market to market: a market with many larger listings is broken down further (`0`, `1`, `2`, `3`, `4`, `5`, `6+`) than one without them (`0`, `1`, `2+`). Read a market's groups from `GET /market_report/{market_id}/bedroom_groups` rather than assuming a fixed set. A group the market has no data for is rejected, and the error names the groups it does have. The top group holds every listing with at least that many bedrooms. A request for a top group is answered from the exact bedroom count it names where the market is broken down past it, so `4+` returns the 4 bedroom group in a market broken down into `4`, `5` and `6+`. (pattern: `^\d{1,2}\+?$`, example: `2`) | | `property_type` | string | no | Filter to a property type. Omit to include all property types. (one of: `apartment`, `bnb`, `boat`, `bus`, `cabin`, `camper`, `camping`, `castle`, `holiday_home`, `hostel`, `hotel`, `house`, `houseboat`, `island`, `mill`, `other`, `room`, `shared`, `tower`) | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/market_report/{market_id}/distribution' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Market metric distributions for the month. Body (`application/json`): object - `currency` (string): ISO-4217 currency code for monetary metrics. - `month` (string (date)): The start of the month these distributions cover (YYYY-MM-DD). - `updated_at` (string, example: `2026-08-30 04:17:22 UTC`): When the underlying market report was last generated, as a timestamp with a time zone abbreviation rather than ISO-8601. - `data` (map of string to array of object): Distribution buckets keyed by metric name. Each metric maps to an array of histogram buckets sorted by probability descending. - `bucket_min_incl` (number): Inclusive lower bound of the bucket. - `bucket_max_excl` (number): Exclusive upper bound of the bucket. - `probability` (number): Fraction of observations in this bucket (0–1). - `percentile` (number): Cumulative probability up to and including this bucket (0–1). Example shape (generated from the schema; placeholder values, not a real response): ```json { "currency": "string", "month": "2026-01-01", "updated_at": "2026-08-30 04:17:22 UTC", "data": { "key": [ { "bucket_min_incl": 0, "bucket_max_excl": 0, "probability": 0, "percentile": 0 } ] } } ``` ### 204 Not enough data for the requested parameters. ### 400 Invalid parameter value (e.g. month out of range, or a `bedrooms` group this market is not broken down by). ### 401 API key authorization failed. ### 404 Market not found or not accessible. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get daily neighborhood pricing data for a listing. `GET /listings/{listing_id}/neighborhood/pricing` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-neighborhood-pricing · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetNeighborhoodPricing` · Tag: Neighborhood Data Returns a daily time series of neighborhood price data for the listing's local cluster — a geographic group of comparable properties with the same bedroom count near the listing. Each entry includes the median nightly price, the p25 (`low_price`) and p75 (`high_price`) price percentiles, and the number of listings in the cluster for that stay date. All prices are in the market's native currency, reported in the `currency` field. Prices include the fees guests pay on top of the nightly rate. To compare a listing's nightly rate with them, multiply it by the `fee_multiplier` from `GET /listings/{listing_id}/fee_impact_calendar` first. This is the same neighborhood data shown in the Wheelhouse pricing chart. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/neighborhood/pricing` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/neighborhood/pricing?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Neighborhood price data. Body (`application/json`): object `neighborhood_pricing_response` Daily neighborhood price percentiles. - `data` (array of object `neighborhood_pricing_day`, required): Daily neighborhood price entries ordered by stay date. - `stay_date` (string (date), required): The stay date (YYYY-MM-DD). - `median_price` (number, required): Median nightly price (p50) across listings in the neighborhood cluster. - `low_price` (number, required): Lower-quartile nightly price (p25) across listings in the neighborhood cluster. - `high_price` (number, required): Upper-quartile nightly price (p75) across listings in the neighborhood cluster. - `listings_count` (integer, required): Number of listings contributing to the neighborhood data for this date. - `currency` (string, required): ISO-4217 currency code that all price fields are expressed in (the listing's market currency). Example shape (generated from the schema; placeholder values, not a real response): ```json { "data": [ { "stay_date": "2026-01-01", "median_price": 0, "low_price": 0, "high_price": 0, "listings_count": 0 } ], "currency": "string" } ``` ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found, or no neighborhood cluster found for this listing's location. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 422 Listing is not covered by a Wheelhouse market, or has no location data. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get daily neighborhood occupancy and booking data for a listing. `GET /listings/{listing_id}/neighborhood/occupancy` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-neighborhood-occupancy · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetNeighborhoodOccupancy` · Tag: Neighborhood Data Returns a daily time series of occupancy and booking model data for the listing's local neighborhood cluster. This is the same data used to render the occupancy, expected bookings, and observed bookings series in the Wheelhouse pricing chart. - `occupancy` — raw occupancy rate (booked nights / calendar nights). - `adjusted_occupancy` — occupancy computed against bookable (unblocked) nights only. - `expected_bookings` — model-predicted booking count for the stay date. - `expected_bookings_sd` — standard deviation of the expected bookings prediction. - `observed_bookings` — actual booking count observed for the stay date. - `calendar_nights` — total calendar nights in the cluster for the stay date. Returns `404` if no neighborhood cluster is found for the listing's location, or if no occupancy data has been generated for the cluster. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/neighborhood/occupancy` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/neighborhood/occupancy?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Neighborhood occupancy and booking data. Body (`application/json`): object `neighborhood_occupancy_response` Daily neighborhood occupancy and bookings. - `data` (array of object `neighborhood_occupancy_day`, required): Daily neighborhood occupancy entries ordered by stay date. - `stay_date` (string (date), required): The stay date (YYYY-MM-DD). - `occupancy` (number, nullable): Raw occupancy rate for the cluster on this date (booked nights / calendar nights). - `adjusted_occupancy` (number, nullable): Occupancy rate computed against bookable (unblocked) nights only. - `expected_bookings` (number, nullable): Model-predicted number of bookings for this stay date. - `expected_bookings_sd` (number, nullable): Standard deviation of the expected bookings prediction. - `observed_bookings` (number, nullable): Actual number of bookings observed for this stay date. - `calendar_nights` (integer, nullable): Total calendar nights in the neighborhood cluster for this stay date. Example shape (generated from the schema; placeholder values, not a real response): ```json { "data": [ { "stay_date": "2026-01-01", "occupancy": 0, "adjusted_occupancy": 0, "expected_bookings": 0, "expected_bookings_sd": 0, "observed_bookings": 0, "calendar_nights": 0 } ] } ``` ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found, or no neighborhood cluster or occupancy data found for this listing's location. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 422 Listing is not covered by a Wheelhouse market, or has no location data. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # List dynamic sets. `GET /sets` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-sets · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetSets` · Tag: Dynamic Sets Returns all dynamic sets the authenticated user owns or has shared access to, including both free and paid sets. Use the `is_paid` field to tell them apart — only paid sets expose KPI data, and free sets can be upgraded via `POST /sets/{set_id}/upgrade`. Results are ordered by most recently updated first and paginated. Narrow the list with `name` and `kind`. Both are optional, and sending both returns only the sets matching each of them. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/sets` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | Match sets by name. `*` stands for any run of characters, so `*Palm Springs*` matches sets with that phrase anywhere in the name, `Palm*` matches names starting with it, and a value with no `*` has to match the whole name. Matching ignores case, and any other character — including `%` and `_` — is matched literally. (example: `*Palm Springs*`) | | `kind` | string | no | Match sets by their `kind` — see the `kind` field of the set object for the values. Comma-separate several to match any of them, e.g. `competitive,market`. Sets with no kind are reported as `other` and are matched by `kind=other`. An unrecognised value returns 400. (example: `competitive`) | | `per_page` | integer | no | Number of sets per page. (default: `50`, min: 1, max: 100) | | `page` | integer | no | Page number to retrieve. | | `offset` | integer | no | Number of items to skip before starting to collect the result set. | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/sets' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of dynamic sets. Body (`application/json`): array of object `dynamic_set_response` A dynamic set (comp set). - `id` (integer, required): The Wheelhouse internal dynamic set ID. - `user_id` (integer, required): The Wheelhouse internal ID of the user that owns the set. - `name` (string, required): The set name. - `description` (string, nullable): An optional description of the set. - `kind` (string, one of: `competitive`, `market`, `neighborhood`, `marketing`, `acquisition`, `underwriting`, `other`, `merchandising`): The intended use case for the set: - `competitive` — tracks direct competitor properties. - `market` — broad market-wide overview. - `neighborhood` — properties in the same geographic sub-area. - `marketing` — properties used as marketing or positioning references. - `acquisition` — evaluating potential acquisition targets. - `underwriting` — used in underwriting or investment analysis. - `merchandising` — set curated for merchandising purposes. - `other` — general-purpose or uncategorized set. - `currency` (string, nullable): The ISO-4217 3-letter currency code of the set. - `is_static` (boolean): Whether the set membership is static. Non-static sets are kept in sync automatically based on the set's boundary and filters. - `is_paid` (boolean): Whether the set is on the paid Dynamic Sets plan. Only paid sets expose the set-level analytics endpoints (aggregated_metrics, time_series, distribution, changelog), which return `404 Not Found` for a free set. Endpoints for building and reviewing a set — including its member listings and associated_listings — work on free sets too. See the Dynamic Sets section for the full per-endpoint breakdown. Upgrade a free set via `POST /sets/{set_id}/upgrade`. - `filters` (object, nullable): The filter criteria used to select member listings (non-static sets). Keys are listing attributes/metrics, values contain `lower`/`upper` bounds or `one_of` lists. - `boundary` (array of array of array of array of number, nullable, each item each item each item min items: 2, max items: 2): The geographic boundary of the set as MultiPolygon coordinates (`[[[[lng, lat], ...]]]`), if one is defined. The four levels of nesting are: **polygons** → **rings** → **points** → **coordinates**. - **Polygons** (`boundary[i]`): Each element is one polygon. - **Rings** (`boundary[i][j]`): Each polygon contains one or more linear rings. The first ring is the exterior boundary (outer shell of the shape); any subsequent rings represent interior boundaries (holes inside the polygon). - **Points** (`boundary[i][j][k]`): Each ring is an array of `[longitude, latitude]` coordinate pairs. - **Coordinates** (`boundary[i][j][k][0/1]`): Each point is `[longitude, latitude]` as floating-point numbers. - `listing_counts` (object): Number of member listings in the set per status. - `active` (integer) - `hidden` (integer) - `review` (integer) - `removed` (integer) - `updated_at` (string (date-time)): When the set was last updated (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "id": 0, "user_id": 0, "name": "string", "description": "string", "kind": "competitive", "currency": "string", "is_static": true, "is_paid": true, "filters": {}, "boundary": [ [ [ [ 0, 0 ] ] ] ], "listing_counts": { "active": 0, "hidden": 0, "review": 0, "removed": 0 }, "updated_at": "2026-01-01T00:00:00Z" } ] ``` ### 400 An unrecognised `kind` was requested. ### 401 API key authorization failed. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Create a dynamic set. `POST /sets` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-create-set · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmCreateSet` · Tag: Dynamic Sets Creates a free dynamic set owned by the authenticated user. Add candidate listings (from `GET /sets/candidates`) by passing their internal `listing_id`s in `listing_ids`; they are added with the `active` status. The set is created on the free plan — upgrade it with `POST /sets/{set_id}/upgrade` to access its KPI endpoints. ## Request `POST https://api.usewheelhouse.com/ss_api/v1/sets` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Request body (`application/json`, required) - `name` (string, required): Name of the dynamic set. - `description` (string): Optional description of the set. - `currency` (string): ISO-4217 3-letter currency code. Defaults to the currency of the most common market among the set's listings. - `listing_ids` (array of integer): Internal listing IDs (the `listing_id` values returned by GET /sets/candidates) to add as members. Maximum 500 per request. ### Example request ```bash curl -X POST 'https://api.usewheelhouse.com/ss_api/v1/sets' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{ "name": "string" }' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 201 The created dynamic set. Body (`application/json`): object `dynamic_set_response` A dynamic set (comp set). - `id` (integer, required): The Wheelhouse internal dynamic set ID. - `user_id` (integer, required): The Wheelhouse internal ID of the user that owns the set. - `name` (string, required): The set name. - `description` (string, nullable): An optional description of the set. - `kind` (string, one of: `competitive`, `market`, `neighborhood`, `marketing`, `acquisition`, `underwriting`, `other`, `merchandising`): The intended use case for the set: - `competitive` — tracks direct competitor properties. - `market` — broad market-wide overview. - `neighborhood` — properties in the same geographic sub-area. - `marketing` — properties used as marketing or positioning references. - `acquisition` — evaluating potential acquisition targets. - `underwriting` — used in underwriting or investment analysis. - `merchandising` — set curated for merchandising purposes. - `other` — general-purpose or uncategorized set. - `currency` (string, nullable): The ISO-4217 3-letter currency code of the set. - `is_static` (boolean): Whether the set membership is static. Non-static sets are kept in sync automatically based on the set's boundary and filters. - `is_paid` (boolean): Whether the set is on the paid Dynamic Sets plan. Only paid sets expose the set-level analytics endpoints (aggregated_metrics, time_series, distribution, changelog), which return `404 Not Found` for a free set. Endpoints for building and reviewing a set — including its member listings and associated_listings — work on free sets too. See the Dynamic Sets section for the full per-endpoint breakdown. Upgrade a free set via `POST /sets/{set_id}/upgrade`. - `filters` (object, nullable): The filter criteria used to select member listings (non-static sets). Keys are listing attributes/metrics, values contain `lower`/`upper` bounds or `one_of` lists. - `boundary` (array of array of array of array of number, nullable, each item each item each item min items: 2, max items: 2): The geographic boundary of the set as MultiPolygon coordinates (`[[[[lng, lat], ...]]]`), if one is defined. The four levels of nesting are: **polygons** → **rings** → **points** → **coordinates**. - **Polygons** (`boundary[i]`): Each element is one polygon. - **Rings** (`boundary[i][j]`): Each polygon contains one or more linear rings. The first ring is the exterior boundary (outer shell of the shape); any subsequent rings represent interior boundaries (holes inside the polygon). - **Points** (`boundary[i][j][k]`): Each ring is an array of `[longitude, latitude]` coordinate pairs. - **Coordinates** (`boundary[i][j][k][0/1]`): Each point is `[longitude, latitude]` as floating-point numbers. - `listing_counts` (object): Number of member listings in the set per status. - `active` (integer) - `hidden` (integer) - `review` (integer) - `removed` (integer) - `updated_at` (string (date-time)): When the set was last updated (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json { "id": 0, "user_id": 0, "name": "string", "description": "string", "kind": "competitive", "currency": "string", "is_static": true, "is_paid": true, "filters": {}, "boundary": [ [ [ [ 0, 0 ] ] ] ], "listing_counts": { "active": 0, "hidden": 0, "review": 0, "removed": 0 }, "updated_at": "2026-01-01T00:00:00Z" } ``` ### 400 Validation error (e.g. name missing, or too many listing IDs). ### 401 API key authorization failed. ### 403 The API key is read-only. ### 404 One or more of the provided listing IDs were not found. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Search candidate listings for a dynamic set. `GET /sets/candidates` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-set-candidates · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetSetCandidates` · Tag: Dynamic Sets Returns market listings near a location, with their trailing-year performance metrics, to choose from when building a dynamic set. Provide either a `lat`/`long`/`radius` (radius in meters) or one or more `market_ids`. Results are ordered nearest-first (each carries a `distance_meters` value) and paginated. Pass the returned `listing_id`s to `POST /sets` to add them as members. Not tied to a set, so no set plan applies. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/sets/candidates` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `lat` | number | no | Latitude of the search center. Must be sent together with long and radius. | | `long` | number | no | Longitude of the search center. Must be sent together with lat and radius. | | `radius` | integer | no | Search radius in meters. Must be sent together with lat and long. | | `market_ids` | array of integer | no | Restrict candidates to these markets. Provide this or lat/long/radius. Send more than one in brackets (`?market_ids[]=12&market_ids[]=34`); a key repeated without brackets keeps only its last value. | | `min_bedrooms` | integer | no | | | `max_bedrooms` | integer | no | | | `min_bathrooms` | number | no | | | `max_bathrooms` | number | no | | | `room_types` | array of string | no | Restrict candidates to these normalized room types. Send more than one in brackets (`?room_types[]=apartment&room_types[]=house`); a key repeated without brackets keeps only its last value. (each item one of: `apartment`, `bnb`, `boat`, `bus`, `cabin`, `camper`, `camping`, `castle`, `holiday_home`, `hostel`, `hotel`, `house`, `houseboat`, `island`, `mill`, `other`, `room`, `shared`, `tower`) | | `min_bookable_nights_0_365` | integer | no | Minimum bookable nights over the next 365 days. | | `min_open_occupancy_0_365` | number | no | Minimum forward-looking adjusted occupancy (0–1). | | `min_open_occupancy_365_0` | number | no | Minimum trailing-year adjusted occupancy (0–1). Defaults to 0.35. (default: `0.35`) | | `min_bookable_nights_365_0` | integer | no | Minimum trailing-year bookable nights. Defaults to 127. (default: `127`) | | `per_page` | integer | no | Number of candidates per page. (default: `50`, min: 1, max: 100) | | `page` | integer | no | Page number to retrieve. | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/sets/candidates' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of candidate listings ordered nearest-first. Body (`application/json`): array of object `candidate_listing_response` A market listing with trailing-year performance metrics, named per the public [Wheelhouse metrics definitions](https://www.usewheelhouse.com/research-metrics). Metrics with the suffix `_365_0` cover the past 365 days; `_90_0` covers the past 90 days. When returned from a proximity search (`GET /sets/candidates`), `distance_meters` is the distance from the search center. - `listing_id` (integer, required): The Wheelhouse internal listing ID. - `title` (string, nullable): The listing title. - `source` (string, nullable): The channel the listing was sourced from. - `url` (string, nullable): Public URL of the listing on its channel. - `thumb_url` (string, nullable): Thumbnail image URL. - `owner_name` (string, nullable): The listing host/owner name. - `lat` (number): Latitude of the listing. - `long` (number): Longitude of the listing. - `market_id` (integer, nullable): The Wheelhouse internal market ID of the listing. - `currency` (string, nullable): The ISO-4217 3-letter currency code of the listing's monetary metrics. - `bedrooms` (integer, nullable): Number of bedrooms. - `bathrooms` (number, nullable): Number of bathrooms (may be fractional, e.g. 1.5). - `beds` (integer, nullable): Number of beds. - `sleeps` (integer, nullable): Maximum number of guests the listing sleeps. - `guests_included` (integer, nullable): Number of guests included in the base price. - `room_type` (string, nullable): The room type of the listing. - `property_type` (string, nullable): The property type of the listing. - `amenities` (array of string): List of amenities available at the listing. - `cleaning_fee` (integer, nullable): Cleaning fee amount in the listing's currency. - `star_rating` (number, nullable): Guest star rating. - `review_count` (integer, nullable): Number of guest reviews. - `adr_365_0` (number, nullable): Average Daily Rate — average nightly price over the past 365 days. - `asking_rate_365_0` (number, nullable): Average nightly asking price over the past 365 days. - `occupancy_365_0` (number, nullable): Occupancy over the past 365 days. - `occupancy_adjusted_365_0` (number, nullable): Adjusted occupancy (booked as a share of bookable nights, excluding blocked inventory) over the past 365 days. - `nights_percent_open_365_0` (number, nullable): Share of nights open for booking over the past 365 days. - `nights_percent_open_90_0` (number, nullable): Share of nights open for booking over the past 90 days. - `nights_available_365_0` (integer, nullable): Number of unbooked, bookable nights over the past 365 days. - `nights_blocked_365_0` (integer, nullable): Number of owner-blocked nights over the past 365 days. - `nights_bookable_365_0` (integer, nullable): Available plus booked nights, excluding blocked nights, over the past 365 days. - `nights_booked_365_0` (integer, nullable): Number of reserved nights over the past 365 days. - `lead_time_365_0` (number, nullable): Average booking lead time in days over the past 365 days. - `length_of_stay_365_0` (number, nullable): Average length of stay over the past 365 days. - `revenue_365_0` (number, nullable): Rental revenue over the past 365 days. - `revpar_365_0` (number, nullable): Revenue per available night over the past 365 days. - `revpar_adjusted_365_0` (number, nullable): Revenue per bookable night, excluding blocked inventory, over the past 365 days. - `distance_meters` (integer): Distance from the search origin, if applicable. - `listing_created_at` (string (date-time), nullable): When the listing was first indexed by Wheelhouse (ISO-8601). - `listing_last_updated` (string (date-time), nullable): When the listing data was last updated (ISO-8601). - `updated_at` (string (date-time)): When this listing's metrics record was last updated (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "listing_id": 0, "title": "string", "source": "string", "url": "string", "thumb_url": "string", "owner_name": "string", "lat": 0, "long": 0, "market_id": 0, "currency": "string", "bedrooms": 0, "bathrooms": 0, "beds": 0, "sleeps": 0, "guests_included": 0, "room_type": "string", "property_type": "string", "amenities": [ "string" ], "cleaning_fee": 0, "star_rating": 0, "review_count": 0, "adr_365_0": 0, "asking_rate_365_0": 0, "occupancy_365_0": 0, "occupancy_adjusted_365_0": 0, "nights_percent_open_365_0": 0, "nights_percent_open_90_0": 0, "nights_available_365_0": 0, "nights_blocked_365_0": 0, "nights_bookable_365_0": 0, "nights_booked_365_0": 0, "lead_time_365_0": 0, "length_of_stay_365_0": 0, "revenue_365_0": 0, "revpar_365_0": 0, "revpar_adjusted_365_0": 0, "distance_meters": 0, "listing_created_at": "2026-01-01T00:00:00Z", "listing_last_updated": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ] ``` ### 400 Neither lat/long/radius nor market_ids were provided, or lat/long/radius were not sent together. ### 401 API key authorization failed. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get a single dynamic set. `GET /sets/{set_id}` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-set · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetSet` · Tag: Dynamic Sets Returns detailed information about one dynamic set, including its definition (kind, filters, boundary) and member listing counts per status. **Works for free and paid sets.** ## Request `GET https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `set_id` | integer | yes | The Wheelhouse internal dynamic set ID. | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The dynamic set. Body (`application/json`): object `dynamic_set_response` A dynamic set (comp set). - `id` (integer, required): The Wheelhouse internal dynamic set ID. - `user_id` (integer, required): The Wheelhouse internal ID of the user that owns the set. - `name` (string, required): The set name. - `description` (string, nullable): An optional description of the set. - `kind` (string, one of: `competitive`, `market`, `neighborhood`, `marketing`, `acquisition`, `underwriting`, `other`, `merchandising`): The intended use case for the set: - `competitive` — tracks direct competitor properties. - `market` — broad market-wide overview. - `neighborhood` — properties in the same geographic sub-area. - `marketing` — properties used as marketing or positioning references. - `acquisition` — evaluating potential acquisition targets. - `underwriting` — used in underwriting or investment analysis. - `merchandising` — set curated for merchandising purposes. - `other` — general-purpose or uncategorized set. - `currency` (string, nullable): The ISO-4217 3-letter currency code of the set. - `is_static` (boolean): Whether the set membership is static. Non-static sets are kept in sync automatically based on the set's boundary and filters. - `is_paid` (boolean): Whether the set is on the paid Dynamic Sets plan. Only paid sets expose the set-level analytics endpoints (aggregated_metrics, time_series, distribution, changelog), which return `404 Not Found` for a free set. Endpoints for building and reviewing a set — including its member listings and associated_listings — work on free sets too. See the Dynamic Sets section for the full per-endpoint breakdown. Upgrade a free set via `POST /sets/{set_id}/upgrade`. - `filters` (object, nullable): The filter criteria used to select member listings (non-static sets). Keys are listing attributes/metrics, values contain `lower`/`upper` bounds or `one_of` lists. - `boundary` (array of array of array of array of number, nullable, each item each item each item min items: 2, max items: 2): The geographic boundary of the set as MultiPolygon coordinates (`[[[[lng, lat], ...]]]`), if one is defined. The four levels of nesting are: **polygons** → **rings** → **points** → **coordinates**. - **Polygons** (`boundary[i]`): Each element is one polygon. - **Rings** (`boundary[i][j]`): Each polygon contains one or more linear rings. The first ring is the exterior boundary (outer shell of the shape); any subsequent rings represent interior boundaries (holes inside the polygon). - **Points** (`boundary[i][j][k]`): Each ring is an array of `[longitude, latitude]` coordinate pairs. - **Coordinates** (`boundary[i][j][k][0/1]`): Each point is `[longitude, latitude]` as floating-point numbers. - `listing_counts` (object): Number of member listings in the set per status. - `active` (integer) - `hidden` (integer) - `review` (integer) - `removed` (integer) - `updated_at` (string (date-time)): When the set was last updated (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json { "id": 0, "user_id": 0, "name": "string", "description": "string", "kind": "competitive", "currency": "string", "is_static": true, "is_paid": true, "filters": {}, "boundary": [ [ [ [ 0, 0 ] ] ] ], "listing_counts": { "active": 0, "hidden": 0, "review": 0, "removed": 0 }, "updated_at": "2026-01-01T00:00:00Z" } ``` ### 401 API key authorization failed. ### 404 Dynamic set not found or not accessible to the user. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Upgrade a dynamic set to a paid set. `POST /sets/{set_id}/upgrade` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-upgrade-set · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmUpgradeSet` · Tag: Dynamic Sets Purchases the paid Dynamic Sets plan for a free set so its KPI endpoints (aggregated_metrics, time_series, distribution, report) become available. **This creates a real paid subscription and charges the billable user's payment method.** Only the set's owner or a manager-level collaborator may upgrade a set (editors cannot), and the billable user must have a valid payment method on file. Returns the upgraded set. ## Request `POST https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/upgrade` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `set_id` | integer | yes | The Wheelhouse internal dynamic set ID. | ### Example request ```bash curl -X POST 'https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/upgrade' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The upgraded (now paid) dynamic set. Body (`application/json`): object `dynamic_set_response` A dynamic set (comp set). - `id` (integer, required): The Wheelhouse internal dynamic set ID. - `user_id` (integer, required): The Wheelhouse internal ID of the user that owns the set. - `name` (string, required): The set name. - `description` (string, nullable): An optional description of the set. - `kind` (string, one of: `competitive`, `market`, `neighborhood`, `marketing`, `acquisition`, `underwriting`, `other`, `merchandising`): The intended use case for the set: - `competitive` — tracks direct competitor properties. - `market` — broad market-wide overview. - `neighborhood` — properties in the same geographic sub-area. - `marketing` — properties used as marketing or positioning references. - `acquisition` — evaluating potential acquisition targets. - `underwriting` — used in underwriting or investment analysis. - `merchandising` — set curated for merchandising purposes. - `other` — general-purpose or uncategorized set. - `currency` (string, nullable): The ISO-4217 3-letter currency code of the set. - `is_static` (boolean): Whether the set membership is static. Non-static sets are kept in sync automatically based on the set's boundary and filters. - `is_paid` (boolean): Whether the set is on the paid Dynamic Sets plan. Only paid sets expose the set-level analytics endpoints (aggregated_metrics, time_series, distribution, changelog), which return `404 Not Found` for a free set. Endpoints for building and reviewing a set — including its member listings and associated_listings — work on free sets too. See the Dynamic Sets section for the full per-endpoint breakdown. Upgrade a free set via `POST /sets/{set_id}/upgrade`. - `filters` (object, nullable): The filter criteria used to select member listings (non-static sets). Keys are listing attributes/metrics, values contain `lower`/`upper` bounds or `one_of` lists. - `boundary` (array of array of array of array of number, nullable, each item each item each item min items: 2, max items: 2): The geographic boundary of the set as MultiPolygon coordinates (`[[[[lng, lat], ...]]]`), if one is defined. The four levels of nesting are: **polygons** → **rings** → **points** → **coordinates**. - **Polygons** (`boundary[i]`): Each element is one polygon. - **Rings** (`boundary[i][j]`): Each polygon contains one or more linear rings. The first ring is the exterior boundary (outer shell of the shape); any subsequent rings represent interior boundaries (holes inside the polygon). - **Points** (`boundary[i][j][k]`): Each ring is an array of `[longitude, latitude]` coordinate pairs. - **Coordinates** (`boundary[i][j][k][0/1]`): Each point is `[longitude, latitude]` as floating-point numbers. - `listing_counts` (object): Number of member listings in the set per status. - `active` (integer) - `hidden` (integer) - `review` (integer) - `removed` (integer) - `updated_at` (string (date-time)): When the set was last updated (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json { "id": 0, "user_id": 0, "name": "string", "description": "string", "kind": "competitive", "currency": "string", "is_static": true, "is_paid": true, "filters": {}, "boundary": [ [ [ [ 0, 0 ] ] ] ], "listing_counts": { "active": 0, "hidden": 0, "review": 0, "removed": 0 }, "updated_at": "2026-01-01T00:00:00Z" } ``` ### 401 API key authorization failed. ### 402 Payment required — there is no valid payment method on file, or the charge failed. ### 403 The API key is read-only, or the user is not the set's owner or a manager. ### 404 Dynamic set not found or not accessible to the user. ### 409 The dynamic set is already on a paid plan. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get aggregated metrics for a dynamic set. `GET /sets/{set_id}/aggregated_metrics` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-set-aggregated-metrics · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetSetAggregatedMetrics` · Tag: Dynamic Sets Returns monthly performance metrics aggregated across the active member listings of the set. Monetary values are converted to the requested currency (defaults to the set's currency). **Paid sets only.** Returns `404 Not Found` for a free set — upgrade it first with `POST /sets/{set_id}/upgrade`. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/aggregated_metrics` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `set_id` | integer | yes | The Wheelhouse internal dynamic set ID. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `currency` | string | no | ISO-4217 3-letter currency code to convert monetary metrics to. Defaults to the set's currency. | | `dates` | array of string (date) | no | Restrict the response to periods starting on these dates (first of month, YYYY-MM-DD). Send more than one in brackets (`?dates[]=2026-05-01&dates[]=2026-06-01`); a key repeated without brackets keeps only its last value. Defaults to all available periods. | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/aggregated_metrics' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Aggregated metrics per period. Body (`application/json`): object - `data` (array of object `set_aggregated_metric_response`) - Each item: Performance metrics for one month, aggregated across the active member listings of a dynamic set. Metric names follow the [Wheelhouse metrics definitions](https://www.usewheelhouse.com/research-metrics). Values derive from calendar prices and exclude fees and taxes. Monetary values are converted to the response `currency` and rounded to whole units; ratios are expressed as fractions (0–1). - `start_date` (string (date)): First day of the period (YYYY-MM-DD). - `end_date` (string (date)): Last day of the period (YYYY-MM-DD). - `occupancy` (number, nullable): Booked nights as a share of all calendar nights (`nights_booked / nights_calendar`). - `occupancy_adjusted` (number, nullable): Booked nights as a share of bookable nights, excluding blocked inventory (`nights_booked / nights_bookable`). - `nights_percent_open` (number, nullable): Share of calendar nights that are bookable (`nights_bookable / nights_calendar`), as a fraction. - `revenue` (number, nullable): Sum of rental prices for booked nights, excluding fees and taxes. - `adr` (number, nullable): Average Daily Rate — average price per booked night, excluding fees (`revenue / nights_booked`). - `asking_rate` (number, nullable): Asking Rate (Booked + Available Nights): average nightly price across booked and available nights, excluding fees. A booked night counts at the rate it was booked for, an available night at its current price. Blocked nights are left out. `null` when no night qualifies. See `asking_rate_available` for available nights only. - `asking_rate_available` (number, nullable): Asking Rate (Available Nights): sum of nightly prices on available nights / number of available nights, excluding fees. Booked and blocked nights, and nights without a price, count in neither. `null`, not `0`, when no available night has a price. - `revpar` (number, nullable): Revenue per available night, excluding fees (Average Daily Rate × Occupancy). - `revpar_adjusted` (number, nullable): Revenue per bookable night using adjusted occupancy, excluding fees and blocked inventory. - `revenue_available` (number, nullable): Potential earnings from currently available nights at current asking rates. - `revenue_blocked` (number, nullable): Unrealized revenue from blocked nights at current asking rates. - `lead_time` (number, nullable): Days between booking date and stay start date (median across the set's member listings). - `length_of_stay` (number, nullable): Nights per reservation (median across the set's member listings). - `nights_available` (number, nullable): Currently unbooked, bookable nights. - `nights_blocked` (number, nullable): Owner-blocked nights preventing bookings. - `nights_booked` (number, nullable): Currently reserved nights. - `nights_bookable` (number, nullable): Available plus booked nights, excluding blocked nights. - `nights_calendar` (integer, nullable): All nights in the period regardless of status. - `count_bookings` (integer, nullable): Total number of unique reservations. - `currency` (string): The ISO-4217 3-letter currency code of the monetary metrics. Example shape (generated from the schema; placeholder values, not a real response): ```json { "data": [ { "start_date": "2026-01-01", "end_date": "2026-01-01", "occupancy": 0, "occupancy_adjusted": 0, "nights_percent_open": 0, "revenue": 0, "adr": 0, "asking_rate": 0, "asking_rate_available": 0, "revpar": 0, "revpar_adjusted": 0, "revenue_available": 0, "revenue_blocked": 0, "lead_time": 0, "length_of_stay": 0, "nights_available": 0, "nights_blocked": 0, "nights_booked": 0, "nights_bookable": 0, "nights_calendar": 0, "count_bookings": 0 } ], "currency": "string" } ``` ### 401 API key authorization failed. ### 404 Dynamic set not found, not accessible to the user, or not a paid set. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # List the listings in a dynamic set. `GET /sets/{set_id}/listings` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-set-listings · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetSetListings` · Tag: Dynamic Sets Returns the member listings of the set with their trailing-year performance metrics, grouped by membership status (`active`, `hidden`, `review`, `removed`). Monetary metrics are converted to the set's currency. Works for both free and paid sets, so a set can be reviewed before it is upgraded; the same per-listing metrics are also available ungated via `GET /sets/candidates`. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/listings` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `set_id` | integer | yes | The Wheelhouse internal dynamic set ID. | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/listings' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Member listings grouped by status. Body (`application/json`): object - `active` (array of object `set_member_listing_response`) - Fields: see `set_member_listing_response` under Schemas. - `hidden` (array of object `set_member_listing_response`) - Fields: see `set_member_listing_response` under Schemas. - `review` (array of object `set_member_listing_response`) - Fields: see `set_member_listing_response` under Schemas. - `removed` (array of object `set_member_listing_response`) - Fields: see `set_member_listing_response` under Schemas. Example shape (generated from the schema; placeholder values, not a real response): ```json { "active": [ { "listing_id": 0, "title": "string", "source": "string", "url": "string", "thumb_url": "string", "owner_name": "string", "lat": 0, "long": 0, "market_id": 0, "currency": "string", "bedrooms": 0, "bathrooms": 0, "beds": 0, "sleeps": 0, "guests_included": 0, "room_type": "string", "property_type": "string", "amenities": [ "string" ], "cleaning_fee": 0, "star_rating": 0, "review_count": 0, "adr_365_0": 0, "asking_rate_365_0": 0, "occupancy_365_0": 0, "occupancy_adjusted_365_0": 0, "nights_percent_open_365_0": 0, "nights_percent_open_90_0": 0, "nights_available_365_0": 0, "nights_blocked_365_0": 0, "nights_bookable_365_0": 0, "nights_booked_365_0": 0, "lead_time_365_0": 0, "length_of_stay_365_0": 0, "revenue_365_0": 0, "revpar_365_0": 0, "revpar_adjusted_365_0": 0, "distance_meters": 0, "listing_created_at": "2026-01-01T00:00:00Z", "listing_last_updated": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "status": "active" } ], "hidden": [ { "listing_id": 0, "title": "string", "source": "string", "url": "string", "thumb_url": "string", "owner_name": "string", "lat": 0, "long": 0, "market_id": 0, "currency": "string", "bedrooms": 0, "bathrooms": 0, "beds": 0, "sleeps": 0, "guests_included": 0, "room_type": "string", "property_type": "string", "amenities": [ "string" ], "cleaning_fee": 0, "star_rating": 0, "review_count": 0, "adr_365_0": 0, "asking_rate_365_0": 0, "occupancy_365_0": 0, "occupancy_adjusted_365_0": 0, "nights_percent_open_365_0": 0, "nights_percent_open_90_0": 0, "nights_available_365_0": 0, "nights_blocked_365_0": 0, "nights_bookable_365_0": 0, "nights_booked_365_0": 0, "lead_time_365_0": 0, "length_of_stay_365_0": 0, "revenue_365_0": 0, "revpar_365_0": 0, "revpar_adjusted_365_0": 0, "distance_meters": 0, "listing_created_at": "2026-01-01T00:00:00Z", "listing_last_updated": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "status": "active" } ], "review": [ { "listing_id": 0, "title": "string", "source": "string", "url": "string", "thumb_url": "string", "owner_name": "string", "lat": 0, "long": 0, "market_id": 0, "currency": "string", "bedrooms": 0, "bathrooms": 0, "beds": 0, "sleeps": 0, "guests_included": 0, "room_type": "string", "property_type": "string", "amenities": [ "string" ], "cleaning_fee": 0, "star_rating": 0, "review_count": 0, "adr_365_0": 0, "asking_rate_365_0": 0, "occupancy_365_0": 0, "occupancy_adjusted_365_0": 0, "nights_percent_open_365_0": 0, "nights_percent_open_90_0": 0, "nights_available_365_0": 0, "nights_blocked_365_0": 0, "nights_bookable_365_0": 0, "nights_booked_365_0": 0, "lead_time_365_0": 0, "length_of_stay_365_0": 0, "revenue_365_0": 0, "revpar_365_0": 0, "revpar_adjusted_365_0": 0, "distance_meters": 0, "listing_created_at": "2026-01-01T00:00:00Z", "listing_last_updated": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "status": "active" } ], "removed": [ { "listing_id": 0, "title": "string", "source": "string", "url": "string", "thumb_url": "string", "owner_name": "string", "lat": 0, "long": 0, "market_id": 0, "currency": "string", "bedrooms": 0, "bathrooms": 0, "beds": 0, "sleeps": 0, "guests_included": 0, "room_type": "string", "property_type": "string", "amenities": [ "string" ], "cleaning_fee": 0, "star_rating": 0, "review_count": 0, "adr_365_0": 0, "asking_rate_365_0": 0, "occupancy_365_0": 0, "occupancy_adjusted_365_0": 0, "nights_percent_open_365_0": 0, "nights_percent_open_90_0": 0, "nights_available_365_0": 0, "nights_blocked_365_0": 0, "nights_bookable_365_0": 0, "nights_booked_365_0": 0, "lead_time_365_0": 0, "length_of_stay_365_0": 0, "revenue_365_0": 0, "revpar_365_0": 0, "revpar_adjusted_365_0": 0, "distance_meters": 0, "listing_created_at": "2026-01-01T00:00:00Z", "listing_last_updated": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "status": "active" } ] } ``` ### 401 API key authorization failed. ### 404 Dynamic set not found or not accessible to the user. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` ## Schemas Shared by more than one field above. ### `set_member_listing_response` Type: object `set_member_listing_response` A market listing that is a member of a dynamic set — the candidate listing shape plus its membership `status` within the set. A market listing with trailing-year performance metrics, named per the public [Wheelhouse metrics definitions](https://www.usewheelhouse.com/research-metrics). Metrics with the suffix `_365_0` cover the past 365 days; `_90_0` covers the past 90 days. When returned from a proximity search (`GET /sets/candidates`), `distance_meters` is the distance from the search center. - `listing_id` (integer, required): The Wheelhouse internal listing ID. - `title` (string, nullable): The listing title. - `source` (string, nullable): The channel the listing was sourced from. - `url` (string, nullable): Public URL of the listing on its channel. - `thumb_url` (string, nullable): Thumbnail image URL. - `owner_name` (string, nullable): The listing host/owner name. - `lat` (number): Latitude of the listing. - `long` (number): Longitude of the listing. - `market_id` (integer, nullable): The Wheelhouse internal market ID of the listing. - `currency` (string, nullable): The ISO-4217 3-letter currency code of the listing's monetary metrics. - `bedrooms` (integer, nullable): Number of bedrooms. - `bathrooms` (number, nullable): Number of bathrooms (may be fractional, e.g. 1.5). - `beds` (integer, nullable): Number of beds. - `sleeps` (integer, nullable): Maximum number of guests the listing sleeps. - `guests_included` (integer, nullable): Number of guests included in the base price. - `room_type` (string, nullable): The room type of the listing. - `property_type` (string, nullable): The property type of the listing. - `amenities` (array of string): List of amenities available at the listing. - `cleaning_fee` (integer, nullable): Cleaning fee amount in the listing's currency. - `star_rating` (number, nullable): Guest star rating. - `review_count` (integer, nullable): Number of guest reviews. - `adr_365_0` (number, nullable): Average Daily Rate — average nightly price over the past 365 days. - `asking_rate_365_0` (number, nullable): Average nightly asking price over the past 365 days. - `occupancy_365_0` (number, nullable): Occupancy over the past 365 days. - `occupancy_adjusted_365_0` (number, nullable): Adjusted occupancy (booked as a share of bookable nights, excluding blocked inventory) over the past 365 days. - `nights_percent_open_365_0` (number, nullable): Share of nights open for booking over the past 365 days. - `nights_percent_open_90_0` (number, nullable): Share of nights open for booking over the past 90 days. - `nights_available_365_0` (integer, nullable): Number of unbooked, bookable nights over the past 365 days. - `nights_blocked_365_0` (integer, nullable): Number of owner-blocked nights over the past 365 days. - `nights_bookable_365_0` (integer, nullable): Available plus booked nights, excluding blocked nights, over the past 365 days. - `nights_booked_365_0` (integer, nullable): Number of reserved nights over the past 365 days. - `lead_time_365_0` (number, nullable): Average booking lead time in days over the past 365 days. - `length_of_stay_365_0` (number, nullable): Average length of stay over the past 365 days. - `revenue_365_0` (number, nullable): Rental revenue over the past 365 days. - `revpar_365_0` (number, nullable): Revenue per available night over the past 365 days. - `revpar_adjusted_365_0` (number, nullable): Revenue per bookable night, excluding blocked inventory, over the past 365 days. - `distance_meters` (integer): Distance from the search origin, if applicable. - `listing_created_at` (string (date-time), nullable): When the listing was first indexed by Wheelhouse (ISO-8601). - `listing_last_updated` (string (date-time), nullable): When the listing data was last updated (ISO-8601). - `updated_at` (string (date-time)): When this listing's metrics record was last updated (ISO-8601). - `status` (string, one of: `active`, `hidden`, `review`, `removed`): The membership status of the listing within the set. --- # Add member listings to a dynamic set. `PUT /sets/{set_id}/listings` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-put-set-listings · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPutSetListings` · Tag: Dynamic Sets Adds the given listings to the set as members — the comparison listings the set is built from. Identify them by the internal `listing_id` values returned by `GET /sets/candidates`; only listings that are eligible comparison candidates can be added. Returns the set's member listings after the change, in the same shape as `GET /sets/{set_id}/listings`. Requires editor or manager access to the set when the set is shared. **Works for free and paid sets.** This is an upsert: a listing already in the set keeps its single membership and takes the requested `status`, so repeating an identical call leaves the set in the same state. ## Request `PUT https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/listings` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `set_id` | integer | yes | The Wheelhouse internal dynamic set ID. | ### Request body (`application/json`, required) - `listing_ids` (array of integer, required, max items: 500): Internal listing IDs to add as members — the `listing_id` values returned by `GET /sets/candidates`, not channel listing IDs. A listing already in the set is not duplicated. At most 500 per request. - `status` (string, one of: `active`, `hidden`, `review`, `removed`, default: `active`): Membership status to add the listings with. Defaults to `active`. This applies to listings already in the set as well, so omitting it moves an existing `hidden`, `review` or `removed` member back to `active` — pass the status explicitly when re-sending a list that includes existing members. ### Example request ```bash curl -X PUT 'https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/listings' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{ "listing_ids": [ 0 ] }' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The set's member listings after the change, grouped by status. Body (`application/json`): object - `active` (array of object `set_member_listing_response`) - Fields: see `set_member_listing_response` under Schemas. - `hidden` (array of object `set_member_listing_response`) - Fields: see `set_member_listing_response` under Schemas. - `review` (array of object `set_member_listing_response`) - Fields: see `set_member_listing_response` under Schemas. - `removed` (array of object `set_member_listing_response`) - Fields: see `set_member_listing_response` under Schemas. Example shape (generated from the schema; placeholder values, not a real response): ```json { "active": [ { "listing_id": 0, "title": "string", "source": "string", "url": "string", "thumb_url": "string", "owner_name": "string", "lat": 0, "long": 0, "market_id": 0, "currency": "string", "bedrooms": 0, "bathrooms": 0, "beds": 0, "sleeps": 0, "guests_included": 0, "room_type": "string", "property_type": "string", "amenities": [ "string" ], "cleaning_fee": 0, "star_rating": 0, "review_count": 0, "adr_365_0": 0, "asking_rate_365_0": 0, "occupancy_365_0": 0, "occupancy_adjusted_365_0": 0, "nights_percent_open_365_0": 0, "nights_percent_open_90_0": 0, "nights_available_365_0": 0, "nights_blocked_365_0": 0, "nights_bookable_365_0": 0, "nights_booked_365_0": 0, "lead_time_365_0": 0, "length_of_stay_365_0": 0, "revenue_365_0": 0, "revpar_365_0": 0, "revpar_adjusted_365_0": 0, "distance_meters": 0, "listing_created_at": "2026-01-01T00:00:00Z", "listing_last_updated": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "status": "active" } ], "hidden": [ { "listing_id": 0, "title": "string", "source": "string", "url": "string", "thumb_url": "string", "owner_name": "string", "lat": 0, "long": 0, "market_id": 0, "currency": "string", "bedrooms": 0, "bathrooms": 0, "beds": 0, "sleeps": 0, "guests_included": 0, "room_type": "string", "property_type": "string", "amenities": [ "string" ], "cleaning_fee": 0, "star_rating": 0, "review_count": 0, "adr_365_0": 0, "asking_rate_365_0": 0, "occupancy_365_0": 0, "occupancy_adjusted_365_0": 0, "nights_percent_open_365_0": 0, "nights_percent_open_90_0": 0, "nights_available_365_0": 0, "nights_blocked_365_0": 0, "nights_bookable_365_0": 0, "nights_booked_365_0": 0, "lead_time_365_0": 0, "length_of_stay_365_0": 0, "revenue_365_0": 0, "revpar_365_0": 0, "revpar_adjusted_365_0": 0, "distance_meters": 0, "listing_created_at": "2026-01-01T00:00:00Z", "listing_last_updated": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "status": "active" } ], "review": [ { "listing_id": 0, "title": "string", "source": "string", "url": "string", "thumb_url": "string", "owner_name": "string", "lat": 0, "long": 0, "market_id": 0, "currency": "string", "bedrooms": 0, "bathrooms": 0, "beds": 0, "sleeps": 0, "guests_included": 0, "room_type": "string", "property_type": "string", "amenities": [ "string" ], "cleaning_fee": 0, "star_rating": 0, "review_count": 0, "adr_365_0": 0, "asking_rate_365_0": 0, "occupancy_365_0": 0, "occupancy_adjusted_365_0": 0, "nights_percent_open_365_0": 0, "nights_percent_open_90_0": 0, "nights_available_365_0": 0, "nights_blocked_365_0": 0, "nights_bookable_365_0": 0, "nights_booked_365_0": 0, "lead_time_365_0": 0, "length_of_stay_365_0": 0, "revenue_365_0": 0, "revpar_365_0": 0, "revpar_adjusted_365_0": 0, "distance_meters": 0, "listing_created_at": "2026-01-01T00:00:00Z", "listing_last_updated": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "status": "active" } ], "removed": [ { "listing_id": 0, "title": "string", "source": "string", "url": "string", "thumb_url": "string", "owner_name": "string", "lat": 0, "long": 0, "market_id": 0, "currency": "string", "bedrooms": 0, "bathrooms": 0, "beds": 0, "sleeps": 0, "guests_included": 0, "room_type": "string", "property_type": "string", "amenities": [ "string" ], "cleaning_fee": 0, "star_rating": 0, "review_count": 0, "adr_365_0": 0, "asking_rate_365_0": 0, "occupancy_365_0": 0, "occupancy_adjusted_365_0": 0, "nights_percent_open_365_0": 0, "nights_percent_open_90_0": 0, "nights_available_365_0": 0, "nights_blocked_365_0": 0, "nights_bookable_365_0": 0, "nights_booked_365_0": 0, "lead_time_365_0": 0, "length_of_stay_365_0": 0, "revenue_365_0": 0, "revpar_365_0": 0, "revpar_adjusted_365_0": 0, "distance_meters": 0, "listing_created_at": "2026-01-01T00:00:00Z", "listing_last_updated": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "status": "active" } ] } ``` ### 400 More than 500 listing IDs were sent. ### 401 API key authorization failed. ### 403 The set is shared with the user without editor or manager access, or the API key is read-only and may not be used with PUT. ### 404 Dynamic set not found or not accessible to the user, or one or more listing IDs are not eligible as members. ### 409 Another request is already in progress for this set. Retry after the concurrent request completes. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` ## Schemas Shared by more than one field above. ### `set_member_listing_response` Type: object `set_member_listing_response` A market listing that is a member of a dynamic set — the candidate listing shape plus its membership `status` within the set. A market listing with trailing-year performance metrics, named per the public [Wheelhouse metrics definitions](https://www.usewheelhouse.com/research-metrics). Metrics with the suffix `_365_0` cover the past 365 days; `_90_0` covers the past 90 days. When returned from a proximity search (`GET /sets/candidates`), `distance_meters` is the distance from the search center. - `listing_id` (integer, required): The Wheelhouse internal listing ID. - `title` (string, nullable): The listing title. - `source` (string, nullable): The channel the listing was sourced from. - `url` (string, nullable): Public URL of the listing on its channel. - `thumb_url` (string, nullable): Thumbnail image URL. - `owner_name` (string, nullable): The listing host/owner name. - `lat` (number): Latitude of the listing. - `long` (number): Longitude of the listing. - `market_id` (integer, nullable): The Wheelhouse internal market ID of the listing. - `currency` (string, nullable): The ISO-4217 3-letter currency code of the listing's monetary metrics. - `bedrooms` (integer, nullable): Number of bedrooms. - `bathrooms` (number, nullable): Number of bathrooms (may be fractional, e.g. 1.5). - `beds` (integer, nullable): Number of beds. - `sleeps` (integer, nullable): Maximum number of guests the listing sleeps. - `guests_included` (integer, nullable): Number of guests included in the base price. - `room_type` (string, nullable): The room type of the listing. - `property_type` (string, nullable): The property type of the listing. - `amenities` (array of string): List of amenities available at the listing. - `cleaning_fee` (integer, nullable): Cleaning fee amount in the listing's currency. - `star_rating` (number, nullable): Guest star rating. - `review_count` (integer, nullable): Number of guest reviews. - `adr_365_0` (number, nullable): Average Daily Rate — average nightly price over the past 365 days. - `asking_rate_365_0` (number, nullable): Average nightly asking price over the past 365 days. - `occupancy_365_0` (number, nullable): Occupancy over the past 365 days. - `occupancy_adjusted_365_0` (number, nullable): Adjusted occupancy (booked as a share of bookable nights, excluding blocked inventory) over the past 365 days. - `nights_percent_open_365_0` (number, nullable): Share of nights open for booking over the past 365 days. - `nights_percent_open_90_0` (number, nullable): Share of nights open for booking over the past 90 days. - `nights_available_365_0` (integer, nullable): Number of unbooked, bookable nights over the past 365 days. - `nights_blocked_365_0` (integer, nullable): Number of owner-blocked nights over the past 365 days. - `nights_bookable_365_0` (integer, nullable): Available plus booked nights, excluding blocked nights, over the past 365 days. - `nights_booked_365_0` (integer, nullable): Number of reserved nights over the past 365 days. - `lead_time_365_0` (number, nullable): Average booking lead time in days over the past 365 days. - `length_of_stay_365_0` (number, nullable): Average length of stay over the past 365 days. - `revenue_365_0` (number, nullable): Rental revenue over the past 365 days. - `revpar_365_0` (number, nullable): Revenue per available night over the past 365 days. - `revpar_adjusted_365_0` (number, nullable): Revenue per bookable night, excluding blocked inventory, over the past 365 days. - `distance_meters` (integer): Distance from the search origin, if applicable. - `listing_created_at` (string (date-time), nullable): When the listing was first indexed by Wheelhouse (ISO-8601). - `listing_last_updated` (string (date-time), nullable): When the listing data was last updated (ISO-8601). - `updated_at` (string (date-time)): When this listing's metrics record was last updated (ISO-8601). - `status` (string, one of: `active`, `hidden`, `review`, `removed`): The membership status of the listing within the set. --- # Remove member listings from a dynamic set. `DELETE /sets/{set_id}/listings` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-delete-set-listings · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmDeleteSetListings` · Tag: Dynamic Sets Removes the given listings from the set's membership. Identify them by their internal `listing_id`. Returns the set's member listings after the change, in the same shape as `GET /sets/{set_id}/listings`. Requires editor or manager access to the set when the set is shared. **Works for free and paid sets.** Note that on a filter-based (non-static) set, membership is derived from the set's own filters, so removed members may be restored by the next sync — the same behaviour as the Wheelhouse app. ## Request `DELETE https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/listings` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `set_id` | integer | yes | The Wheelhouse internal dynamic set ID. | ### Request body (`application/json`, required) - `listing_ids` (array of integer, required, max items: 500): Internal listing IDs to remove from the set. IDs that are not members are ignored. At most 500 per request. ### Example request ```bash curl -X DELETE 'https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/listings' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{ "listing_ids": [ 0 ] }' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The set's member listings after the change, grouped by status. Body (`application/json`): object - `active` (array of object `set_member_listing_response`) - Fields: see `set_member_listing_response` under Schemas. - `hidden` (array of object `set_member_listing_response`) - Fields: see `set_member_listing_response` under Schemas. - `review` (array of object `set_member_listing_response`) - Fields: see `set_member_listing_response` under Schemas. - `removed` (array of object `set_member_listing_response`) - Fields: see `set_member_listing_response` under Schemas. Example shape (generated from the schema; placeholder values, not a real response): ```json { "active": [ { "listing_id": 0, "title": "string", "source": "string", "url": "string", "thumb_url": "string", "owner_name": "string", "lat": 0, "long": 0, "market_id": 0, "currency": "string", "bedrooms": 0, "bathrooms": 0, "beds": 0, "sleeps": 0, "guests_included": 0, "room_type": "string", "property_type": "string", "amenities": [ "string" ], "cleaning_fee": 0, "star_rating": 0, "review_count": 0, "adr_365_0": 0, "asking_rate_365_0": 0, "occupancy_365_0": 0, "occupancy_adjusted_365_0": 0, "nights_percent_open_365_0": 0, "nights_percent_open_90_0": 0, "nights_available_365_0": 0, "nights_blocked_365_0": 0, "nights_bookable_365_0": 0, "nights_booked_365_0": 0, "lead_time_365_0": 0, "length_of_stay_365_0": 0, "revenue_365_0": 0, "revpar_365_0": 0, "revpar_adjusted_365_0": 0, "distance_meters": 0, "listing_created_at": "2026-01-01T00:00:00Z", "listing_last_updated": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "status": "active" } ], "hidden": [ { "listing_id": 0, "title": "string", "source": "string", "url": "string", "thumb_url": "string", "owner_name": "string", "lat": 0, "long": 0, "market_id": 0, "currency": "string", "bedrooms": 0, "bathrooms": 0, "beds": 0, "sleeps": 0, "guests_included": 0, "room_type": "string", "property_type": "string", "amenities": [ "string" ], "cleaning_fee": 0, "star_rating": 0, "review_count": 0, "adr_365_0": 0, "asking_rate_365_0": 0, "occupancy_365_0": 0, "occupancy_adjusted_365_0": 0, "nights_percent_open_365_0": 0, "nights_percent_open_90_0": 0, "nights_available_365_0": 0, "nights_blocked_365_0": 0, "nights_bookable_365_0": 0, "nights_booked_365_0": 0, "lead_time_365_0": 0, "length_of_stay_365_0": 0, "revenue_365_0": 0, "revpar_365_0": 0, "revpar_adjusted_365_0": 0, "distance_meters": 0, "listing_created_at": "2026-01-01T00:00:00Z", "listing_last_updated": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "status": "active" } ], "review": [ { "listing_id": 0, "title": "string", "source": "string", "url": "string", "thumb_url": "string", "owner_name": "string", "lat": 0, "long": 0, "market_id": 0, "currency": "string", "bedrooms": 0, "bathrooms": 0, "beds": 0, "sleeps": 0, "guests_included": 0, "room_type": "string", "property_type": "string", "amenities": [ "string" ], "cleaning_fee": 0, "star_rating": 0, "review_count": 0, "adr_365_0": 0, "asking_rate_365_0": 0, "occupancy_365_0": 0, "occupancy_adjusted_365_0": 0, "nights_percent_open_365_0": 0, "nights_percent_open_90_0": 0, "nights_available_365_0": 0, "nights_blocked_365_0": 0, "nights_bookable_365_0": 0, "nights_booked_365_0": 0, "lead_time_365_0": 0, "length_of_stay_365_0": 0, "revenue_365_0": 0, "revpar_365_0": 0, "revpar_adjusted_365_0": 0, "distance_meters": 0, "listing_created_at": "2026-01-01T00:00:00Z", "listing_last_updated": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "status": "active" } ], "removed": [ { "listing_id": 0, "title": "string", "source": "string", "url": "string", "thumb_url": "string", "owner_name": "string", "lat": 0, "long": 0, "market_id": 0, "currency": "string", "bedrooms": 0, "bathrooms": 0, "beds": 0, "sleeps": 0, "guests_included": 0, "room_type": "string", "property_type": "string", "amenities": [ "string" ], "cleaning_fee": 0, "star_rating": 0, "review_count": 0, "adr_365_0": 0, "asking_rate_365_0": 0, "occupancy_365_0": 0, "occupancy_adjusted_365_0": 0, "nights_percent_open_365_0": 0, "nights_percent_open_90_0": 0, "nights_available_365_0": 0, "nights_blocked_365_0": 0, "nights_bookable_365_0": 0, "nights_booked_365_0": 0, "lead_time_365_0": 0, "length_of_stay_365_0": 0, "revenue_365_0": 0, "revpar_365_0": 0, "revpar_adjusted_365_0": 0, "distance_meters": 0, "listing_created_at": "2026-01-01T00:00:00Z", "listing_last_updated": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "status": "active" } ] } ``` ### 400 More than 500 listing IDs were sent. ### 401 API key authorization failed. ### 403 The set is shared with the user without editor or manager access, or the API key is read-only and may not be used with DELETE. ### 404 Dynamic set not found or not accessible to the user. ### 409 Another request is already in progress for this set. Retry after the concurrent request completes. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` ## Schemas Shared by more than one field above. ### `set_member_listing_response` Type: object `set_member_listing_response` A market listing that is a member of a dynamic set — the candidate listing shape plus its membership `status` within the set. A market listing with trailing-year performance metrics, named per the public [Wheelhouse metrics definitions](https://www.usewheelhouse.com/research-metrics). Metrics with the suffix `_365_0` cover the past 365 days; `_90_0` covers the past 90 days. When returned from a proximity search (`GET /sets/candidates`), `distance_meters` is the distance from the search center. - `listing_id` (integer, required): The Wheelhouse internal listing ID. - `title` (string, nullable): The listing title. - `source` (string, nullable): The channel the listing was sourced from. - `url` (string, nullable): Public URL of the listing on its channel. - `thumb_url` (string, nullable): Thumbnail image URL. - `owner_name` (string, nullable): The listing host/owner name. - `lat` (number): Latitude of the listing. - `long` (number): Longitude of the listing. - `market_id` (integer, nullable): The Wheelhouse internal market ID of the listing. - `currency` (string, nullable): The ISO-4217 3-letter currency code of the listing's monetary metrics. - `bedrooms` (integer, nullable): Number of bedrooms. - `bathrooms` (number, nullable): Number of bathrooms (may be fractional, e.g. 1.5). - `beds` (integer, nullable): Number of beds. - `sleeps` (integer, nullable): Maximum number of guests the listing sleeps. - `guests_included` (integer, nullable): Number of guests included in the base price. - `room_type` (string, nullable): The room type of the listing. - `property_type` (string, nullable): The property type of the listing. - `amenities` (array of string): List of amenities available at the listing. - `cleaning_fee` (integer, nullable): Cleaning fee amount in the listing's currency. - `star_rating` (number, nullable): Guest star rating. - `review_count` (integer, nullable): Number of guest reviews. - `adr_365_0` (number, nullable): Average Daily Rate — average nightly price over the past 365 days. - `asking_rate_365_0` (number, nullable): Average nightly asking price over the past 365 days. - `occupancy_365_0` (number, nullable): Occupancy over the past 365 days. - `occupancy_adjusted_365_0` (number, nullable): Adjusted occupancy (booked as a share of bookable nights, excluding blocked inventory) over the past 365 days. - `nights_percent_open_365_0` (number, nullable): Share of nights open for booking over the past 365 days. - `nights_percent_open_90_0` (number, nullable): Share of nights open for booking over the past 90 days. - `nights_available_365_0` (integer, nullable): Number of unbooked, bookable nights over the past 365 days. - `nights_blocked_365_0` (integer, nullable): Number of owner-blocked nights over the past 365 days. - `nights_bookable_365_0` (integer, nullable): Available plus booked nights, excluding blocked nights, over the past 365 days. - `nights_booked_365_0` (integer, nullable): Number of reserved nights over the past 365 days. - `lead_time_365_0` (number, nullable): Average booking lead time in days over the past 365 days. - `length_of_stay_365_0` (number, nullable): Average length of stay over the past 365 days. - `revenue_365_0` (number, nullable): Rental revenue over the past 365 days. - `revpar_365_0` (number, nullable): Revenue per available night over the past 365 days. - `revpar_adjusted_365_0` (number, nullable): Revenue per bookable night, excluding blocked inventory, over the past 365 days. - `distance_meters` (integer): Distance from the search origin, if applicable. - `listing_created_at` (string (date-time), nullable): When the listing was first indexed by Wheelhouse (ISO-8601). - `listing_last_updated` (string (date-time), nullable): When the listing data was last updated (ISO-8601). - `updated_at` (string (date-time)): When this listing's metrics record was last updated (ISO-8601). - `status` (string, one of: `active`, `hidden`, `review`, `removed`): The membership status of the listing within the set. --- # List the user listings associated with a dynamic set. `GET /sets/{set_id}/associated_listings` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-set-associated-listings · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetSetAssociatedListings` · Tag: Dynamic Sets Returns the user's own listings that are associated with the set for comparison. Listings are returned in the standard RM API listing format; the `id` field is the channel listing ID used by the PUT and DELETE endpoints. For shared sets, associated listings the authenticated user does not have access to are omitted. Works for both free and paid sets: associating a listing is set configuration, not KPI data. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/associated_listings` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `set_id` | integer | yes | The Wheelhouse internal dynamic set ID. | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/associated_listings' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of associated listings. Body (`application/json`): array of object `listing_response` A listing as returned by the RM API. - `id` (string, required): The channel's unique listing identifier. Always the channel's ID, whichever way the request identified the listing; the Wheelhouse listing ID is the separate `wheelhouse_id` field. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). - `channel` (string, required): The channel name of the listing. - `wheelhouse_id` (integer, nullable): The Wheelhouse internal listing ID. - `title` (string, nullable): The listing's name. - `nickname` (string, nullable): Listing nickname used as a shortened title. - `description` (string, nullable): The listing's description text. - `location` (object, nullable): The listing's location. - `country` (string, nullable): ISO-3166 2-letter country code. - `postal_code` (string, nullable) - `address` (string, nullable) - `latitude` (number, nullable) - `longitude` (number, nullable) - `num_bedrooms` (integer, nullable): Number of bedrooms. - `num_beds` (integer, nullable): Number of beds. - `num_bathrooms` (number, nullable): Number of bathrooms (may be fractional, e.g. 1.5). - `room_type` (string, nullable): The room type of the listing. - `property_type` (string, nullable): The property type of the listing. - `currency` (string, nullable): The ISO-4217 3-letter currency code of the listing. - `star_rating` (number, nullable): Star rating. - `num_reviews` (integer, nullable): Number of reviews. - `num_photos` (integer, nullable): Number of photos. - `thumb_url` (string, nullable): URL of the listing's thumbnail image. - `access_level` (string, nullable, one of: `owner`, `viewer`, `restricted_editor`, `editor`, `manager`): How the authenticated user accesses this listing in the RM API: `owner` for listings on their account, or the delegated role when shared access applies (`viewer`, `restricted_editor`, `editor`, `manager`). **API permissions by level:** - `owner`, `editor`, `manager` — full read and write access (GET, PUT, POST, DELETE). - `restricted_editor` — read and write access to the listing itself, except that `PUT /listings/{listing_id}/tags` returns 403 and the batch `PUT /preferences` reports the listing in `errors` with status 403. - `viewer` — read-only; write endpoints (PUT, POST, DELETE) return 403, except that a viewer may remove the listing from a set with `DELETE /sets/{set_id}/associated_listings`. - `amenities` (array of string, nullable): List of amenities available at the listing. - `owner_name` (string, nullable): The property owner's name, as supplied by the channel. This is display text about the physical property's owner and is unrelated to the Wheelhouse account that holds the listing — see `owner_user` for that. - `owner_user` (object, nullable): The Wheelhouse account this listing belongs to. Use this to tell whose portfolio a listing sits in when a response mixes owned and managed listings — for example `GET /listings?include_managed_listings=true`, or the listings of a portfolio segment or dynamic set. For listings the authenticated user owns (`access_level` of `owner`) this is the authenticated user's own account. For managed listings it is the account that granted the shared access. - `id` (integer): The Wheelhouse internal user ID of the owning account. - `email` (string): Email address of the owning account. - `first_name` (string, nullable): First name of the owning account. - `last_name` (string, nullable): Last name of the owning account. - `source_user_id` (string, nullable): The ID of the listing's host on the source channel, as reported by that channel. This is an identifier in the channel's own namespace, not a Wheelhouse account — see `owner_user` for the Wheelhouse account the listing belongs to. - `channel_ids` (object, nullable): A mapping of channel names to the channel's listing ID. - `airbnb` (string, nullable) - `tripadvisor` (string, nullable) - `vrbo` (string, nullable) - `wheelhouse` (string, nullable) - `links` (object, nullable): Useful links to the Wheelhouse app. - `calendar` (string, nullable): Link to the listing calendar page on Wheelhouse. - `upgrade` (string, nullable): Link to the upgrade flow for this listing on Wheelhouse. - `security_deposit` (number, nullable): Security deposit amount in the listing's currency. - `base_min_night_stay` (integer, nullable): The minimum night stay floor for this listing. - `listing_preferences` (object, nullable): A summary of the listing's pricing preferences and fee configuration. Use `GET /preferences/{listing_id}` for the full structured preference object, including date-specific rules. - `automatic_rate_posting_enabled` (boolean, nullable): Whether recommended prices are posted to the channel automatically. - `base_price` (number, nullable): The base price the user set by hand, in the listing's currency. `null` does not mean the listing has no base price. It means the base price follows the Wheelhouse recommendation, multiplied by `base_price_adjustment` (or by `1.0` when that is also `null`). To read the base price in use, call `GET /listings/{listing_id}/price_recommendations` and read its top-level `base_price`. - `base_price_adjustment` (number, nullable): Multiplier applied to the recommended base price when `base_price` is `null`. The presets are `0.9` (conservative), `1.0` (recommended), and `1.1` (aggressive). Any other value is a custom adjustment. When both fields are `null`, the pricing engine uses `1.0`. - `fees` (array of object): Fees charged when booking the listing. Only fees with a configured value are listed. - `name` (string, required): The name of the fee as it appears on line items. - `type` (string, required, one of: `cleaning`, `extra_guest`): Classification of the fee. - `multiplier` (string, required, one of: `PER_STAY`, `PER_NIGHT`): What the fee is charged per. - `value_type` (string, required, one of: `FIXED`, `PERCENTAGE`): Whether `value` is a fixed amount in the listing's currency or a percentage of the booking value. - `value` (number, required): The fee amount. - `max_price` (integer): The global maximum nightly price for automated pricing. Only present when a maximum price is configured. - `min_price` (integer): The global minimum nightly price for automated pricing. Only present when a minimum price is configured. - `minimum_stay` (integer): The global minimum stay in nights. Only present when a minimum stay is configured. - `monthly_discount_pct` (number, nullable): The percent discount given to bookings of 28 nights or more. - `nickname` (string, nullable): User-editable nickname for the listing. - `num_included_guests` (integer, nullable): The number of guests included in the nightly price. - `num_max_guests` (integer, nullable): The maximum number of guests the listing sleeps. - `weekly_discount_pct` (number, nullable): The percent discount given to bookings of 7 nights or more. - `meta` (object, nullable): Supplementary listing attributes. `photos` is present only where photos are requested, such as `GET /listings` with `include_photos=true`; the other fields repeat the top-level fields of the same name. - `amenities` (array of string, nullable) - `num_beds` (integer, nullable) - `num_photos` (integer, nullable) - `num_reviews` (integer, nullable) - `photos` (array of object, nullable): The listing's photos. - `caption` (string, nullable): The photo's caption. - `regular` (string, nullable): URL of the web-sized photo. - `thumbnail` (string, nullable): URL of the thumbnail-sized photo. - `security_deposit` (number, nullable) - `source_user_id` (string, nullable) - `star_rating` (number, nullable) - `market_id` (integer, nullable): The Wheelhouse market ID for this listing. - `market_name` (string, nullable): The human-readable name of the market identified by `market_id`, e.g. `San Francisco, CA, United States`. It is the same `market_name` that `GET /market_report` returns, so there is no need to look it up there. `null` when the listing has no market. - `is_active` (boolean, nullable): Whether the listing is currently active. - `is_hidden` (boolean): Whether the listing has been hidden in the Wheelhouse app. Hiding a listing does not deactivate or disconnect it, so a hidden listing is still returned with `exclude_inactive=true`; filter on this field to leave hidden listings out. Unrelated to the `hidden` membership status of a listing in a dynamic set. - `wheelhouse_created_at` (string, nullable): The datetime the listing was created in Wheelhouse (Rails-style timestamp, e.g. `2016-09-20 02:07:32 -0700`). - `number_of_active_units` (integer, nullable): The number of independently bookable units under this listing. `null` for standard single-unit listings; a positive integer for multi-unit listings. See the **Multi-Unit Listings** section in the overview. - `supported_settings` (object `supported_settings`, read-only): Which listing preference settings this listing's channel can act on. A setting reported `false` is discarded on write rather than posted to the channel, so check this before sending it. Reflects any per-account early access, so two listings on the same channel can differ. - `checkin_checkout` (boolean): Whether `checkin_checkout` rules can be set. - `min_stays` (boolean): Whether minimum stay settings (`min_min_stay`, `min_stays_enabled`, `minimum_stay_rules`) can be set. - `long_term_discounts` (boolean): Whether long-term discounts (`long_term_discounts`, `weekly_discount`, `monthly_discount`) can be set at all. - `long_term_discount_type` (string, one of: `disabled`, `simple`, `rules`, `complex`): The form of long-term discount the channel accepts. `disabled` takes none; `simple` takes only flat `weekly_discount` and `monthly_discount` values and ignores a `rules` object; `rules` additionally takes the 7 and 28 night tiers; `complex` takes arbitrary tiers. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "id": "string", "channel": "string", "wheelhouse_id": 0, "title": "string", "nickname": "string", "description": "string", "location": { "country": "string", "postal_code": "string", "address": "string", "latitude": 0, "longitude": 0 }, "num_bedrooms": 0, "num_beds": 0, "num_bathrooms": 0, "room_type": "string", "property_type": "string", "currency": "string", "star_rating": 0, "num_reviews": 0, "num_photos": 0, "thumb_url": "string", "access_level": "owner", "amenities": [ "string" ], "owner_name": "string", "owner_user": { "id": 0, "email": "string", "first_name": "string", "last_name": "string" }, "source_user_id": "string", "channel_ids": { "airbnb": "string", "tripadvisor": "string", "vrbo": "string", "wheelhouse": "string" }, "links": { "calendar": "string", "upgrade": "string" }, "security_deposit": 0, "base_min_night_stay": 0, "listing_preferences": { "automatic_rate_posting_enabled": true, "base_price": 0, "base_price_adjustment": 0, "fees": [ { "name": "string", "type": "cleaning", "multiplier": "PER_STAY", "value_type": "FIXED", "value": 0 } ], "max_price": 0, "min_price": 0, "minimum_stay": 0, "monthly_discount_pct": 0, "nickname": "string", "num_included_guests": 0, "num_max_guests": 0, "weekly_discount_pct": 0 }, "meta": { "amenities": [ "string" ], "num_beds": 0, "num_photos": 0, "num_reviews": 0, "photos": [ { "caption": "string", "regular": "string", "thumbnail": "string" } ], "security_deposit": 0, "source_user_id": "string", "star_rating": 0 }, "market_id": 0, "market_name": "string", "is_active": true, "is_hidden": true, "wheelhouse_created_at": "string", "number_of_active_units": 0, "supported_settings": { "checkin_checkout": true, "min_stays": true, "long_term_discounts": true, "long_term_discount_type": "disabled" } } ] ``` ### 401 API key authorization failed. ### 404 Dynamic set not found or not accessible to the user. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Associate user listings with a dynamic set. `PUT /sets/{set_id}/associated_listings` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-put-set-associated-listings · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPutSetAssociatedListings` · Tag: Dynamic Sets Associates the given listings (the authenticated user's own listings, identified by their channel listing IDs) with the set for comparison. Listings that are already associated are left unchanged. Requires editor or manager access to the set when the set is shared. Works for both free and paid sets: associating a listing is set configuration, not KPI data. ## Request `PUT https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/associated_listings` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `set_id` | integer | yes | The Wheelhouse internal dynamic set ID. | ### Request body (`application/json`, required) - `listing_ids` (array of string, required, max items: 500): Channel listing IDs of the user's listings to associate, or their Wheelhouse listing IDs when `channel` is `wheelhouse`. At most 500 per request. - `channel` (string): Channel name the listings are on, or the literal `wheelhouse` to read `listing_ids` as Wheelhouse listing IDs instead. Required if it cannot be derived from the API key. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). ### Example request ```bash curl -X PUT 'https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/associated_listings' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{ "listing_ids": [ "string" ] }' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The updated array of associated listings. Body (`application/json`): array of object `listing_response` A listing as returned by the RM API. - `id` (string, required): The channel's unique listing identifier. Always the channel's ID, whichever way the request identified the listing; the Wheelhouse listing ID is the separate `wheelhouse_id` field. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). - `channel` (string, required): The channel name of the listing. - `wheelhouse_id` (integer, nullable): The Wheelhouse internal listing ID. - `title` (string, nullable): The listing's name. - `nickname` (string, nullable): Listing nickname used as a shortened title. - `description` (string, nullable): The listing's description text. - `location` (object, nullable): The listing's location. - `country` (string, nullable): ISO-3166 2-letter country code. - `postal_code` (string, nullable) - `address` (string, nullable) - `latitude` (number, nullable) - `longitude` (number, nullable) - `num_bedrooms` (integer, nullable): Number of bedrooms. - `num_beds` (integer, nullable): Number of beds. - `num_bathrooms` (number, nullable): Number of bathrooms (may be fractional, e.g. 1.5). - `room_type` (string, nullable): The room type of the listing. - `property_type` (string, nullable): The property type of the listing. - `currency` (string, nullable): The ISO-4217 3-letter currency code of the listing. - `star_rating` (number, nullable): Star rating. - `num_reviews` (integer, nullable): Number of reviews. - `num_photos` (integer, nullable): Number of photos. - `thumb_url` (string, nullable): URL of the listing's thumbnail image. - `access_level` (string, nullable, one of: `owner`, `viewer`, `restricted_editor`, `editor`, `manager`): How the authenticated user accesses this listing in the RM API: `owner` for listings on their account, or the delegated role when shared access applies (`viewer`, `restricted_editor`, `editor`, `manager`). **API permissions by level:** - `owner`, `editor`, `manager` — full read and write access (GET, PUT, POST, DELETE). - `restricted_editor` — read and write access to the listing itself, except that `PUT /listings/{listing_id}/tags` returns 403 and the batch `PUT /preferences` reports the listing in `errors` with status 403. - `viewer` — read-only; write endpoints (PUT, POST, DELETE) return 403, except that a viewer may remove the listing from a set with `DELETE /sets/{set_id}/associated_listings`. - `amenities` (array of string, nullable): List of amenities available at the listing. - `owner_name` (string, nullable): The property owner's name, as supplied by the channel. This is display text about the physical property's owner and is unrelated to the Wheelhouse account that holds the listing — see `owner_user` for that. - `owner_user` (object, nullable): The Wheelhouse account this listing belongs to. Use this to tell whose portfolio a listing sits in when a response mixes owned and managed listings — for example `GET /listings?include_managed_listings=true`, or the listings of a portfolio segment or dynamic set. For listings the authenticated user owns (`access_level` of `owner`) this is the authenticated user's own account. For managed listings it is the account that granted the shared access. - `id` (integer): The Wheelhouse internal user ID of the owning account. - `email` (string): Email address of the owning account. - `first_name` (string, nullable): First name of the owning account. - `last_name` (string, nullable): Last name of the owning account. - `source_user_id` (string, nullable): The ID of the listing's host on the source channel, as reported by that channel. This is an identifier in the channel's own namespace, not a Wheelhouse account — see `owner_user` for the Wheelhouse account the listing belongs to. - `channel_ids` (object, nullable): A mapping of channel names to the channel's listing ID. - `airbnb` (string, nullable) - `tripadvisor` (string, nullable) - `vrbo` (string, nullable) - `wheelhouse` (string, nullable) - `links` (object, nullable): Useful links to the Wheelhouse app. - `calendar` (string, nullable): Link to the listing calendar page on Wheelhouse. - `upgrade` (string, nullable): Link to the upgrade flow for this listing on Wheelhouse. - `security_deposit` (number, nullable): Security deposit amount in the listing's currency. - `base_min_night_stay` (integer, nullable): The minimum night stay floor for this listing. - `listing_preferences` (object, nullable): A summary of the listing's pricing preferences and fee configuration. Use `GET /preferences/{listing_id}` for the full structured preference object, including date-specific rules. - `automatic_rate_posting_enabled` (boolean, nullable): Whether recommended prices are posted to the channel automatically. - `base_price` (number, nullable): The base price the user set by hand, in the listing's currency. `null` does not mean the listing has no base price. It means the base price follows the Wheelhouse recommendation, multiplied by `base_price_adjustment` (or by `1.0` when that is also `null`). To read the base price in use, call `GET /listings/{listing_id}/price_recommendations` and read its top-level `base_price`. - `base_price_adjustment` (number, nullable): Multiplier applied to the recommended base price when `base_price` is `null`. The presets are `0.9` (conservative), `1.0` (recommended), and `1.1` (aggressive). Any other value is a custom adjustment. When both fields are `null`, the pricing engine uses `1.0`. - `fees` (array of object): Fees charged when booking the listing. Only fees with a configured value are listed. - `name` (string, required): The name of the fee as it appears on line items. - `type` (string, required, one of: `cleaning`, `extra_guest`): Classification of the fee. - `multiplier` (string, required, one of: `PER_STAY`, `PER_NIGHT`): What the fee is charged per. - `value_type` (string, required, one of: `FIXED`, `PERCENTAGE`): Whether `value` is a fixed amount in the listing's currency or a percentage of the booking value. - `value` (number, required): The fee amount. - `max_price` (integer): The global maximum nightly price for automated pricing. Only present when a maximum price is configured. - `min_price` (integer): The global minimum nightly price for automated pricing. Only present when a minimum price is configured. - `minimum_stay` (integer): The global minimum stay in nights. Only present when a minimum stay is configured. - `monthly_discount_pct` (number, nullable): The percent discount given to bookings of 28 nights or more. - `nickname` (string, nullable): User-editable nickname for the listing. - `num_included_guests` (integer, nullable): The number of guests included in the nightly price. - `num_max_guests` (integer, nullable): The maximum number of guests the listing sleeps. - `weekly_discount_pct` (number, nullable): The percent discount given to bookings of 7 nights or more. - `meta` (object, nullable): Supplementary listing attributes. `photos` is present only where photos are requested, such as `GET /listings` with `include_photos=true`; the other fields repeat the top-level fields of the same name. - `amenities` (array of string, nullable) - `num_beds` (integer, nullable) - `num_photos` (integer, nullable) - `num_reviews` (integer, nullable) - `photos` (array of object, nullable): The listing's photos. - `caption` (string, nullable): The photo's caption. - `regular` (string, nullable): URL of the web-sized photo. - `thumbnail` (string, nullable): URL of the thumbnail-sized photo. - `security_deposit` (number, nullable) - `source_user_id` (string, nullable) - `star_rating` (number, nullable) - `market_id` (integer, nullable): The Wheelhouse market ID for this listing. - `market_name` (string, nullable): The human-readable name of the market identified by `market_id`, e.g. `San Francisco, CA, United States`. It is the same `market_name` that `GET /market_report` returns, so there is no need to look it up there. `null` when the listing has no market. - `is_active` (boolean, nullable): Whether the listing is currently active. - `is_hidden` (boolean): Whether the listing has been hidden in the Wheelhouse app. Hiding a listing does not deactivate or disconnect it, so a hidden listing is still returned with `exclude_inactive=true`; filter on this field to leave hidden listings out. Unrelated to the `hidden` membership status of a listing in a dynamic set. - `wheelhouse_created_at` (string, nullable): The datetime the listing was created in Wheelhouse (Rails-style timestamp, e.g. `2016-09-20 02:07:32 -0700`). - `number_of_active_units` (integer, nullable): The number of independently bookable units under this listing. `null` for standard single-unit listings; a positive integer for multi-unit listings. See the **Multi-Unit Listings** section in the overview. - `supported_settings` (object `supported_settings`, read-only): Which listing preference settings this listing's channel can act on. A setting reported `false` is discarded on write rather than posted to the channel, so check this before sending it. Reflects any per-account early access, so two listings on the same channel can differ. - `checkin_checkout` (boolean): Whether `checkin_checkout` rules can be set. - `min_stays` (boolean): Whether minimum stay settings (`min_min_stay`, `min_stays_enabled`, `minimum_stay_rules`) can be set. - `long_term_discounts` (boolean): Whether long-term discounts (`long_term_discounts`, `weekly_discount`, `monthly_discount`) can be set at all. - `long_term_discount_type` (string, one of: `disabled`, `simple`, `rules`, `complex`): The form of long-term discount the channel accepts. `disabled` takes none; `simple` takes only flat `weekly_discount` and `monthly_discount` values and ignores a `rules` object; `rules` additionally takes the 7 and 28 night tiers; `complex` takes arbitrary tiers. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "id": "string", "channel": "string", "wheelhouse_id": 0, "title": "string", "nickname": "string", "description": "string", "location": { "country": "string", "postal_code": "string", "address": "string", "latitude": 0, "longitude": 0 }, "num_bedrooms": 0, "num_beds": 0, "num_bathrooms": 0, "room_type": "string", "property_type": "string", "currency": "string", "star_rating": 0, "num_reviews": 0, "num_photos": 0, "thumb_url": "string", "access_level": "owner", "amenities": [ "string" ], "owner_name": "string", "owner_user": { "id": 0, "email": "string", "first_name": "string", "last_name": "string" }, "source_user_id": "string", "channel_ids": { "airbnb": "string", "tripadvisor": "string", "vrbo": "string", "wheelhouse": "string" }, "links": { "calendar": "string", "upgrade": "string" }, "security_deposit": 0, "base_min_night_stay": 0, "listing_preferences": { "automatic_rate_posting_enabled": true, "base_price": 0, "base_price_adjustment": 0, "fees": [ { "name": "string", "type": "cleaning", "multiplier": "PER_STAY", "value_type": "FIXED", "value": 0 } ], "max_price": 0, "min_price": 0, "minimum_stay": 0, "monthly_discount_pct": 0, "nickname": "string", "num_included_guests": 0, "num_max_guests": 0, "weekly_discount_pct": 0 }, "meta": { "amenities": [ "string" ], "num_beds": 0, "num_photos": 0, "num_reviews": 0, "photos": [ { "caption": "string", "regular": "string", "thumbnail": "string" } ], "security_deposit": 0, "source_user_id": "string", "star_rating": 0 }, "market_id": 0, "market_name": "string", "is_active": true, "is_hidden": true, "wheelhouse_created_at": "string", "number_of_active_units": 0, "supported_settings": { "checkin_checkout": true, "min_stays": true, "long_term_discounts": true, "long_term_discount_type": "disabled" } } ] ``` ### 400 Invalid parameters, e.g. more than 500 listing IDs in one request. ### 401 API key authorization failed. ### 403 Listing authorization failed, user lacks editor/manager access to the shared set, or the API key is read-only. ### 404 Dynamic set or listing not found, or not accessible to the user. ### 409 A concurrent request for this set is already in progress. Retry after it completes. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Remove associated user listings from a dynamic set. `DELETE /sets/{set_id}/associated_listings` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-delete-set-associated-listings · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmDeleteSetAssociatedListings` · Tag: Dynamic Sets Removes the association between the given listings (identified by their channel listing IDs) and the set. Requires editor or manager access to the set when the set is shared. Works for both free and paid sets: associating a listing is set configuration, not KPI data. ## Request `DELETE https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/associated_listings` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `set_id` | integer | yes | The Wheelhouse internal dynamic set ID. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_ids` | array of string | yes | Channel listing IDs of the user's listings to disassociate, or their Wheelhouse listing IDs when `channel` is `wheelhouse`. At most 500 per request. Send more than one in brackets (`?listing_ids[]=abc&listing_ids[]=def`); a key repeated without brackets keeps only its last value. (max items: 500) | | `channel` | string | no | Channel name the listings are on, or the literal `wheelhouse` to read `listing_ids` as Wheelhouse listing IDs instead. Required if it cannot be derived from the API key. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Example request ```bash curl -X DELETE 'https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/associated_listings?listing_ids=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The updated array of associated listings. Body (`application/json`): array of object `listing_response` A listing as returned by the RM API. - `id` (string, required): The channel's unique listing identifier. Always the channel's ID, whichever way the request identified the listing; the Wheelhouse listing ID is the separate `wheelhouse_id` field. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). - `channel` (string, required): The channel name of the listing. - `wheelhouse_id` (integer, nullable): The Wheelhouse internal listing ID. - `title` (string, nullable): The listing's name. - `nickname` (string, nullable): Listing nickname used as a shortened title. - `description` (string, nullable): The listing's description text. - `location` (object, nullable): The listing's location. - `country` (string, nullable): ISO-3166 2-letter country code. - `postal_code` (string, nullable) - `address` (string, nullable) - `latitude` (number, nullable) - `longitude` (number, nullable) - `num_bedrooms` (integer, nullable): Number of bedrooms. - `num_beds` (integer, nullable): Number of beds. - `num_bathrooms` (number, nullable): Number of bathrooms (may be fractional, e.g. 1.5). - `room_type` (string, nullable): The room type of the listing. - `property_type` (string, nullable): The property type of the listing. - `currency` (string, nullable): The ISO-4217 3-letter currency code of the listing. - `star_rating` (number, nullable): Star rating. - `num_reviews` (integer, nullable): Number of reviews. - `num_photos` (integer, nullable): Number of photos. - `thumb_url` (string, nullable): URL of the listing's thumbnail image. - `access_level` (string, nullable, one of: `owner`, `viewer`, `restricted_editor`, `editor`, `manager`): How the authenticated user accesses this listing in the RM API: `owner` for listings on their account, or the delegated role when shared access applies (`viewer`, `restricted_editor`, `editor`, `manager`). **API permissions by level:** - `owner`, `editor`, `manager` — full read and write access (GET, PUT, POST, DELETE). - `restricted_editor` — read and write access to the listing itself, except that `PUT /listings/{listing_id}/tags` returns 403 and the batch `PUT /preferences` reports the listing in `errors` with status 403. - `viewer` — read-only; write endpoints (PUT, POST, DELETE) return 403, except that a viewer may remove the listing from a set with `DELETE /sets/{set_id}/associated_listings`. - `amenities` (array of string, nullable): List of amenities available at the listing. - `owner_name` (string, nullable): The property owner's name, as supplied by the channel. This is display text about the physical property's owner and is unrelated to the Wheelhouse account that holds the listing — see `owner_user` for that. - `owner_user` (object, nullable): The Wheelhouse account this listing belongs to. Use this to tell whose portfolio a listing sits in when a response mixes owned and managed listings — for example `GET /listings?include_managed_listings=true`, or the listings of a portfolio segment or dynamic set. For listings the authenticated user owns (`access_level` of `owner`) this is the authenticated user's own account. For managed listings it is the account that granted the shared access. - `id` (integer): The Wheelhouse internal user ID of the owning account. - `email` (string): Email address of the owning account. - `first_name` (string, nullable): First name of the owning account. - `last_name` (string, nullable): Last name of the owning account. - `source_user_id` (string, nullable): The ID of the listing's host on the source channel, as reported by that channel. This is an identifier in the channel's own namespace, not a Wheelhouse account — see `owner_user` for the Wheelhouse account the listing belongs to. - `channel_ids` (object, nullable): A mapping of channel names to the channel's listing ID. - `airbnb` (string, nullable) - `tripadvisor` (string, nullable) - `vrbo` (string, nullable) - `wheelhouse` (string, nullable) - `links` (object, nullable): Useful links to the Wheelhouse app. - `calendar` (string, nullable): Link to the listing calendar page on Wheelhouse. - `upgrade` (string, nullable): Link to the upgrade flow for this listing on Wheelhouse. - `security_deposit` (number, nullable): Security deposit amount in the listing's currency. - `base_min_night_stay` (integer, nullable): The minimum night stay floor for this listing. - `listing_preferences` (object, nullable): A summary of the listing's pricing preferences and fee configuration. Use `GET /preferences/{listing_id}` for the full structured preference object, including date-specific rules. - `automatic_rate_posting_enabled` (boolean, nullable): Whether recommended prices are posted to the channel automatically. - `base_price` (number, nullable): The base price the user set by hand, in the listing's currency. `null` does not mean the listing has no base price. It means the base price follows the Wheelhouse recommendation, multiplied by `base_price_adjustment` (or by `1.0` when that is also `null`). To read the base price in use, call `GET /listings/{listing_id}/price_recommendations` and read its top-level `base_price`. - `base_price_adjustment` (number, nullable): Multiplier applied to the recommended base price when `base_price` is `null`. The presets are `0.9` (conservative), `1.0` (recommended), and `1.1` (aggressive). Any other value is a custom adjustment. When both fields are `null`, the pricing engine uses `1.0`. - `fees` (array of object): Fees charged when booking the listing. Only fees with a configured value are listed. - `name` (string, required): The name of the fee as it appears on line items. - `type` (string, required, one of: `cleaning`, `extra_guest`): Classification of the fee. - `multiplier` (string, required, one of: `PER_STAY`, `PER_NIGHT`): What the fee is charged per. - `value_type` (string, required, one of: `FIXED`, `PERCENTAGE`): Whether `value` is a fixed amount in the listing's currency or a percentage of the booking value. - `value` (number, required): The fee amount. - `max_price` (integer): The global maximum nightly price for automated pricing. Only present when a maximum price is configured. - `min_price` (integer): The global minimum nightly price for automated pricing. Only present when a minimum price is configured. - `minimum_stay` (integer): The global minimum stay in nights. Only present when a minimum stay is configured. - `monthly_discount_pct` (number, nullable): The percent discount given to bookings of 28 nights or more. - `nickname` (string, nullable): User-editable nickname for the listing. - `num_included_guests` (integer, nullable): The number of guests included in the nightly price. - `num_max_guests` (integer, nullable): The maximum number of guests the listing sleeps. - `weekly_discount_pct` (number, nullable): The percent discount given to bookings of 7 nights or more. - `meta` (object, nullable): Supplementary listing attributes. `photos` is present only where photos are requested, such as `GET /listings` with `include_photos=true`; the other fields repeat the top-level fields of the same name. - `amenities` (array of string, nullable) - `num_beds` (integer, nullable) - `num_photos` (integer, nullable) - `num_reviews` (integer, nullable) - `photos` (array of object, nullable): The listing's photos. - `caption` (string, nullable): The photo's caption. - `regular` (string, nullable): URL of the web-sized photo. - `thumbnail` (string, nullable): URL of the thumbnail-sized photo. - `security_deposit` (number, nullable) - `source_user_id` (string, nullable) - `star_rating` (number, nullable) - `market_id` (integer, nullable): The Wheelhouse market ID for this listing. - `market_name` (string, nullable): The human-readable name of the market identified by `market_id`, e.g. `San Francisco, CA, United States`. It is the same `market_name` that `GET /market_report` returns, so there is no need to look it up there. `null` when the listing has no market. - `is_active` (boolean, nullable): Whether the listing is currently active. - `is_hidden` (boolean): Whether the listing has been hidden in the Wheelhouse app. Hiding a listing does not deactivate or disconnect it, so a hidden listing is still returned with `exclude_inactive=true`; filter on this field to leave hidden listings out. Unrelated to the `hidden` membership status of a listing in a dynamic set. - `wheelhouse_created_at` (string, nullable): The datetime the listing was created in Wheelhouse (Rails-style timestamp, e.g. `2016-09-20 02:07:32 -0700`). - `number_of_active_units` (integer, nullable): The number of independently bookable units under this listing. `null` for standard single-unit listings; a positive integer for multi-unit listings. See the **Multi-Unit Listings** section in the overview. - `supported_settings` (object `supported_settings`, read-only): Which listing preference settings this listing's channel can act on. A setting reported `false` is discarded on write rather than posted to the channel, so check this before sending it. Reflects any per-account early access, so two listings on the same channel can differ. - `checkin_checkout` (boolean): Whether `checkin_checkout` rules can be set. - `min_stays` (boolean): Whether minimum stay settings (`min_min_stay`, `min_stays_enabled`, `minimum_stay_rules`) can be set. - `long_term_discounts` (boolean): Whether long-term discounts (`long_term_discounts`, `weekly_discount`, `monthly_discount`) can be set at all. - `long_term_discount_type` (string, one of: `disabled`, `simple`, `rules`, `complex`): The form of long-term discount the channel accepts. `disabled` takes none; `simple` takes only flat `weekly_discount` and `monthly_discount` values and ignores a `rules` object; `rules` additionally takes the 7 and 28 night tiers; `complex` takes arbitrary tiers. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "id": "string", "channel": "string", "wheelhouse_id": 0, "title": "string", "nickname": "string", "description": "string", "location": { "country": "string", "postal_code": "string", "address": "string", "latitude": 0, "longitude": 0 }, "num_bedrooms": 0, "num_beds": 0, "num_bathrooms": 0, "room_type": "string", "property_type": "string", "currency": "string", "star_rating": 0, "num_reviews": 0, "num_photos": 0, "thumb_url": "string", "access_level": "owner", "amenities": [ "string" ], "owner_name": "string", "owner_user": { "id": 0, "email": "string", "first_name": "string", "last_name": "string" }, "source_user_id": "string", "channel_ids": { "airbnb": "string", "tripadvisor": "string", "vrbo": "string", "wheelhouse": "string" }, "links": { "calendar": "string", "upgrade": "string" }, "security_deposit": 0, "base_min_night_stay": 0, "listing_preferences": { "automatic_rate_posting_enabled": true, "base_price": 0, "base_price_adjustment": 0, "fees": [ { "name": "string", "type": "cleaning", "multiplier": "PER_STAY", "value_type": "FIXED", "value": 0 } ], "max_price": 0, "min_price": 0, "minimum_stay": 0, "monthly_discount_pct": 0, "nickname": "string", "num_included_guests": 0, "num_max_guests": 0, "weekly_discount_pct": 0 }, "meta": { "amenities": [ "string" ], "num_beds": 0, "num_photos": 0, "num_reviews": 0, "photos": [ { "caption": "string", "regular": "string", "thumbnail": "string" } ], "security_deposit": 0, "source_user_id": "string", "star_rating": 0 }, "market_id": 0, "market_name": "string", "is_active": true, "is_hidden": true, "wheelhouse_created_at": "string", "number_of_active_units": 0, "supported_settings": { "checkin_checkout": true, "min_stays": true, "long_term_discounts": true, "long_term_discount_type": "disabled" } } ] ``` ### 400 Invalid parameters, e.g. more than 500 listing IDs in one request. ### 401 API key authorization failed. ### 403 Listing authorization failed, user lacks editor/manager access to the shared set, or the API key is read-only. ### 404 Dynamic set or listing not found, or not accessible to the user. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get the price calendar of a dynamic set's member listings. `GET /sets/{set_id}/price_calendar` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-set-price-calendar · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetSetPriceCalendar` · Tag: Dynamic Sets Returns a night-by-night calendar for each **active member listing** of the set — the API equivalent of the set calendar in the Wheelhouse app. Each listing carries its own array of nights, with prices converted to a single currency so they are comparable across comps priced differently. Available only for **small sets**: a set with more than 25 member listings responds with `422`. Every membership counts toward that limit, whatever its status, even though the response itself covers only the active ones. **Paid sets only** — a free set responds with `404`; upgrade it first with `POST /sets/{set_id}/upgrade`. Both limits follow the detailed per-night scraping that backs this data, which Wheelhouse requests only for paid sets at or under that size. The shape follows `GET /listings/{listing_id}/price_calendar` with two deliberate differences, because a comparison listing is not one of your own: there is no `is_booked` flag and no `reservation_id`. See `booking_probability_percent` on the night object for what replaces them. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/price_calendar` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `set_id` | integer | yes | The Wheelhouse internal dynamic set ID. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `start_date` | string (date) | no | First stay date to return (inclusive). Defaults to today. | | `end_date` | string (date) | no | Last stay date to return (inclusive). Defaults to 545 days out, the maximum calendar horizon. The range may not exceed 3 years. | | `currency` | string | no | ISO-4217 3-letter currency code to convert prices to. Defaults to the set's own currency, so nights are comparable across comps priced in different currencies. | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/price_calendar' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 One calendar per active member listing. Body (`application/json`): array of object - `listing_id` (integer): The Wheelhouse internal listing ID of the member listing. - `title` (string, nullable): The member listing's title, for labelling the calendar. - `currency` (string): ISO-4217 currency code every price in this listing's calendar is expressed in. - `price_calendar` (array of object `set_calendar_day_response`): The listing's nights, ordered by stay date. - Each item: One night of a member listing's calendar. Mirrors the single-listing price calendar (`GET /listings/{listing_id}/price_calendar`) minus three fields. Two do not carry over to a comparison listing: `is_booked`, which for a comp would be an estimate rather than a fact, and `reservation_id`, which a comp has none of — the underlying assessment is reported as `booking_probability_percent` in their place. The third, `created_at`, is dropped as an internal record-keeping timestamp of no use here. Note there is deliberately no `status` field either, unlike the Comp Set API's calendar: that field separates booked from blocked using the same probability, so offering it would reintroduce exactly the estimate left out above. Use `is_available`, which is observed directly, together with `booking_probability_percent`. - `stay_date` (string (date)): The stay date. - `price` (integer, nullable): The observed price for this night, converted to the response `currency` and rounded. For an available night this is the live price; for an unavailable one it is the price it was last seen at. - `currency` (string): ISO-4217 currency code the price is expressed in. - `is_available` (boolean): Whether the night is available to book. This is observed directly, unlike the booked/blocked distinction. - `booking_probability_percent` (integer, min: 0, max: 90): Wheelhouse's assessment of the likelihood this night is booked rather than merely held, as a whole percentage. For a comparison listing we observe only that a night became unavailable, not why, so this replaces the `is_booked` flag of the single-listing calendar. **Bounded to 10–90 for unavailable nights.** We never assert certainty about a listing we infer from scraping rather than receive reservations for, so a value of `10` means "10% or less" and `90` means "90% or more" — matching the app's set calendar, which renders those cases as `<10%` and `>90%`. Do not read `10` and `90` as exact. An **available** night reports `0`: its state is observed rather than inferred, and the app shows no probability for it at all. So `0` is the only value outside the band, and it always pairs with `is_available: true`. - `block_time` (string (date-time), nullable): When this night was first observed as unavailable (ISO-8601). Null while the night is still available. - `unit_number` (integer): The unit number. Always `0` in practice, since comparison listings come from scraped channels that have no units. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "listing_id": 0, "title": "string", "currency": "string", "price_calendar": [ { "stay_date": "2026-01-01", "price": 0, "currency": "string", "is_available": true, "booking_probability_percent": 0, "block_time": "2026-01-01T00:00:00Z", "unit_number": 0 } ] } ] ``` ### 400 The date range exceeds 3 years, ends before it starts, or an unsupported currency was requested. ### 401 API key authorization failed. ### 404 Dynamic set not found, not accessible to the user, or not a paid set. ### 422 The set has more than 25 member listings, which is more than the set calendar supports. All memberships count toward the limit, whatever their status. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get the changelog of a dynamic set. `GET /sets/{set_id}/changelog` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-set-changelog · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetSetChangelog` · Tag: Dynamic Sets Returns the history of changes made to the set (membership changes, edits), ordered oldest first and optionally restricted to a date range. **Paid sets only.** Returns `404 Not Found` for a free set — upgrade it first with `POST /sets/{set_id}/upgrade`. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/changelog` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `set_id` | integer | yes | The Wheelhouse internal dynamic set ID. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `after` | string (date) | no | Only include changes on or after this date (YYYY-MM-DD). | | `before` | string (date) | no | Only include changes before this date (YYYY-MM-DD, exclusive). | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/changelog' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of changelog entries. Body (`application/json`): array of object `set_changelog_entry_response` A change made to a dynamic set. - `action` (string): The action that was performed (e.g. listing added/removed, set edited). - `edit_details` (object, nullable): Details about the change. - `listing_id` (integer, nullable): The Wheelhouse internal ID of the affected member listing, if the change concerns a listing. - `created_at` (string (date-time)): When the change happened (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "action": "string", "edit_details": {}, "listing_id": 0, "created_at": "2026-01-01T00:00:00Z" } ] ``` ### 401 API key authorization failed. ### 404 Dynamic set not found, not accessible to the user, or not a paid set. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Share a dynamic set with other users. `POST /sets/{set_id}/share` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-share-set · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmShareSet` · Tag: Dynamic Sets Grants specified access levels to other users for this dynamic set. Only the set's owner or a manager-level collaborator may share the set. Access levels are: **R** (viewer, read-only), **E** (restricted editor), **F** (editor, can modify set and associated listings), **M** (manager, can share and upgrade the set), and **N** (disabled, revokes access). Sharing with a user who already has access updates their level to the newly specified one. Returns the updated dynamic set. **Works for free and paid sets.** ## Request `POST https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/share` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `set_id` | integer | yes | The Wheelhouse internal dynamic set ID. | ### Request body (`application/json`, required) - `access` (object, required): Access levels to grant, keyed by level code. - `R` (array of integer): Array of user IDs to grant viewer (read-only) access. - `E` (array of integer): Array of user IDs to grant restricted editor access. - `F` (array of integer): Array of user IDs to grant editor access. - `M` (array of integer): Array of user IDs to grant manager access. - `N` (array of integer): Array of user IDs to disable (revoke access). ### Example request ```bash curl -X POST 'https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/share' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{ "access": {} }' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The dynamic set with updated sharing settings. Body (`application/json`): object `dynamic_set_response` A dynamic set (comp set). - `id` (integer, required): The Wheelhouse internal dynamic set ID. - `user_id` (integer, required): The Wheelhouse internal ID of the user that owns the set. - `name` (string, required): The set name. - `description` (string, nullable): An optional description of the set. - `kind` (string, one of: `competitive`, `market`, `neighborhood`, `marketing`, `acquisition`, `underwriting`, `other`, `merchandising`): The intended use case for the set: - `competitive` — tracks direct competitor properties. - `market` — broad market-wide overview. - `neighborhood` — properties in the same geographic sub-area. - `marketing` — properties used as marketing or positioning references. - `acquisition` — evaluating potential acquisition targets. - `underwriting` — used in underwriting or investment analysis. - `merchandising` — set curated for merchandising purposes. - `other` — general-purpose or uncategorized set. - `currency` (string, nullable): The ISO-4217 3-letter currency code of the set. - `is_static` (boolean): Whether the set membership is static. Non-static sets are kept in sync automatically based on the set's boundary and filters. - `is_paid` (boolean): Whether the set is on the paid Dynamic Sets plan. Only paid sets expose the set-level analytics endpoints (aggregated_metrics, time_series, distribution, changelog), which return `404 Not Found` for a free set. Endpoints for building and reviewing a set — including its member listings and associated_listings — work on free sets too. See the Dynamic Sets section for the full per-endpoint breakdown. Upgrade a free set via `POST /sets/{set_id}/upgrade`. - `filters` (object, nullable): The filter criteria used to select member listings (non-static sets). Keys are listing attributes/metrics, values contain `lower`/`upper` bounds or `one_of` lists. - `boundary` (array of array of array of array of number, nullable, each item each item each item min items: 2, max items: 2): The geographic boundary of the set as MultiPolygon coordinates (`[[[[lng, lat], ...]]]`), if one is defined. The four levels of nesting are: **polygons** → **rings** → **points** → **coordinates**. - **Polygons** (`boundary[i]`): Each element is one polygon. - **Rings** (`boundary[i][j]`): Each polygon contains one or more linear rings. The first ring is the exterior boundary (outer shell of the shape); any subsequent rings represent interior boundaries (holes inside the polygon). - **Points** (`boundary[i][j][k]`): Each ring is an array of `[longitude, latitude]` coordinate pairs. - **Coordinates** (`boundary[i][j][k][0/1]`): Each point is `[longitude, latitude]` as floating-point numbers. - `listing_counts` (object): Number of member listings in the set per status. - `active` (integer) - `hidden` (integer) - `review` (integer) - `removed` (integer) - `updated_at` (string (date-time)): When the set was last updated (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json { "id": 0, "user_id": 0, "name": "string", "description": "string", "kind": "competitive", "currency": "string", "is_static": true, "is_paid": true, "filters": {}, "boundary": [ [ [ [ 0, 0 ] ] ] ], "listing_counts": { "active": 0, "hidden": 0, "review": 0, "removed": 0 }, "updated_at": "2026-01-01T00:00:00Z" } ``` ### 400 Invalid access levels or user IDs. ### 401 API key authorization failed. ### 403 The API key is read-only, or the user is not the set's owner or a manager. ### 404 Dynamic set not found or not accessible to the user. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get time-series metrics for a dynamic set. `GET /sets/{set_id}/time_series` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-set-time-series · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetSetTimeSeries` · Tag: Dynamic Sets Returns daily time-series data for one or more metrics over a date range, aggregated across the active member listings of the set. **Paid sets only.** Returns `404 Not Found` for a free set — upgrade it first with `POST /sets/{set_id}/upgrade`. Available metrics: `asking_rate_w_fees`, `occupancy`, `occupancy_adjusted`, `adr_w_fees`, `lead_time`, `revpar_adjusted_w_fees`, `revpar_w_fees`, `revenue_w_fees`, `nights_bookable`. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/time_series` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `set_id` | integer | yes | The Wheelhouse internal dynamic set ID. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `metric` | array of string | no | Metrics to include. Defaults to all metrics. Send more than one in brackets (`?metric[]=asking_rate_w_fees&metric[]=occupancy`); a key repeated without brackets keeps only its last value. (each item one of: `occupancy`, `occupancy_adjusted`, `nights_bookable`, `asking_rate_w_fees`, `adr_w_fees`, `lead_time`, `revpar_adjusted_w_fees`, `revpar_w_fees`, `revenue_w_fees`) | | `start_date` | string (date) | no | Start of the date range (YYYY-MM-DD). Defaults to today. Must be within 3 years in the past and 1 year in the future. | | `end_date` | string (date) | no | End of the date range (YYYY-MM-DD). Defaults to 1 year from today. Must be after `start_date`. | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/time_series' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Time-series data for the dynamic set. Body (`application/json`): object - `currency` (string): ISO-4217 currency code for monetary metrics. - `updated_at` (string, example: `2026-08-30 04:17:22 UTC`): When the underlying set report was last generated, as a timestamp with a time zone abbreviation rather than ISO-8601. - `data` (array of object): Daily metric values. - `stay_date` (string (date)): Stay date (YYYY-MM-DD). - `occupancy` (number, nullable): Occupancy rate (0–1). Present when `occupancy` is requested. - `occupancy_adjusted` (number, nullable): Occupancy rate over open (non-blocked) nights (0–1). Present when `occupancy_adjusted` is requested. - `nights_bookable` (number, nullable): Number of open (non-blocked) available room-nights. Present when `nights_bookable` is requested. - `asking_rate_w_fees` (number, nullable): Average asking rate including fees. Present when `asking_rate_w_fees` is requested. - `adr_w_fees` (number, nullable): Average daily rate including fees of booked rooms. Present when `adr_w_fees` is requested. - `lead_time` (number, nullable): Average lead time in days. Present when `lead_time` is requested. - `revpar_adjusted_w_fees` (number, nullable): Revenue per open available room-night including fees. Present when `revpar_adjusted_w_fees` is requested. - `revpar_w_fees` (number, nullable): Revenue per available room-night including fees. Present when `revpar_w_fees` is requested. - `revenue_w_fees` (number, nullable): Total revenue including fees. Present when `revenue_w_fees` is requested. Example shape (generated from the schema; placeholder values, not a real response): ```json { "currency": "string", "updated_at": "2026-08-30 04:17:22 UTC", "data": [ { "stay_date": "2026-01-01", "occupancy": 0, "occupancy_adjusted": 0, "nights_bookable": 0, "asking_rate_w_fees": 0, "adr_w_fees": 0, "lead_time": 0, "revpar_adjusted_w_fees": 0, "revpar_w_fees": 0, "revenue_w_fees": 0 } ] } ``` ### 204 Not enough data for the requested parameters. ### 400 Invalid parameter value (e.g. invalid date range). ### 401 API key authorization failed. ### 404 Dynamic set not found, not accessible to the user, or not a paid set. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get metric distributions for a dynamic set. `GET /sets/{set_id}/distribution` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-set-distribution · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetSetDistribution` · Tag: Dynamic Sets Returns histogram distributions for one or more metrics for a given calendar month, aggregated across the active member listings of the set. **Paid sets only.** Returns `404 Not Found` for a free set — upgrade it first with `POST /sets/{set_id}/upgrade`. Available metrics: `occupancy`, `occupancy_adjusted`, `asking_rate_w_fees`, `adr_w_fees`, `lead_time`, `revpar_adjusted_w_fees`, `revpar_w_fees`, `length_of_stay`. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/distribution` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `set_id` | integer | yes | The Wheelhouse internal dynamic set ID. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `metric` | array of string | no | Metrics to include. Defaults to all metrics. Send more than one in brackets (`?metric[]=asking_rate_w_fees&metric[]=occupancy`); a key repeated without brackets keeps only its last value. (each item one of: `occupancy`, `occupancy_adjusted`, `asking_rate_w_fees`, `adr_w_fees`, `lead_time`, `revpar_adjusted_w_fees`, `revpar_w_fees`, `length_of_stay`) | | `month` | string (date) | no | The month to retrieve distributions for (YYYY-MM-DD or YYYY-MM, e.g. `2026-05-01` or `2026-05`). Defaults to the start of the current month. (example: `2026-05-01`) | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/distribution' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Metric distributions for the dynamic set for the month. Body (`application/json`): object - `currency` (string): ISO-4217 currency code for monetary metrics. - `month` (string (date)): The start of the month these distributions cover (YYYY-MM-DD). - `updated_at` (string, example: `2026-08-30 04:17:22 UTC`): When the underlying set report was last generated, as a timestamp with a time zone abbreviation rather than ISO-8601. - `data` (map of string to array of object): Distribution buckets keyed by metric name. Each metric maps to an array of histogram buckets sorted by probability descending. - `bucket_min_incl` (number): Inclusive lower bound of the bucket. - `bucket_max_excl` (number): Exclusive upper bound of the bucket. - `probability` (number): Fraction of observations in this bucket (0–1). - `percentile` (number): Cumulative probability up to and including this bucket (0–1). Example shape (generated from the schema; placeholder values, not a real response): ```json { "currency": "string", "month": "2026-01-01", "updated_at": "2026-08-30 04:17:22 UTC", "data": { "key": [ { "bucket_min_incl": 0, "bucket_max_excl": 0, "probability": 0, "percentile": 0 } ] } } ``` ### 204 Not enough data for the requested parameters. ### 400 Invalid parameter value (e.g. month out of range). ### 401 API key authorization failed. ### 404 Dynamic set not found, not accessible to the user, or not a paid set. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get the notes of a listing. `GET /listings/{listing_id}/notes` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-notes · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetNotes` · Tag: Notes Returns the notes of the listing, most recently updated first. Deleted notes are not included. Optionally restrict the response to notes whose date range overlaps a given date range — `start_date` and `end_date` must be provided together. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/notes` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | | `start_date` | string (date) | no | Only include notes whose date range overlaps the given range (YYYY-MM-DD). Must be provided together with `end_date`. | | `end_date` | string (date) | no | Only include notes whose date range overlaps the given range (YYYY-MM-DD). Must be provided together with `start_date`. | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/notes?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of notes. Body (`application/json`): array of object `note_response` A note on a listing. - `id` (integer, required): The Wheelhouse internal note ID. - `description` (string, nullable): The note text. `null` when the note has no text. - `category` (array of string, each item one of: `base_price`, `last_minute_discounts`, `far_future`, `weekend_adjustment`, `seasonality_adjustment`, `demand_sensitivity`, `minimum_price`, `maximum_price`, `minimum_stays`, `discounts`, `far_future_premium`, `checkin_checkout`, `gap_night`, `occupancy_pacing`, `revenue_pacing`, `historical_anchoring`, `custom_date_ranges`, `calendar`): The Wheelhouse pricing settings sections the note relates to. Each value maps to a settings area in the Wheelhouse UI: `base_price` (Base Price), `last_minute_discounts` (Last-Minute Discounts), `far_future_premium` / `far_future` (Far-Future Premium), `weekend_adjustment` (Day-of-Week), `seasonality_adjustment` (Seasonality Adjustment), `demand_sensitivity` (Local Events), `minimum_price` (Price Floor), `maximum_price` (Price Ceiling), `minimum_stays` (Minimum Stay), `discounts` (Long-Term Discounts), `checkin_checkout` (Check-in/Check-out), `gap_night` (Gap Night), `occupancy_pacing` (Occupancy Pacing), `revenue_pacing` (Revenue Pacing), `historical_anchoring` (Historical Protections), `custom_date_ranges` (Custom Date Ranges), `calendar` (general calendar note not tied to a specific setting). - `start_date` (string (date), nullable): First stay date the note applies to (YYYY-MM-DD). - `end_date` (string (date), nullable): Last stay date the note applies to (YYYY-MM-DD). - `remind_by` (string (date), nullable): Date of the note's reminder (YYYY-MM-DD). - `repeat_by` (string, nullable, one of: `daily`, `weekly`, `monthly`, `does_not_repeat`): How the reminder repeats. - `status` (string, required, one of: `active`, `archived`): The note status. - `created_at` (string (date-time)): When the note was created (ISO-8601). - `updated_at` (string (date-time)): When the note was last updated (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "id": 0, "description": "string", "category": [ "base_price" ], "start_date": "2026-01-01", "end_date": "2026-01-01", "remind_by": "2026-01-01", "repeat_by": "daily", "status": "active", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ] ``` ### 400 Invalid parameters. ### 401 API key authorization failed. ### 403 Listing authorization failed. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Create a note on a listing. `POST /listings/{listing_id}/notes` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-post-note · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPostNote` · Tag: Notes Creates a note on the listing. All fields are optional — provide a `description`, an optional stay date range (`start_date`/`end_date`), settings categories, and an optional reminder (`remind_by` with `repeat_by`). ## Request `POST https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/notes` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Request body (`application/json`, required) - `description` (string): The note text. - `category` (array of string): The settings categories the note relates to. See the `note_response` schema for allowed values. - `start_date` (string (date)): First stay date the note applies to (YYYY-MM-DD). Must be provided together with `end_date` and must be on or before it. - `end_date` (string (date)): Last stay date the note applies to (YYYY-MM-DD). Must be provided together with `start_date`. - `remind_by` (string (date)): Date of the note's reminder (YYYY-MM-DD). Must be provided together with `repeat_by`. - `repeat_by` (string, one of: `daily`, `weekly`, `monthly`, `does_not_repeat`): How the reminder repeats. Must be provided together with `remind_by` (use `does_not_repeat` for a one-time reminder). - `status` (string, one of: `active`, `archived`): The note status. Defaults to `active`. ### Example request ```bash curl -X POST 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/notes?channel=' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{}' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 201 The created note. Body (`application/json`): object `note_response` A note on a listing. - `id` (integer, required): The Wheelhouse internal note ID. - `description` (string, nullable): The note text. `null` when the note has no text. - `category` (array of string, each item one of: `base_price`, `last_minute_discounts`, `far_future`, `weekend_adjustment`, `seasonality_adjustment`, `demand_sensitivity`, `minimum_price`, `maximum_price`, `minimum_stays`, `discounts`, `far_future_premium`, `checkin_checkout`, `gap_night`, `occupancy_pacing`, `revenue_pacing`, `historical_anchoring`, `custom_date_ranges`, `calendar`): The Wheelhouse pricing settings sections the note relates to. Each value maps to a settings area in the Wheelhouse UI: `base_price` (Base Price), `last_minute_discounts` (Last-Minute Discounts), `far_future_premium` / `far_future` (Far-Future Premium), `weekend_adjustment` (Day-of-Week), `seasonality_adjustment` (Seasonality Adjustment), `demand_sensitivity` (Local Events), `minimum_price` (Price Floor), `maximum_price` (Price Ceiling), `minimum_stays` (Minimum Stay), `discounts` (Long-Term Discounts), `checkin_checkout` (Check-in/Check-out), `gap_night` (Gap Night), `occupancy_pacing` (Occupancy Pacing), `revenue_pacing` (Revenue Pacing), `historical_anchoring` (Historical Protections), `custom_date_ranges` (Custom Date Ranges), `calendar` (general calendar note not tied to a specific setting). - `start_date` (string (date), nullable): First stay date the note applies to (YYYY-MM-DD). - `end_date` (string (date), nullable): Last stay date the note applies to (YYYY-MM-DD). - `remind_by` (string (date), nullable): Date of the note's reminder (YYYY-MM-DD). - `repeat_by` (string, nullable, one of: `daily`, `weekly`, `monthly`, `does_not_repeat`): How the reminder repeats. - `status` (string, required, one of: `active`, `archived`): The note status. - `created_at` (string (date-time)): When the note was created (ISO-8601). - `updated_at` (string (date-time)): When the note was last updated (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json { "id": 0, "description": "string", "category": [ "base_price" ], "start_date": "2026-01-01", "end_date": "2026-01-01", "remind_by": "2026-01-01", "repeat_by": "daily", "status": "active", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ``` ### 400 Invalid parameters. ### 401 API key authorization failed. ### 403 Listing authorization failed, or the API key is read-only. ### 404 Listing not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Update a note. `PUT /listings/{listing_id}/notes/{note_id}` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-put-note · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPutNote` · Tag: Notes Updates the given fields of a note. Fields that are not provided are left unchanged. Set `status` to `archived` to archive a note, or back to `active` to restore it. **Note:** it is not currently possible to clear an optional field once set (for example, removing an existing date range or reminder). Omitting a field in the request body leaves the current value in place; there is no way to unset `start_date`/`end_date` or `remind_by`/`repeat_by` via this endpoint. ## Request `PUT https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/notes/{note_id}` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | | `note_id` | integer | yes | The Wheelhouse internal note ID. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Request body (`application/json`, required) - `description` (string): The note text. - `category` (array of string): The settings categories the note relates to. See the `note_response` schema for allowed values. - `start_date` (string (date)): First stay date the note applies to (YYYY-MM-DD). Must be provided together with `end_date` and must be on or before it. - `end_date` (string (date)): Last stay date the note applies to (YYYY-MM-DD). Must be provided together with `start_date`. - `remind_by` (string (date)): Date of the note's reminder (YYYY-MM-DD). Must be provided together with `repeat_by`. - `repeat_by` (string, one of: `daily`, `weekly`, `monthly`, `does_not_repeat`): How the reminder repeats. Must be provided together with `remind_by` (use `does_not_repeat` for a one-time reminder). - `status` (string, one of: `active`, `archived`): The note status. ### Example request ```bash curl -X PUT 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/notes/{note_id}?channel=' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{}' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The updated note. Body (`application/json`): object `note_response` A note on a listing. - `id` (integer, required): The Wheelhouse internal note ID. - `description` (string, nullable): The note text. `null` when the note has no text. - `category` (array of string, each item one of: `base_price`, `last_minute_discounts`, `far_future`, `weekend_adjustment`, `seasonality_adjustment`, `demand_sensitivity`, `minimum_price`, `maximum_price`, `minimum_stays`, `discounts`, `far_future_premium`, `checkin_checkout`, `gap_night`, `occupancy_pacing`, `revenue_pacing`, `historical_anchoring`, `custom_date_ranges`, `calendar`): The Wheelhouse pricing settings sections the note relates to. Each value maps to a settings area in the Wheelhouse UI: `base_price` (Base Price), `last_minute_discounts` (Last-Minute Discounts), `far_future_premium` / `far_future` (Far-Future Premium), `weekend_adjustment` (Day-of-Week), `seasonality_adjustment` (Seasonality Adjustment), `demand_sensitivity` (Local Events), `minimum_price` (Price Floor), `maximum_price` (Price Ceiling), `minimum_stays` (Minimum Stay), `discounts` (Long-Term Discounts), `checkin_checkout` (Check-in/Check-out), `gap_night` (Gap Night), `occupancy_pacing` (Occupancy Pacing), `revenue_pacing` (Revenue Pacing), `historical_anchoring` (Historical Protections), `custom_date_ranges` (Custom Date Ranges), `calendar` (general calendar note not tied to a specific setting). - `start_date` (string (date), nullable): First stay date the note applies to (YYYY-MM-DD). - `end_date` (string (date), nullable): Last stay date the note applies to (YYYY-MM-DD). - `remind_by` (string (date), nullable): Date of the note's reminder (YYYY-MM-DD). - `repeat_by` (string, nullable, one of: `daily`, `weekly`, `monthly`, `does_not_repeat`): How the reminder repeats. - `status` (string, required, one of: `active`, `archived`): The note status. - `created_at` (string (date-time)): When the note was created (ISO-8601). - `updated_at` (string (date-time)): When the note was last updated (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json { "id": 0, "description": "string", "category": [ "base_price" ], "start_date": "2026-01-01", "end_date": "2026-01-01", "remind_by": "2026-01-01", "repeat_by": "daily", "status": "active", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ``` ### 400 Invalid parameters. ### 401 API key authorization failed. ### 403 Listing authorization failed, or the API key is read-only. ### 404 Listing or note not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 409 A concurrent request for this note is already in progress. Retry after it completes. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Delete a note. `DELETE /listings/{listing_id}/notes/{note_id}` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-delete-note · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmDeleteNote` · Tag: Notes Deletes the note. Deletion is permanent — the note is no longer returned by the API and cannot be restored. ## Request `DELETE https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/notes/{note_id}` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. | | `note_id` | integer | yes | The Wheelhouse internal note ID. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). | ### Example request ```bash curl -X DELETE 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/notes/{note_id}?channel=' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 204 The note was deleted. ### 401 API key authorization failed. ### 403 Listing authorization failed, or the API key is read-only. ### 404 Listing or note not found. ### 406 The listing is inactive. See the **Inactive Listings** section in the overview. Body (`application/json`): object - `error` (string, example: `Listing '12345' is inactive`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "Listing '12345' is inactive" } ``` ### 409 A concurrent request for this note is already in progress. Retry after it completes. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # List active notifications. `GET /notifications` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-notifications · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetNotifications` · Tag: Notifications Returns all active (non-dismissed, non-expired) notifications for the authenticated user, ordered most-recent first. These are the same notifications displayed in the Wheelhouse dashboard at `/u/account/notifications`. `review_url` is a relative Wheelhouse dashboard URL that links to the relevant feature page for each notification (e.g. the market report, listing calendar, or dynamic set it relates to). ## Request `GET https://api.usewheelhouse.com/ss_api/v1/notifications` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/notifications' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of active notifications. Body (`application/json`): array of object `notification_response` An in-app notification. - `id` (integer): The Wheelhouse internal notification ID. Use this when dismissing specific notifications. - `title` (string, nullable): Short title of the notification. - `body_text` (string, nullable): Body text of the notification. - `category` (string, nullable): Category of the notification. - `reference_type` (string, nullable): The type of entity this notification relates to (e.g. `MarketReport`, `CompSetV2`, `PricePostingError`). - `reference_id` (integer, nullable): The ID of the referenced entity. - `expires_at` (string (date-time), nullable): When the notification expires and will no longer be returned (ISO-8601). - `created_at` (string (date-time)): When the notification was created (ISO-8601). - `review_url` (string, nullable): Relative Wheelhouse dashboard URL for the feature related to this notification (e.g. `/markets/v1/123/overview`). Falls back to `/u/account/notifications` when no specific page applies. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "id": 0, "title": "string", "body_text": "string", "category": "string", "reference_type": "string", "reference_id": 0, "expires_at": "2026-01-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z", "review_url": "string" } ] ``` ### 401 API key authorization failed. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Dismiss notifications. `POST /notifications/dismiss` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-dismiss-notifications · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmDismissNotifications` · Tag: Notifications Marks one or more notifications as dismissed. Dismissed notifications are no longer returned by `GET /notifications`. ## Request `POST https://api.usewheelhouse.com/ss_api/v1/notifications/dismiss` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Request body (`application/json`, required) - `ids` (array of integer, required): IDs of notifications to dismiss. ### Example request ```bash curl -X POST 'https://api.usewheelhouse.com/ss_api/v1/notifications/dismiss' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{ "ids": [ 0 ] }' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 204 Notifications dismissed. ### 401 API key authorization failed. ### 403 The API key is read-only and may not be used to dismiss notifications. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # List notification alert settings. `GET /notification_settings` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-notification-settings · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetNotificationSettings` · Tag: Notifications Returns the alert delivery settings for the authenticated user — each documented `event`/`channel` pair the user currently receives. These control which alerts trigger the notifications returned by `GET /notifications` (and their email equivalents). A setting stored under an event name outside that list is left unchanged and omitted here. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/notification_settings` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/notification_settings' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of the user's active notification settings. Body (`application/json`): array of object `notification_setting` A single alert delivery setting. The presence of an `event`/`channel` pair means the user receives that alert on that channel; its absence means they do not. - `event` (string, required, one of: `price_posting_error`, `market_report_updated`, `reminder`, `sub_user_invite`, `new_listing_created`, `report_shared`, `report_comment_reply`, `report_comment_mention`, `comp_set_v2_shared`, `api_spend_alert`): The alert event type. - `channel` (string, required, one of: `inapp`, `email`): The delivery channel the alert is sent on. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "event": "price_posting_error", "channel": "inapp" } ] ``` ### 401 API key authorization failed. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Configure notification alert settings. `PUT /notification_settings` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-update-notification-settings · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmUpdateNotificationSettings` · Tag: Notifications Enables or disables which alerts the authenticated user receives. Only the settings included in the request are affected — a setting is created when `enabled` is `true` and removed when `enabled` is `false`. Any `event`/`channel` pair not included is left unchanged. Enabling an already-enabled setting (or disabling one that is already off) is a no-op. Returns the user's documented alert settings after the update. A setting stored under an event name outside that list is left unchanged and omitted. ## Request `PUT https://api.usewheelhouse.com/ss_api/v1/notification_settings` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Request body (`application/json`, required) - `settings` (array of object, required): Alert settings to update. - `event` (string, required, one of: `price_posting_error`, `market_report_updated`, `reminder`, `sub_user_invite`, `new_listing_created`, `report_shared`, `report_comment_reply`, `report_comment_mention`, `comp_set_v2_shared`, `api_spend_alert`): The alert event type. - `channel` (string, required, one of: `inapp`, `email`): The delivery channel the alert is sent on. - `enabled` (boolean, required): Whether the user should receive this alert on this channel. ### Example request ```bash curl -X PUT 'https://api.usewheelhouse.com/ss_api/v1/notification_settings' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{ "settings": [ { "event": "price_posting_error", "channel": "inapp", "enabled": true } ] }' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of the user's active notification settings after the update. Body (`application/json`): array of object `notification_setting` A single alert delivery setting. The presence of an `event`/`channel` pair means the user receives that alert on that channel; its absence means they do not. - `event` (string, required, one of: `price_posting_error`, `market_report_updated`, `reminder`, `sub_user_invite`, `new_listing_created`, `report_shared`, `report_comment_reply`, `report_comment_mention`, `comp_set_v2_shared`, `api_spend_alert`): The alert event type. - `channel` (string, required, one of: `inapp`, `email`): The delivery channel the alert is sent on. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "event": "price_posting_error", "channel": "inapp" } ] ``` ### 400 An unknown event or channel was provided. ### 401 API key authorization failed. ### 403 The API key is read-only and may not be used to update notification settings. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # List subscribable event types. `GET /webhook_events` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-webhook-events · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetWebhookEvents` · Tag: Webhooks Returns every event type a webhook subscription can ask for, with the object its ids refer to and how long events of that type are batched before being sent. Use the `event_type` values in `event_types` when creating or updating a subscription. The response does not describe what triggers each event — see [What fires each event](https://docs.usewheelhouse.com/rm/reference/webhooks.md) for the trigger conditions, including what does not fire each one. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/webhook_events` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/webhook_events' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of subscribable event types. Body (`application/json`): array of object `webhook_event_type` An event type a webhook subscription can ask for. - `event_type` (string, required, one of: `recommendations.updated`, `reservations.ingested`, `flags.detected`): Identifier used in `event_types` when creating or updating a subscription, and sent as the `type` field of the delivery envelope. See [What fires each event](https://docs.usewheelhouse.com/rm/reference/webhooks.md) for what triggers each one. - `subject` (string, required, example: `listing`): The kind of object the event's ids refer to. - `batch_window_seconds` (integer, required, example: `300`): How long events of this type are batched before being sent. Deliveries name every listing affected within the window. Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "event_type": "recommendations.updated", "subject": "listing", "batch_window_seconds": 300 } ] ``` ### 401 API key authorization failed. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # List webhook subscriptions. `GET /webhooks` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-webhooks · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetWebhooks` · Tag: Webhooks Returns the webhook subscriptions belonging to the authenticated user, most recently created first. Signing secrets are **not** included — they are only available when a subscription is created or its secret is rotated. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/webhooks` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/webhooks' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of the user's webhook subscriptions. Body (`application/json`): array of object `webhook` A registered webhook subscription. - `id` (integer, required): The Wheelhouse internal subscription ID. - `url` (string, required, example: `https://example.com/wheelhouse/webhooks`): The HTTPS endpoint deliveries are posted to. - `description` (string, nullable): Label for this subscription. - `event_types` (array of string, required): The event types this subscription receives. - `enabled` (boolean, required): Whether deliveries are being sent. Set to `false` automatically after sustained delivery failures; re-enable with `PUT /webhooks/{id}`. - `consecutive_failures` (integer): Failed deliveries since the last successful one. Reset on success. - `disabled_at` (string (date-time), nullable): When the subscription was disabled, automatically or otherwise (ISO-8601). - `last_delivered_at` (string (date-time), nullable): When a delivery to this endpoint last succeeded (ISO-8601). - `created_at` (string (date-time)): When the subscription was created (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "id": 0, "url": "https://example.com/wheelhouse/webhooks", "description": "string", "event_types": [ "string" ], "enabled": true, "consecutive_failures": 0, "disabled_at": "2026-01-01T00:00:00Z", "last_delivered_at": "2026-01-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z" } ] ``` ### 401 API key authorization failed. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Create a webhook subscription. `POST /webhooks` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-create-webhook · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmCreateWebhook` · Tag: Webhooks Registers an HTTPS endpoint to receive the given event types. The subscription covers the authenticated user's entire portfolio — owned listings plus listings shared with them to manage — and each delivery names only listings they can access. The response is the **only** place the signing secret appears; store it, because it cannot be read back afterwards. If you lose it, use `POST /webhooks/{id}/rotate_secret`. The endpoint must be `https`. Deliveries begin with the next batch window. ## Request `POST https://api.usewheelhouse.com/ss_api/v1/webhooks` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Request body (`application/json`, required) - `url` (string, required, example: `https://example.com/wheelhouse/webhooks`): HTTPS endpoint that deliveries are posted to. - `event_types` (array of string, required, each item one of: `recommendations.updated`, `reservations.ingested`, `flags.detected`): Event types this subscription should receive. See `GET /webhook_events`. - `description` (string): Label for this subscription. ### Example request ```bash curl -X POST 'https://api.usewheelhouse.com/ss_api/v1/webhooks' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{ "url": "https://example.com/wheelhouse/webhooks", "event_types": [ "recommendations.updated" ] }' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 201 The created subscription, including its signing secret. Body (`application/json`): object `webhook_with_secret` A registered webhook subscription. A subscription including its signing secret. Returned only on creation and by `POST /webhooks/{id}/rotate_secret`; store it, because it cannot be read back. - `id` (integer, required): The Wheelhouse internal subscription ID. - `url` (string, required, example: `https://example.com/wheelhouse/webhooks`): The HTTPS endpoint deliveries are posted to. - `description` (string, nullable): Label for this subscription. - `event_types` (array of string, required): The event types this subscription receives. - `enabled` (boolean, required): Whether deliveries are being sent. Set to `false` automatically after sustained delivery failures; re-enable with `PUT /webhooks/{id}`. - `consecutive_failures` (integer): Failed deliveries since the last successful one. Reset on success. - `disabled_at` (string (date-time), nullable): When the subscription was disabled, automatically or otherwise (ISO-8601). - `last_delivered_at` (string (date-time), nullable): When a delivery to this endpoint last succeeded (ISO-8601). - `created_at` (string (date-time)): When the subscription was created (ISO-8601). - `secret` (string, required, example: `whsec_0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0`): Secret used to verify the `Wh-Signature` header on each delivery. Recompute `HMAC-SHA256(secret, ".")` and compare. Example shape (generated from the schema; placeholder values, not a real response): ```json { "id": 0, "url": "https://example.com/wheelhouse/webhooks", "description": "string", "event_types": [ "string" ], "enabled": true, "consecutive_failures": 0, "disabled_at": "2026-01-01T00:00:00Z", "last_delivered_at": "2026-01-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z", "secret": "whsec_0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0" } ``` ### 400 An unknown event type was provided, or a required field was missing. ### 401 API key authorization failed. ### 403 The API key is read-only and may not be used to create a webhook. ### 409 A concurrent webhook request for this user is already in progress. Retry once it completes. ### 422 The endpoint was rejected. It must be an `https` URL on port 443 that resolves to a publicly routable address. This is re-checked before every delivery, so an endpoint that stops meeting it also stops receiving events. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Get a webhook subscription. `GET /webhooks/{id}` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-webhook · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetWebhook` · Tag: Webhooks Returns one of the authenticated user's webhook subscriptions, without its signing secret. Responds `404` for a subscription belonging to another account. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/webhooks/{id}` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `id` | integer | yes | The Wheelhouse internal subscription ID. | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/webhooks/{id}' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The subscription. Body (`application/json`): object `webhook` A registered webhook subscription. - `id` (integer, required): The Wheelhouse internal subscription ID. - `url` (string, required, example: `https://example.com/wheelhouse/webhooks`): The HTTPS endpoint deliveries are posted to. - `description` (string, nullable): Label for this subscription. - `event_types` (array of string, required): The event types this subscription receives. - `enabled` (boolean, required): Whether deliveries are being sent. Set to `false` automatically after sustained delivery failures; re-enable with `PUT /webhooks/{id}`. - `consecutive_failures` (integer): Failed deliveries since the last successful one. Reset on success. - `disabled_at` (string (date-time), nullable): When the subscription was disabled, automatically or otherwise (ISO-8601). - `last_delivered_at` (string (date-time), nullable): When a delivery to this endpoint last succeeded (ISO-8601). - `created_at` (string (date-time)): When the subscription was created (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json { "id": 0, "url": "https://example.com/wheelhouse/webhooks", "description": "string", "event_types": [ "string" ], "enabled": true, "consecutive_failures": 0, "disabled_at": "2026-01-01T00:00:00Z", "last_delivered_at": "2026-01-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z" } ``` ### 401 API key authorization failed. ### 404 No such webhook subscription for this user. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Update a webhook subscription. `PUT /webhooks/{id}` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-update-webhook · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmUpdateWebhook` · Tag: Webhooks Updates the fields provided and leaves the rest unchanged. Passing `event_types` **replaces** the subscribed set rather than adding to it; omitting it leaves the current set alone. Set `enabled` to `false` to pause delivery, and `true` to resume it. Resuming also clears the accumulated failure count, so a subscription disabled automatically after sustained failures starts fresh once the endpoint is healthy again. ## Request `PUT https://api.usewheelhouse.com/ss_api/v1/webhooks/{id}` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `id` | integer | yes | The Wheelhouse internal subscription ID. | ### Request body (`application/json`, required) - `url` (string): HTTPS endpoint that deliveries are posted to. - `event_types` (array of string, each item one of: `recommendations.updated`, `reservations.ingested`, `flags.detected`): Replaces the event types this subscription receives. - `description` (string): Label for this subscription. - `enabled` (boolean): Set `false` to pause delivery, `true` to resume it. ### Example request ```bash curl -X PUT 'https://api.usewheelhouse.com/ss_api/v1/webhooks/{id}' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{}' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The updated subscription. Body (`application/json`): object `webhook` A registered webhook subscription. - `id` (integer, required): The Wheelhouse internal subscription ID. - `url` (string, required, example: `https://example.com/wheelhouse/webhooks`): The HTTPS endpoint deliveries are posted to. - `description` (string, nullable): Label for this subscription. - `event_types` (array of string, required): The event types this subscription receives. - `enabled` (boolean, required): Whether deliveries are being sent. Set to `false` automatically after sustained delivery failures; re-enable with `PUT /webhooks/{id}`. - `consecutive_failures` (integer): Failed deliveries since the last successful one. Reset on success. - `disabled_at` (string (date-time), nullable): When the subscription was disabled, automatically or otherwise (ISO-8601). - `last_delivered_at` (string (date-time), nullable): When a delivery to this endpoint last succeeded (ISO-8601). - `created_at` (string (date-time)): When the subscription was created (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json { "id": 0, "url": "https://example.com/wheelhouse/webhooks", "description": "string", "event_types": [ "string" ], "enabled": true, "consecutive_failures": 0, "disabled_at": "2026-01-01T00:00:00Z", "last_delivered_at": "2026-01-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z" } ``` ### 400 An unknown event type was provided. ### 401 API key authorization failed. ### 403 The API key is read-only and may not be used to update a webhook. ### 404 No such webhook subscription for this user. ### 409 A concurrent webhook request for this user is already in progress. Retry once it completes. ### 422 The endpoint was rejected. It must be an `https` URL on port 443 that resolves to a publicly routable address. This is re-checked before every delivery, so an endpoint that stops meeting it also stops receiving events. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Delete a webhook subscription. `DELETE /webhooks/{id}` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-delete-webhook · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmDeleteWebhook` · Tag: Webhooks Removes the subscription and stops all delivery to it. Its delivery history is removed with it. ## Request `DELETE https://api.usewheelhouse.com/ss_api/v1/webhooks/{id}` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `id` | integer | yes | The Wheelhouse internal subscription ID. | ### Example request ```bash curl -X DELETE 'https://api.usewheelhouse.com/ss_api/v1/webhooks/{id}' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 204 Subscription deleted. ### 401 API key authorization failed. ### 403 The API key is read-only and may not be used to delete a webhook. ### 404 No such webhook subscription for this user. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Rotate a webhook signing secret. `POST /webhooks/{id}/rotate_secret` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-rotate-webhook-secret · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmRotateWebhookSecret` · Tag: Webhooks Issues a new signing secret and returns it. Use this if the current secret has leaked or been lost. The old secret stops being valid immediately, so deliveries signed with the new secret will fail verification until your endpoint is using it. Deploy the new secret promptly after rotating. ## Request `POST https://api.usewheelhouse.com/ss_api/v1/webhooks/{id}/rotate_secret` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `id` | integer | yes | The Wheelhouse internal subscription ID. | ### Example request ```bash curl -X POST 'https://api.usewheelhouse.com/ss_api/v1/webhooks/{id}/rotate_secret' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 201 The subscription, including its new signing secret. Body (`application/json`): object `webhook_with_secret` A registered webhook subscription. A subscription including its signing secret. Returned only on creation and by `POST /webhooks/{id}/rotate_secret`; store it, because it cannot be read back. - `id` (integer, required): The Wheelhouse internal subscription ID. - `url` (string, required, example: `https://example.com/wheelhouse/webhooks`): The HTTPS endpoint deliveries are posted to. - `description` (string, nullable): Label for this subscription. - `event_types` (array of string, required): The event types this subscription receives. - `enabled` (boolean, required): Whether deliveries are being sent. Set to `false` automatically after sustained delivery failures; re-enable with `PUT /webhooks/{id}`. - `consecutive_failures` (integer): Failed deliveries since the last successful one. Reset on success. - `disabled_at` (string (date-time), nullable): When the subscription was disabled, automatically or otherwise (ISO-8601). - `last_delivered_at` (string (date-time), nullable): When a delivery to this endpoint last succeeded (ISO-8601). - `created_at` (string (date-time)): When the subscription was created (ISO-8601). - `secret` (string, required, example: `whsec_0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0`): Secret used to verify the `Wh-Signature` header on each delivery. Recompute `HMAC-SHA256(secret, ".")` and compare. Example shape (generated from the schema; placeholder values, not a real response): ```json { "id": 0, "url": "https://example.com/wheelhouse/webhooks", "description": "string", "event_types": [ "string" ], "enabled": true, "consecutive_failures": 0, "disabled_at": "2026-01-01T00:00:00Z", "last_delivered_at": "2026-01-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z", "secret": "whsec_0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0" } ``` ### 401 API key authorization failed. ### 403 The API key is read-only and may not be used to rotate a secret. ### 404 No such webhook subscription for this user. ### 409 A concurrent webhook request for this user is already in progress. Retry once it completes. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # List recent delivery attempts. `GET /webhooks/{id}/deliveries` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-webhook-deliveries · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetWebhookDeliveries` · Tag: Webhooks Returns recent deliveries for the subscription, most recent first, with the HTTP status the endpoint returned and the reason for any failure. Use it to confirm what was sent and to diagnose an endpoint that is failing verification or timing out. Deliveries are retained for 7 days. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/webhooks/{id}/deliveries` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `id` | integer | yes | The Wheelhouse internal subscription ID. | ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `limit` | integer | no | Maximum number of deliveries to return. (default: `50`, min: 1, max: 200) | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/webhooks/{id}/deliveries' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of recent deliveries. Body (`application/json`): array of object `webhook_delivery` One attempt series to deliver one event to one subscription. - `id` (integer, required): The Wheelhouse internal delivery ID. - `event_id` (string (uuid), required): The idempotency key sent as the `Wh-Event-Id` header and the envelope `id`. Stable across retries of the same event, so it can be matched against your own records. - `event_type` (string, required): The event type delivered. - `status` (string, required, one of: `pending`, `delivered`, `failed`): `pending` while attempts remain, `delivered` once the endpoint returned 2xx, and `failed` once attempts were exhausted or the subscription was disabled. - `attempts` (integer, required): How many times delivery has been attempted. - `response_code` (integer, nullable): HTTP status the endpoint returned on the most recent attempt. - `error_message` (string, nullable): Why the most recent attempt failed, when it did. An HTTP status is reported as-is; other failures are reported as an error type without further detail. - `delivered_at` (string (date-time), nullable): When the endpoint accepted the delivery (ISO-8601). - `failed_at` (string (date-time), nullable): When the delivery was given up on (ISO-8601). - `created_at` (string (date-time)): When the delivery was queued (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "id": 0, "event_id": "string", "event_type": "string", "status": "pending", "attempts": 0, "response_code": 0, "error_message": "string", "delivered_at": "2026-01-01T00:00:00Z", "failed_at": "2026-01-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z" } ] ``` ### 401 API key authorization failed. ### 404 No such webhook subscription for this user. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # List team members. `GET /teams/members` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-team-members · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetTeamMembers` · Tag: Teams Returns the team members managed by the authenticated user. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/teams/members` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `include_managed_subs` | boolean | no | Also include the team members of any other Wheelhouse account for which the authenticated user has been granted manager-level (co-host) access to at least one listing — i.e., accounts the authenticated user administers on the owner's behalf. (default: `false`) | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/teams/members' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of team members. Body (`application/json`): array of object `sub_user_response` A team membership, linking a team owner (`user_id`) and a team member (`sub_user_id`). - `user_id` (integer): The Wheelhouse internal user ID of the team owner. - `sub_user_id` (integer): The Wheelhouse internal user ID of the team member. - `status` (string, one of: `A`, `P`, `I`, `D`): Membership status: `A` active, `P` pending, `I` inactive, `D` declined. - `user_first_name` (string, nullable): First name of the team owner. - `user_last_name` (string, nullable): Last name of the team owner. - `user_email` (string): Email of the team owner. - `subuser_first_name` (string, nullable): First name of the team member. - `subuser_last_name` (string, nullable): Last name of the team member. - `subuser_email` (string): Email of the team member. - `billing_delegated` (boolean, nullable): Whether the team owner's billing is delegated to the team member. - `billing_delegated_at` (string (date-time), nullable): When billing was delegated (ISO-8601). - `auto_managed_listing_level` (string, one of: `N`, `R`, `E`, `F`, `M`): The access level the team member is automatically granted on the owner's listings: `N` disabled, `R` viewer, `E` restricted editor, `F` editor, `M` manager. - `sub_user_assignments` (array of object): Portfolio segments assigned to the team member for auto managed listing access. - `id` (integer): The Wheelhouse internal assignment ID. - `sub_user_id` (integer): The Wheelhouse internal `SubUser` record ID this assignment belongs to (distinct from the `sub_user_id` field on the team membership itself). - `assignable_id` (integer): The ID of the assigned resource (currently always a portfolio segment ID). - `assignable_type` (string): The type of the assigned resource (currently always `PortfolioSegment`). - `created_at` (string (date-time)): When the assignment was created (ISO-8601). - `updated_at` (string (date-time)): When the assignment was last updated (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "user_id": 0, "sub_user_id": 0, "status": "A", "user_first_name": "string", "user_last_name": "string", "user_email": "string", "subuser_first_name": "string", "subuser_last_name": "string", "subuser_email": "string", "billing_delegated": true, "billing_delegated_at": "2026-01-01T00:00:00Z", "auto_managed_listing_level": "N", "sub_user_assignments": [ { "id": 0, "sub_user_id": 0, "assignable_id": 0, "assignable_type": "string", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ] } ] ``` ### 401 API key authorization failed. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Invite a team member. `POST /teams/members/invite` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-post-team-member-invite · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPostTeamMemberInvite` · Tag: Teams Invites a user by email to join the authenticated user's team. If the invitee does not yet have a Wheelhouse account, a pending one is created for them. ## Request `POST https://api.usewheelhouse.com/ss_api/v1/teams/members/invite` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Request body (`application/json`, required) - `email` (string, required): Email address of the invitee. - `billing_delegated` (boolean): Delegate billing for the invitee to the authenticated user. ### Example request ```bash curl -X POST 'https://api.usewheelhouse.com/ss_api/v1/teams/members/invite' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{ "email": "string" }' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 201 The newly created (pending) team membership. Body (`application/json`): object `sub_user_response` A team membership, linking a team owner (`user_id`) and a team member (`sub_user_id`). - `user_id` (integer): The Wheelhouse internal user ID of the team owner. - `sub_user_id` (integer): The Wheelhouse internal user ID of the team member. - `status` (string, one of: `A`, `P`, `I`, `D`): Membership status: `A` active, `P` pending, `I` inactive, `D` declined. - `user_first_name` (string, nullable): First name of the team owner. - `user_last_name` (string, nullable): Last name of the team owner. - `user_email` (string): Email of the team owner. - `subuser_first_name` (string, nullable): First name of the team member. - `subuser_last_name` (string, nullable): Last name of the team member. - `subuser_email` (string): Email of the team member. - `billing_delegated` (boolean, nullable): Whether the team owner's billing is delegated to the team member. - `billing_delegated_at` (string (date-time), nullable): When billing was delegated (ISO-8601). - `auto_managed_listing_level` (string, one of: `N`, `R`, `E`, `F`, `M`): The access level the team member is automatically granted on the owner's listings: `N` disabled, `R` viewer, `E` restricted editor, `F` editor, `M` manager. - `sub_user_assignments` (array of object): Portfolio segments assigned to the team member for auto managed listing access. - `id` (integer): The Wheelhouse internal assignment ID. - `sub_user_id` (integer): The Wheelhouse internal `SubUser` record ID this assignment belongs to (distinct from the `sub_user_id` field on the team membership itself). - `assignable_id` (integer): The ID of the assigned resource (currently always a portfolio segment ID). - `assignable_type` (string): The type of the assigned resource (currently always `PortfolioSegment`). - `created_at` (string (date-time)): When the assignment was created (ISO-8601). - `updated_at` (string (date-time)): When the assignment was last updated (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json { "user_id": 0, "sub_user_id": 0, "status": "A", "user_first_name": "string", "user_last_name": "string", "user_email": "string", "subuser_first_name": "string", "subuser_last_name": "string", "subuser_email": "string", "billing_delegated": true, "billing_delegated_at": "2026-01-01T00:00:00Z", "auto_managed_listing_level": "N", "sub_user_assignments": [ { "id": 0, "sub_user_id": 0, "assignable_id": 0, "assignable_type": "string", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ] } ``` ### 400 Request body is invalid (e.g. `email` is missing). ### 401 API key authorization failed. ### 403 Read-only API key cannot invite team members. ### 409 A concurrent request for this team is already in progress. Retry after it completes. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Remove a team member. `DELETE /teams/members/{sub_user_id}` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-delete-team-member · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmDeleteTeamMember` · Tag: Teams Deactivates a team member, revoking their access to the authenticated user's listings. ## Request `DELETE https://api.usewheelhouse.com/ss_api/v1/teams/members/{sub_user_id}` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `sub_user_id` | integer | yes | The Wheelhouse internal user ID of the team member (the `sub_user_id` field from a team member response). | ### Example request ```bash curl -X DELETE 'https://api.usewheelhouse.com/ss_api/v1/teams/members/{sub_user_id}' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The deactivated team member. Body (`application/json`): object `sub_user_response` A team membership, linking a team owner (`user_id`) and a team member (`sub_user_id`). - `user_id` (integer): The Wheelhouse internal user ID of the team owner. - `sub_user_id` (integer): The Wheelhouse internal user ID of the team member. - `status` (string, one of: `A`, `P`, `I`, `D`): Membership status: `A` active, `P` pending, `I` inactive, `D` declined. - `user_first_name` (string, nullable): First name of the team owner. - `user_last_name` (string, nullable): Last name of the team owner. - `user_email` (string): Email of the team owner. - `subuser_first_name` (string, nullable): First name of the team member. - `subuser_last_name` (string, nullable): Last name of the team member. - `subuser_email` (string): Email of the team member. - `billing_delegated` (boolean, nullable): Whether the team owner's billing is delegated to the team member. - `billing_delegated_at` (string (date-time), nullable): When billing was delegated (ISO-8601). - `auto_managed_listing_level` (string, one of: `N`, `R`, `E`, `F`, `M`): The access level the team member is automatically granted on the owner's listings: `N` disabled, `R` viewer, `E` restricted editor, `F` editor, `M` manager. - `sub_user_assignments` (array of object): Portfolio segments assigned to the team member for auto managed listing access. - `id` (integer): The Wheelhouse internal assignment ID. - `sub_user_id` (integer): The Wheelhouse internal `SubUser` record ID this assignment belongs to (distinct from the `sub_user_id` field on the team membership itself). - `assignable_id` (integer): The ID of the assigned resource (currently always a portfolio segment ID). - `assignable_type` (string): The type of the assigned resource (currently always `PortfolioSegment`). - `created_at` (string (date-time)): When the assignment was created (ISO-8601). - `updated_at` (string (date-time)): When the assignment was last updated (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json { "user_id": 0, "sub_user_id": 0, "status": "A", "user_first_name": "string", "user_last_name": "string", "user_email": "string", "subuser_first_name": "string", "subuser_last_name": "string", "subuser_email": "string", "billing_delegated": true, "billing_delegated_at": "2026-01-01T00:00:00Z", "auto_managed_listing_level": "N", "sub_user_assignments": [ { "id": 0, "sub_user_id": 0, "assignable_id": 0, "assignable_type": "string", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ] } ``` ### 401 API key authorization failed. ### 403 Read-only API key cannot remove team members. ### 404 Team member not found. ### 409 A concurrent request for this team is already in progress. Retry after it completes. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Set a team member's auto managed listing level. `POST /teams/members/{sub_user_id}/auto_managed_listing_level` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-post-team-member-auto-managed-listing-level · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPostTeamMemberAutoManagedListingLevel` · Tag: Teams Sets the access level a team member is automatically granted on the authenticated user's listings. When no portfolio segments are assigned to the team member (see `POST /teams/members/{sub_user_id}/assigned_segments`), this level applies to all of the authenticated user's listings. ## Request `POST https://api.usewheelhouse.com/ss_api/v1/teams/members/{sub_user_id}/auto_managed_listing_level` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `sub_user_id` | integer | yes | The Wheelhouse internal user ID of the team member. | ### Request body (`application/json`, required) - `level` (string, required, one of: `N`, `R`, `E`, `F`, `M`): The auto managed listing level. `N` disabled, `R` viewer, `E` restricted editor, `F` editor, `M` manager. ### Example request ```bash curl -X POST 'https://api.usewheelhouse.com/ss_api/v1/teams/members/{sub_user_id}/auto_managed_listing_level' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{ "level": "N" }' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The updated team member. Body (`application/json`): object `sub_user_response` A team membership, linking a team owner (`user_id`) and a team member (`sub_user_id`). - `user_id` (integer): The Wheelhouse internal user ID of the team owner. - `sub_user_id` (integer): The Wheelhouse internal user ID of the team member. - `status` (string, one of: `A`, `P`, `I`, `D`): Membership status: `A` active, `P` pending, `I` inactive, `D` declined. - `user_first_name` (string, nullable): First name of the team owner. - `user_last_name` (string, nullable): Last name of the team owner. - `user_email` (string): Email of the team owner. - `subuser_first_name` (string, nullable): First name of the team member. - `subuser_last_name` (string, nullable): Last name of the team member. - `subuser_email` (string): Email of the team member. - `billing_delegated` (boolean, nullable): Whether the team owner's billing is delegated to the team member. - `billing_delegated_at` (string (date-time), nullable): When billing was delegated (ISO-8601). - `auto_managed_listing_level` (string, one of: `N`, `R`, `E`, `F`, `M`): The access level the team member is automatically granted on the owner's listings: `N` disabled, `R` viewer, `E` restricted editor, `F` editor, `M` manager. - `sub_user_assignments` (array of object): Portfolio segments assigned to the team member for auto managed listing access. - `id` (integer): The Wheelhouse internal assignment ID. - `sub_user_id` (integer): The Wheelhouse internal `SubUser` record ID this assignment belongs to (distinct from the `sub_user_id` field on the team membership itself). - `assignable_id` (integer): The ID of the assigned resource (currently always a portfolio segment ID). - `assignable_type` (string): The type of the assigned resource (currently always `PortfolioSegment`). - `created_at` (string (date-time)): When the assignment was created (ISO-8601). - `updated_at` (string (date-time)): When the assignment was last updated (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json { "user_id": 0, "sub_user_id": 0, "status": "A", "user_first_name": "string", "user_last_name": "string", "user_email": "string", "subuser_first_name": "string", "subuser_last_name": "string", "subuser_email": "string", "billing_delegated": true, "billing_delegated_at": "2026-01-01T00:00:00Z", "auto_managed_listing_level": "N", "sub_user_assignments": [ { "id": 0, "sub_user_id": 0, "assignable_id": 0, "assignable_type": "string", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ] } ``` ### 400 Request body is invalid (e.g. `level` is not a recognized value). ### 401 API key authorization failed. ### 403 Read-only API key cannot update team members. ### 404 Team member not found. ### 409 A concurrent request for this team is already in progress. Retry after it completes. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Assign portfolio segments to a team member. `POST /teams/members/{sub_user_id}/assigned_segments` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-post-team-member-assigned-segments · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPostTeamMemberAssignedSegments` · Tag: Teams Sets the portfolio segments a team member auto manages listings for, then immediately refreshes their auto managed listing access to match. Replaces any previously assigned segments. ## Request `POST https://api.usewheelhouse.com/ss_api/v1/teams/members/{sub_user_id}/assigned_segments` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `sub_user_id` | integer | yes | The Wheelhouse internal user ID of the team member. | ### Request body (`application/json`, required) - `ids` (array of integer, required): Portfolio segment IDs. ### Example request ```bash curl -X POST 'https://api.usewheelhouse.com/ss_api/v1/teams/members/{sub_user_id}/assigned_segments' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{ "ids": [ 0 ] }' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The updated team member. Body (`application/json`): object `sub_user_response` A team membership, linking a team owner (`user_id`) and a team member (`sub_user_id`). - `user_id` (integer): The Wheelhouse internal user ID of the team owner. - `sub_user_id` (integer): The Wheelhouse internal user ID of the team member. - `status` (string, one of: `A`, `P`, `I`, `D`): Membership status: `A` active, `P` pending, `I` inactive, `D` declined. - `user_first_name` (string, nullable): First name of the team owner. - `user_last_name` (string, nullable): Last name of the team owner. - `user_email` (string): Email of the team owner. - `subuser_first_name` (string, nullable): First name of the team member. - `subuser_last_name` (string, nullable): Last name of the team member. - `subuser_email` (string): Email of the team member. - `billing_delegated` (boolean, nullable): Whether the team owner's billing is delegated to the team member. - `billing_delegated_at` (string (date-time), nullable): When billing was delegated (ISO-8601). - `auto_managed_listing_level` (string, one of: `N`, `R`, `E`, `F`, `M`): The access level the team member is automatically granted on the owner's listings: `N` disabled, `R` viewer, `E` restricted editor, `F` editor, `M` manager. - `sub_user_assignments` (array of object): Portfolio segments assigned to the team member for auto managed listing access. - `id` (integer): The Wheelhouse internal assignment ID. - `sub_user_id` (integer): The Wheelhouse internal `SubUser` record ID this assignment belongs to (distinct from the `sub_user_id` field on the team membership itself). - `assignable_id` (integer): The ID of the assigned resource (currently always a portfolio segment ID). - `assignable_type` (string): The type of the assigned resource (currently always `PortfolioSegment`). - `created_at` (string (date-time)): When the assignment was created (ISO-8601). - `updated_at` (string (date-time)): When the assignment was last updated (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json { "user_id": 0, "sub_user_id": 0, "status": "A", "user_first_name": "string", "user_last_name": "string", "user_email": "string", "subuser_first_name": "string", "subuser_last_name": "string", "subuser_email": "string", "billing_delegated": true, "billing_delegated_at": "2026-01-01T00:00:00Z", "auto_managed_listing_level": "N", "sub_user_assignments": [ { "id": 0, "sub_user_id": 0, "assignable_id": 0, "assignable_type": "string", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ] } ``` ### 401 API key authorization failed. ### 403 Read-only API key cannot update team members. ### 404 Team member not found, or one or more portfolio segment IDs are not owned by the authenticated user. ### 409 A concurrent request for this team is already in progress. Retry after it completes. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Refresh a team member's auto managed listing access. `POST /teams/members/{sub_user_id}/refresh_auto_managed_listings` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-post-team-member-refresh-auto-managed-listings · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPostTeamMemberRefreshAutoManagedListings` · Tag: Teams Re-evaluates and applies the auto managed listing level and assigned segments for a team member against the authenticated user's current listings. ## Request `POST https://api.usewheelhouse.com/ss_api/v1/teams/members/{sub_user_id}/refresh_auto_managed_listings` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `sub_user_id` | integer | yes | The Wheelhouse internal user ID of the team member. | ### Example request ```bash curl -X POST 'https://api.usewheelhouse.com/ss_api/v1/teams/members/{sub_user_id}/refresh_auto_managed_listings' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 The refreshed team member. Body (`application/json`): object `sub_user_response` A team membership, linking a team owner (`user_id`) and a team member (`sub_user_id`). - `user_id` (integer): The Wheelhouse internal user ID of the team owner. - `sub_user_id` (integer): The Wheelhouse internal user ID of the team member. - `status` (string, one of: `A`, `P`, `I`, `D`): Membership status: `A` active, `P` pending, `I` inactive, `D` declined. - `user_first_name` (string, nullable): First name of the team owner. - `user_last_name` (string, nullable): Last name of the team owner. - `user_email` (string): Email of the team owner. - `subuser_first_name` (string, nullable): First name of the team member. - `subuser_last_name` (string, nullable): Last name of the team member. - `subuser_email` (string): Email of the team member. - `billing_delegated` (boolean, nullable): Whether the team owner's billing is delegated to the team member. - `billing_delegated_at` (string (date-time), nullable): When billing was delegated (ISO-8601). - `auto_managed_listing_level` (string, one of: `N`, `R`, `E`, `F`, `M`): The access level the team member is automatically granted on the owner's listings: `N` disabled, `R` viewer, `E` restricted editor, `F` editor, `M` manager. - `sub_user_assignments` (array of object): Portfolio segments assigned to the team member for auto managed listing access. - `id` (integer): The Wheelhouse internal assignment ID. - `sub_user_id` (integer): The Wheelhouse internal `SubUser` record ID this assignment belongs to (distinct from the `sub_user_id` field on the team membership itself). - `assignable_id` (integer): The ID of the assigned resource (currently always a portfolio segment ID). - `assignable_type` (string): The type of the assigned resource (currently always `PortfolioSegment`). - `created_at` (string (date-time)): When the assignment was created (ISO-8601). - `updated_at` (string (date-time)): When the assignment was last updated (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json { "user_id": 0, "sub_user_id": 0, "status": "A", "user_first_name": "string", "user_last_name": "string", "user_email": "string", "subuser_first_name": "string", "subuser_last_name": "string", "subuser_email": "string", "billing_delegated": true, "billing_delegated_at": "2026-01-01T00:00:00Z", "auto_managed_listing_level": "N", "sub_user_assignments": [ { "id": 0, "sub_user_id": 0, "assignable_id": 0, "assignable_type": "string", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ] } ``` ### 401 API key authorization failed. ### 403 Read-only API key cannot update team members. ### 404 Team member not found. ### 409 A concurrent request for this team is already in progress. Retry after it completes. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # List team memberships. `GET /teams/memberships` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-team-memberships · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetTeamMemberships` · Tag: Teams Returns the teams the authenticated user belongs to as a team member (i.e. teams owned by another Wheelhouse account). ## Request `GET https://api.usewheelhouse.com/ss_api/v1/teams/memberships` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/teams/memberships' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Array of team memberships. Body (`application/json`): array of object `sub_user_response` A team membership, linking a team owner (`user_id`) and a team member (`sub_user_id`). - `user_id` (integer): The Wheelhouse internal user ID of the team owner. - `sub_user_id` (integer): The Wheelhouse internal user ID of the team member. - `status` (string, one of: `A`, `P`, `I`, `D`): Membership status: `A` active, `P` pending, `I` inactive, `D` declined. - `user_first_name` (string, nullable): First name of the team owner. - `user_last_name` (string, nullable): Last name of the team owner. - `user_email` (string): Email of the team owner. - `subuser_first_name` (string, nullable): First name of the team member. - `subuser_last_name` (string, nullable): Last name of the team member. - `subuser_email` (string): Email of the team member. - `billing_delegated` (boolean, nullable): Whether the team owner's billing is delegated to the team member. - `billing_delegated_at` (string (date-time), nullable): When billing was delegated (ISO-8601). - `auto_managed_listing_level` (string, one of: `N`, `R`, `E`, `F`, `M`): The access level the team member is automatically granted on the owner's listings: `N` disabled, `R` viewer, `E` restricted editor, `F` editor, `M` manager. - `sub_user_assignments` (array of object): Portfolio segments assigned to the team member for auto managed listing access. - `id` (integer): The Wheelhouse internal assignment ID. - `sub_user_id` (integer): The Wheelhouse internal `SubUser` record ID this assignment belongs to (distinct from the `sub_user_id` field on the team membership itself). - `assignable_id` (integer): The ID of the assigned resource (currently always a portfolio segment ID). - `assignable_type` (string): The type of the assigned resource (currently always `PortfolioSegment`). - `created_at` (string (date-time)): When the assignment was created (ISO-8601). - `updated_at` (string (date-time)): When the assignment was last updated (ISO-8601). Example shape (generated from the schema; placeholder values, not a real response): ```json [ { "user_id": 0, "sub_user_id": 0, "status": "A", "user_first_name": "string", "user_last_name": "string", "user_email": "string", "subuser_first_name": "string", "subuser_last_name": "string", "subuser_email": "string", "billing_delegated": true, "billing_delegated_at": "2026-01-01T00:00:00Z", "auto_managed_listing_level": "N", "sub_user_assignments": [ { "id": 0, "sub_user_id": 0, "assignable_id": 0, "assignable_type": "string", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ] } ] ``` ### 401 API key authorization failed. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Accept a team invitation. `POST /teams/memberships/{master_user_id}` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-post-team-membership · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPostTeamMembership` · Tag: Teams Accepts a pending invitation to join another Wheelhouse account's team. Does nothing (still returns success) if there is no matching pending invitation. ## Request `POST https://api.usewheelhouse.com/ss_api/v1/teams/memberships/{master_user_id}` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `master_user_id` | integer | yes | The Wheelhouse internal user ID of the team owner (the `user_id` field from a team membership response). | ### Example request ```bash curl -X POST 'https://api.usewheelhouse.com/ss_api/v1/teams/memberships/{master_user_id}' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Invitation accepted (or no matching pending invitation existed). The body is an empty object. Body (`application/json`): object Example shape (generated from the schema; placeholder values, not a real response): ```json {} ``` ### 401 API key authorization failed. ### 403 Read-only API key cannot accept team invitations. ### 409 A concurrent request for this team is already in progress. Retry after it completes. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Leave a team, or decline an invitation. `DELETE /teams/memberships/{master_user_id}` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-delete-team-membership · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmDeleteTeamMembership` · Tag: Teams Deactivates the authenticated user's membership in another Wheelhouse account's team. Also used to decline a pending invitation. ## Request `DELETE https://api.usewheelhouse.com/ss_api/v1/teams/memberships/{master_user_id}` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `master_user_id` | integer | yes | The Wheelhouse internal user ID of the team owner. | ### Example request ```bash curl -X DELETE 'https://api.usewheelhouse.com/ss_api/v1/teams/memberships/{master_user_id}' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Membership deactivated (or no matching membership existed). The body is an empty object. Body (`application/json`): object Example shape (generated from the schema; placeholder values, not a real response): ```json {} ``` ### 401 API key authorization failed. ### 403 Read-only API key cannot leave a team. ### 409 A concurrent request for this team is already in progress. Retry after it completes. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ``` --- # Send feedback about the API. `POST /feedback` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-post-feedback · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPostFeedback` · Tag: Feedback Sends feedback about this API to the Wheelhouse team: something that failed, documentation that was unclear or wrong, an endpoint or field you needed and could not find, or something that worked well. Every item is read and triaged; nobody replies to it, so do not use it for account support. Write the `message` so that someone without your context can act on it: what you tried, what happened, and what you expected. Send one item per issue. Leave out guest names, contact details and other personal data. Read-only API keys may send feedback, and feedback calls are not billed. Each user can send up to 30 items per hour and 100 per day; more returns **429**. ## Request `POST https://api.usewheelhouse.com/ss_api/v1/feedback` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`. ### Request body (`application/json`, required) - `message` (string, required, max length: 4000): The feedback itself. At most 4000 characters. - `category` (string, one of: `bug`, `confusing_docs`, `missing_capability`, `praise`, `other`, default: `other`): What kind of feedback this is. `bug`: something returned an error or a wrong result. `confusing_docs`: the documentation was unclear, incomplete or wrong. `missing_capability`: something you needed that the API cannot do. `praise`: something that worked well. `other`: anything else. Defaults to `other`. - `endpoint` (string, max length: 255): The endpoint the feedback is about, such as `GET /listings/{listing_id}/price_recommendations`. Leave it out for feedback that is not about one endpoint, such as a request for something new. At most 255 characters. - `listing_id` (string, max length: 100): The listing the feedback is about, if any, as you would pass it to other endpoints. At most 100 characters. ### Example request ```bash curl -X POST 'https://api.usewheelhouse.com/ss_api/v1/feedback' \ -H 'X-Integration-Api-Key: ' \ -H 'Content-Type: application/json' \ -d '{ "message": "string" }' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 201 The feedback was received. Body (`application/json`): object - `id` (integer): Identifies this feedback item. Quote it if you refer to the item elsewhere. - `category` (string): The category the feedback was stored under. - `created_at` (string (date-time)): When the feedback was received. - `note` (string): A confirmation to pass on to the person you are working for, including where to go for account support. Example shape (generated from the schema; placeholder values, not a real response): ```json { "id": 0, "category": "string", "created_at": "2026-01-01T00:00:00Z", "note": "string" } ``` ### 400 Invalid parameters, such as a missing or overlong `message` or an unknown `category`. ### 401 API key authorization failed. ### 429 Too much feedback from this user in the last hour or day, or the API key is at its rate limit. --- # Aggregated API usage for the authenticated user. `GET /usage` > Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-usage · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetUsage` · Tag: Usage Returns request volumes, error rates and response times over a recent window, broken down by day, by endpoint and by API key. It answers the questions the audit log in the Wheelhouse app answers, without having to read it request by request: which endpoint dominates your traffic, whether a key is being throttled, when errors started. Covers every RM API key on the account, not just the one making the request. Pass `token_id` to narrow it to a single key. **The window is limited to 7 days.** Pass `days_back` for a rolling window ending now, or `start_time` and `end_time` for an explicit one — a window longer than 7 days returns **400**. A window with more requests than can be read in one call sets `window.truncated` to `true` and reports the shorter window actually measured, with the most recent requests always covered. **Results are cached for a few minutes.** `generated_at` reports when the figures were computed, which is not the same as when they were served: repeat calls inside the cache window return the same numbers. Polling faster than that gains nothing. If what you want is your live rate limit headroom, read the `X-RateLimit-*` headers on any response instead — they are current as of that request and cost nothing extra. Requests are grouped by the endpoint that served them rather than by the exact path called, so every `GET /listings/{listing_id}/notes` counts towards one entry no matter which listing it named. ## Request `GET https://api.usewheelhouse.com/ss_api/v1/usage` Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint. ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `days_back` | integer | no | Size in days of a rolling window ending now. Ignored when `start_time` is given. (default: `7`, min: 1, max: 7) | | `start_time` | string (date-time) | no | Start of an explicit window (ISO-8601). Overrides `days_back`. | | `end_time` | string (date-time) | no | End of an explicit window (ISO-8601). Defaults to now. | | `token_id` | integer | no | Restrict the figures to a single RM API key. Must be a key belonging to the authenticated user; the `id` values returned in `by_token` are valid here. | ### Example request ```bash curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/usage' \ -H 'X-Integration-Api-Key: ' ``` Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say. ## Responses ### 200 Usage figures for the window. Body (`application/json`): object `usage_response` - `generated_at` (string (date-time)): When these figures were computed (ISO-8601). Repeat calls within the cache window return the same value. - `window` (object) - `start` (string (date-time)): Start of the window the figures cover (ISO-8601). - `end` (string (date-time)): End of the window the figures cover (ISO-8601). - `truncated` (boolean): Whether the window was too busy to measure in full. When `true`, `start` has been moved forward to the oldest request actually counted, and every figure below covers that shorter window. - `totals` (object) - `requests` (integer): Requests made in the window. - `by_status_class` (map of string to integer): Requests by response status class. `2xx`, `3xx`, `4xx` and `5xx` are always present; other classes appear only if observed. - `rate_limited` (integer): Requests rejected with 429 Too Many Requests. Also counted under `4xx`. - `avg_response_ms` (number, nullable): Mean server-side response time in milliseconds. `null` if no requests were made. - `p95_response_ms` (number, nullable): 95th-percentile server-side response time in milliseconds. `null` if no requests were made. - `by_day` (array of object): One entry per UTC day on which requests were made, oldest first. Days with no traffic are omitted. - `date` (string (date)): The UTC day (YYYY-MM-DD). - `requests` (integer) - `errors` (integer): Requests that returned 4xx or 5xx. - `by_endpoint` (array of object): One entry per endpoint, busiest first. Paths are reported as route patterns, so all requests to the same endpoint are grouped regardless of which listing or resource they named. - `method` (string, example: `GET`) - `path` (string, example: `/listings/{listing_id}/notes`): The route pattern, relative to the API base path. `other` covers requests that matched no endpoint. - `requests` (integer) - `errors` (integer): Requests that returned 4xx or 5xx. - `avg_response_ms` (number, nullable): Mean server-side response time in milliseconds for this endpoint. - `by_token` (array of object): One entry per RM API key that made requests in the window, busiest first. - `id` (integer) - `name` (string, nullable): The name given to the key, or `null` if it has been revoked or was never named. - `last_chars` (string, nullable): The last four characters of the key, as shown in the Wheelhouse app. - `requests` (integer) Example shape (generated from the schema; placeholder values, not a real response): ```json { "generated_at": "2026-01-01T00:00:00Z", "window": { "start": "2026-01-01T00:00:00Z", "end": "2026-01-01T00:00:00Z", "truncated": true }, "totals": { "requests": 0, "by_status_class": { "key": 0 }, "rate_limited": 0, "avg_response_ms": 0, "p95_response_ms": 0 }, "by_day": [ { "date": "2026-01-01", "requests": 0, "errors": 0 } ], "by_endpoint": [ { "method": "GET", "path": "/listings/{listing_id}/notes", "requests": 0, "errors": 0, "avg_response_ms": 0 } ], "by_token": [ { "id": 0, "name": "string", "last_chars": "string", "requests": 0 } ] } ``` ### 400 The requested window is longer than 7 days, `start_time` is after `end_time`, or `days_back` is out of range. ### 401 API key authorization failed. ### 404 No such API key belongs to the authenticated user. ### 429 Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy. Body (`application/json`): object - `error` (string, example: `API token is at rate limit`) Example shape (generated from the schema; placeholder values, not a real response): ```json { "error": "API token is at rate limit" } ```