> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unifystays.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Room Options

> Start live supplier room retrieval for a selected hotel and receive bookable options with booking tokens.

Call this endpoint after the customer selects a hotel. Send the same dates,
occupancy, and nationality used for hotel search. Unifystays calls the active
suppliers in parallel and normalizes their room options.

## Request Example

<RequestExample>
  ```bash theme={null}
  curl "$UNIFYSTAYS_BASE_URL/hotels/123456/rooms" \
    -X POST \
    -H "content-type: application/json" \
    -H "x-api-key: $UNIFYSTAYS_API_KEY" \
    -H "language: en" \
    -d '{
      "check_in": "2026-09-12",
      "check_out": "2026-09-15",
      "nationality": "IN",
      "rooms": [
        {
          "adults": 2,
          "child_ages": []
        }
      ]
    }'
  ```
</RequestExample>

## Use the Response

The response contains the static room catalogue, supplier options, and a
`stream_id` with `sse_stream_url` for progressive provider results. Every
bookable option includes a short signed `booking_token` required by
[Prebook a Room](/api-reference/prebook).

* An option can have `our_room: null` and still be bookable.
* Keep the selected option's `booking_token` only for the immediate prebook
  step; it is time-sensitive.
* Use the room stream when your product needs to render options as providers
  return them. See [Stream Room Updates](/api-reference/hotel-room-stream).
* Request fresh room options if the stay dates, guest mix, nationality, or
  selected hotel changes.

<Warning>
  Do not cache room options or reuse their booking tokens as a checkout
  guarantee. Supplier-backed availability and price can change.
</Warning>

The OpenAPI section below provides the complete request body and response
fields, including room options and stream identifiers.


## OpenAPI

````yaml reference/openapi.json POST /hotels/{hotel_id}/rooms
openapi: 3.0.0
info:
  title: Unifystays API
  description: >-
    One unified hotel API across suppliers. Integrate once, then enable and
    manage suppliers from the Unifystays portal.
  version: '1.0'
  contact: {}
servers:
  - url: https://api-sandbox.unifystays.com
    description: Sandbox
  - url: https://api.unifystays.com
    description: Production
security:
  - x-api-key: []
