Rooms and rates

Two endpoints that power the booking engine’s search results: the room list, which returns sellable room types, board types and prices for the given dates and occupancy, and availability, which returns day-by-day availability and rates for calendar views.

POST/external/online/roomTypeRoom list and rates GET/external/room/type/hotel/availabilityCalendar availability

Room list and rates#

POST/external/online/roomType

Authentication: Authorization: Bearer · Body: application/x-www-form-urlencoded or multipart/form-data

Returns the hotel’s room types open for online sale for the given dates and occupancy. For each room type the available count (roomCount), restrictions (minimum stay, closed to check-in/check-out), board types and price options are calculated. If children travel, send their ages with childAges[]; child pricing depends on age.

Validation rules: check-in today or later, check-out after check-in, at most 30 nights, 1–40 adults, 0–10 children (ages 0–16).

Form fields

hotelIDintegerrequired

Hotel ID. Must match the token’s hotel.

startDatedaterequired

Check-in date, YYYY-MM-DD.

endDatedaterequired

Check-out date, YYYY-MM-DD.

adultCountintegerrequired

Number of adults (1–40).

childCountintegerdefault: 0

Number of children (0–10). If it disagrees with childAges, the length of the age list wins.

childAges[]integer[]

Age of each child (0–16). Repeated as a form field: childAges[]=7&childAges[]=12.

languagestringdefault: tr

Response language (room names, feature titles, error messages).

buildingIDinteger

Lists only rooms in this building (block).

Response

200 List of room types. Prices sit under each board type in the prices object, keyed "<persons>-<1|0>": -1 is the standard (refundable) rate, -0 the non-refundable ([NR]) rate. With per-room pricing the keys are 1-1 / 1-0.

items[].id / nameinteger / string

Room type ID and name. Sent as roomTypeID in the booking.

items[].capacityAdult / capacityChildren / capacityTotalinteger

Adult, child and total capacity.

items[].roomCountinteger

Rooms sellable for these dates. 0 means not sellable; the reason is in roomRestrictionMessage.

items[].roomRestrictionMessagestring | null

Sales restriction.

closed_to_checkinclosed_to_checkoutpassive_salesminimum_staymaximum_stayclosed_to_arrivalprice_not_found

items[].nonRefundable / refundableboolean

Whether the room type offers non-refundable and/or refundable rates.

items[].images[]string[]

Image paths, relative to the API base URL.

items[].accommodationTypes[]object[]

Board types. id becomes ratePlanID in the booking. priceType: 0 per-person, 1 per-room pricing.

…accommodationTypes[].prices{}object

Price options. Each option: total nights, price total amount, currency, nonRefundable ("[NR]" means non-refundable), id selection ID, prices[] nightly rates (price, tarih as dd.mm.yyyy).

items[].roomFeatures[]object[]

Room features: title, icon.

countinteger

Number of room types returned.

errorMessage / errorCodestring | integer | null

Set on failure. Code list: Error codes.

Error responses

200 errorCode 10001 hotel not found · 10002 missing parameter · 10003 hotel closed to online sales · 10004 no room type open for sale · 10022 invalid date/occupancy parameters · 20001–20004 not enough availability.

Request

curl "https://test.hms.gen.tr/external/online/roomType" \
  -H "Authorization: Bearer $HMS_TOKEN" \
  -d "hotelID=1000" \
  -d "startDate=2026-08-18" \
  -d "endDate=2026-08-20" \
  -d "adultCount=2" \
  -d "childCount=1" \
  -d "childAges[]=7" \
  -d "language=en"

