> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uknvas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hotels

> Search, quote, book and cancel hotel stays, charged to your wallet.

Inventory from GTW's hotel supplier. Prices include GTW's margin
and are charged to your **NGN wallet** by default (or USD if you ask), at
GTW's exchange rate, locked when you quote.

| Method | Path (API key) | Scope |
| - | - | - |
| GET | `/hotels/cities?countryCode=NG&q=` | `hotels:read` |
| GET | `/hotels?cityId=… \| countryCode=… \| hotelIds=a,b&pageIndex&pageSize&resultTag&includeImages` | `hotels:read` |
| GET | `/hotels/:hotelId/rooms` | `hotels:read` |
| POST | `/hotels/search` — `hotelId, checkInDate, checkOutDate, rooms, adults, children, childrenAges?, nationality, currency?` | `hotels:read` |
| POST | `/hotels/quote` — the search fields + `roomTypeId, productCode` | `hotels:book` |
| POST | `/hotels/bookings` — `quoteId, guests[], contact?, noteToHotel?, customerReference?, hotelName?` + **`Idempotency-Key`** | `hotels:book` |
| GET | `/hotels/bookings?status&customerReference&limit`, `/hotels/bookings/:id` | `hotels:read` |
| POST | `/hotels/bookings/:id/cancel` — `reason?` | `hotels:book` |

The same routes exist for the dashboard under
`/organizations/:orgId/hotels/…` (roles with `bookings:read` / `bookings:create`).

**Flow.** `search` returns room products with an indicative price (`total` for the stay, `nightly` per room per night).
`quote` re-checks the live rate with the supplier and returns a firm
`price` and `quoteId`, valid for 15 minutes. `bookings` charges exactly the
quoted amount — you never send a price — then places the order.

* `201` `BOOK_SUCCESS`: confirmed (`hotelConfirmCode` when the hotel issues one).
* `202` `BOOKING` / `RETRY_PENDING`: still being confirmed; poll the booking.
* `202` `BOOK_FAIL`: not booked; `refunded` is the full price, already back
  in your wallet. `failureReason` is `rejected_by_hotel`, or
  `supplier_unavailable` when the problem is on GTW's side (tell your user to
  try again later).
* `402 insufficient_funds` / `credit_limit_exceeded` / `invoice_overdue`:
  nothing was booked. Top up and retry **with the same Idempotency-Key**.
* `409 price_changed`: the rate moved after the quote. Nothing was charged; quote again.
* `409 quote_used`, `410 quote_expired`.

Retrying a booking request with the same `Idempotency-Key` never books or
charges twice. Use `customerReference` for your own traveller or staff id.

**Cancellation.** Allowed for `BOOK_SUCCESS`, `BOOKING`, `RETRY_PENDING`. If
the supplier's answer is lost the booking shows `CANCELING` and settles on its
own; poll it. `409 booking_busy` means another update is in progress: retry.
On `CANCEL_SUCCESS` you are refunded your price minus the supplier's
cancellation penalty, in proportion (see the booking's `refundRules`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.