---
title: "Booking flow"
description: "Search, quote, hold and book a Kong hotel, then modify or cancel the reservation."
url: "https://portal.konghotels.cloud/guides/booking-flow"
image: "https://portal.konghotels.cloud/_og/d/c_Ocean.takumi,title_Booking+flow,description_~U2VhcmNoLCBxdW90ZSwgaG9sZCBhbmQgYm9vayBhIEtvbmcgaG90ZWwsIHRoZW4gbW9kaWZ5IG9yIGNhbmNlbCB0aGUgcmVzZXJ2YXRpb24u,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwRTJBMUYifX19,p_Ii9ndWlkZXMvYm9va2luZy1mbG93Ig,s_oJVc6UtUUZ-aQHzv.png"
---

# Booking flow

From a search to a confirmation number in five calls, and what to do after the guest has booked.

## [Five calls from search to booking](#five-calls-from-search-to-booking)

Write operations (`POST`, `PATCH`, `DELETE`) return `403 writes-disabled` while the API is in read-only mode. Steps 1 and 2 work today against the sandbox.

1. Search across hotels

`GET /availability` returns the cheapest sellable offer per property for a `destination`, a list of `properties`, or a radius around `latitude` and `longitude`. Up to 50 properties are evaluated per call. Use it for listing and metasearch pages.

2. Price every room in one hotel

`GET /properties/{code}/availability` returns every room type and rate plan for the stay, fully priced. For flexible-date shoppers, `GET /properties/{code}/calendar` gives a rate calendar.

3. Create a quote

`POST /quotes` locks the price for **15 minutes** and returns a `quote_id`. Include loyalty details for member rates, a promotion code and any add-ons here.

4. Hold the rooms (optional)

`POST /holds` takes the rooms off sale for 15 minutes while the guest pays. Release a hold you no longer need with `DELETE /holds/{holdId}`.

5. Book

`POST /reservations` with the `quote_id` confirms the booking and returns a `confirmation_number`. This call **requires** an `Idempotency-Key` header.

## [Create a quote](#create-a-quote)

Request

```bash
curl -X POST "https://api.konghotels.cloud/quotes" \
  -H "apikey: $KONG_HOTELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "property_code": "KTNYC",
    "room_type_code": "TWRK",
    "rate_plan_code": "MBR",
    "check_in": "2026-12-04",
    "check_out": "2026-12-07",
    "adults": 2,
    "promotion_code": "KONGWEEKEND",
    "loyalty": { "member_number": "KR10000001", "last_name": "Darrow" },
    "add_ons": [{ "code": "BRKFST", "quantity": 1 }]
  }'
```

## [Book the quote](#book-the-quote)

Request

```bash
curl -X POST "https://api.konghotels.cloud/reservations" \
  -H "apikey: $KONG_HOTELS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4c1f6a52-2a8e-4f0e-9a0b-1f3d7c9e2b11" \
  -d '{
    "quote_id": "qt_01jbx4m6n2kz9v8c7d5e3f1g0h",
    "payment_model": "pay_at_hotel",
    "partner_reference": "BKG-88231001",
    "guest": {
      "first_name": "Ann",
      "last_name": "Darrow",
      "email": "ann.darrow@example.com",
      "phone": "+1 212 555 0100",
      "country_code": "US"
    },
    "additional_guests": [{ "first_name": "Jack", "last_name": "Driscoll" }],
    "special_requests": "High floor, away from the elevator.",
    "estimated_arrival_time": "18:30"
  }'
```

A successful booking returns `201` with the reservation and a `Location` header. If the rooms sold out after you quoted, you get `409 room-unavailable`. If the quote is older than 15 minutes, you get `410 quote-expired`: create a new quote and try again.

## [After the booking](#after-the-booking)

-   **Modify:** `PATCH /reservations/{confirmation_number}` changes guest details or the stay. Changing the stay re-prices it. Some rate plans don't allow changes (`422 modification-not-allowed`).
-   **Cancel:** call `GET /reservations/{confirmation_number}/cancellation-quote` first to show the guest the fee, then `POST /reservations/{confirmation_number}/cancel` with that `expected_fee`. If the fee has gone up since, you get `409 cancellation-fee-changed` instead of a surprise charge.
-   **Folio:** `GET /reservations/{confirmation_number}/folio` returns the itemised bill.
-   **Add-ons:** list, add and remove extras such as breakfast on an existing reservation.
-   **Groups:** 10 or more rooms of the same type must go through `POST /group-requests`.

## [All-in pricing](#all-in-pricing)

Every price you see is **all-in**: nightly room charges after rate-plan adjustments and discounts, plus add-ons, plus every mandatory tax and fee itemised in `pricing.taxes`. Kong Hotels never charges resort or destination fees, so the total you show is the total the guest pays.