Skip to main content
Version: v1.0%20%28beta%29

Wheelhouse Revenue Management API

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:

HeaderMeaning
X-RateLimit-LimitRequests allowed per window for the key you used.
X-RateLimit-RemainingRequests still available in the current window. Never negative.
X-RateLimit-ResetUnix 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). 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).

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:

{"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).

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:

TierWhat it is
FreeNo Pro plan.
Pro Flex, Pro FlatThe paid Pro plans. They differ in how they are billed, not in what the API allows.
Pro TrialA trial of Pro, with the same access as the paid Pro plans.
Pro OnboardingAn 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.

FreePro Flex, Pro Flat, Pro TrialPro Onboarding
GET /listings/{listing_id}/price_recommendations30 days ahead by default545 days (18 months) ahead by default545 days (18 months) ahead by default
GET /listings/{listing_id}/price_calendarToday through 545 days ahead by default, up to 3 years per requestSameSame
GET /listings/{listing_id}/calendar_day_history402 Payment RequiredStay dates up to 180 days backStay dates up to 180 days back
Market report endpoints (/market_report)404 Not Found for a market where you hold only Free listingsAvailableAvailable
POST /listings/{listing_id}/sync429 Too Many RequestsNo daily limit429 Too Many Requests
Automatic price postingNot available (except on some channels)Available, and on when automatic_rate_posting_enabled is trueNot 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 for the endpoints that need a paid set.

Authentication​

All RM API requests require an RM API key sent in this header.

Read-only keys are limited to GET, HEAD, OPTIONS, and POST. PUT and DELETE return 403 Forbidden (as do other disallowed methods), as do POST endpoints that create or modify data, except POST /feedback.

Security Scheme Type:

apiKey

Header parameter name:

X-Integration-Api-Key

License