# Add member listings to a dynamic set.

`PUT /sets/{set_id}/listings`

> Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-put-set-listings · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPutSetListings` · Tag: Dynamic Sets

Adds the given listings to the set as members — the comparison listings the set is built from. Identify them by the internal `listing_id` values returned by `GET /sets/candidates`; only listings that are eligible comparison candidates can be added. Returns the set's member listings after the change, in the same shape as `GET /sets/{set_id}/listings`. Requires editor or manager access to the set when the set is shared. **Works for free and paid sets.** This is an upsert: a listing already in the set keeps its single membership and takes the requested `status`, so repeating an identical call leaves the set in the same state.

## Request

`PUT https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/listings`

Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `set_id` | integer | yes | The Wheelhouse internal dynamic set ID. |

### Request body (`application/json`, required)

- `listing_ids` (array of integer, required, max items: 500): Internal listing IDs to add as members — the `listing_id` values returned by `GET /sets/candidates`, not channel listing IDs. A listing already in the set is not duplicated. At most 500 per request.
- `status` (string, one of: `active`, `hidden`, `review`, `removed`, default: `active`): Membership status to add the listings with. Defaults to `active`. This applies to listings already in the set as well, so omitting it moves an existing `hidden`, `review` or `removed` member back to `active` — pass the status explicitly when re-sending a list that includes existing members.

### Example request

```bash
curl -X PUT 'https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/listings' \
  -H 'X-Integration-Api-Key: <your RM API key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "listing_ids": [
    0
  ]
}'
```

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 set's member listings after the change, grouped by status.

Body (`application/json`): object

- `active` (array of object `set_member_listing_response`)
  - Fields: see `set_member_listing_response` under Schemas.
- `hidden` (array of object `set_member_listing_response`)
  - Fields: see `set_member_listing_response` under Schemas.
- `review` (array of object `set_member_listing_response`)
  - Fields: see `set_member_listing_response` under Schemas.
- `removed` (array of object `set_member_listing_response`)
  - Fields: see `set_member_listing_response` under Schemas.

Example shape (generated from the schema; placeholder values, not a real response):

```json
{
  "active": [
    {
      "listing_id": 0,
      "title": "string",
      "source": "string",
      "url": "string",
      "thumb_url": "string",
      "owner_name": "string",
      "lat": 0,
      "long": 0,
      "market_id": 0,
      "currency": "string",
      "bedrooms": 0,
      "bathrooms": 0,
      "beds": 0,
      "sleeps": 0,
      "guests_included": 0,
      "room_type": "string",
      "property_type": "string",
      "amenities": [
        "string"
      ],
      "cleaning_fee": 0,
      "star_rating": 0,
      "review_count": 0,
      "adr_365_0": 0,
      "asking_rate_365_0": 0,
      "occupancy_365_0": 0,
      "occupancy_adjusted_365_0": 0,
      "nights_percent_open_365_0": 0,
      "nights_percent_open_90_0": 0,
      "nights_available_365_0": 0,
      "nights_blocked_365_0": 0,
      "nights_bookable_365_0": 0,
      "nights_booked_365_0": 0,
      "lead_time_365_0": 0,
      "length_of_stay_365_0": 0,
      "revenue_365_0": 0,
      "revpar_365_0": 0,
      "revpar_adjusted_365_0": 0,
      "distance_meters": 0,
      "listing_created_at": "2026-01-01T00:00:00Z",
      "listing_last_updated": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "status": "active"
    }
  ],
  "hidden": [
    {
      "listing_id": 0,
      "title": "string",
      "source": "string",
      "url": "string",
      "thumb_url": "string",
      "owner_name": "string",
      "lat": 0,
      "long": 0,
      "market_id": 0,
      "currency": "string",
      "bedrooms": 0,
      "bathrooms": 0,
      "beds": 0,
      "sleeps": 0,
      "guests_included": 0,
      "room_type": "string",
      "property_type": "string",
      "amenities": [
        "string"
      ],
      "cleaning_fee": 0,
      "star_rating": 0,
      "review_count": 0,
      "adr_365_0": 0,
      "asking_rate_365_0": 0,
      "occupancy_365_0": 0,
      "occupancy_adjusted_365_0": 0,
      "nights_percent_open_365_0": 0,
      "nights_percent_open_90_0": 0,
      "nights_available_365_0": 0,
      "nights_blocked_365_0": 0,
      "nights_bookable_365_0": 0,
      "nights_booked_365_0": 0,
      "lead_time_365_0": 0,
      "length_of_stay_365_0": 0,
      "revenue_365_0": 0,
      "revpar_365_0": 0,
      "revpar_adjusted_365_0": 0,
      "distance_meters": 0,
      "listing_created_at": "2026-01-01T00:00:00Z",
      "listing_last_updated": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "status": "active"
    }
  ],
  "review": [
    {
      "listing_id": 0,
      "title": "string",
      "source": "string",
      "url": "string",
      "thumb_url": "string",
      "owner_name": "string",
      "lat": 0,
      "long": 0,
      "market_id": 0,
      "currency": "string",
      "bedrooms": 0,
      "bathrooms": 0,
      "beds": 0,
      "sleeps": 0,
      "guests_included": 0,
      "room_type": "string",
      "property_type": "string",
      "amenities": [
        "string"
      ],
      "cleaning_fee": 0,
      "star_rating": 0,
      "review_count": 0,
      "adr_365_0": 0,
      "asking_rate_365_0": 0,
      "occupancy_365_0": 0,
      "occupancy_adjusted_365_0": 0,
      "nights_percent_open_365_0": 0,
      "nights_percent_open_90_0": 0,
      "nights_available_365_0": 0,
      "nights_blocked_365_0": 0,
      "nights_bookable_365_0": 0,
      "nights_booked_365_0": 0,
      "lead_time_365_0": 0,
      "length_of_stay_365_0": 0,
      "revenue_365_0": 0,
      "revpar_365_0": 0,
      "revpar_adjusted_365_0": 0,
      "distance_meters": 0,
      "listing_created_at": "2026-01-01T00:00:00Z",
      "listing_last_updated": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "status": "active"
    }
  ],
  "removed": [
    {
      "listing_id": 0,
      "title": "string",
      "source": "string",
      "url": "string",
      "thumb_url": "string",
      "owner_name": "string",
      "lat": 0,
      "long": 0,
      "market_id": 0,
      "currency": "string",
      "bedrooms": 0,
      "bathrooms": 0,
      "beds": 0,
      "sleeps": 0,
      "guests_included": 0,
      "room_type": "string",
      "property_type": "string",
      "amenities": [
        "string"
      ],
      "cleaning_fee": 0,
      "star_rating": 0,
      "review_count": 0,
      "adr_365_0": 0,
      "asking_rate_365_0": 0,
      "occupancy_365_0": 0,
      "occupancy_adjusted_365_0": 0,
      "nights_percent_open_365_0": 0,
      "nights_percent_open_90_0": 0,
      "nights_available_365_0": 0,
      "nights_blocked_365_0": 0,
      "nights_bookable_365_0": 0,
      "nights_booked_365_0": 0,
      "lead_time_365_0": 0,
      "length_of_stay_365_0": 0,
      "revenue_365_0": 0,
      "revpar_365_0": 0,
      "revpar_adjusted_365_0": 0,
      "distance_meters": 0,
      "listing_created_at": "2026-01-01T00:00:00Z",
      "listing_last_updated": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "status": "active"
    }
  ]
}
```

### 400

More than 500 listing IDs were sent.

### 401

API key authorization failed.

### 403

The set is shared with the user without editor or manager access, or the API key is read-only and may not be used with PUT.

### 404

Dynamic set not found or not accessible to the user, or one or more listing IDs are not eligible as members.

### 409

Another request is already in progress for this set. Retry after the concurrent request completes.

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

## Schemas

Shared by more than one field above.

### `set_member_listing_response`

Type: object `set_member_listing_response`

A market listing that is a member of a dynamic set — the candidate listing shape plus its membership `status` within the set.

A market listing with trailing-year performance metrics, named per the public [Wheelhouse metrics definitions](https://www.usewheelhouse.com/research-metrics). Metrics with the suffix `_365_0` cover the past 365 days; `_90_0` covers the past 90 days. When returned from a proximity search (`GET /sets/candidates`), `distance_meters` is the distance from the search center.

- `listing_id` (integer, required): The Wheelhouse internal listing ID.
- `title` (string, nullable): The listing title.
- `source` (string, nullable): The channel the listing was sourced from.
- `url` (string, nullable): Public URL of the listing on its channel.
- `thumb_url` (string, nullable): Thumbnail image URL.
- `owner_name` (string, nullable): The listing host/owner name.
- `lat` (number): Latitude of the listing.
- `long` (number): Longitude of the listing.
- `market_id` (integer, nullable): The Wheelhouse internal market ID of the listing.
- `currency` (string, nullable): The ISO-4217 3-letter currency code of the listing's monetary metrics.
- `bedrooms` (integer, nullable): Number of bedrooms.
- `bathrooms` (number, nullable): Number of bathrooms (may be fractional, e.g. 1.5).
- `beds` (integer, nullable): Number of beds.
- `sleeps` (integer, nullable): Maximum number of guests the listing sleeps.
- `guests_included` (integer, nullable): Number of guests included in the base price.
- `room_type` (string, nullable): The room type of the listing.
- `property_type` (string, nullable): The property type of the listing.
- `amenities` (array of string): List of amenities available at the listing.
- `cleaning_fee` (integer, nullable): Cleaning fee amount in the listing's currency.
- `star_rating` (number, nullable): Guest star rating.
- `review_count` (integer, nullable): Number of guest reviews.
- `adr_365_0` (number, nullable): Average Daily Rate — average nightly price over the past 365 days.
- `asking_rate_365_0` (number, nullable): Average nightly asking price over the past 365 days.
- `occupancy_365_0` (number, nullable): Occupancy over the past 365 days.
- `occupancy_adjusted_365_0` (number, nullable): Adjusted occupancy (booked as a share of bookable nights, excluding blocked inventory) over the past 365 days.
- `nights_percent_open_365_0` (number, nullable): Share of nights open for booking over the past 365 days.
- `nights_percent_open_90_0` (number, nullable): Share of nights open for booking over the past 90 days.
- `nights_available_365_0` (integer, nullable): Number of unbooked, bookable nights over the past 365 days.
- `nights_blocked_365_0` (integer, nullable): Number of owner-blocked nights over the past 365 days.
- `nights_bookable_365_0` (integer, nullable): Available plus booked nights, excluding blocked nights, over the past 365 days.
- `nights_booked_365_0` (integer, nullable): Number of reserved nights over the past 365 days.
- `lead_time_365_0` (number, nullable): Average booking lead time in days over the past 365 days.
- `length_of_stay_365_0` (number, nullable): Average length of stay over the past 365 days.
- `revenue_365_0` (number, nullable): Rental revenue over the past 365 days.
- `revpar_365_0` (number, nullable): Revenue per available night over the past 365 days.
- `revpar_adjusted_365_0` (number, nullable): Revenue per bookable night, excluding blocked inventory, over the past 365 days.
- `distance_meters` (integer): Distance from the search origin, if applicable.
- `listing_created_at` (string (date-time), nullable): When the listing was first indexed by Wheelhouse (ISO-8601).
- `listing_last_updated` (string (date-time), nullable): When the listing data was last updated (ISO-8601).
- `updated_at` (string (date-time)): When this listing's metrics record was last updated (ISO-8601).
- `status` (string, one of: `active`, `hidden`, `review`, `removed`): The membership status of the listing within the set.
