Reservations & FoliosAuth: Bearer JWT + API Key

Bookings & Stay Management API

Create reservations, list guest bookings, perform digital self check-in on arrival, query extension options, and retrieve comprehensive billing folios.

POSThttps://api.thegrandeur.vip/api/v1/bookings/

Header Parameters

Authorizationstringrequired

Bearer access token obtained from /auth/login or /auth/register.

Example: Bearer eyJhbGciOiJIUzI1NiIsIn...

X-API-Keystringrequired

Your hotel live public API key.

Example: hak_live_8f3a1290...

Request Body Schema (JSON)

guest_idUUIDrequired

UUID of the authenticated guest account.

Example: usr_9a4f21b

room_type_idUUIDrequired

Target room type category being booked.

Example: rt_deluxe_ocean

check_in_datestring (YYYY-MM-DD)required

Scheduled arrival date.

Example: 2026-10-01

check_out_datestring (YYYY-MM-DD)required

Scheduled departure date.

Example: 2026-10-05

num_adultsintegeroptional

Number of adult guests. Defaults to 1.

Example: 2

pricing_modestring ('nightly' | 'hourly')optional

Whether the stay is billed nightly (standard) or hourly (day-use).

Example: nightly

special_requestsstringoptional

Notes for the front desk (e.g. high floor, late arrival).

Example: Quiet room away from elevator please.

Extending Active Stays

In-house guests can extend their stay directly from their mobile portal. Use GET /bookings/:bookingId/extend-options?max_nights=14 to preview availability and extra charges, then commit with POST /bookings/:bookingId/extend.

# 1) Create a New Booking
curl -s -X POST "https://api.thegrandeur.vip/api/v1/bookings/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-API-Key: hak_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "guest_id": "usr_9a4f21b",
    "room_type_id": "rt_deluxe_ocean",
    "check_in_date": "2026-10-01",
    "check_out_date": "2026-10-05",
    "num_adults": 2,
    "pricing_mode": "nightly"
  }'

# 2) Perform Self Check-In
curl -s -X POST "https://api.thegrandeur.vip/api/v1/bookings/check-in" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-API-Key: hak_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "booking_id": "bk_9812a" }'

# 3) Get Stay Folio (Billing details & balance)
curl -s "https://api.thegrandeur.vip/api/v1/folios/booking/bk_9812a" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-API-Key: hak_live_YOUR_KEY"

Response Preview

{
  "success_status": true,
  "message": "Booking created successfully",
  "data": {
    "id": "bk_9812a",
    "confirmation_code": "GRND-9812",
    "status": "confirmed",
    "total_amount": 1120,
    "paid_amount": 0,
    "currency": "USD",
    "check_in_date": "2026-10-01",
    "check_out_date": "2026-10-05",
    "room": {
      "room_number": "304",
      "room_type": "Deluxe Ocean View"
    }
  }
}

Rooms & Availability

Room Service & Menus