Wheelhouse logo
Documentation Powered by ReDoc

Wheelhouse Pro API (v1.0)

Download OpenAPI specification:Download

E-mail: tech-support@usewheelhouse.com License: All Rights Reserved Terms of Service

Basic Execution Flow

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.

Basic Flow

PMS / CM Execution Flow

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.

PMS / CM Execution Flow

PMS / CM UX

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

Connecting

Activating Pricing

Activating

Deactivating Pricing

Deactivating

Authentication

IntegrationApiKey

All integrations will be given an integration API key. Contact us with a description of your use-case to get one.

Security Scheme Type API Key
Header parameter name: X-Integration-API-Key

UserApiKey

Requests to the API must be made in a specific User's context. When a user is registered, we will return an API key for that specific user.

BOTH API key headers are required to make Wheelhouse Pro API calls with the exception being that the new end user creation endpoint only requires IntegrationApiKey.

Security Scheme Type API Key
Header parameter name: X-User-API-Key

Rate Limit

By default, our API is limited to 20 requests / minute to prevent any accidental DOS attack in the testing phase or overloading the system. This can be adjusted so please reach out to us with any questions. We recommend using an exponential backoff strategy if you receive a 429 response code.

On average you can expect 4-6 API calls to update a single listing. That means for example a portfolio with 100 listings that makes 400 - 600 API calls for a full portfolio update. At a rate limit of 100 requests per minute, that means a full portfolio update would be achieved in at most six minutes.

Web Hook Callbacks

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.

Users

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}.

Create a new end user

Authorizations:
IntegrationApiKey
Request Body schema: application/json

A user

first_name
required
string

The user's first name.

last_name
required
string

The user's last name.

email
required
string

The email contact for this user. This is a unique identifier across the system.

phone
required
string

The phone number for this user.

integrators_user_id
required
string

The unique id used to identify this user within the integration partner. This MUST be unique across environments.

integrators_affiliate_name
string

The name of the affiliate if the end user is through an affiliate.

integrators_affiliate_user_id
string

The unique id used to identify this user within the integration partner.

password
string

(Recommended) Password for accessing Wheelhouse website. If not specified, user will not have access to Wheelhouse website.

allow_marketing_emails
boolean
Default: false

Whether we are allowed to send marketing emails to the customer.

company
string

Company affiliation of the user.

portfolio_size
string
Enum: "0-9" "10-49" "50-99" "100+"

Number of listings the user operates.

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "phone": "string",
  • "integrators_user_id": "string",
  • "integrators_affiliate_name": "string",
  • "integrators_affiliate_user_id": "string",
  • "password": "string",
  • "allow_marketing_emails": false,
  • "company": "string",
  • "portfolio_size": "0-9"
}

Response samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "user_api_key": "string"
}

Update user info

Authorizations:
IntegrationApiKeyUserApiKey
Request Body schema: application/json

User info

integrators_user_id
required
string

The unique id used to identify this user within the integration partner. This MUST be unique across environments.

Responses

Request samples

Content type
application/json
{
  • "integrators_user_id": "string"
}

Deactivate channel account

This will set the integration account to inactive on the Wheelhouse UI and will stop it from being processed on a daily basis.

Authorizations:
IntegrationApiKeyUserApiKey

Responses

Listings

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.

Retrieve all listings associated with a user.

Authorizations:
IntegrationApiKeyUserApiKey
query Parameters
offset
integer

The number of items to skip before starting to collect the result set. (Optional)

page
integer

The page of listings to retrieve. (Optional)

per_page
integer

Number of listings per page. Default is 50. (Optional)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or update a listing

Authorizations:
IntegrationApiKeyUserApiKey
Request Body schema: application/json

A listing

id
required
string

The integration partner's unique listing identifier. This MUST be unique across environments and users.

wheelhouse_id
integer

Wheelhouse's unique listing indentifier.

title
string

(Recommended) The listing's name to show in the UI.

required
object or object or object (location)

Attributes describing a location with enough accuracy to identify a postal code. Prefer more precision.

num_bedrooms
required
integer >= 0

The number of bedrooms included in the unit. Whole numbers only.

