# 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=<channel>' \
  -H 'X-Integration-Api-Key: <your RM 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"
}
```
