# Identifying Listings

> Web version: https://docs.usewheelhouse.com/rm/concepts/listings

Most endpoints require a `listing_id` and `channel` path or query parameter to
identify the listing a request is being made for. There are two ways to fill
them in, and both values come from the `GET /listings` endpoint.

**By channel listing ID (default).** A channel's listing IDs are only unique
within that channel, so `channel` is what disambiguates them:

- **`listing_id`** — the `id` field from the listing object.
- **`channel`** — the `channel` field from the same listing object.

**By Wheelhouse listing ID.** Pass the literal value `wheelhouse` as `channel`,
and `listing_id` is read as a Wheelhouse listing ID:

- **`listing_id`** — the `wheelhouse_id` field from the listing object.
- **`channel`** — the literal string `wheelhouse`.

Wheelhouse listing IDs are unique across all channels, so no channel has to be
named alongside them. This is the more convenient form when you already hold
Wheelhouse IDs — for example from `GET /listings/kpis`, which returns them as
`listing_id`, or from a Wheelhouse listing URL. Note that the two ID spaces are
distinct: passing a Wheelhouse ID without `channel=wheelhouse`, or a channel
listing ID with it, returns **404 Not Found**.

Either form works anywhere a listing is identified, including the batched
`listing_ids` parameters on `GET /preferences`,
`PUT /sets/{set_id}/associated_listings`, and
`DELETE /sets/{set_id}/associated_listings`, and the `copy_preferences_from`
object on `PUT /preferences/{listing_id}/copy` (whose nested `channel` is
resolved independently of the top-level one, so the source and target listing
may each be identified their own way).

Which form you use does not change what you can reach: a Wheelhouse listing ID
grants no access to a listing that a channel listing ID would not. It does
change how an unreachable listing is reported. Because Wheelhouse IDs are
sequential and span every account, a listing you cannot access returns
**404 Not Found** under `channel=wheelhouse` — the same response as an ID that
matches nothing — so that the ID space cannot be walked to discover other
accounts' listings. Under a channel listing ID, a listing you cannot access
still returns **403 Forbidden**. Listings shared with you to manage are
reachable under both forms.

A typical flow is to call `GET /listings` once to build a local map of your
listings, then use the `id` and `channel` values from that map — or each
listing's `wheelhouse_id` with `channel=wheelhouse` — for all subsequent
listing-specific calls.

## Inactive listings

A listing is inactive when Wheelhouse no longer syncs it: for example, its
channel stopped returning it, or its channel account was disconnected. The
listing object reports this as `is_active: false`. `GET /listings` leaves
inactive listings out by default; pass `exclude_inactive=false` to include them.

Endpoints that act on one listing return **406 Not Acceptable** for an inactive
listing:

```json
{"error": "Listing '12345' is inactive"}
```

This applies to reads as well as writes, including
`GET /listings/{listing_id}/price_calendar`,
`GET /listings/{listing_id}/last_posted_prices` and
`GET /preferences/{listing_id}`. Retrying does not help. The listing becomes
active again only if a later sync finds it on its channel, so skip it until
then.

`PUT /preferences` does not fail the whole request for an inactive listing. It
reports that listing in `errors` with code `406` and applies the rest of the
batch.

Under `channel=wheelhouse`, a listing you cannot access returns
**404 Not Found** even when it is inactive.

## Multi-unit listings

Some listings represent a single bookable property that has multiple
independently bookable units underneath it — for example, a building with several
apartments, or a property with a main house and a guest cottage managed as one
listing. These are called **multi-unit listings**.

You can identify a multi-unit listing by the `number_of_active_units` field on
the listing object (returned by `GET /listings` and
`GET /listings/{listing_id}`). A non-null value indicates a multi-unit listing;
`null` indicates a standard single-unit listing.

For endpoints that return per-date data (such as
`GET /listings/{listing_id}/price_calendar` and
`GET /listings/{listing_id}/last_posted_prices`), multi-unit listings return
**one row per unit per date**. Each row includes a `unit_number` field (a
positive integer starting at `1`) that identifies which unit the row belongs to.
Single-unit listings always return `unit_number: 0`.

When processing calendar data for a multi-unit listing, group rows by
`unit_number` to get the per-unit availability and pricing. Preferences and
settings (fetched via `GET /preferences/{listing_id}`) apply at the listing
level and are shared across all units.
