> ## 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.

# Prebook a Room

> Verify the selected room's current availability and price immediately before booking.

Prebook is the final supplier-backed availability and price check before
creating a booking. Send only the `booking_token` from the selected room option;
Unifystays resolves supplier-specific booking codes and prebook context
server-side.

## Request Example

<RequestExample>
  ```bash theme={null}
  curl "$UNIFYSTAYS_BASE_URL/hotels/prebook" \
    -X POST \
    -H "content-type: application/json" \
    -H "x-api-key: $UNIFYSTAYS_API_KEY" \
    -H "language: en" \
    -d '{
      "booking_token": "bq1.Y0QxTmtKc21Wbmk.3.6zI4D6fUEw2jVv7KQdM4Kw"
    }'
  ```
</RequestExample>

## Handle the Result

<Steps>
  <Step title="Check availability">
    Continue only when `data.status` is `AVAILABLE`. When it is `SOLDOUT`,
    return the customer to live room options.
  </Step>

  <Step title="Check the price">
    Inspect `data.price_status` and `data.pricing`. Show any new price or
    pricing condition to the customer before booking.
  </Step>

  <Step title="Keep booking inputs">
    Store `data.unifystays_prebooking_id`, the returned rooms and their
    `room_ref` values, and any applicable compliance requirements.
  </Step>

  <Step title="Create the booking">
    Send the prebooking ID and room-wise guest details to
    [Create Booking](/api-reference/create-booking).
  </Step>
</Steps>

The prebook response also includes hotel details, cancellation information,
important notes, and compliance requirements. Some suppliers can require
additional guest documents for particular stays or nationalities; collect and
send those details when the response and booking contract require them.

<Warning>
  Prebooking is time-sensitive. Do not defer checkout or reuse a stale
  prebooking ID. If it expires or the price/availability is no longer
  acceptable, restart from room options.
</Warning>

The OpenAPI section below provides the exact prebook request, availability and
price fields, cancellation data, compliance data, and response schema.


## OpenAPI

