Kong Hotels Partner API

The Kong Hotels Partner API gives online travel agencies, metasearch engines, wholesalers and
corporate booking tools direct access to every Kong hotel: descriptive content, live availability
and rates, guaranteed quotes, inventory holds, reservations, and the change feed and webhooks
you need to keep your copy of our data fresh.

Brands

Brand	Segment	What to expect
Kong Summit	Luxury	Flagship hotels with butler service and destination dining.
Kong Tower	Upper upscale	High-rise city hotels with Club Lounge rooms.
Kong Lagoon	Resort	Beachfront villas with half-board and activity add-ons.
Kong Canopy	Boutique	Nature-forward hideaways and treehouse lofts.
Kong Basecamp	Select service	Smart, social city hotels with bunk rooms for groups.

Authentication & partner identity

Authentication, API keys and quotas per contract are enforced by Kong Gateway in front of this
service. After authenticating you, the gateway forwards your consumer identity to us in
X-Consumer-Custom-ID, X-Consumer-ID or X-Consumer-Username (first non-empty wins).

That identity is your partner ID. Quotes, holds, reservations, group requests and webhooks are
private to the partner that created them; requests for another partner’s resources return 404.

Local development: call the service directly and send X-Consumer-ID: your-partner-id yourself.
Requests without a consumer header are treated as the anonymous partner. In production the service
must only be reachable through the gateway.

Read-only mode

The API currently runs in read-only mode. Every GET endpoint is live; every POST, PATCH and
DELETE returns 403 with problem type writes-disabled. Operations marked Write below are fully
implemented and documented so you can build against them now; they will be switched on in a later
phase (KONG_WRITES_ENABLED=true).

Seeded demo reservations belonging to the partner demo-partner let you exercise the reservation,
folio and cancellation-quote endpoints while writes are off.

Booking flow

Step	Call	What it does
1. Search	GET /availability	Which properties have rooms, with the cheapest offer at each.
2. Price	GET /properties/{code}/availability	Every room type × rate plan for the stay, fully priced.
3. Quote	POST /quotes	Locks the price for 15 minutes and returns a quote_id.
4. Hold (optional)	POST /holds	Takes the rooms off sale for 15 minutes while the guest pays.
5. Book	POST /reservations	Confirms the booking and returns a confirmation_number. Requires an Idempotency-Key header.

After booking:

Task	Call
Look up the reservation	GET /reservations/{confirmation_number}
Change guest details or the stay (re-priced)	PATCH /reservations/{confirmation_number}
Check the cancellation fee	GET /reservations/{confirmation_number}/cancellation-quote
Cancel	POST /reservations/{confirmation_number}/cancel

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.

Money, dates & times

• Amounts are decimal strings with two decimal places ("389.00") in the property’s local
  currency (ISO 4217). Never parse them as floats.
• Stay dates are YYYY-MM-DD in the property’s local calendar. check_out is the departure date.
• Timestamps are ISO 8601. Cancellation deadlines carry the property’s UTC offset.

Idempotency

POST /reservations requires an Idempotency-Key header (we recommend a UUID v4). Other POST
operations accept one optionally. The first response for a key is stored for 24 hours; retrying with the
same key and body replays it with Idempotent-Replayed: true. Reusing a key with a different body
returns 422 idempotency-key-reused; retrying while the first request is still running returns
409 idempotency-request-in-progress. 5xx responses are not stored, so you can retry them safely.

Rate limits

Limits apply per partner (or per client IP for anonymous requests) per minute, in three buckets:

Bucket	Default	Endpoints
read	300/min	Content, reservations, feeds — every GET except the ones below
search	120/min	/availability, /properties/{code}/availability, /properties/{code}/calendar
write	60/min	Every POST, PATCH, DELETE

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. When you exceed a limit you get
429 rate-limited with Retry-After (seconds). Contracted quotas enforced at the gateway are separate.

Errors

Errors use RFC 9457 problem details with
Content-Type: application/problem+json. Switch on type, not on title or detail:

