> 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/english/b2b2c-partner/api-method/hotel-1/api/api-hotel-availability.md).

# API Hotel Availability

Endpoint: `availability`

Lowest price across 1–50 hotels. Limits: max 30 nights, 1–8 rooms, 1–8 adults per room, children aged 0–17.

**Request**

| Field         | Type      | Required | Description                               |
| ------------- | --------- | -------- | ----------------------------------------- |
| `masterIds[]` | string\[] | ✔        | 1–50 ids                                  |
| `checkin`     | date      | ✔        | `yyyy-MM-dd`                              |
| `checkout`    | date      | ✔        | At most 30 nights after `checkin`         |
| `rooms[]`     | array     | ✔        | 1–8 rooms, each `{ 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": "en"
}
```

**Response**

| Field                           | Type    | Description                                                                             |
| ------------------------------- | ------- | --------------------------------------------------------------------------------------- |
| `checkin`, `checkout`, `nights` |         | Echoed from the request                                                                 |
| `complete`                      | boolean | `false` = some price sources have not answered yet                                      |
| `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 | The lowest rate is free-cancellation; the detailed penalty schedule comes from `offers` |
| `results[].breakfastIncluded`   | boolean |                                                                                         |
| `results[].promo`               | boolean | Promotion applied → `totalBeforePromo` is the strikethrough price                       |

```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` → poll.** Re-send the **same payload** with a **new** `requestId` after 2–3 seconds, up to 5 times. While `complete: false`, `results` contains only hotels that already have a price; `SOLD_OUT` and `NOT_FOUND` appear only once `complete: true` (roughly 6 seconds after the first search).
{% endhint %}

`results` is sorted by `masterId` **as a string** (e.g. `"10"` precedes `"9"`), not in request order — join results by `masterId`.
