---
title: "Create Hotel Search Booking Session"
method: POST
path: "/hotel-search/booking-sessions/"
tags: ["hotel-search"]
---

# Create Hotel Search Booking Session

`POST /hotel-search/booking-sessions/`

Create or upsert a resumable hotel-search booking session.

## Request body

- HotelSearchBookingSessionCreate — Create or upsert a persisted hotel-search checkout session.
  - `hotel_id` integer, required — Hotel identifier
  - `quote_id` string, required — Selected quote identifier
  - `check_in` string, date, required — Check-in date
  - `check_out` string, date, required — Check-out date
  - `checkout_step` 'review' | 'guests' | 'membership' | 'payment' | 'processing' | 'confirmed' | 'failed', required — Current step in checkout flow
  - `status` 'active' | 'processing' | 'completed' | 'failed' | 'abandoned'
  - `is_valid` boolean — Whether the session is still valid for resume/banner display
  - `payload` object — Snapshot payload from frontend (hotel details, offer, guests, etc)
  - `booking_id` string, nullable
  - `hotel_purchase_id` string, nullable
  - `confirmation_code` string, nullable
  - `failure_reason` string, nullable
  - `replacement_for_booking_id` string, nullable — Optional imported booking ID this checkout is intended to replace.
  - `conv_trip_id` string, nullable — Optional conversational trip ID (string) carried through checkout
  - `hotel_name` string, nullable — Hotel property name for display in payment block
  - `room_type` string, nullable — Selected room type name for display in payment block
  - `price_amount` integer, nullable — Total customer price in cents for display in payment block
  - `price_currency` string, nullable — Currency code for price (e.g. USD)
  - `cancellation_policy` string, nullable — Cancellation policy text (e.g. 'Free cancellation until Apr 30')
  - `fees_at_property_amount` integer, nullable — Total mandatory fees in cents due at property (resort fee, city tax, etc.)
  - `fees_at_property_currency` string, nullable — Currency code for fees_at_property (e.g. EUR, USD). Often local currency.
  - `retail_price_amount` integer, nullable — Retail comparison price in cents (e.g. Expedia) for strikethrough display
  - `retail_price_currency` string, nullable — Currency code for retail price (e.g. USD)
  - `wake_token_hash` string, nullable — SHA-256 hex hash of the wake token this checkout originated from. Write-through attribution only — never the raw token. Absence must not block checkout.
  - `src` string, nullable — Short deeplink source slug the checkout originated from (e.g. 'wake_limited_time_flight_offer'). Write-through attribution only.

## Response `201`

Successful Response

- HotelSearchBookingSessionResponse — Persisted hotel-search checkout session.
  - `id` string, uuid, required
  - `user_id` string, uuid, required
  - `hotel_id` integer, required
  - `quote_id` string, required
  - `check_in` string, date, required
  - `check_out` string, date, required
  - `checkout_step` 'review' | 'guests' | 'membership' | 'payment' | 'processing' | 'confirmed' | 'failed', required
  - `status` 'active' | 'processing' | 'completed' | 'failed' | 'abandoned', required
  - `is_valid` boolean, required
  - `payload` object, required
  - `booking_id` string, nullable, required
  - `hotel_purchase_id` string, nullable, required
  - `confirmation_code` string, nullable, required
  - `failure_reason` string, nullable, required
  - `replacement_for_booking_id` string, nullable
  - `conv_trip_id` string, nullable
  - `hotel_name` string, nullable
  - `room_type` string, nullable
  - `price_amount` integer, nullable
  - `price_currency` string, nullable
  - `cancellation_policy` string, nullable
  - `fees_at_property_amount` integer, nullable
  - `fees_at_property_currency` string, nullable
  - `retail_price_amount` integer, nullable
  - `retail_price_currency` string, nullable
  - `guest_names` string[] — Guest names extracted from guest_rooms in payload
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `price` Money, required — Immutable money value stored as integer minor units. Amount is always stored in the smallest currency unit (cents, yen, pesos, etc). This avoids floating-point precision issues and matches payment processor standards. Examples: $19.99 USD -> Money(amount=1999, currency="USD") ¥1000 JPY -> Money(amount=1000, currency="JPY") $1000.00 CLP -> Money(amount=1000, currency="CLP") Serializes to {"amount": 1999, "currency": "USD"}. IMPORTANT: Use Money.from_decimal() for user-facing amounts like "$19.99". The constructor expects integer minor units (cents).
    - `amount` integer, required
    - `currency` string, required
  - `fees_at_property` Money, required — Immutable money value stored as integer minor units. Amount is always stored in the smallest currency unit (cents, yen, pesos, etc). This avoids floating-point precision issues and matches payment processor standards. Examples: $19.99 USD -> Money(amount=1999, currency="USD") ¥1000 JPY -> Money(amount=1000, currency="JPY") $1000.00 CLP -> Money(amount=1000, currency="CLP") Serializes to {"amount": 1999, "currency": "USD"}. IMPORTANT: Use Money.from_decimal() for user-facing amounts like "$19.99". The constructor expects integer minor units (cents).
    - `amount` integer, required
    - `currency` string, required
  - `retail_price` Money, required — Immutable money value stored as integer minor units. Amount is always stored in the smallest currency unit (cents, yen, pesos, etc). This avoids floating-point precision issues and matches payment processor standards. Examples: $19.99 USD -> Money(amount=1999, currency="USD") ¥1000 JPY -> Money(amount=1000, currency="JPY") $1000.00 CLP -> Money(amount=1000, currency="CLP") Serializes to {"amount": 1999, "currency": "USD"}. IMPORTANT: Use Money.from_decimal() for user-facing amounts like "$19.99". The constructor expects integer minor units (cents).
    - `amount` integer, required
    - `currency` string, required
  - `price_breakdown` HotelPriceBreakdown, required — Computed price breakdown for frontend display.
    - `nights` integer, required
    - `nightly_rate_cents` integer, required
    - `nightly_rate_currency` string, required
    - `subtotal_cents` integer, required
    - `fees_at_property_cents` integer, nullable
    - `fees_at_property_currency` string, nullable
    - `total_cents` integer, nullable
    - `total_currency` string, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/helloaxel/apis/client-api-gateway.md) · [All operations](https://skmtc.dev/helloaxel/apis/client-api-gateway/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/helloaxel/client-api-gateway/revisions/4f4ea4eb6a21/schema)