Wheelhouse Pro API (v1.0)

For a minimal direct integration of a proprietary system, we recommend to follow this basic execution flow in order to set up a portfolio and get daily price recommendations.

To integrate a property management system or channel manager, we recommend to follow this execution flow in order to connect individual end users, refresh daily price recommendations, and leverage the full capabilities of the Wheelhouse platform.

For the integration of a property management system or channel manager, we recommend these UX flows for the typical processes of connecting a new user and (de-)activating pricing for a listing.

Connecting

Activating Pricing

Deactivating Pricing

https://api.usewheelhouse.com/ss_api/v1/

Wheelhouse can support any reasonable rate limit that you require.

On average you can expect 4-6 API calls to update a single listing. For a portfolio with 1,000 listings, your system would therefore likely make 4,000 - 6,000 API calls per day to update a full portfolio update. At 100 calls per minute, your system would update these 1,000 listings in ~50 minutes.

To ensure no undue latency, we recommend using an exponential backoff strategy when encountering a 429 Too Many Requests response from our API. If your traffic increases to the point where you are receiving many 429s a day, we will discuss mitigation strategies, including an increase of the rate limit.

Note: during the initial build/testing phase, our API's default rate limit is 20 requests / minute to prevent any accidental overloading of the system. If this is an impediment to testing, please [reach out to us] (mailto:tech-support@usewheelhouse.com) with any questions and we can adjust accordingly.

We do support webhook callbacks to alert API users e.g. when a listing's price recommndations have been updated or when a front end user requested a calendar refresh for a listing for which they have granted access to an API customer. Each web hook will provide the event name (as event), a boolean flag user_initiated that indicates if the webhook was initiated by a user action or through automatic routines, the external_user_id of the user the listing belongs to, and additional parameters in the body of the callback. We currently support these web hooks:

• account_sync_requested: all listings and data of a user should be refreshed
• listing_sync_requested: a particular listing and its data should be refreshed (parameters: listing_id)
• listing_recommendations_updated: updated recommendations for a listing are available (parameters: listing_id)
• listing_automation_changed: the automation status of a listing has changed (parameters: listing_id, posting_enabled)
• account_deactivated: the account has been deactivated on Wheelhouse

For example, the payload of a call to notify about updated recommendations could look like this: { "event": "listing_recommendations_updated", "listing_id": "abc_1234", "user_initiated": false, "external_user_id": "user_007" }

Web hooks can use separate URLs for the individual events as well as separate URLs for test and production environments. Please reach out to us directly to inquire about the setup of this feature.

Registering each end user is a requirement of using our API. It allows us to isolate billing information and may enable future APIs or integrations.

Once registered, each user will receive a specific API key that must be included in requests for that user's listings.

Additionally, if you have a customer who already has a Wheelhouse account with linked listings, the user can grant you API access to their listings by generating a User API Key here: https://app.usewheelhouse.com/u/account/api_token. Once they have created this key, they give it to you and you can use it in the X-User-API-Key header to retrieve and update their listings and pull price recommendations.

Important: A user's id (external_user_id in the User payload) MUST be unique across environments. In systems where uniqueness cannot be guaranteed, we recommend prepending the id with the environment. For example, an integrator may be using the primary key in their User database table as the external_user_id. If they had separate databases per environment, it would be possible for these ids to collide. Instead, the integrator could send an external_user_id of the format test-{user_primary_key} and prod-{user_primary_key}.

Listing information drives the baseline of our price recommendations. The more detail you can provide, the better our recommendations will be.

Important: A listing id (id in the PUT Listing payload) MUST be unique across environments and users. In systems where uniqueness cannot be guaranteed, we recommend prepending the id with the environment and user id, if necessary. For example, an integrator may be using the primary key in their Listing database table as the listing's id. If they had separate databases per environment, it would be possible for these ids to collide. Instead, the integrator could send an id of the format test-{listing_primary_key} and prod-{listing_primary_key}.

Another example would would be if an integrator re-used listing ids between different users. In this case, the integrator could send an id of the format {external_user_id}-{listing_primary_key} to guarantee uniqueness.

Reservations drive price anchoring and occupancy statistics for your properties. They are instrumental to our ability to make price recommendations.

During setup

The reservations create/update endpoint is called at least once per listing during the initial setup of a user's account to create historical reservations. Integrators MUST send us 1 year of historical reservations. Integrators SHOULD send us 2 years of historical reservations on setup.

At least daily updates

Once the listing is setup and active, this endpoint MUST be called with reservation calendar changes. This MAY happen in real time or be batched, but Wheelhouse MUST be notified of changes on the same day they occur.

The more detail included in the reservation object, the more accurate our recommendations will be.

Price calendars help us keep our system up to date, understand usage, and drive some of our internal models for booking probabilities, gap night pricing, and more. They also provide us with information on which stay dates are available, and which ones are blocked as well as what asking prices are currently set relative to our recommendation.

Preferences allow to adapt the Wheelhouse recommendation engine to the host specifically for each listing. Read and update detailed pricing preferences for listings, including base price, seasonality, discounts, min stay rules, min/max price rules, occupancy pacing, custom date ranges, and more.