tags: []
paths:
  /hotels/{hotel_id}/rooms:
    post:
      tags:
        - Hotel Rooms
      summary: Get all room options for a hotel
      description: >-
        Calls every active provider in parallel using their mapped hotel ID.

        Each provider option is matched against our room catalogue via name
        similarity.

        Returns a flat options list (no meal-plan grouping).

        Unmapped options (our_room: null) are still included.

        Each option includes a short signed `booking_token` required by

        `POST /hotels/prebook`.
      operationId: HotelRoomsController_getRooms
      parameters:
        - name: hotel_id
          required: true
          in: path
          description: Internal hotel ID (bigint as string)
          schema:
            type: string
            example: '123456'
        - name: language
          description: Enter language code(ex. en)
          in: header
          schema: {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HotelRoomsRequestDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelRoomsResponseDto'
        '400':
          description: Invalid request parameters
        '404':
          description: Hotel not found
components:
  schemas:
    HotelRoomsRequestDto:
      type: object
      properties:
        check_in:
          type: string
          description: Check-in date in YYYY-MM-DD format. Must be today or a future date.
          example: '2026-07-01'
        check_out:
          type: string
          description: Check-out date in YYYY-MM-DD format. Must be after check_in.
          example: '2026-07-04'
        nationality:
          type: string
          description: >-
            Guest nationality — ISO alpha-2 code (e.g. IN, AE, US). Defaults to
            IN.
          example: IN
          default: IN
        rooms:
          description: >-
            Room configurations — 1 to 5 rooms. Each room specifies adults and
            optional child ages.
          minItems: 1
          maxItems: 5
          example:
            - adults: 2
              child_ages: []
          type: array
          items:
            $ref: '#/components/schemas/RoomConfigDto'
      required:
        - check_in
        - check_out
        - rooms
    HotelRoomsResponseDto:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Rooms fetched successfully
        data:
          $ref: '#/components/schemas/HotelRoomsDataDto'
      required:
        - success
        - message
        - data
    RoomConfigDto:
      type: object
      properties:
        adults:
          type: number
          description: Number of adults in this room (min 1, max 5)
          example: 2
          minimum: 1
          maximum: 5
        child_ages:
          description: >-
            Age of each child in this room (0–17). Total occupants (adults +
            children) must not exceed 5.
          example:
            - 5
            - 8
          type: array
          items:
            type: number
      required:
        - adults
    HotelRoomsDataDto:
      type: object
      properties:
        hotel_id:
          type: string
          example: '123456'
        hotel_name:
          type: string
          example: The Taj Mahal Palace
        check_in:
          type: string
          example: '2026-07-01'
        check_out:
          type: string
          example: '2026-07-04'
        nights:
          type: number
          example: 3
        total_options:
          type: number
          example: 2
          description: Total options returned across all providers
        providers_queried:
          example:
            - TBO
            - TRIPJACK
          type: array
          items:
            type: string
        unifystays_rooms:
          description: Full static room catalogue from our DB for this hotel.
          type: array
          items:
            $ref: '#/components/schemas/MappedRoomDto'
        stream_id:
          type: string
          example: stream_8f4b9d1f6d9e
          description: Unique stream id for provider room streaming.
        sse_stream_url:
          type: string
          example: /hotels/123456/rooms/stream/stream_8f4b9d1f6d9e
          description: SSE URL to consume provider room options as they arrive.
        options:
          description: Flat list of room options from all providers.
          type: array
          items:
            $ref: '#/components/schemas/RoomOptionDto'
      required:
        - hotel_id
        - hotel_name
        - check_in
        - check_out
        - nights
        - total_options
        - providers_queried
        - unifystays_rooms
        - stream_id
        - sse_stream_url
        - options
    MappedRoomDto:
      type: object
      properties:
        room_id:
          type: string
          example: '1001'
        room_name:
          type: string
          example: Deluxe King Room
        description:
          type: object
          example: Spacious room with king bed and city view.
        room_size_value:
          type: object
          example: 32
        room_size_unit:
          type: object
          example: sqm
        bed_relation:
          type: object
          example: King Bed
        max_adults:
          type: object
          example: 2
        max_children:
          type: object
          example: 1
        max_occupancy:
          type: object
          example: 3
        bed_types:
          type: object
        amenities:
          type: object
        photos:
          type: object
        views:
          type: object
      required:
        - room_id
        - room_name
    RoomOptionDto:
      type: object
      properties:
        provider_code:
          type: string
          example: TBO
          description: Provider that returned this option
        booking_token:
          type: string
          example: bq1.Y0QxTmtKc21Wbmk.3.6zI4D6fUEw2jVv7KQdM4Kw
          description: Short signed token required by /hotels/prebook.
        rooms:
          description: >-
            One entry per room slot requested. Each contains the provider room
            name and matched Unifystays room.
          type: array
          items:
            $ref: '#/components/schemas/RoomDetailDto'
        pricing:
          description: Supplier-native and USD-converted cents-based pricing breakup.
          allOf:
            - $ref: '#/components/schemas/PricingBreakupDto'
        metadata:
          type: object
          additionalProperties: true
          description: Provider-specific pricing metadata sandbox.
          example:
            extra_guest_charge: 0
            recommended_selling_rate: 140
        meal_plan:
          description: Normalized Unifystays meal plan mapped from supplier meal basis.
          allOf:
            - $ref: '#/components/schemas/MealPlanDto'
        compliance:
          description: Provider compliance requirements. Defaults to no requirements.
          allOf:
            - $ref: '#/components/schemas/RoomOptionComplianceDto'
        cancellation:
          $ref: '#/components/schemas/CancellationDto'
        inclusion:
          type: object
          example: Free WiFi
          nullable: true
        tags:
          example:
            - Free Cancellation
            - Breakfast Included
          type: array
          items:
            type: string
        promotions:
          example:
            - Private sale
          type: array
          items:
            type: string
      required:
        - provider_code
        - booking_token
        - rooms
        - pricing
        - meal_plan
        - compliance
        - cancellation
        - tags
        - promotions
    RoomDetailDto:
      type: object
      properties:
        provider_room_name:
          type: string
          example: Luxury Room, 1 King Bed
          description: Raw room name from supplier
        unifystays_room_id:
          type: object
          description: Matched Unifystays room id from static_rooms (null if not mapped).
          example: '1001'
          nullable: true
      required:
        - provider_room_name
    PricingBreakupDto:
      type: object
      properties:
        supplier_breakup:
          $ref: '#/components/schemas/SupplierPriceBreakupDto'
        converted_breakup:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/UsdPriceBreakupDto'
      required:
        - supplier_breakup
    MealPlanDto:
      type: object
      properties:
        code:
          type: string
          example: BB
        label:
          type: string
          example: Bed & Breakfast
        is_breakfast_included:
          type: boolean
          example: true
      required:
        - code
        - label
        - is_breakfast_included
    RoomOptionComplianceDto:
      type: object
      properties:
        requires_passport:
          type: boolean
          example: true
        special_requirements:
          type: array
          items:
            $ref: '#/components/schemas/ComplianceRequirementDto'
      required:
        - requires_passport
        - special_requirements
    CancellationDto:
      type: object
      properties:
        is_refundable:
          type: boolean
          example: true
        free_cancellation_until:
          type: object
          example: '2026-05-18T23:59:59Z'
          nullable: true
        policy_text:
          type: string
          example: >-
            Free cancellation until May 18, 2026, hotel local time. After this
            date, a 100% penalty applies.
        penalties:
          type: array
          items:
            $ref: '#/components/schemas/CancellationPenaltyDto'
      required:
        - is_refundable
        - policy_text
        - penalties
    SupplierPriceBreakupDto:
      type: object
      properties:
        currency:
          type: string
          example: GBP
        total_payable_now:
          type: number
          example: 66227
          description: Amount in minor units (cents).
        total_payable_at_property:
          type: number
          example: 6000
          description: Amount in minor units (cents).
        base_price:
          type: number
          example: 52452
          description: Amount in minor units (cents).
        breakdown:
          type: array
          items:
            $ref: '#/components/schemas/PriceBreakupItemDto'
      required:
        - currency
        - total_payable_now
        - total_payable_at_property
        - base_price
        - breakdown
    UsdPriceBreakupDto:
      type: object
      properties:
        currency:
          type: string
          example: USD
        total_payable_now:
          type: number
          example: 84108
          description: Amount in minor units (cents).
        total_payable_at_property:
          type: number
          example: 7620
          description: Amount in minor units (cents).
        base_price:
          type: number
          example: 66614
          description: Amount in minor units (cents).
        breakdown:
          type: array
          items:
            $ref: '#/components/schemas/PriceBreakupItemDto'
        exchange_rate:
          $ref: '#/components/schemas/UsdExchangeRateDto'
      required:
        - currency
        - total_payable_now
        - total_payable_at_property
        - base_price
        - breakdown
        - exchange_rate
    ComplianceRequirementDto:
      type: object
      properties:
        type:
          type: string
          example: LOCAL_ID
        description:
          type: string
          example: PAN Card or Aadhaar required for Indian Nationals
        applies_to:
          type: object
          example: IN
          nullable: true
      required:
        - type
        - description
    CancellationPenaltyDto:
      type: object
      properties:
        from_date:
          type: string
          example: '2026-02-10T19:07:00Z'
        to_date:
          type: string
          example: '2026-05-18T23:59:59Z'
        supplier_currency:
          type: string
          example: GBP
        supplier_amount:
          type: number
          example: 0
        converted_currency:
          type: string
          example: USD
        converted_amount:
          type: number
          example: 0
        description:
          type: string
          example: Free Cancellation Window
        local_time_policy:
          $ref: '#/components/schemas/CancellationLocalTimePolicyDto'
      required:
        - from_date
        - to_date
        - supplier_currency
        - supplier_amount
        - converted_currency
        - converted_amount
        - description
        - local_time_policy
    PriceBreakupItemDto:
      type: object
      properties:
        category:
          type: string
          example: tax
        amount:
          type: number
          example: 13775
          description: Amount in minor units (cents).
        payable_at:
          type: string
          example: now
          enum:
            - now
            - property
        description:
          type: string
          example: standard_tax
      required:
        - category
        - amount
        - payable_at
        - description
    UsdExchangeRateDto:
      type: object
      properties:
        rate:
          type: number
          example: 1.2715
        rate_updated_at:
          type: object
          example: '2026-04-14T08:41:22.000Z'
          nullable: true
      required:
        - rate
    CancellationLocalTimePolicyDto:
      type: object
      properties:
        display_text:
          type: string
          example: Free until May 18th (Hotel Local Time)
        hotel_timezone:
          type: string
          example: Europe/London
      required:
        - display_text
        - hotel_timezone
  securitySchemes:
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key
      description: Environment-specific API key created in the Unifystays portal

````