# Set multiple custom rates for a listing in bulk.

`PUT /listings/{listing_id}/bulk_custom_rates`

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

Creates or replaces multiple custom rates in a single request. Partially successful
requests return status `207`; fully failed requests return `424`.

For `adjustment` rates, per-day values are percentages where 100 = no adjustment,
110 = +10%, and 90 = −10%.

If a 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}/bulk_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)

- `custom_rates` (array of object `custom_rate_input`, required)
  - Each item: 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}/bulk_custom_rates?channel=<channel>' \
  -H 'X-Integration-Api-Key: <your RM API key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "custom_rates": [
    {
      "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

All custom rates set successfully. An empty `custom_rates` array is accepted and returns an empty `updated_custom_rates`; nothing is changed.

Body (`application/json`): object

- `updated_custom_rates` (array of object `rate_period_response`)
  - Fields: see `rate_period_response` under Schemas.

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

```json
{
  "updated_custom_rates": [
    {
      "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"
    }
  ]
}
```

### 207

Some custom rates succeeded and some failed.

Body (`application/json`): object

- `updated_custom_rates` (array of object `rate_period_response`)
  - Fields: see `rate_period_response` under Schemas.
- `errors` (array of object `custom_rate_error`)
  - Fields: see `custom_rate_error` under Schemas.

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

```json
{
  "updated_custom_rates": [
    {
      "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"
    }
  ],
  "errors": [
    {
      "start_date": "2026-01-01",
      "end_date": "2026-01-01",
      "http_code": 0,
      "message": "string"
    }
  ]
}
```

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

### 424

All custom rates failed.

Body: same as `207` above.

### 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.

### `rate_period_response`

Type: 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).

### `custom_rate_error`

Type: object `custom_rate_error`

An error that occurred when processing a custom rate.

- `start_date` (string (date))
- `end_date` (string (date))
- `http_code` (integer)
- `message` (string)

## 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 live custom rates that will be posted to the channel, and will silently shorten or split any existing custom rates that overlap 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.
