# Get the price calendar for a listing.

`GET /listings/{listing_id}/price_calendar`

> Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-price-calendar · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetPriceCalendar` · Tag: Calendar

Returns the price calendar for a single listing. Each entry represents one stay date and includes the price, availability, and booking state.

The data reflects the current state of the calendar as of the time of the request:
- **Future dates** — the current price and availability as they stand right now.
- **Past dates** — the state the date ended up in (e.g. whether it was booked, blocked, or left available, and the price that was in effect at the time).

Defaults to today through the maximum calendar horizon (1.5 years) when `start_date` and `end_date` are omitted. The total date range may not exceed 3 years.

## Request

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

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 (date) | no | First stay date to include (YYYY-MM-DD). Defaults to today. |
| `end_date` | string (date) | no | Last stay date to include (YYYY-MM-DD). Defaults to the maximum calendar horizon (1.5 years from today). The total range (`start_date` to `end_date`) may not exceed 3 years. |

### Example request

```bash
curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/price_calendar?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 calendar day entries ordered by stay date.

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

One stay date of a listing's price calendar.

- `stay_date` (string (date), required): The stay date.
- `price` (integer, required, nullable): The current observed price for this date, or `null` if none is recorded. For available dates this is the live price. For booked or blocked dates this is the price it booked at. Use `GET /listings/{listing_id}/last_posted_prices` to retrieve the last price posted to the channel.
- `currency` (string, nullable): ISO 4217 currency code for the price, or `null` if none is recorded.
- `is_available` (boolean, required): Whether the date is available for booking. State matrix: `is_available=true, is_booked=false` = available; `is_available=false, is_booked=true` = booked (confirmed reservation); `is_available=false, is_booked=false` = blocked (owner hold or similar).
- `is_booked` (boolean, required): Whether the date has a confirmed booking. See `is_available` for the full state matrix.
- `block_time` (string (date), nullable): The date and time (ISO-8601) when this night first became unavailable. Null for available nights.

  This field applies to both owner-blocked and guest-booked nights using the same column:
  - **Booked nights** (`is_booked=true`): the date the reservation was first detected as pending or accepted by Wheelhouse.
  - **Blocked nights** (`is_booked=false, is_available=false`): approximately the date the calendar sync recorded the block.

  The value is not the check-in date or booking date in the channel sense — it reflects when Wheelhouse's calendar ingestion first observed the night as unavailable.
- `reservation_id` (string, nullable): The reservation ID associated with this date, if booked. This is the channel reservation ID (a string), or `null` when the night is not booked.
- `unit_number` (integer, required): The unit number, 0 if the listing is single-unit.
- `created_at` (string (date-time)): The date and time the data was created.

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

```json
[
  {
    "stay_date": "2026-01-01",
    "price": 0,
    "currency": "string",
    "is_available": true,
    "is_booked": true,
    "block_time": "2026-01-01",
    "reservation_id": "string",
    "unit_number": 0,
    "created_at": "2026-01-01T00:00:00Z"
  }
]
```

### 400

Date range exceeds the 3-year maximum.

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