> 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/availability.md).

# Availability

Check which rooms a guest can book for a stay, with nightly prices and free beds, using your Hostel Mate API key.

Ask "can a guest book this stay, and for how much?" You get every room your booking page shows, with a price and free beds for each night, and whether the whole stay can be booked.

The answer is the same one your own booking page gives a guest for the same dates. It follows your prices, closed dates, minimum and maximum stay, same-day cutoff and booking window.

### Related API Pages

* [API Authentication](https://docs.hostelmate.co/api-documentation/authentication.md)
* [Rates Calendar](https://docs.hostelmate.co/api-documentation/rates.md)
* [Booking Create](https://docs.hostelmate.co/api-documentation/bookings/create.md)
* [Bookings List](https://docs.hostelmate.co/api-documentation/bookings/list.md)

#### Endpoint

You can ask in two ways. Both give the same answer.

```http
GET /api/v1/client/availability?check_in=…&check_out=…&guests=…
POST /api/v1/client/availability
```

* **GET** with a check-in and check-out date. Use this for new integrations.
* **POST** with a list of dates, the same body `get-new-avilablilty` takes. Use this if you're moving from that endpoint: see [Moving from get-new-avilablilty](#moving-from-get-new-avilablilty).

#### Query Parameters (GET)

<table><thead><tr><th width="120">Parameter</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>check_in</code></td><td>string</td><td><strong>Required.</strong> First night of the stay (YYYY-MM-DD).</td></tr><tr><td><code>check_out</code></td><td>string</td><td><strong>Required.</strong> Departure day (YYYY-MM-DD). It is not a night: a stay from the 2nd to the 5th is 3 nights.</td></tr><tr><td><code>guests</code></td><td>integer</td><td>Number of guests, 1 to 50 (default: 1).</td></tr></tbody></table>

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

* `check_in` can be today, but not earlier.
* A stay can be up to 180 nights.
* The last night can be up to 730 days ahead.

#### Request Body (POST)

```bash
curl "https://api.hostelmate.co/api/v1/client/availability" \
  -X POST \
  -H "X-API-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "dates": ["2026-11-02", "2026-11-03", "2026-11-04"],
    "property": "your-property-uuid",
    "guests": 2
  }'
```

<table><thead><tr><th width="120">Field</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>dates</code></td><td>array</td><td><strong>Required.</strong> The nights to check (YYYY-MM-DD), up to 366. Each date is checked as you send it: any order, gaps and past dates are allowed. An empty list returns no rooms.</td></tr><tr><td><code>property</code></td><td>string</td><td>Optional. Your property ID. Your API key already says which property it is; if you send a different ID you get <code>404</code>.</td></tr><tr><td><code>guests</code></td><td>integer</td><td>Optional. Number of guests (default: 1). A value that isn't a whole number, or is below 1, counts as 1.</td></tr></tbody></table>

POST is a read, so it needs no `Idempotency-Key`.

***

#### Example Request

```bash
curl "https://api.hostelmate.co/api/v1/client/availability?check_in=2026-11-02&check_out=2026-11-05&guests=2" \
  -H "X-API-Key: <your_api_key>"
```

#### Example Response (200 OK)

```json
{
  "property_id": "73d9244a-44df-4254-b304-999c122b8dc1",
  "currency": "IDR",
  "check_in": "2026-11-02",
  "check_out": "2026-11-05",
  "nights": 3,
  "guests": 2,
  "rooms": [
    {
      "room_id": "265b373a-6248-4424-bf18-dc2bbf63a920",
      "name": "Mixed Dorm",
      "bookable": true,
      "total": 90000000,
      "nights": [
        { "date": "2026-11-02", "price": 30000000, "available_beds": 6 },
        { "date": "2026-11-03", "price": 30000000, "available_beds": 4 },
        { "date": "2026-11-04", "price": 30000000, "available_beds": 5 }
      ],
      "restriction": null
    },
    {
      "room_id": "7b9e2f12-34cd-4e89-bf45-4a18f5a8a1f0",
      "name": "Private Double",
      "bookable": false,
      "total": null,
      "nights": [
        { "date": "2026-11-02", "price": null, "available_beds": 0 },
        { "date": "2026-11-03", "price": null, "available_beds": 0 },
        { "date": "2026-11-04", "price": null, "available_beds": 0 }
      ],
      "restriction": { "code": "min_stay", "value": 4 }
    }
  ],
  "days": [ … ],
  "name": "Alphatel Hostel",
  "…": "the booking page fields below"
}
```

#### 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>check_in</code>, <code>check_out</code></td><td>string</td><td>The dates you asked for. For a POST: the earliest date, and the day after the latest one (<code>null</code> when <code>dates</code> is empty).</td></tr><tr><td><code>nights</code></td><td>integer</td><td>Number of nights in the stay (for a POST, the number of dates you sent).</td></tr><tr><td><code>guests</code></td><td>integer</td><td>Number of guests the prices are for.</td></tr><tr><td><code>rooms[].room_id</code></td><td>string</td><td>Room ID. Use it as <code>room</code> when you <a href="https://docs.hostelmate.co/api-documentation/bookings/create.md">create a booking</a>.</td></tr><tr><td><code>rooms[].name</code></td><td>string</td><td>Room name.</td></tr><tr><td><code>rooms[].bookable</code></td><td>boolean</td><td><code>true</code> when every night of the stay has a price for this many guests.</td></tr><tr><td><code>rooms[].total</code></td><td>integer</td><td>Sum of the nightly prices when bookable, otherwise <code>null</code>.</td></tr><tr><td><code>rooms[].nights[].date</code></td><td>string</td><td>The night (YYYY-MM-DD), in date order.</td></tr><tr><td><code>rooms[].nights[].price</code></td><td>integer</td><td>Price for that night for the whole party, or <code>null</code> when the night can't be sold to them.</td></tr><tr><td><code>rooms[].nights[].available_beds</code></td><td>integer</td><td>Beds free that night (units, for private rooms).</td></tr><tr><td><code>rooms[].restriction</code></td><td>object</td><td>Why the stay can't be booked when a stay rule is the reason: <code>{"code": "min_stay", "value": 4}</code> or <code>{"code": "max_stay", "value": 7}</code>, where <code>value</code> is in nights. Otherwise <code>null</code>.</td></tr></tbody></table>

#### Booking page fields

Every answer, GET or POST, also carries everything `get-new-avilablilty` returns, with the same names and values. The one difference: photo links (`image_fullpath`) use our image address, `https://cdn.hostelmate.co/`, and point to the same photos. Use these fields to show rooms, photos and your property details on your own page.

```json
{
  "days": [
    {
      "room_id": "265b373a-6248-4424-bf18-dc2bbf63a920",
      "room_name": "Mixed Dorm",
      "room_description": "Six beds, lockers, sea view.",
      "date": [
        { "date": "2026-11-02", "price": 300000.0, "available_beds": 6 }
      ],
      "images": ["dorm-1.jpg"],
      "image_fullpath": ["https://cdn.hostelmate.co/room_images/dorm-1.jpg"]
    }
  ],
  "name": "Alphatel Hostel",
  "city": "Ubud",
  "country": "Indonesia",
  "postal_code": "80571",
  "timezone": "Asia/Makassar",
  "payment_gateway": { "status": true, "currency": "IDR", "options": ["pay_at_property"] },
  "rate": "9.2",
  "phone": "+62 000 000",
  "description": "",
  "about": "",
  "utilities": "",
  "googleMapLink": "https://www.google.com/maps?q=…",
  "address": "Jl. Example 1",
  "website": "https://example.com/",
  "main-image": "https://…/main.jpg",
  "howToReachUsLink": "https://www.google.com/maps?q=…",
  "price_adjustment": { "type": "increase", "percentage": 10 },
  "engine_settings": { … }
}
```

<table><thead><tr><th width="250">Field</th><th width="90">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>days</code></td><td>array</td><td>One entry per room, the same rooms as <code>rooms</code>.</td></tr><tr><td><code>days[].room_id</code>, <code>room_name</code>, <code>room_description</code></td><td>string</td><td>The room's ID, name and description.</td></tr><tr><td><code>days[].date[]</code></td><td>array</td><td>Each date in the order you sent it: <code>date</code>, <code>price</code> and <code>available_beds</code>. Here <code>price</code> is a number in <strong>major units</strong> (<code>300000.0</code> = 300,000.00), or <code>false</code> when the night can't be sold. It's the same price as <code>rooms[].nights[].price</code>, which is in minor units.</td></tr><tr><td><code>days[].images</code>, <code>days[].image_fullpath</code></td><td>array</td><td>The room's photos in your order: the stored path, and the full URL to show or share.</td></tr><tr><td><code>days[].restriction</code></td><td>object</td><td>Only there when a minimum or maximum stay rule is the reason, as in <code>rooms[].restriction</code>.</td></tr><tr><td><code>name</code>, <code>city</code>, <code>country</code>, <code>postal_code</code>, <code>timezone</code></td><td>string</td><td>Your property's details.</td></tr><tr><td><code>payment_gateway</code></td><td>object</td><td>The payment methods your booking page offers: <code>status</code> (<code>true</code> when there is at least one), <code>currency</code>, <code>options</code>.</td></tr><tr><td><code>rate</code>, <code>phone</code>, <code>description</code>, <code>about</code>, <code>utilities</code>, <code>googleMapLink</code>, <code>address</code>, <code>website</code>, <code>main-image</code>, <code>howToReachUsLink</code></td><td>string</td><td>What you entered in your booking page settings, or <code>""</code> when empty.</td></tr><tr><td><code>price_adjustment</code></td><td>object</td><td>The price adjustment you set for your booking page: <code>{"type": "increase" | "decrease", "percentage": n}</code>, or <code>null</code>. Prices in this answer are before it, so apply it yourself if you show booking page prices.</td></tr><tr><td><code>engine_settings</code></td><td>object</td><td>Your booking page settings (guest fields, messages, analytics), the same your booking page uses.</td></tr></tbody></table>

#### How prices work

* Prices are integers in **minor units**, like the [Bookings API](https://docs.hostelmate.co/api-documentation/bookings/list.md): `30000000` = 300,000.00.
* A dorm is priced per guest, so the night's price is already multiplied by `guests`. A private room is priced per room.
* These are your nightly prices before any price adjustment you set for your booking page.
* Prices can follow your free-bed price rules, so the same search can give a different price later.

#### When a night has no price

A night's `price` is `null`, and the room is not bookable, when:

* the room has no price for that night, or the night is closed;
* there are fewer free beds than guests (`available_beds` still shows how many are free);
* a private room sleeps fewer people than `guests`;
* the stay breaks a minimum or maximum stay rule (see `restriction`);
* guests can't arrive on `check_in` or leave on `check_out` (no `restriction` is given for these);
* the night is past your booking window, or it is tonight and your same-day cutoff has passed.

#### Which rooms are listed

Every room your booking page shows. Rooms you hid from your booking page, and rooms that are switched off, are not listed.

#### From availability to a booking

1. Pick a room with `"bookable": true`.
2. Call [Booking Create](https://docs.hostelmate.co/api-documentation/bookings/create.md) with that `room_id`. Send each night's `date`, and its price as `booking.dates[].amount`.
3. One booking holds one bed, or one private room. For a private room, one booking covers the party: use the night's `price` as is. For several guests in a dorm, create one booking per guest, each with that guest's share of the night's price (`price` divided by `guests`).
4. Availability changes every time someone books, so a room can be taken in between. Booking Create checks again and answers `409 availability_conflict` if the beds are gone. Search again and offer what's left.

If Booking Create answers `409` with "Room is not enabled for client API bookings", that room isn't set up for API bookings yet. Contact support about it.

#### Moving from get-new-avilablilty

If you call `POST /api/v1/get-new-avilablilty` today, you only change two things:

1. The URL: `https://api.hostelmate.co/api/v1/client/availability`.
2. Add your API key: `-H "X-API-Key: <your_api_key>"`.

Keep your request body and your code. Every field you read today is in the answer with the same name and value; only photo links now start with `https://cdn.hostelmate.co/` (the same photos). The new fields (`rooms`, `bookable`, `total`, minor units) are there when you want them.

Two small differences:

* **Limits:** up to 366 dates per request, and your key's 120 requests a minute (see [Authentication](https://docs.hostelmate.co/api-documentation/authentication.md)).
* **Errors:** a request the old endpoint couldn't read now gets a clear `400` or `422`.

#### Error Codes

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

```json
{ "code": "bad_request", "message": "check_out must be after check_in" }
```

<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>GET: a date is missing, <code>check_out</code> is not after <code>check_in</code>, <code>check_in</code> is in the past, the stay is longer than 180 nights or goes past 730 days ahead, or <code>guests</code> is not a whole number from 1 to 50. POST: the body is not a JSON object, <code>dates</code> is missing or not a list, or it holds more than 366 dates. 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>not_found</code></td><td>Your property is not taking bookings, or (POST) <code>property</code> is not your property.</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>
