How do I book a room?

Overview

The booking flow is four API calls. Each step returns next_actions pointing at the next step.

POST /v1/search → POST /v1/quotes → POST /v1/holds → POST /v1/bookings

Step 1: Search availability

POST /v1/search

On success: follow next_actions[rel=quote].

Step 2: Create a quote

POST /v1/quotes

Returns quote_id, price_breakdown, policy_snapshot, and expires_at.

Errors: property_not_found (404), room_type_not_found (404), rate_plan_not_found (404).

Step 3: Hold inventory

POST /v1/holds
Headers: Idempotency-Key: <unique-key>
Body: { "quote_id": "<id>" }

Idempotent. Returns hold_id, state: "held", expires_at (default 15 min).

Errors: quote_expired (410) → requote. allocation_failed (409) → search alternatives. allotment_exhausted (409) → try different room/date.

Time pressure: Confirm before expires_at or get hold_expired on step 4.

Step 4: Confirm booking

POST /v1/bookings
Headers: Idempotency-Key: <key>, X-Delegated-User: <jwt>
Body: { hold_id, quote_id, guest: { primary: { full_name, email, phone } }, payment: { method, provider_token, billing_country } }

Idempotent. Retries return cached result including sealed errors.

Errors: hold_expired (410) → requote + rehold. payment_failed (402) → new token. delegation_required (401) → attach JWT.

Other flows

Cancel a booking

GET /v1/bookings/{id}
POST /v1/bookings/{id}/cancel  (X-Delegated-User required)

Fee computed from policy_snapshot frozen at booking time — not current policy.

Abandon and retry

POST /v1/holds/{id}/release    # returns inventory immediately
POST /v1/quotes                # quote new selection
POST /v1/holds                 # hold new selection
POST /v1/bookings              # confirm

Prove what happened

GET /v1/bookings/{id}          # current state
GET /v1/bookings/{id}/audit    # full event timeline