> For the complete documentation index, see [llms.txt](https://developer.gotadi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.gotadi.com/vietnamese/doi-tac-b2b2c/phuong-thuc-api/hotel/api/api-hotel-availability.md).

# API Hotel Availability

Endpoint: `availability`

Giá thấp nhất của 1–50 khách sạn. Giới hạn: tối đa 30 đêm, 1–8 phòng, mỗi phòng 1–8 người lớn, trẻ em 0–17 tuổi.

**Request**

| Field         | Kiểu      | Bắt buộc | Mô tả                                          |
| ------------- | --------- | -------- | ---------------------------------------------- |
| `masterIds[]` | string\[] | ✔        | 1–50 id                                        |
| `checkin`     | date      | ✔        | `yyyy-MM-dd`                                   |
| `checkout`    | date      | ✔        | Tối đa 30 đêm sau `checkin`                    |
| `rooms[]`     | array     | ✔        | 1–8 phòng, mỗi phòng `{ adults, childAges[] }` |
| `language`    | enum      |          | `vi` \| `en`                                   |

```json
{
  "masterIds": ["30715", "1002", "9999"],
  "checkin": "2026-11-20",
  "checkout": "2026-11-22",
  "rooms": [{ "adults": 2, "childAges": [6] }],
  "language": "vi"
}
```

**Response**

| Field                           | Kiểu    | Mô tả                                                                            |
| ------------------------------- | ------- | -------------------------------------------------------------------------------- |
| `checkin`, `checkout`, `nights` |         | Theo request                                                                     |
| `complete`                      | boolean | `false` = còn nguồn giá chưa trả về                                              |
| `results[].masterId`            | string  |                                                                                  |
| `results[].status`              | enum    | `AVAILABLE` \| `SOLD_OUT` \| `NOT_FOUND`                                         |
| `results[].lowestPrice`         | `Money` | `total`, `perNight`, `currency`, `taxIncluded`, `taxAndFees`, `totalBeforePromo` |
| `results[].refundable`          | boolean |                                                                                  |
| `results[].freeCancellation`    | boolean | Giá thấp nhất có huỷ miễn phí; lịch phí huỷ chi tiết lấy từ `offers`             |
| `results[].breakfastIncluded`   | boolean |                                                                                  |
| `results[].promo`               | boolean | Có khuyến mãi → `totalBeforePromo` là giá gạch ngang                             |

```json
{
  "checkin": "2026-11-20",
  "checkout": "2026-11-22",
  "nights": 2,
  "complete": true,
  "results": [
    {
      "masterId": "1002", "status": "SOLD_OUT"
    },
    {
      "masterId": "30715",
      "status": "AVAILABLE",
      "lowestPrice": {
        "total": 2400000, "perNight": 1200000, "currency": "VND",
        "taxIncluded": true, "taxAndFees": 283600, "totalBeforePromo": 2700000
      },
      "refundable": true, "freeCancellation": true, "breakfastIncluded": true, "promo": true
    },
    { "masterId": "9999", "status": "NOT_FOUND" }
  ]
}
```

{% hint style="warning" %}
**`complete: false` → polling.** Gọi lại **cùng payload** với `requestId` **mới** sau 2–3 giây, tối đa 5 lần. Khi `complete: false`, `results` chỉ gồm khách sạn đã có giá; `SOLD_OUT` và `NOT_FOUND` chỉ xuất hiện khi `complete: true` (khoảng 6 giây sau lần tìm đầu).
{% endhint %}

`results` sắp theo `masterId` **dạng chuỗi** (ví dụ `"10"` đứng trước `"9"`), không theo thứ tự gửi lên — ghép kết quả theo `masterId`.