````yaml reference/openapi.json POST /hotels/prebook
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/prebook:
    post:
      tags:
        - Hotels
      summary: 'Pre-book: verify price & availability before booking'
      description: >-
        Accepts only `booking_token` from rooms option payload.

        The short signed token is verified server-side and resolved from
        Postgres

        quote context to recover provider code, booking code, and prebook
        context.


        This keeps provider-specific prebook requirements out of the client
        contract

        while supporting suppliers with different prebook workflows.
      operationId: HotelPreBookController_preBook
      parameters:
        - name: language
          description: Enter language code(ex. en)
          in: header
          schema: {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HotelPreBookRequestDto'
      responses:
        '200':
          description: >-
            Universal pre-book response with availability status, price status,
            pricing breakup, and unifystays_prebooking_id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelPreBookResponseDto'
        '400':
          description: Invalid request, unregistered provider, or provider API error.
        '404':
          description: Not found.
components:
  schemas:
    HotelPreBookRequestDto:
      type: object
      properties:
        booking_token:
          type: string
          description: >-
            Short signed booking token from rooms API option (`booking_token`).
            Provider routing and prebook context are resolved server-side from
            Postgres context.
          example: bq1.Y0QxTmtKc21Wbmk.3.6zI4D6fUEw2jVv7KQdM4Kw
      required:
        - booking_token
    HotelPreBookResponseDto:
      type: object
      properties:
        status:
          type: boolean
          example: true
        message:
          type: string
          example: Pre-booking completed. Option is available and ready for booking.
        data:
          $ref: '#/components/schemas/PrebookDataDto'
      required:
        - status
        - message
        - data
    PrebookDataDto:
      type: object
      properties:
        unifystays_prebooking_id:
          type: string
          example: pbq1.bjNQb1Y5R2hRWEg.k6jQ3nW4cF1nL4MWvN7A9Q
        status:
          type: string
          enum:
            - AVAILABLE
            - SOLDOUT
          example: AVAILABLE
        price_status:
          $ref: '#/components/schemas/PrebookPriceStatusDto'
        provider_code:
          type: string
          example: TBO
        hotel_info:
          $ref: '#/components/schemas/PrebookHotelInfoDto'
        rooms:
          type: array
          items:
            $ref: '#/components/schemas/PrebookRoomDto'
        pricing:
          $ref: '#/components/schemas/PricingBreakupDto'
        cancellation:
          $ref: '#/components/schemas/PrebookCancellationDto'
        compliance:
          $ref: '#/components/schemas/PrebookComplianceDto'
        important_notes:
          type: array
          items:
            type: string
        metadata:
          type: object
          additionalProperties: true
          example:
            check_in_instructions: Front desk staff will greet guests on arrival.
            search_request:
              check_in: '2026-05-26'
              check_out: '2026-05-28'
              rooms:
                - adults: 2
                  child_ages:
                    - 5
              total_rooms: 1
              total_adults: 2
              total_children: 1
              total_guests: 3
              nationality: IN
      required:
        - unifystays_prebooking_id
        - status
        - price_status
        - provider_code
        - hotel_info
        - rooms
        - pricing
        - cancellation
        - compliance
        - important_notes
    PrebookPriceStatusDto:
      type: object
      properties:
        is_price_changed:
          type: boolean
          example: true
        type:
          type: string
          enum:
            - INCREASE
            - DECREASE
            - NONE
          example: INCREASE
        diff_amount_supplier:
          type: number
          example: 1500
          description: Difference in supplier minor units (cents).
        diff_amount_converted:
          type: number
          example: 1905
          description: Difference in converted minor units (cents).
      required:
        - is_price_changed
        - type
        - diff_amount_supplier
        - diff_amount_converted
    PrebookHotelInfoDto:
      type: object
      properties:
        name:
          type: string
          example: Pride Plaza Hotel Aerocity New Delhi
        address:
          type: string
          example: Asset 5-A, Aerocity, Delhi, 110037
        check_in:
          type: string
          example: '2026-05-26'
        check_out:
          type: string
          example: '2026-05-28'
        hotel_timezone:
          type: string
          example: Asia/Kolkata
      required:
        - name
        - address
        - check_in
        - check_out
        - hotel_timezone
    PrebookRoomDto:
      type: object
      properties:
        supplier_room_name:
          type: string
          example: Deluxe Lake View Room
        quantity:
          type: number
          example: 2
        unifystays_room_id:
          type: object
          example: '1321374576'
          nullable: true
        unifystays_room_name:
          type: object
          example: Deluxe King Room
          nullable: true
        unifystays_room:
          nullable: true
          description: >-
            Complete static Unifystays room object mapped for this supplier
            room.
          allOf:
            - $ref: '#/components/schemas/PrebookMappedRoomDto'
        meal_plan:
          $ref: '#/components/schemas/PrebookMealPlanDto'
        inclusions:
          example:
            - Free WiFi
            - Free valet parking
          type: array
          items:
            type: string
      required:
        - supplier_room_name
        - quantity
        - meal_plan
        - inclusions
    PricingBreakupDto:
      type: object
      properties:
        supplier_breakup:
          $ref: '#/components/schemas/SupplierPriceBreakupDto'
        converted_breakup:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/UsdPriceBreakupDto'
      required:
        - supplier_breakup
    PrebookCancellationDto:
      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. After this, a 100% penalty
            applies.
        penalties:
          type: array
          items:
            $ref: '#/components/schemas/PrebookCancellationPenaltyDto'
      required:
        - is_refundable
        - policy_text
        - penalties
    PrebookComplianceDto:
      type: object
      properties:
        requires_pan:
          type: boolean
          example: true
          description: >-
            TripJack requires the primary guest's PAN card number (validated by
            the supplier — no other ID is accepted). Collect a PAN when true.
        requires_id:
          type: boolean
          example: false
          description: >-
            Deprecated — generic ID flag. Mirrors requires_pan today; use
            requires_pan.
        requires_passport:
          type: boolean
          example: false
        special_instructions:
          type: string
          example: >-
            A valid PAN card number is required for the primary guest. Only a
            PAN card is accepted and it is verified by the supplier — other ID
            types will not complete the booking.
      required:
        - requires_pan
        - requires_id
        - requires_passport
        - special_instructions
    PrebookMappedRoomDto:
      type: object
      properties:
        room_id:
          type: string
          example: '1321374576'
        room_name:
          type: string
          example: Deluxe King Room
        description:
          type: object
          example: Spacious room with king bed and city view.
          nullable: true
        room_size_value:
          type: object
          example: 32
          nullable: true
        room_size_unit:
          type: object
          example: sqm
          nullable: true
        bed_relation:
          type: object
          example: King Bed
          nullable: true
        max_adults:
          type: object
          example: 2
          nullable: true
        max_children:
          type: object
          example: 1
          nullable: true
        max_occupancy:
          type: object
          example: 3
          nullable: true
        bed_types:
          type: object
          additionalProperties: true
          nullable: true
        amenities:
          type: object
          additionalProperties: true
          nullable: true
        photos:
          type: object
          additionalProperties: true
          nullable: true
        views:
          type: object
          additionalProperties: true
          nullable: true
      required:
        - room_id
        - room_name
    PrebookMealPlanDto:
      type: object
      properties:
        code:
          type: string
          example: RO
        label:
          type: string
          example: Room Only
        is_breakfast_included:
          type: boolean
          example: false
      required:
        - code
        - label
        - is_breakfast_included
    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
    PrebookCancellationPenaltyDto:
      type: object
      properties:
        from_date:
          type: string
          example: '2026-05-19T00:00:00Z'
        to_date:
          type: string
          example: '2026-05-26T00:00:00Z'
        supplier_amount:
          type: number
          example: 67727
        converted_amount:
          type: number
          example: 86013
        local_time_policy:
          $ref: '#/components/schemas/PrebookCancellationLocalTimePolicyDto'
      required:
        - from_date
        - to_date
        - supplier_amount
        - converted_amount
        - 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
    PrebookCancellationLocalTimePolicyDto:
      type: object
      properties:
        display_text:
          type: string
          example: From May 19th, 00:00 (Hotel Local Time)
        hotel_timezone:
          type: string
          example: Asia/Kolkata
      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

````