# Set a custom rate for a listing.

`PUT /listings/{listing_id}/custom_rates`

> Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-put-custom-rate · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPutCustomRate` · Tag: Custom Rates

Creates or replaces a custom rate for a date range. Setting a `fixed` rate applies an
absolute nightly price; setting an `adjustment` rate applies a percentage multiplier to
the Wheelhouse recommendation. For `adjustment` rates, per-day values are percentages
where 100 = no adjustment, 110 = +10%, and 90 = −10%.

If the specified date range overlaps an existing custom rate, the existing rate is
shortened or split so the new rate takes precedence for the overlapping dates. Custom
rates are not stacked — a new adjustment rate replaces rather than compounds with any
existing adjustment for the same dates. To combine adjustments, compute the target
multiplier explicitly and submit the combined value.

## Request

`PUT https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/custom_rates`

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 |
| --- | --- | --- | --- |
| `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). |

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

A custom rate to set for a date range.

- `start_date` (string (date), required): The first date of the custom rate period (YYYY-MM-DD).
- `end_date` (string (date), required): The last date of the custom rate period (YYYY-MM-DD).
- `rate_type` (string, required, one of: `fixed`, `adjustment`): The type of custom rate.
  - `fixed`: A fixed nightly price. Requires `currency`. Per-day values (`sunday`–`saturday`) are absolute prices.
  - `adjustment`: A percentage adjustment to the Wheelhouse recommendation. Per-day values are percentages where 100 = no adjustment, 110 = +10%, and 90 = −10%.

  **Minimum price interactions:** Fixed rates are constrained only by `min_min_price` (the
  absolute floor) — they bypass `minimum_price_rules_v3` entirely. Adjustment rates are
  additionally constrained by per-date `minimum_price_rules_v3` floors; the resulting dollar
  price after applying the multiplier must meet or exceed the effective minimum price rule for
  each date.

  **Read-side representation:** When reading prices via `GET /listings/{listing_id}/price_recommendations`,
  an `adjustment` rate appears as `custom_type: "adjusted"` (past-tense form). The write value
  (`adjustment`) and the read value (`adjusted`) differ in form; match them accordingly when
  reconciling written rates against recommendation responses.
- `currency` (string): The ISO-4217 3-letter currency code. Required for `fixed` type.
- `sunday` (number, min: 1): Price or adjustment value for Sundays.
- `monday` (number, min: 1): Price or adjustment value for Mondays.
- `tuesday` (number, min: 1): Price or adjustment value for Tuesdays.
- `wednesday` (number, min: 1): Price or adjustment value for Wednesdays.
- `thursday` (number, min: 1): Price or adjustment value for Thursdays.
- `friday` (number, min: 1): Price or adjustment value for Fridays.
- `saturday` (number, min: 1): Price or adjustment value for Saturdays.
- `expires_at` (string (date-time)): When the custom rate expires (ISO-8601). Once past this timestamp the rate is no longer applied. Omit to create a rate that never expires.

### Example request

```bash
curl -X PUT 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/custom_rates?channel=<channel>' \
  -H 'X-Integration-Api-Key: <your RM API key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "start_date": "2026-01-01",
  "end_date": "2026-01-01",
  "rate_type": "fixed"
}'
```

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 created custom rate period.

Body (`application/json`): object `rate_period_response`

A custom rate period.

- `id` (integer): The Wheelhouse internal rate period ID.
- `listing_id` (integer): The Wheelhouse internal listing ID.
- `rate_type` (string, one of: `fixed`, `adjustment`): The type of custom rate. `fixed` means a fixed nightly price; `adjustment` means a percentage adjustment to the Wheelhouse recommendation. Note: when reading prices via `GET /listings/{listing_id}/price_recommendations`, an `adjustment` rate appears as `custom_type: "adjusted"` (past-tense form).
- `currency` (string, nullable): The currency of the fixed rate (ISO-4217). Only present for `fixed` type rates.
- `start_date` (string (date)): The first date of the rate period (YYYY-MM-DD).
- `end_date` (string (date)): The last date of the rate period (YYYY-MM-DD).
- `sunday` (number, nullable): Sunday price or adjustment value.
- `monday` (number, nullable): Monday price or adjustment value.
- `tuesday` (number, nullable): Tuesday price or adjustment value.
- `wednesday` (number, nullable): Wednesday price or adjustment value.
- `thursday` (number, nullable): Thursday price or adjustment value.
- `friday` (number, nullable): Friday price or adjustment value.
- `saturday` (number, nullable): Saturday price or adjustment value.
- `created_user_id` (integer): The ID of the user who created this rate period.
- `split_user_id` (integer, nullable): When a PUT or DELETE operation partially overlaps this rate period, causing it to be shortened or split, this field records the ID of the user whose request triggered the split. Null if the period has never been split.
- `expires_at` (string (date-time), nullable): The date-time after which this rate period is considered expired and no longer applies. Null if the period does not expire automatically.
- `valid_until` (string (date-time), nullable): Internal archival timestamp. Null means this is the currently active rate period. Non-null means this period has been replaced or deleted — the replacement took effect at this time.
- `created_at` (string (date-time)): When this rate period was created (ISO-8601).
- `updated_at` (string (date-time)): When this rate period was last updated (ISO-8601).

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

```json
{
  "id": 0,
  "listing_id": 0,
  "rate_type": "fixed",
  "currency": "string",
  "start_date": "2026-01-01",
  "end_date": "2026-01-01",
  "sunday": 0,
  "monday": 0,
  "tuesday": 0,
  "wednesday": 0,
  "thursday": 0,
  "friday": 0,
  "saturday": 0,
  "created_user_id": 0,
  "split_user_id": 0,
  "expires_at": "2026-01-01T00:00:00Z",
  "valid_until": "2026-01-01T00:00:00Z",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}
```

### 400

Validation failed.

### 401

API key authorization failed.

### 403

Listing authorization failed, or the API key is read-only and may not be used with PUT.

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

### 409

Another request is already in progress for this listing. 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"
}
```

## Notes for AI agents

The Wheelhouse MCP server gives agents these instructions for this operation. They apply equally when calling the API directly.

⚠️ **Requires user confirmation before calling.** This writes a live custom rate that will be posted to the channel, and will silently shorten or split any existing custom rate that overlaps the given date range(s).

**Step 1 — Check for an existing rate first.** Before writing any rate for a listing/date range, check for an existing overlapping custom rate (`rmGetCustomRates`). Do not assume intent based on the existing rate's presence.

**Step 2 — If an existing rate is found, ask the user to choose:**

* **(a) Adjust existing** — compound the requested change on top of what's already there, or
* **(b) Replace** — discard the existing rate and set only the new value

**Step 3 — If "adjust existing" is chosen, compute the combined value before calling this tool** — this tool does not compound automatically; whatever value is submitted is treated as the final value.

* `adjustment` type rates: the combination is **additive on percentage-points**, not multiplicative.
  * Example: existing rate is 110 (+10%). User requests +10% more. → Submit **120** (+20% total), *not* 110 × 1.10 = 121.
  * Formula: `new_value = existing_value + requested_delta_points`
* `fixed` type rates: the combination is **multiplicative on the dollar value**.
  * Example: existing rate is $100. User requests +10%. → Submit **$110** (100 × 1.10).
  * Formula: `new_value = round(existing_value × (1 + requested_delta_pct / 100))`

**Step 4 — Before calling, state to the user:** the listing, the exact date range(s), the rate type (fixed/adjustment), the existing value (if any), the computed new value, which mode was used (adjust/replace), and flag if this overlaps an existing rate. Do not call until the user has explicitly confirmed the specific dates and values.
