# Get reservations for a listing.

`GET /listings/{listing_id}/reservations`

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

Returns a list of reservations for a listing.

**Fetching only what changed:** Use `date_filter_type=updated_at` with timestamps, e.g. `start_date=2026-09-01T00:00:00Z&end_date=2026-09-02T00:00:00Z`, to get the reservations created, amended or cancelled in that window rather than every reservation in a stay range.

**Deriving pickup metrics:** Use `date_filter_type=booked_at` to filter by booking date rather than stay date:
- **Pickup (Booked Nights)** — new nights booked in a time window — sum `end_date − start_date` (in days) across returned reservations.
- **Pickup (Bookings)** — new reservations created in a time window — count the number of reservation records returned.

## Request

`GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/reservations`

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). |
| `start_date` | string | no | Filter start, as a date (YYYY-MM-DD) or, for `updated_at`, an ISO 8601 timestamp. Behavior depends on `date_filter_type`: - `stay_date` (default): returns reservations whose stay period overlaps with this date (i.e. `end_date > start_date`). - `booked_at`: returns reservations booked on or after the start of this date. - `updated_at`: returns reservations last changed at or after this time. A date alone means midnight UTC.  (example: `2026-09-01`) |
| `end_date` | string | no | Filter end, as a date (YYYY-MM-DD) or, for `updated_at`, an ISO 8601 timestamp. Behavior depends on `date_filter_type`: - `stay_date` (default): returns reservations whose stay period overlaps with this date (i.e. `start_date <= end_date`). - `booked_at`: returns reservations booked before the end of this date. - `updated_at`: returns reservations last changed before this time. A date alone means midnight UTC, so that day itself is not included.  (example: `2026-09-10`) |
| `date_filter_type` | string | no | Controls which date field is used for filtering: - `stay_date` (default): filter by the reservation's stay dates. - `booked_at`: filter by the date the reservation was booked. - `updated_at`: filter by when Wheelhouse last recorded a change to the reservation (the `updated_at` field), for example a new booking, an amendment or a cancellation. Use it to fetch only what changed since your last request: pass the previous request's `end_date` as the next `start_date`. Times are compared exactly, with `start_date` included and `end_date` excluded, so consecutive windows do not overlap. Keep `end_date` a few minutes in the past: a change can take a short while to become visible after the time it is recorded with. A reservation can also be returned when Wheelhouse re-recorded it without a visible change, so treat the result as the reservations to re-read rather than a list of confirmed changes.  (one of: `stay_date`, `booked_at`, `updated_at`, default: `stay_date`) |
| `per_page` | integer | no | Number of reservations 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/{listing_id}/reservations?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

Array of reservations.

Body (`application/json`): array of object `reservation_response`

A reservation.

- `id` (string, required): The reservation ID.
- `status` (string, required): The reservation status. Known values: `Accepted`, `Declined`, `Expired`, `Canceled`, `Pending`, `Ignored`.
- `start_date` (string (date), required): The check-in date (YYYY-MM-DD).
- `end_date` (string (date), required): The check-out date (YYYY-MM-DD).
- `booked_at` (string (date-time), nullable): When the reservation was booked (ISO-8601), or `null` if it is unknown.
- `canceled_at` (string (date-time), nullable): When the reservation was cancelled (ISO-8601), or `null` if it was not. Set whenever `status` is `Canceled`. Note the single-l spelling, matching the `Canceled` status value; the `PUT` request body uses `cancelled`.
- `num_guests` (integer, nullable): Number of guests, or `null` if it was not provided.
- `currency` (string, nullable): The ISO-4217 3-letter currency code, or `null` if it is unknown.
- `total_price` (number, nullable): Total price of the reservation paid by the guest, or `null` if it is unknown.
- `nightly_subtotal` (number, nullable): Sum of all nightly room prices. This is the 'Revenue' metric in the Wheelhouse platform (rent only, excluding fees and taxes). To derive Revenue + Fees, compute `total_price − taxes`. To derive ADR (Average Daily Rate) for this reservation, divide by the number of nights. `null` if it is unknown.
- `extra_guest` (number, nullable): Extra guest fee amount, or `null` if it is unknown.
- `security_deposit` (number, nullable): Security deposit amount, or `null` if it is unknown.
- `extras` (number, nullable): Additional extras charges, or `null` if it is unknown.
- `taxes` (number, nullable): Tax amount, or `null` if it is unknown.
- `confirmation_code` (string, nullable): The reservation confirmation code from the booking channel, or `null` if none was provided.
- `source_name` (string, nullable): The name of the booking source/channel, or `null` if it is unknown.
- `comments` (string, nullable): Any comments or notes about the reservation, or `null` if none were provided.
- `created_at` (string (date-time), nullable): When the reservation was created in Wheelhouse (ISO-8601), or `null` if it is unknown.
- `updated_at` (string (date-time), nullable): When the reservation was last updated in Wheelhouse (ISO-8601), or `null` if it is unknown.

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

```json
[
  {
    "id": "string",
    "status": "string",
    "start_date": "2026-01-01",
    "end_date": "2026-01-01",
    "booked_at": "2026-01-01T00:00:00Z",
    "canceled_at": "2026-01-01T00:00:00Z",
    "num_guests": 0,
    "currency": "string",
    "total_price": 0,
    "nightly_subtotal": 0,
    "extra_guest": 0,
    "security_deposit": 0,
    "extras": 0,
    "taxes": 0,
    "confirmation_code": "string",
    "source_name": "string",
    "comments": "string",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z"
  }
]
```

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