Build a booking

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

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

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

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

  • 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

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.