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.
Related API Pages
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/availabilityGET with a check-in and check-out date. Use this for new integrations.
POST with a list of dates, the same body
get-new-avilabliltytakes. Use this if you're moving from that endpoint: see Moving from get-new-avilablilty.
Query Parameters (GET)
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_incan 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)
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
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[].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.
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_bedsstill 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_inor leave oncheck_out(norestrictionis 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
Pick a room with
"bookable": true.Call Booking Create with that
room_id. Send each night'sdate, and its price asbooking.dates[].amount.One booking holds one bed, or one private room. For a private room, one booking covers the party: use the night's
priceas is. For several guests in a dorm, create one booking per guest, each with that guest's share of the night's price (pricedivided byguests).Availability changes every time someone books, so a room can be taken in between. Booking Create checks again and answers
409 availability_conflictif 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:
The URL:
https://api.hostelmate.co/api/v1/client/availability.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
400or422.
Error Codes
Errors come back as JSON with a code and a message:
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