# 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)