const res = await fetch("https://test.hms.gen.tr/external/online/roomType", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.HMS_TOKEN}`
  },
  body: new URLSearchParams([
    ["hotelID", "1000"],
    ["startDate", "2026-08-18"],
    ["endDate", "2026-08-20"],
    ["adultCount", "2"],
    ["childCount", "1"],
    ["childAges[]", "7"],
    ["language", "en"]
  ])
});
const data = await res.json();

$ch = curl_init('https://test.hms.gen.tr/external/online/roomType');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('HMS_TOKEN'),
    ],
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query([
        'hotelID' => '1000',
        'startDate' => '2026-08-18',
        'endDate' => '2026-08-20',
        'adultCount' => '2',
        'childCount' => '1',
        'childAges' => [
            '7',
        ],
        'language' => 'en',
    ]),
]);
$data = json_decode(curl_exec($ch), true);

Response · 200

{
    "success": true,
    "items": [
        {
            "id": 2,
            "name": "Standard Room",
            "capacityAdult": 2,
            "capacityTotal": 3,
            "totalBed": 1,
            "totalBathroom": 1,
            "roomSize": 24,
            "currency": "TRY",
            "detail": "<p>Garden view, 24 m² standard room.</p>",
            "roomCount": 5,
            "roomRestrictionMessage": null,
            "nonRefundable": false,
            "refundable": true,
            "images": [
                "images/1000/odatipi/standart-1.jpg",
                "images/1000/odatipi/standart-2.jpg"
            ],
            "accommodationTypes": [
                {
                    "id": 2,
                    "title": "Bed & Breakfast",
                    "priceType": 0,
                    "roomRestriction": 1,
                    "roomRestrictionMessage": null,
                    "roomRestrictionValue": null,
                    "prices": {
                        "2-1": {
                            "total": 2,
                            "title": 2,
                            "nonRefundable": "",
                            "price": "1930.00",
                            "currency": "TRY",
                            "id": "2/2",
                            "prices": [
                                {
                                    "price": "965.00",
                                    "tarih": "18.08.2026"
                                },
                                {
                                    "price": "965.00",
                                    "tarih": "19.08.2026"
                                }
                            ]
                        },
                        "2-0": {
                            "total": 2,
                            "title": 2,
                            "nonRefundable": "[NR]",
                            "price": "1737.00",
                            "currency": "TRY",
                            "id": "2-0/2",
                            "prices": [
                                {
                                    "price": "868.50",
                                    "tarih": "18.08.2026"
                                },
                                {
                                    "price": "868.50",
                                    "tarih": "19.08.2026"
                                }
                            ]
                        }
                    }
                }
            ],
            "roomFeatures": [
                {
                    "title": "Air conditioning",
                    "icon": "fa-snowflake"
                },
                {
                    "title": "Free Wi-Fi",
                    "icon": "fa-wifi"
                }
            ],
            "capacityChildren": 1
        }
    ],
    "count": 1,
    "errorMessage": null,
    "errorCode": null
}

Response · 200 (no availability)

{
    "success": false,
    "errorMessage": "Not enough adult availability.",
    "errorCode": 20001
}

Calendar availability#

GET/external/room/type/hotel/availability

Authentication: Authorization: Bearer

Returns the available room count and base rate per day for each room type. Designed for calendar and rate heat-map views; use the room list for exact prices and restriction checks.

Query parameters

hotelIDintegerrequired

Hotel ID.

startDatedatetimerequired

Start, YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS.

endDatedatetimerequired

End (inclusive).

Response

200 Daily list per room type. availability -1 means no availability data for that day; price "-" means no rate defined.

Error responses

200 hotel_id_is_not_found, start_date_is_not_found, end_date_is_not_found — missing parameter.

Request

curl "https://test.hms.gen.tr/external/room/type/hotel/availability?hotelID=1000&startDate=2026-08-18&endDate=2026-08-21" \
  -H "Authorization: Bearer $HMS_TOKEN"

const res = await fetch("https://test.hms.gen.tr/external/room/type/hotel/availability?hotelID=1000&startDate=2026-08-18&endDate=2026-08-21", {
  headers: {
    "Authorization": `Bearer ${process.env.HMS_TOKEN}`
  }
});
const data = await res.json();

$ch = curl_init('https://test.hms.gen.tr/external/room/type/hotel/availability?hotelID=1000&startDate=2026-08-18&endDate=2026-08-21');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('HMS_TOKEN'),
    ],
]);
$data = json_decode(curl_exec($ch), true);

Response · 200

{
    "success": true,
    "roomTypes": [
        {
            "name": "Standard Room",
            "id": 2,
            "rate": 2,
            "availability": [
                {
                    "id": 20260818,
                    "start": "2026-08-18 12:00:00",
                    "end": "2026-08-19 12:00:00",
                    "availability": 5,
                    "price": "965.00"
                },
                {
                    "id": 20260819,
                    "start": "2026-08-19 12:00:00",
                    "end": "2026-08-20 12:00:00",
                    "availability": 3,
                    "price": "965.00"
                },
                {
                    "id": 20260820,
                    "start": "2026-08-20 12:00:00",
                    "end": "2026-08-21 12:00:00",
                    "availability": 0,
                    "price": "1,100.00"
                },
                {
                    "id": 20260821,
                    "start": "2026-08-21 12:00:00",
                    "end": "2026-08-22 12:00:00",
                    "availability": -1,
                    "price": "-"
                }
            ]
        }
    ],
    "currency": "TRY"
}

Last updated: 8 September 2026Found a mistake? Let us know