num_beds
integer >= 0

The number of actual beds within the listing

num_bathrooms
required
number >= 0

The number of bathrooms included in the unit, e.g. 1 or 1.5.

room_type
required
string
Enum: "shared" "private" "apartment" "entire_place" "hotel_room"

Description of the type of room offered. One of shared (a room shared with other guests), private (a private room in a shared larger accommodation), apartment (a whole apartment in a larger building), entire_place (a house where the entire building is available to the guest), hotel_room (a room in a classic hotel).

property_type
string
Enum: "house" "cabin" "bnb" "boat" "bus" "camping" "camper" "castle" "hostel" "hotel" "houseboat" "island" "tower" "mill"

(Recommended) Description of the property this rental is in.

currency
required
string

The ISO-4217 currency code this listing uses for pricing.

security_deposit
required
number >= 0

An extra charge held against damage to the unit at booking. In the currency of the listing.

star_rating
required
number [ 0 .. 5 ]

The average review rating of the listing. 0 is the lowest possible rating, 5 is the highest possible rating.

num_reviews
required
integer >= 0

The number of reviews on the listing.

num_photos
required
integer >= 0

The number of photos on the listing.

thumb_url
string

(Recommended) URL of thumbnail image for listing. Default to first photos thumbnail if not specified.

amenities
required
Array of strings
Items Enum: "24_hour_check_in" "air_conditioning" "baby_bath" "baby_monitor" "babysitter_recommendations" "balcony" "bathroom_essentials" "bathtub" "bbq" "beach_essentials" "beachfront" "bed_linens" "bedroom_comforts" "bicycles" "breakfast" "building_staff" "cable_or_satellite_tv" "carbon_monoxide_detector" "ceiling_fans" "changing_table" "childrens_books_and_toys" "childrens_dinnerware" "cleaning_before_checkout" "coffee_maker" "cooking_basics" "deck" "dishes_and_silverware" "dishwasher" "dog_friendly" "dryer" "elderly_accessible" "elevator" "essentials" "ev_charger" "extra_pillows_and_blankets" "family_kid_friendly" "fire_extinguisher" "fireplace" "fireplace_guards" "first_aid_kit" "freezer" "fresh_linens" "fridge" "game_console" "garage" "gym" "hair_dryer" "hangers" "heating" "high_chair" "host_greets_you" "hot_tub" "hot_water" "internet" "iron" "jacuzzi" "kettle" "keypad" "kitchen" "lake_access" "laptop_friendly_workspace" "lock_on_bedroom_door" "lockbox" "long_term_stays_allowed" "luggage_dropoff" "microwave" "outlet_covers" "oven" "parking" "parking_free_on_premises" "parking_free_street" "parking_paid" "parking_paid_on_premises" "patio" "pets_allowed" "pool" "pool_cover" "pool_toys" "private_entrance" "private_living_room" "private_yard" "refrigerator" "room_darkening_shades" "sauna" "self_check_in" "shampoo" "shared_pool" "single_level_home" "ski_in_out" "smart_lock" "smoke_detector" "smoking_allowed" "step_free_access" "stereo" "stove" "streaming" "suitable_for_events" "table_corner_guards" "towel" "travel_crib" "tv" "washing_machine" "water_views" "waterfront" "window_guards"

A list of amenities available at this listing.

required
object (listing_preference)

Settable attributes on the listing that help us compare apples to apples.

object (channel_ids)

A mapping of supported channel names to the channel's listing id. We use these to dedupe listings and it improves our demand modeling. For unit type inventory, this can be a comma-separated list to denote all individual units on the channel. Note that this is not used to create channel-specific pricing.

description
string

The listing's description text.

nickname
string

Listing nickname used as a shortened title.

base_min_night_stay
integer >= 0

This informs Wheelhouse of the length of the shortest stay this listing accepts.

owner_name
string

The listing owner's name to show in the UI.

is_active
boolean

Whether the listing is active and valid on the integration channel.

source_user_id
string

The user id of the user on the integration channel.

object (meta)
Deprecated

Container for additional non-required attributes that will help price this listing. See new top-level attributes that are recommended to provide this data.

Array of objects

