---
title: "Start a hotel booking (asynchronous)"
method: POST
path: "/api/v1/hotels/book"
tags: ["Hotels"]
---

# Start a hotel booking (asynchronous)

`POST /api/v1/hotels/book`

Returns a `booking_job_id`, **not** a booking. A real booking takes minutes: the rate is
re-blocked at the supplier, the card charged, and the room committed. Poll
`GET /api/v1/hotels/booking/{booking_job_id}` until `status` is `succeeded` or `failed`.

This is not ceremony — it is what makes it impossible to charge a card and then lose the
confirmation to a timeout.

The 5% reservation fee is charged BEFORE the room is committed, so a declined card costs
nothing: no reservation exists and nothing is charged.

Send `expected_price` and `expected_balance` back exactly as search returned them. The
booking is refused if the supplier's price has moved, so a guest is never charged a price
they did not agree to.

NOT idempotent. Calling twice for the same rate books the room twice and charges two fees.

## Request body

- object
  - `session_id` string, required
  - `hotel_code` integer, required
  - `combination_id_v2` string, required — Identifies the exact rate. Room name alone is ambiguous.
  - `combination_id` integer
  - `expected_price` number, required — The offer's `price`, verbatim.
  - `expected_balance` number, required — The offer's `balance_to_supplier`, verbatim.
  - `hotel_name` string
  - `city_id` integer, required
  - `city_name` string, required
  - `check_in` string, date, required
  - `check_out` string, date, required
  - `adults` integer
  - `guests` object[], required
    - `title` string, required
    - `first_name` string, required
    - `last_name` string, required
  - `email` string, required — The voucher and pay link go here. A typo loses the booking.
  - `phone` string, required
  - `phone_country_code` string
  - `special_requests` string[]

## Response `202`

Booking started — poll the returned booking_job_id

## Other responses

- `402` — No payment method on file
- `409` — The chosen rate is gone

---

[API](https://skmtc.dev/letsfg/apis/letsfg-api.md) · [All operations](https://skmtc.dev/letsfg/apis/letsfg-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/letsfg/letsfg-api/revisions/89a6a1405650/schema)