Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Availability

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.

Endpoint

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

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.

Query Parameters (GET)

Parameter
Type
Description

check_in

string

Required. First night of the stay (YYYY-MM-DD).

check_out

string

Required. Departure day (YYYY-MM-DD). It is not a night: a stay from the 2nd to the 5th is 3 nights.

guests

integer

Number of guests, 1 to 50 (default: 1).

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)

Field
Type
Description

dates

array

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

property

string

Optional. Your property ID. Your API key already says which property it is; if you send a different ID you get 404.

guests

integer

Optional. Number of guests (default: 1). A value that isn't a whole number, or is below 1, counts as 1.

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


Example Request

Example Response (200 OK)

Response Fields

Field
Type
Description

property_id

string

Your property ID.

currency

string

Your property's currency. All prices are in it.

check_in, check_out

string

The dates you asked for. For a POST: the earliest date, and the day after the latest one (null when dates is empty).

nights

integer

Number of nights in the stay (for a POST, the number of dates you sent).

guests

integer

Number of guests the prices are for.

rooms[].room_id

string

Room ID. Use it as room when you create a booking.

rooms[].name

string

Room name.

rooms[].bookable

boolean

true when every night of the stay has a price for this many guests.

rooms[].total

integer

Sum of the nightly prices when bookable, otherwise null.

rooms[].nights[].date

string

The night (YYYY-MM-DD), in date order.

rooms[].nights[].price

integer

Price for that night for the whole party, or null when the night can't be sold to them.

rooms[].nights[].available_beds

integer

Beds free that night (units, for private rooms).

rooms[].restriction

object

Why the stay can't be booked when a stay rule is the reason: {"code": "min_stay", "value": 4} or {"code": "max_stay", "value": 7}, where value is in nights. Otherwise null.

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.

Field
Type
Description

days

array

One entry per room, the same rooms as rooms.

days[].room_id, room_name, room_description

string

The room's ID, name and description.

days[].date[]

array

Each date in the order you sent it: date, price and available_beds. Here price is a number in major units (300000.0 = 300,000.00), or false when the night can't be sold. It's the same price as rooms[].nights[].price, which is in minor units.

days[].images, days[].image_fullpath

array

The room's photos in your order: the stored path, and the full URL to show or share.

days[].restriction

object

Only there when a minimum or maximum stay rule is the reason, as in rooms[].restriction.

name, city, country, postal_code, timezone

string

Your property's details.

payment_gateway

object

The payment methods your booking page offers: status (true when there is at least one), currency, options.

rate, phone, description, about, utilities, googleMapLink, address, website, main-image, howToReachUsLink

string

What you entered in your booking page settings, or "" when empty.

price_adjustment

object

The price adjustment you set for your booking page: {"type": "increase" | "decrease", "percentage": n}, or null. Prices in this answer are before it, so apply it yourself if you show booking page prices.

engine_settings

object

Your booking page settings (guest fields, messages, analytics), the same your booking page uses.

How prices work

  • Prices are integers in minor units, like the Bookings API: 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 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).

  • 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:

HTTP
Code
When

400

bad_request

GET: a date is missing, check_out is not after check_in, check_in is in the past, the stay is longer than 180 nights or goes past 730 days ahead, or guests is not a whole number from 1 to 50. POST: the body is not a JSON object, dates is missing or not a list, or it holds more than 366 dates. The message says which.

422

invalid_date_format

A date can't be read. Use YYYY-MM-DD.

404

not_found

Your property is not taking bookings, or (POST) property is not your property.

401 / 403 / 429

Missing or wrong API key, plan or origin not allowed, or too many requests. See Authentication.

500

server_error

Something failed on our side. Retry with backoff.

Last updated