A list of photos of the listing.

unit_names
string

Used for hotel room or "unit type" inventory. This should be a comma delimited list of unit names available under this listing. If omitted, we assume there is only 1 unit. This enables scarcity pricing.

created_at
string <date-time>

The datetime the listing was created on your platform (ISO-8601).

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "wheelhouse_id": 0,
  • "title": "string",
  • "location": { },
  • "num_bedrooms": 0,
  • "num_beds": 0,
  • "num_bathrooms": 0,
  • "room_type": "shared",
  • "property_type": "house",
  • "currency": "string",
  • "security_deposit": 0,
  • "star_rating": 5,
  • "num_reviews": 0,
  • "num_photos": 0,
  • "thumb_url": "string",
  • "amenities": [
    ],
  • "listing_preferences": {
    },
  • "channel_ids": {
    },
  • "description": "string",
  • "nickname": "string",
  • "base_min_night_stay": 0,
  • "owner_name": "string",
  • "is_active": true,
  • "source_user_id": "string",
  • "meta": {
    },
  • "photos": [
    ],
  • "unit_names": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "wheelhouse_id": 0,
  • "title": "string",
  • "location": { },
  • "num_bedrooms": 0,
  • "num_beds": 0,
  • "num_bathrooms": 0,
  • "room_type": "shared",
  • "property_type": "house",
  • "currency": "string",
  • "security_deposit": 0,
  • "star_rating": 5,
  • "num_reviews": 0,
  • "num_photos": 0,
  • "thumb_url": "string",
  • "amenities": [
    ],
  • "listing_preferences": {
    },
  • "channel_ids": {
    },
  • "description": "string",
  • "nickname": "string",
  • "base_min_night_stay": 0,
  • "owner_name": "string",
  • "is_active": true,
  • "source_user_id": "string",
  • "meta": {
    },
  • "channel": "string",
  • "links": {
    },
  • "wheelhouse_created_at": "2019-08-24T14:15:22Z"
}

Get a listing

Authorizations:
IntegrationApiKeyUserApiKey
path Parameters
id
required
string

The integration partner's unique listing identifier.

query Parameters
channel
string

Channel name of the listing. Can be ommitted if you request a listing you created, but required if you request a listing from another channel. See return value of the /listings endpoint.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "wheelhouse_id": 0,
  • "title": "string",
  • "location": { },
  • "num_bedrooms": 0,
  • "num_beds": 0,
  • "num_bathrooms": 0,
  • "room_type": "shared",
  • "property_type": "house",
  • "currency": "string",
  • "security_deposit": 0,
  • "star_rating": 5,
  • "num_reviews": 0,
  • "num_photos": 0,
  • "thumb_url": "string",
  • "amenities": [
    ],
  • "listing_preferences": {
    },
  • "channel_ids": {
    },
  • "description": "string",
  • "nickname": "string",
  • "base_min_night_stay": 0,
  • "owner_name": "string",
  • "is_active": true,
  • "source_user_id": "string",
  • "meta": {
    },
  • "channel": "string",
  • "links": {
    },
  • "wheelhouse_created_at": "2019-08-24T14:15:22Z"
}

Delete a listing

This will set a listing to inactive on the Wheelhouse UI and will stop it from being processed on a daily basis.

Authorizations:
IntegrationApiKeyUserApiKey
path Parameters
id
required
string

The integration partner's unique listing identifier.

Responses

Get pricing tier info for a listing

Authorizations:
IntegrationApiKeyUserApiKey
path Parameters
id
required
string

The integration partner's unique listing identifier.

query Parameters
channel
string

Channel name of the listing. Can be ommitted if you request a listing you created, but required if you request a listing from another channel. See return value of the /listings endpoint.

Responses

Response samples

Content type
application/json
{
  • "name": "Free",
  • "horizon": 0
}

Update pricing tier for a listing

Authorizations:
IntegrationApiKeyUserApiKey
path Parameters
id
required
string

The integration partner's unique listing identifier.

Request Body schema: application/json

Pricing tier info

name
string
Enum: "Free" "Pro Flex" "Pro Flat" "Pro SS API"

Name of the Wheelhouse pricing tier.

