> For the complete documentation index, see [llms.txt](https://docs.hostelmate.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hostelmate.co/api-documentation/rates.md).

# Rates Calendar

Read and change each room's nightly prices and closed dates with your Hostel Mate API key. Changes reach your booking channels automatically.

Read your rate calendar night by night, and change it. For every room you get the price you set, whether the night is closed, how many beds are for sale, and the stay rules. You can change prices and open or close nights; the change is saved at once and sent to your booking channels.

Use it to show a calendar, to keep another system in step, or to manage your prices from a revenue tool. To price a specific guest stay, use [Availability](https://docs.hostelmate.co/api-documentation/availability.md) instead.

* [Read rates](#read-rates): `GET /api/v1/client/rates`
* [Update rates](#update-rates): `POST /api/v1/client/rates`

### Related API Pages

* [API Authentication](https://docs.hostelmate.co/api-documentation/authentication.md)
* [Availability](https://docs.hostelmate.co/api-documentation/availability.md)
* [Booking Create](https://docs.hostelmate.co/api-documentation/bookings/create.md)

## Read rates

#### Endpoint

```http
GET /api/v1/client/rates
```

#### Query Parameters

<table><thead><tr><th width="120">Parameter</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>start_date</code></td><td>string</td><td><strong>Required.</strong> First night (YYYY-MM-DD).</td></tr><tr><td><code>end_date</code></td><td>string</td><td><strong>Required.</strong> Last night, included (YYYY-MM-DD). Send the same date as <code>start_date</code> for one night.</td></tr><tr><td><code>room</code></td><td>string</td><td>Optional. A room ID, to get only that room.</td></tr></tbody></table>

**Date rules.** Dates are in your property's own time zone.

* `start_date` can be today, but not earlier.
* One request covers up to 366 nights.
* `end_date` can be up to 730 days ahead.

***

#### Example Request

```bash
curl "https://api.hostelmate.co/api/v1/client/rates?start_date=2026-11-02&end_date=2026-11-03" \
  -H "X-API-Key: <your_api_key>"
```

#### Example Response (200 OK)

```json
{
  "property_id": "73d9244a-44df-4254-b304-999c122b8dc1",
  "currency": "EUR",
  "start_date": "2026-11-02",
  "end_date": "2026-11-03",
  "rooms": [
    {
      "room_id": "265b373a-6248-4424-bf18-dc2bbf63a920",
      "name": "Mixed Dorm",
      "sell_mode": "per_person",
      "sell_count": null,
      "nights": [
        {
          "date": "2026-11-02", "price": 2500, "closed": false, "available": 6,
          "min_stay": 2, "max_stay": null, "closed_to_arrival": false, "closed_to_departure": false
        },
        {
          "date": "2026-11-03", "price": null, "closed": true, "available": 6,
          "min_stay": null, "max_stay": null, "closed_to_arrival": false, "closed_to_departure": false
        }
      ]
    }
  ]
}
```

#### Response Fields

<table><thead><tr><th width="250">Field</th><th width="90">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>property_id</code></td><td>string</td><td>Your property ID.</td></tr><tr><td><code>currency</code></td><td>string</td><td>Your property's currency. All prices are in it.</td></tr><tr><td><code>start_date</code>, <code>end_date</code></td><td>string</td><td>The range you asked for.</td></tr><tr><td><code>rooms[].room_id</code></td><td>string</td><td>Room ID.</td></tr><tr><td><code>rooms[].name</code></td><td>string</td><td>Room name.</td></tr><tr><td><code>rooms[].sell_mode</code></td><td>string</td><td><code>per_person</code> (sold by the bed), <code>per_room</code> or <code>hybrid</code> (sold as whole units).</td></tr><tr><td><code>rooms[].sell_count</code></td><td>integer</td><td>Guests one unit sleeps, for rooms sold as units. <code>null</code> when not set.</td></tr><tr><td><code>nights[].date</code></td><td>string</td><td>The night (YYYY-MM-DD).</td></tr><tr><td><code>nights[].price</code></td><td>integer</td><td>The price you set for that night, or <code>null</code> when none is set. Per guest for <code>per_person</code> rooms, per unit otherwise.</td></tr><tr><td><code>nights[].closed</code></td><td>boolean</td><td><code>true</code> when the night is closed for sale. A night you never priced shows <code>"price": null</code> and <code>"closed": true</code>.</td></tr><tr><td><code>nights[].available</code></td><td>integer</td><td>Beds (or units) for sale that night: the same number your booking channels get.</td></tr><tr><td><code>nights[].min_stay</code></td><td>integer</td><td>Minimum nights for a stay arriving that night, or <code>null</code>.</td></tr><tr><td><code>nights[].max_stay</code></td><td>integer</td><td>Maximum nights for a stay arriving that night, or <code>null</code>.</td></tr><tr><td><code>nights[].closed_to_arrival</code></td><td>boolean</td><td>Guests can't arrive that day.</td></tr><tr><td><code>nights[].closed_to_departure</code></td><td>boolean</td><td>Guests can't leave that day.</td></tr></tbody></table>

#### Good to know

* Prices are integers in **minor units**: `2500` = 25.00.
* This is the price you set. The price a guest pays can move with your free-bed price rules; [Availability](https://docs.hostelmate.co/api-documentation/availability.md) gives that live price for a stay.
* `available` counts free beds on its own. A closed night can still show beds, so check `closed` too.
* Every room is listed, including rooms hidden from your booking page and rooms that are switched off.

#### Error Codes

Errors come back as JSON with a `code` and a `message`:

```json
{ "code": "bad_request", "message": "end_date can't be before start_date" }
```

<table><thead><tr><th width="80">HTTP</th><th width="190">Code</th><th>When</th></tr></thead><tbody><tr><td>400</td><td><code>bad_request</code></td><td>A date is missing, <code>end_date</code> is before <code>start_date</code>, <code>start_date</code> is in the past, the range is longer than 366 nights or goes past 730 days ahead, or <code>room</code> is not an ID. The <code>message</code> says which.</td></tr><tr><td>422</td><td><code>invalid_date_format</code></td><td>A date can't be read. Use YYYY-MM-DD.</td></tr><tr><td>404</td><td><code>room_not_found</code></td><td><code>room</code> is not one of your rooms.</td></tr><tr><td>401 / 403 / 429</td><td></td><td>Missing or wrong API key, plan or origin not allowed, or too many requests. See <a href="https://docs.hostelmate.co/api-documentation/authentication.md">Authentication</a>.</td></tr><tr><td>500</td><td><code>server_error</code></td><td>Something failed on our side. Retry with backoff.</td></tr></tbody></table>

***

## Update rates

Change prices and open or close nights, for one or more rooms, in one request. It's the same as saving on your Pricing page: the new prices are live on your booking page at once, and they're sent to your booking channels within moments.

#### Endpoint

```http
POST /api/v1/client/rates
```

Send an `Idempotency-Key` header, as for every change (see [Authentication](https://docs.hostelmate.co/api-documentation/authentication.md)).

#### Example Request

```bash
curl "https://api.hostelmate.co/api/v1/client/rates" \
  -X POST \
  -H "X-API-Key: <your_api_key>" \
  -H "Idempotency-Key: 6f1c2a90-weekend-december" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {
        "room_id": "265b373a-6248-4424-bf18-dc2bbf63a920",
        "start_date": "2026-12-01",
        "end_date": "2026-12-31",
        "days_of_week": ["fri", "sat"],
        "price": 3200
      },
      {
        "room_id": "7b9e2f12-34cd-4e89-bf45-4a18f5a8a1f0",
        "start_date": "2026-12-24",
        "end_date": "2026-12-26",
        "closed": true
      }
    ]
  }'
```

#### Request Body

The body is `{"updates": [...]}`, a list of 1 to 100 changes. Each change is one room and one date range:

<table><thead><tr><th width="150">Field</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>room_id</code></td><td>string</td><td><strong>Required.</strong> One of your rooms (the <code>room_id</code> from <a href="#read-rates">Read rates</a>).</td></tr><tr><td><code>start_date</code>, <code>end_date</code></td><td>string</td><td><strong>Required.</strong> The first and last night to change, both included (YYYY-MM-DD). Send the same date twice for one night.</td></tr><tr><td><code>days_of_week</code></td><td>array</td><td>Optional. Only change these days in the range: any of <code>mon</code>, <code>tue</code>, <code>wed</code>, <code>thu</code>, <code>fri</code>, <code>sat</code>, <code>sun</code>.</td></tr><tr><td><code>price</code></td><td>integer</td><td>The new nightly price in <strong>minor units</strong>: <code>3200</code> = 32.00. From 1 to 999999999. Per guest for <code>per_person</code> rooms, per unit otherwise, as in <a href="#read-rates">Read rates</a>.</td></tr><tr><td><code>closed</code></td><td>boolean</td><td><code>true</code> closes the nights for sale, <code>false</code> opens them.</td></tr></tbody></table>

Send `price`, `closed`, or both. What you leave out stays as it is.

**Date rules.** Dates are in your property's own time zone. `start_date` can be today, but not earlier, and `end_date` can be up to 730 days ahead.

**All or nothing.** If any change in the list is wrong, nothing is saved, and the error says which one (`updates[2]: …`). Two changes in one request can't touch the same room and night.

#### What gets saved

<table><thead><tr><th width="230">You send</th><th>Result</th></tr></thead><tbody><tr><td><code>price</code></td><td>The new price. A night that was closed stays closed; a night that had no price yet is created <strong>open</strong>.</td></tr><tr><td><code>closed: true</code></td><td>The nights are closed. Their price is kept for when you open them again.</td></tr><tr><td><code>closed: false</code></td><td>The nights are opened. Every night must already have a price; otherwise send <code>price</code> too.</td></tr><tr><td><code>price</code> and <code>closed</code></td><td>Both are saved.</td></tr></tbody></table>

#### Example Response (200 OK)

```json
{
  "saved_nights": 12,
  "changed_nights": 9,
  "sync": "queued",
  "rooms": [
    {
      "room_id": "265b373a-6248-4424-bf18-dc2bbf63a920",
      "name": "Mixed Dorm",
      "sell_mode": "per_person",
      "sell_count": null,
      "nights": [
        {
          "date": "2026-12-04", "price": 3200, "closed": false, "available": 6,
          "min_stay": null, "max_stay": null, "closed_to_arrival": false, "closed_to_departure": false
        }
      ]
    }
  ]
}
```

<table><thead><tr><th width="180">Field</th><th width="90">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>saved_nights</code></td><td>integer</td><td>Room-nights in your request.</td></tr><tr><td><code>changed_nights</code></td><td>integer</td><td>Room-nights whose price or closed state actually changed.</td></tr><tr><td><code>sync</code></td><td>string</td><td><code>queued</code> when the change is on its way to your booking channels, <code>none</code> when nothing changed.</td></tr><tr><td><code>rooms</code></td><td>array</td><td>The nights you sent, as they are now saved, in the same shape as <a href="#read-rates">Read rates</a>.</td></tr></tbody></table>

#### How it reaches your channels

* The new prices are saved before we answer, so your booking page and your next [Read rates](#read-rates) already show them.
* Your booking channels get the change within moments, in the background. Long ranges are sent in parts.
* Only nights that really changed are sent. Sending the same prices again is safe and doesn't send anything.
* A room that isn't connected to a channel is saved and used by your booking page only.

#### Good to know

* Up to 100 changes and 21,930 room-nights per request.
* Your key's limit of 120 requests a minute applies. Send many rooms and ranges in one request instead of one request each.
* A price is per night. The price a guest pays can still move with your free-bed price rules, as on your booking page.

#### Error Codes

<table><thead><tr><th width="80">HTTP</th><th width="190">Code</th><th>When</th></tr></thead><tbody><tr><td>400</td><td><code>bad_request</code></td><td>The body isn't <code>{"updates": [...]}</code>; a change has an unknown field, a missing <code>room_id</code> or date, a date before today or more than 730 days ahead, an end before the start, <code>days_of_week</code> that's wrong or matches no night, a <code>price</code> that isn't a whole number from 1 to 999999999, a <code>closed</code> that isn't <code>true</code>/<code>false</code>, or neither <code>price</code> nor <code>closed</code>; two changes touch the same room and night; too many changes or room-nights; or the <code>Idempotency-Key</code> header is missing. The <code>message</code> says which.</td></tr><tr><td>422</td><td><code>invalid_date_format</code></td><td>A date can't be read. Use YYYY-MM-DD.</td></tr><tr><td>422</td><td><code>price_required</code></td><td>You opened a night that has no price. Send a <code>price</code> with it.</td></tr><tr><td>404</td><td><code>room_not_found</code></td><td><code>room_id</code> is not one of your rooms.</td></tr><tr><td>409</td><td><code>conflict</code></td><td>The room is sold together with another room on your booking channels; change the price on that room (the message names it).</td></tr><tr><td>401 / 403 / 429</td><td></td><td>Missing or wrong API key, plan or origin not allowed, or too many requests. See <a href="https://docs.hostelmate.co/api-documentation/authentication.md">Authentication</a>.</td></tr><tr><td>500</td><td><code>server_error</code></td><td>Something failed on our side; nothing was saved. Retry with the same <code>Idempotency-Key</code>.</td></tr></tbody></table>
