Prebook a Room

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

POST /hotels/prebook

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"
  }'

200

{
  "status": true,
  "message": "Pre-booking completed. Option is available and ready for booking.",
  "data": {
    "unifystays_prebooking_id": "pbq1.bjNQb1Y5R2hRWEg.k6jQ3nW4cF1nL4MWvN7A9Q",
    "status": "AVAILABLE",
    "price_status": {
      "is_price_changed": true,
      "type": "INCREASE",
      "diff_amount_supplier": 1500,
      "diff_amount_converted": 1905
    },
    "provider_code": "TBO",
    "hotel_info": {
      "name": "Pride Plaza Hotel Aerocity New Delhi",
      "address": "Asset 5-A, Aerocity, Delhi, 110037",
      "check_in": "2026-05-26",
      "check_out": "2026-05-28",
      "hotel_timezone": "Asia/Kolkata"
    },
    "rooms": [
      {
        "supplier_room_name": "Deluxe Lake View Room",
        "quantity": 2,
        "meal_plan": {
          "code": "RO",
          "label": "Room Only",
          "is_breakfast_included": false
        },
        "inclusions": [
          "Free WiFi",
          "Free valet parking"
        ],
        "unifystays_room_id": "1321374576",
        "unifystays_room_name": "Deluxe King Room",
        "unifystays_room": {
          "room_id": "1321374576",
          "room_name": "Deluxe King Room",
          "description": "Spacious room with king bed and city view.",
          "room_size_value": 32,
          "room_size_unit": "sqm",
          "bed_relation": "King Bed",
          "max_adults": 2,
          "max_children": 1,
          "max_occupancy": 3,
          "bed_types": {},
          "amenities": {},
          "photos": {},
          "views": {}
        }
      }
    ],
    "pricing": {
      "supplier_breakup": {
        "currency": "GBP",
        "total_payable_now": 66227,
        "total_payable_at_property": 6000,
        "base_price": 52452,
        "breakdown": [
          {
            "category": "tax",
            "amount": 13775,
            "payable_at": "now",
            "description": "standard_tax"
          }
        ]
      },
      "converted_breakup": {
        "currency": "USD",
        "total_payable_now": 84108,
        "total_payable_at_property": 7620,
        "base_price": 66614,
        "breakdown": [
          {
            "category": "tax",
            "amount": 13775,
            "payable_at": "now",
            "description": "standard_tax"
          }
        ],
        "exchange_rate": {
          "rate": 1.2715,
          "rate_updated_at": "2026-04-14T08:41:22.000Z"
        }
      }
    },
    "cancellation": {
      "is_refundable": true,
      "policy_text": "Free cancellation until May 18, 2026. After this, a 100% penalty applies.",
      "penalties": [
        {
          "from_date": "2026-05-19T00:00:00Z",
          "to_date": "2026-05-26T00:00:00Z",
          "supplier_amount": 67727,
          "converted_amount": 86013,
          "local_time_policy": {
            "display_text": "From May 19th, 00:00 (Hotel Local Time)",
            "hotel_timezone": "Asia/Kolkata"
          }
        }
      ],
      "free_cancellation_until": "2026-05-18T23:59:59Z"
    },
    "compliance": {
      "requires_pan": true,
      "requires_id": false,
      "requires_passport": false,
      "special_instructions": "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."
    },
    "important_notes": [
      "<string>"
    ],
    "metadata": {
      "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"
      }
    }
  }
}

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

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"
  }'

Handle the Result

1. Check availability

   Continue only when data.status is AVAILABLE. When it is SOLDOUT, return the customer to live room options.

2. Check the price

   Inspect data.price_status and data.pricing. Show any new price or pricing condition to the customer before booking.

3. Keep booking inputs

   Store data.unifystays_prebooking_id, the returned rooms and their room_ref values, and any applicable compliance requirements.

4. Create the booking

   Send the prebooking ID and room-wise guest details to Create Booking.

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.

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.

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

Authorizations

x-api-key · string · header · required

Environment-specific API key created in the Unifystays portal

Headers

Body

application/json

booking_token · string · required

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"

Response

200

application/json

Universal pre-book response with availability status, price status, pricing breakup, and unifystays_prebooking_id.

status · boolean · required

Example:

true

message · string · required

Example:

"Pre-booking completed. Option is available and ready for booking."

data · object · required

Show child attributes