Responses

Request samples

Content type
application/json
{
  • "name": "Free"
}

Response samples

Content type
application/json
{
  • "name": "Free",
  • "horizon": 0
}

Get times of latest changes for a listing

Note that this endpoint is experimental and might change in the future!

Authorizations:
IntegrationApiKeyUserApiKey
path Parameters
id
required
string

The integration partner's unique listing identifier.

query Parameters
channel
string

Channel name of the listing. Can be ommitted if you request a listing you created, but required if you request a listing from another channel. See return value of the /listings endpoint.

Responses

Response samples

Content type
application/json
{
  • "settings": "2019-08-24T14:15:22Z",
  • "rates": "2019-08-24T14:15:22Z"
}

Check location coverage

Determine whether a given location is in an active Wheelhouse market.

Authorizations:
IntegrationApiKey
query Parameters
country
required
string 2 characters

The ISO-3166 2 letter country code.

postal_code
required
string

A regional postal code for within the given country.

latitude
required
number [ -90 .. 90 ]

The latitude coordinate of this location.

longitude
required
number [ -180 .. 180 ]

The longitude coordinate of this location.

Responses

Response samples

Content type
application/json
{
  • "in_market": true,
  • "market_name": "string"
}

Set multiple custom rates for a given listing

Creates multiple custom rates for a listing. See description of setCustomRate for details.

Authorizations:
IntegrationApiKeyUserApiKey
path Parameters
listing_id
required
any

The integration partner's unique listing identifier.

Request Body schema: application/json

An object representing the custom rate to be set.

Array of objects (custom_rate)

Responses

Request samples

Content type
application/json
{
  • "custom_rates": [
    ]
}

Response samples

Content type
application/json
{
  • "updated_custom_rates": [
    ]
}

Delete custom rates for a set of ranges

This endpoint allows for multiple date ranges to have their custom rates removed, reverting back to recommended prices for those dates. Note that start_date and end_date of each range are inclusive, and custom rates will be removed on those dates as well.

Authorizations:
IntegrationApiKeyUserApiKey
path Parameters
listing_id
required
any

The integration partner's unique listing identifier.

Request Body schema: application/json

An object representing the set of ranges for which to delete custom rates.

Array of objects

Responses

Request samples