type suffix	Status	Meaning
validation-failed	422	Field errors in errors (field → messages).
booking-rule-violation	422	Valid input that breaks a rule, e.g. minimum stay or occupancy. restrictions may list codes.
membership-required	422	Member-only rate requested without verified loyalty details.
loyalty-verification-failed	422	Member number and last name don’t match.
promotion-invalid / promotion-ineligible	422	Unknown code, or not applicable (reasons).
modification-not-allowed	422	The rate plan doesn’t permit stay changes.
idempotency-key-reused	422	Same key, different request body.
idempotency-key-required	400	POST /reservations without Idempotency-Key.
writes-disabled	403	The API is in read-only mode.
not-found	404	Unknown resource, or one that belongs to another partner.
room-unavailable	409	Inventory is gone. available_units shows what’s left.
invalid-state	409	E.g. cancelling a cancelled reservation, re-booking a used quote.
cancellation-fee-changed	409	The fee rose above your expected_fee.
idempotency-request-in-progress	409	Retry after Retry-After seconds.
quote-expired	410	Request a new quote.
rate-limited	429	See Retry-After.
internal-error	500	Unexpected server error. request_id identifies the failed request.

Every response, success or error, includes X-Request-ID. We reuse the gateway’s Kong-Request-ID or
your own X-Request-ID when present.

Pagination

List endpoints use cursor pagination: follow links.next (or pass meta.next_cursor as cursor)
until it is null. per_page sets the page size. The change feed uses its own since/next_cursor
sequence (see Change Feed).

Staying in sync

Don’t re-crawl everything. Poll GET /changes?since={next_cursor} every minute or two, or subscribe to
webhooks, and refetch only what changed:

• availability.changed / rates.changed → refresh that room type’s dates.
• property.updated → refetch /properties/{code}.
• reservation.* → your own bookings changed (including changes made at the property).

Verifying webhook signatures

Each delivery is a POST of the same event envelope used by /changes, with these headers:

• Kong-Event: the event type
• Kong-Delivery: a unique delivery ID (use it to de-duplicate)
• Kong-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256>

Compute HMAC_SHA256(secret, "<t>.<raw request body>") and compare it to v1 in constant time. Reject
deliveries where t is more than 5 minutes old. Respond with any 2xx within 10 seconds. Failed
deliveries are retried with backoff (30s, 2m, 10m, 30m, 1h) before being marked failed.

[$t, $v1] = sscanf($_SERVER['HTTP_KONG_SIGNATURE'], 't=%d,v1=%s');
$valid = hash_equals(hash_hmac('sha256', $t.'.'.file_get_contents('php://input'), $secret), $v1)
    && abs(time() - $t) < 300;

Test data

What	Values
Properties	KTNYC, KBBRK, KCSFO, KSLON, KBLON, KTPAR, KTTYO, KBTYO, KLDPS, KLSYD, KTSYD, KCMTV
Kong Rewards members	KR10000001 Darrow (silverback), KR10000002 Driscoll (gold), KR10000003 Denham (silver), KR10000004 Raman (member)
Promotions	KONGWEEKEND (12%, 2+ nights), EARLYAPE (15%, stays 60+ days out, city hotels), BANANA25 (25%, Lagoon, 4+ nights, private), MAYFAIR100 (£100 off KSLON), SKULLISLAND (expired)
Demo reservations	KH4DEMO01 … KH4DEMO06 for partner demo-partner (KH4DEMO05 is checked out and can be reviewed)
Change feed	About two weeks of history: nightly rates.changed pushes, daytime availability.changed, a few property.updated, promotion.published and review.published, plus the lifecycle of the demo reservations (visible to demo-partner only)
Webhooks	demo-partner has three subscriptions: bookings, availability & rates for NYC and London (with retries and three failed deliveries from a partner-side outage), and a paused staging listener

Inventory is seeded for 365 days ahead with realistic seasonality, weekday pricing and occasional
sell-outs, so some dates are deliberately unavailable.