# Retrieve all listings for the authenticated user.

`GET /listings`

> Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-listings · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetListings` · Tag: Listings

Returns every listing the authenticated user can access: listings they own (connected via their channel accounts) plus listings they have been granted access to manage in Wheelhouse (shared / delegated access on another user's listings). Set `include_managed_listings` to false to restrict the response to owned listings only. Each listing carries an `access_level` and an `owner_user`, so managed listings can be told apart from owned ones and attributed to the account they belong to. Pass `owner_user_id` to return the listings of one account only, such as a team you belong to.

## Request

`GET https://api.usewheelhouse.com/ss_api/v1/listings`

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.

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `exclude_inactive` | boolean | no | Exclude inactive listings, and listings not linked to a channel, from the response. Hidden listings are not inactive and are still returned; see `is_hidden`. (default: `true`) |
| `include_managed_listings` | boolean | no | When true (default), includes listings the user manages for another Wheelhouse account (valid shared-access grants), in addition to listings they own. Set to false to return only owned listings. (default: `true`) |
| `include_photos` | boolean | no | Set to true to include the URLs of each listing's photos in `meta.photos`. `num_photos` is returned either way. (default: `false`) |
| `owner_user_id` | integer | no | Return only the listings owned by this Wheelhouse user, that is, those whose `owner_user.id` matches. Pass a membership's `user_id` from [`GET /teams/memberships`](https://docs.usewheelhouse.com/rm/reference/rm-get-team-memberships.md) to read one team's listings. It narrows the listings you can already access and grants no others, so a user whose listings you cannot access returns an empty list. |
| `per_page` | integer | no | Number of listings per page. (default: `50`, min: 1, max: 100) |
| `page` | integer | no | Page number to retrieve. |
| `offset` | integer | no | Number of items to skip before starting to collect the result set. |

### Example request

```bash
curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings' \
  -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

Array of listings.

Body (`application/json`): array of 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.

### 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"
}
```