Content type
application/json
{
  • "delete_ranges": [
    ]
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Set a custom rate

Defines a custom rate (an override of recommended pricing) for a date range. A rate_type of fixed defines a fixed rate in the specified currency. A rate_type of adjustment defines a percentage-based adjustment to the recommended price.

Fixed Rate Example: Specifying the currency as "USD", a day of week value of 500 for sunday, 750 for friday and 625 for saturday will set the rates for those days during the specified date range to $500, $750 and $625, respectively.

Adjustment Rate Example: An adjustment value of 115 would mean a 15% increase in price, while a value of 75 would indicate a decrease of 25% from the recommended price. In cases where both an adjustment and day of week values are given, the adjustment will act as the default value for the non-specified days of week. So setting an adjustment of 115 and specifying 125 for sunday, 145 for friday and 135 for saturday would results in a 25% increase for Sunday, a 15% increase for Monday-Thursday, a 45% increase for Friday and a 35% increase for Saturday.

Authorizations:
IntegrationApiKeyUserApiKey
Request Body schema: application/json

An object representing the custom rate to be set.

start_date
required
string <date>

The inclusive start of the stay-date range affected by the custom rate (YYYY-MM-DD).

end_date
required
string <date>

The inclusive end of the stay-date range affected by the custom rate (YYYY-MM-DD).

rate_type
required
string
Enum: "fixed" "adjustment"

Whether the custom rate is percentage-based or a fixed override.

adjustment
number >= 1

The percentage by which the price should be adjusted. For example 100 means 100% of the recommended price, i.e. no adjustment. 90 means 90% and thus reduces the recommended price by 10%. Vice versa 110 means 110% and thus increases the recommended price by 10%. This is required if the rate_type is adjustment. If no day-specific overrides are given, this value will be used as the adjustment for every day in the date range of the custom rate.

currency
string 3 characters

The ISO-4217 3-letter currency code of the price. Required if rate_type is fixed.

monday
number >= 1

The price applied for all Mondays in the given date range.

tuesday
number >= 1

The price applied for all Tuesdays in the given date range.

wednesday
number >= 1

The price applied for all Wednesdays in the given date range.

thursday
number >= 1

The price applied for all Thursdays in the given date range.

friday
number >= 1

The price applied for all Fridays in the given date range.

saturday
number >= 1

The price applied for all Saturdays in the given date range.

sunday
number >= 1

The price applied for all Sundays in the given date range.

weekend_price
number >= 0
Deprecated

The price applied for nights on the weekend (Fri, Sat).

weekday_price
number >= 0
Deprecated

The price applied for nights during the week (Sun-Thu).

Responses

Request samples

Content type
application/json
Example
fixed
fixed
adjustment
{
  • "start_date": "2024-08-05",
  • "end_date": "2024-09-05",
  • "rate_type": "fixed",
  • "currency": "USD",
  • "sunday": 500,
  • "friday": 750,
  • "saturday": 625
}

Response samples

Content type
application/json
Example
fixed
fixed
adjustment
{
  • "start_date": "2024-08-05",
  • "end_date": "2024-09-05",
  • "rate_type": "fixed",
  • "currency": "USD",
  • "sunday": 500,
  • "friday": 750,
  • "saturday": 625
}

Remove custom rates

Remove all custom rates from Wheelhouse for the affected stay dates. Any partially covered custom rates will be adequately shortened and the affected date range will be set to the recommended price again. These will then reflect both in the Wheelhouse UI and in the prices returned from the recommendations endpoint.

Authorizations:
IntegrationApiKeyUserApiKey
query Parameters
start_date
required
string <date>

The inclusive start of the stay-date range where any custom rate is removed (YYYY-MM-DD).

end_date
required
string <date>

The inclusive end of the stay-date range where any custom rate is removed (YYYY-MM-DD).

Responses

Reservations

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.

Create or update a batch of reservations

This endpoint accepts a list of reservation objects and returns a list of processed reservation IDs. The unchanged response field additionaly indicates reservations that were already present and required no update.

Errors

If Wheelhouse errors or otherwise fails to return the reservation IDs that were created or updated, integrators MUST resend them after some period of time. DO NOT repeatedly call this endpoint if it is failing.

Authorizations:
IntegrationApiKeyUserApiKey
path Parameters
id
required
string

The integration partner's unique listing identifier.

Request Body schema: application/json

reservations

Array of objects or objects (schemas)

Responses

Request samples

Content type
application/json
{
  • "reservations": [
    ]
}

Response samples

Content type
application/json
{
  • "error_messages": [
    ],
  • "api_warnings": [
    ],
  • "data": [
    ],
  • "unchanged": [
    ],
  • "failed": {
    }
}

List reservations

Experimental - the interface might change in the future! This endpoint lists reservations of a listing.

Authorizations:
IntegrationApiKeyUserApiKey
path Parameters
listing_id
required
string

The integration partner's unique listing identifier.

query Parameters
start_date
required
string <date>

The inclusive start of the stay-date range to query reservations for (YYYY-MM-DD).

end_date
required
string <date>

The inclusive end of the stay-date range to query reservations for (YYYY-MM-DD).

offset
integer

The number of reservations to skip before starting to collect the result set.

page
integer

The page of reservations to retrieve.

per_page
integer

Number of reservations per page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete a single reservation

This endpoint deletes a single reservation by its id. NOTE: if a reservation is cancelled, it is best to update the reservation's cancelled flag to true with the PUT reservation endpoint. This endpoint is only intended to be used for erroneously created reservations.

Authorizations:
IntegrationApiKeyUserApiKey
path Parameters
listing_id
required
string

The integration partner's unique listing identifier.

reservation_id
required
string

The reservation ID

Responses

Price Calendars

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.

Update the price calendar of a listing

This endpoint should be called before requesting price recommendations. If the listing calendar is changed by our recommendations, integrators MUST call this endpoint again to update our calendar.

Authorizations:
IntegrationApiKeyUserApiKey
path Parameters
id
required
string

The integration partner's unique listing identifier.

Request Body schema: application/json
Array of objects (price_calendar)

A calendar object describing pricing and availability by stay date.

Responses

Request samples

Content type
application/json
{
  • "price_calendars": [
    ]
}

Price Recommendations

Get price recommendations for this listing

Return daily price recommendations for this listing. The horizon of the price recommendations depends on the pricing tier this listing is in and can be queried using the pricing tier endpoint. If the listing calendar is changed by our recommendations, integrators MUST make another PUT to the price calendar to update our calendar.

Authorizations:
IntegrationApiKeyUserApiKey
path Parameters
id
required
string

The integration partner's unique listing identifier.

query Parameters
currency
string

The final currency that the prices should be in. Uses listing's currency by default. Uses 3-digit ISO form (e.g. 'USD', 'GBP').

channel
string

Channel name of the listing. Can be ommitted if you request a listing you created, but required if you request a listing from another channel. See return value of the /listings endpoint.

attribution
boolean
Default: false

Whether or not you want to receive a detailed attribution for each day. The attribution will break a daily recommendation down into contributing prices like seasonality, local events, etc. and activate all attr_ response values.

Responses

Response samples

Content type
application/json
{
  • "error_messages": [
    ],
  • "api_warnings": [
    ],
  • "data": [
    ],
  • "base_price": 0,
  • "global_min_stay": 0,
  • "automatic_rate_posting_enabled": true
}

Get base price recommendations for all active listings in the account

Get base price recommendations for all active listings in the account

Authorizations:
IntegrationApiKeyUserApiKey
query Parameters
currency
string

The final currency that the prices should be in. Uses listing's currency by default. Uses 3-digit ISO form (e.g. 'USD', 'GBP').

Responses

Response samples

Content type
application/json
{
  • "base_price_recommendations": [
    ]
}

Get base price recommendation for this listing

Return base price recommendations for this listing with various options.

Authorizations:
IntegrationApiKeyUserApiKey
path Parameters
id
required
string

The integration partner's unique listing identifier.

query Parameters
currency
string

The final currency that the prices should be in. Uses listing's currency by default. Uses 3-digit ISO form (e.g. 'USD', 'GBP').

Responses

Response samples

Content type
application/json
{
  • "base_price_recommended": 0,
  • "base_price_conservative": 0,
  • "base_price_aggressive": 0,
  • "base_price_selected": 0
}

Listing Preferences

Preferences allow to adapt the Wheelhouse recommendation engine to the host specifically for each listing.

Get check-in/check-out calendar for this listing

Return daily check-in/check-out rules for this listing. The horizon of the rules depends on the pricing tier this listing is in and can be queried using the pricing tier endpoint.

Authorizations:
IntegrationApiKeyUserApiKey
path Parameters
id
required
string

The integration partner's unique listing identifier.

query Parameters
channel
string

Channel name of the listing. Can be ommitted if you request a listing you created, but required if you request a listing from another channel. See return value of the /listings endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get calendar of minimum and maximum prices for this listing

Return daily minimum and maximum price for this listing. The horizon of the rules depends on the pricing tier this listing is in and can be queried using the pricing tier endpoint.

Authorizations:
IntegrationApiKeyUserApiKey
path Parameters
id
required
string

The integration partner's unique listing identifier.

query Parameters
channel
string

Channel name of the listing. Can be ommitted if you request a listing you created, but required if you request a listing from another channel. See return value of the /listings endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Copy the preferences from one listing to another.

This endpoint can be used to copy the preferences from one listing to another. This is useful if you have multiple listings that are very similar and you want to copy the preferences from one listing to another, or if you are creating a listing on a new channel and want to copy the preferences from an existing listing. The source listing is specified in the JSON payload of the request and the target listing is specified in the URL. Note that custom rates can also be copied using this endpoint.

Authorizations:
IntegrationApiKeyUserApiKey
path Parameters
id
required
string

The integration partner's unique listing identifier.

Request Body schema: application/json
object

Identifies the source listing from which to copy the preferences. When identifying the listing from which to copy the preferences, you can either provide the wheelhouse_id of that source listing, or you can provide the channel and channel_id of the source listing. If you provide all of the above, wheelhouse_id is given priority.

Responses

Request samples

Content type
application/json
{
  • "copy_preferences_from": {
    }
}

Update the basic preferences of a listing.

This endpoint can be used to change basic preferences of the Wheelhouse recommendation engine. For each setting you can choose between a conservative (CON), recommended (REC), or aggressive (AGG) setting.

Authorizations:
IntegrationApiKeyUserApiKey
path Parameters
id
required
string

The integration partner's unique listing identifier.

setting
required
string
Enum: "base_price_adjustment" "weekend_factor" "seasonality_adjustment" "last_minute_discount" "far_future_premium"

The setting you want to change.

query Parameters
type
required
string
Enum: "CON" "REC" "AGG"

Setting to be applied.

Responses

Change automatic rate posting status in Wheelhouse.

This setting informs Wheelhouse whether or not the user wishes to use the Wheelhouse recommended prices for this listing.

Authorizations:
IntegrationApiKeyUserApiKey
path Parameters
id
required
string

The integration partner's unique listing identifier.

query Parameters
enabled
required
boolean

Whether or not the user wishes to use the Wheelhouse recommended prices for this listing.

Responses

Get the long term discount settings of a listing.

This endpoint can be used to fetch weekly and monthly discounts set up through Wheelhouse for a listing.

Authorizations:
IntegrationApiKeyUserApiKey
path Parameters
id
required
string

The integration partner's unique listing identifier.

Responses

Response samples

Content type
application/json
{
  • "weekly_discount": 100,
  • "monthly_discount": 100
}

Bulk update the preferences of a set of listings.

Authorizations:
IntegrationApiKeyUserApiKey
Request Body schema: application/json

An array of objects representing the preferences to be set for each listing.

Array ()
listing_id
string

The integration partner's unique listing identifier.

base_price
number >= 0

The base price to use for this listing. Only set it you want to override the Wheelhouse data-derived base price. Setting this option is equivalent to using a "Rule-based" base price definition in the Wheelhouse UI. To remove the base price override, set this value to null.

object

Definition of long term discounts.

Array of objects or objects or objects or objects or objects or objects or objects

Definition of minimum prices.

Array of objects or objects or objects or objects or objects or objects or objects

Definition of maximum prices.

Array of objects or objects or objects or objects or objects or objects or objects or objects or objects

Definition of minimum length of stay.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "updated_preferences": [
    ]
}

Update the preferences of a listing.

Note that this endpoint is experimental and might change in the future! This endpoint can be used to change custom preferences of the Wheelhouse recommendation engine.

Authorizations:
IntegrationApiKeyUserApiKey
path Parameters
id
required
string

The integration partner's unique listing identifier.

Request Body schema: application/json

An object representing the preferences to be set.

base_price
number >= 0

The base price to use for this listing. Only set it you want to override the Wheelhouse data-derived base price. Setting this option is equivalent to using a "Rule-based" base price definition in the Wheelhouse UI. To remove the base price override, set this value to null.

object

Definition of long term discounts.

Array of objects or objects or objects or objects or objects or objects or objects

Definition of minimum prices.

Array of objects or objects or objects or objects or objects or objects or objects

Definition of maximum prices.

Array of objects or objects or objects or objects or objects or objects or objects or objects or objects

Definition of minimum length of stay.

Responses

Request samples

Content type
application/json
{
  • "base_price": 0,
  • "long_term_discounts": {
    },
  • "minimum_price_rules": [
    ],
  • "maximum_price_rules": [
    ],
  • "minimum_stay_rules": [
    ]
}

Changelog

2024-08-28

  • Add 423 status to /price_recommendations endpoint, to indicate cases recommendations are still in the process of being generated.

2024-08-16

  • Add endpoint for bulk deletion of a given listing's custom rates.

2024-08-15

  • Add endpoint for bulk updating of a given listing's custom rates.

2024-08-13

  • Extend custom rate endpoint to include full functionality (eg custom per-day adjustments).
  • Include examples in documentation.

2024-07-08

  • Renamed Pricing API to Wheelhouse Pro API.

2024-05-08

  • Added endpoint for bulk fetching base_price_recommendation for all listings in account.

2024-04-23

  • Add endpoint for bulk updating of listing preferences.

2024-04-17

  • Add wheelhouse_created_at attribute to listing response object.

2024-04-15

  • Added endpoint for switching pricing tiers for a given listing.

2024-03-06

  • Address in location object is optional if latitude and longitude, or postal code and country are provided.
  • Added correct enum values for fee object type attribute.

2024-02-22

  • Added a base_price_recommendation endpoint to fetch recommended base price options.

2023-07-25

  • Allow base_price to be set via the /preferences/{id} endpoint.

2023-07-25

  • Added endpoint for copying listing preferences from one listing to another.

2023-07-17

  • Added min/max price endpoint to fetch daily price limits.

2023-06-16

  • Added an endpoint (/preferences/{id}) to define detailed custom preferences. This endpoint is experimental and subject to changes in the future.

2023-05-30

  • Add num_included_adults, num_included_children, payout_total and cancelled_total to reservation object.

2023-05-05

  • Returns a 204 response if the check-in/check-out calendar is fetched for a listing that does not have check-in/check-out enabled.

2023-05-05

  • Allow company and portfolio size to be set for a User via the API.

2023-05-02

  • Mark base_price attribute of listing as deprecated and ignore value.

2023-03-02

  • Correct description of num_max_guests

2023-03-02

  • Add an endpoint (/listings/{id}/recent_changes) for retrieving the times of the most-recent changes for a listing

2023-02-02

  • Clarify that fee[:type] in the listing object is an enum.

2023-02-01

  • Added further explanation of partial create/update reservation 207 response

2022-12-05

  • Added endpoint to update user information.

2022-10-21

  • Added check-in/check-out endpoint to fetch rules.

2022-09-28

  • Added external_user_id to all webhooks

2022-07-28

  • Added experimental endpoint to retrieve reservations of a listing. At this point, the interface (especially the response) is not fixed and might change in the future.

2022-06-15

  • Added automation endpoint to allow switching the automatic_rate_posting_enabled flag.

2022-06-10

  • Added user_initiated attribute to webhook payloads to differentiate between a webhook was initiated by a user action and one that was called through automatic routines.

2022-06-10

  • Removed duplicate nickname attribute from the Listing#listing_preferences. Please just use the Listing#nickname attribute instead.

2022-06-08

  • Added unchanged reservation ids to the response of the PUT reservations endpoint in the unchanged response field. These indicate that the reservations were already present and required no update.

2022-05-06

  • Added capability for custom rates to be percentage based adjustments.

2022-02-14

  • Added custom rates endpoints to set and delete custom fixed rates for a listing.

2021-12-13

  • Added external_user_id as an identifying parameter to web hook callbacks.

2021-12-08

  • Fix: Ensure accounts are activated when data is pushed to Wheelhouse.
  • Added web hook for account deactivation.
  • Added global minimum stay to price recommendations response payload.

2021-11-26

  • Improved error handling: Aleays differentiating between listings not found (404), listings being inactive (406), and listings being out of market (422).

2021-11-17

  • Added the option to request detailed daily attribution for price recommendations.
  • Providing information on the type of a custom rate overwriting price recommendations: fixed (i.e. a fixed custom price) or adjusted (i.e. a percentage adjustment to the Wheelhouse recommendation).

2021-09-03

  • Fix: Correctly raise rate limiting as a 429 response.

2021-08-02

  • Deprecated Listing#meta atrribute object and lift the relevant attribute to the top level instead. The old meta attribute still works as well for now but will evventually be dropped in a future version.

2021-07-16

  • Updated basic execution flow-chart to reflect requirements of sending a pricing calendar on initial setup and added optional steps.
  • Added details on available web hooks.
  • Added required fields of booked_at and either nightly_subtotal or nightly_prices on reservations.

2021-07-14

  • Added detailed list of accepted values for room_type.

2021-07-08

  • Added PMS / CM execution flow and UX flow charts.

2021-06-14

  • Added endpoint to pull long term discounts.
  • Added endpoint to pull pricing tier information.