Bookings

Bookings are the central entity in the Booking Management System. A booking connects a guest to one or more rooms for a date range. This guide covers the complete booking lifecycle — from creation through checkout.

Booking Lifecycle

Every booking follows a well-defined lifecycle:

Status	Description
`confirmed`	Booking is created and rooms are reserved. Guest has not yet arrived.
`checked-in`	Guest has arrived and is occupying the room(s).
`checked-out`	Guest has departed. Invoice is finalized.
`cancelled`	Booking was cancelled. Rooms are released.

Creating a Booking

Step-by-Step

Select or create a guest — Search existing guests by name, email, or phone. If the guest is new, create their profile inline.
Choose dates — Pick check-in and check-out dates.
Select rooms — Browse available rooms (filtered by your selected dates) and add one or more to the booking.
Review pricing — Pricing auto-calculates based on room category rates × number of nights.
Confirm — Submit the booking.

API: Create Booking

http

POST /api/bookings
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "guestId": "guest_123",
  "checkIn": "2026-03-01",
  "checkOut": "2026-03-05",
  "rooms": ["room_101", "room_205"],
  "notes": "Late arrival expected",
  "source": "walk-in"
}

Response:

json

{
  "success": true,
  "data": {
    "bookingId": "bk_456",
    "bookingNumber": "BK-2026-0112",
    "guestId": "guest_123",
    "guestName": "Priya Mehta",
    "checkIn": "2026-03-01",
    "checkOut": "2026-03-05",
    "rooms": [
      { "roomId": "room_101", "roomNumber": "101", "category": "Deluxe" },
      { "roomId": "room_205", "roomNumber": "205", "category": "Suite" }
    ],
    "status": "confirmed",
    "totalAmount": 28000,
    "invoiceId": "inv_789",
    "createdAt": "2026-02-23T14:30:00Z"
  }
}

What Happens on Create

Key automated actions:

Availability check — The system verifies no conflicting bookings exist for the selected rooms and dates. If a conflict exists, the request returns 409 Conflict.
Invoice generation — An invoice is automatically created with line items for each room × number of nights.
Series increment — The booking number (e.g., BK-2026-0112) and invoice number are auto-incremented from the organization's series configuration.
Cache invalidation — Room availability and booking list caches are cleared.
Real-time event — All connected clients in the organization receive the booking:created event.

Room Availability

Before creating a booking, the system checks room availability. You can also query availability directly.

API: Check Availability

http

GET /api/rooms/availability?checkIn=2026-03-01&checkOut=2026-03-05
Authorization: Bearer <access_token>

Response:

json

{
  "success": true,
  "data": {
    "available": [
      { "roomId": "room_101", "roomNumber": "101", "category": "Deluxe", "price": 3500 },
      { "roomId": "room_205", "roomNumber": "205", "category": "Suite", "price": 7000 }
    ],
    "unavailable": [
      { "roomId": "room_102", "roomNumber": "102", "category": "Deluxe", "conflictingBooking": "BK-2026-0108" }
    ]
  }
}

Availability is determined by checking for any existing bookings that overlap with the requested date range:

Conflict exists if:
  existing.checkIn < requested.checkOut AND existing.checkOut > requested.checkIn

Check-In (Arrival)

When a guest arrives, mark the booking as checked in:

API: Check In

http

PATCH /api/bookings/:bookingId/checkin
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "roomId": "room_101",
  "guestIdProof": "AADHAAR-XXXX-1234",
  "arrivalTime": "2026-03-01T14:00:00Z"
}

Response:

json

{
  "success": true,
  "data": {
    "bookingId": "bk_456",
    "status": "checked-in",
    "rooms": [
      { "roomId": "room_101", "roomNumber": "101", "status": "occupied", "checkedInAt": "2026-03-01T14:00:00Z" },
      { "roomId": "room_205", "roomNumber": "205", "status": "reserved" }
    ]
  }
}

Check-In Behavior

Individual rooms within a booking can be checked in separately (e.g., guest arrives for one room, second room's guest arrives later).
The booking status changes to checked-in when the first room is checked in.
Room status changes from reserved to occupied.
A booking:checkin Socket.IO event is broadcast.

Managing Rooms During a Stay

Adding a Room

A guest might request an additional room during their stay:

http

POST /api/bookings/:bookingId/rooms
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "roomId": "room_103",
  "checkIn": "2026-03-02",
  "checkOut": "2026-03-05"
}

This:

Checks availability for the new room and dates.
Adds the room to the booking's rooms[] array.
Updates the invoice with additional line items.
Invalidates relevant caches.

Removing a Room

Remove a room before checkout (e.g., guest cancels one of multiple rooms):

http

DELETE /api/bookings/:bookingId/rooms/:roomId
Authorization: Bearer <access_token>

This:

Removes the room from the booking.
Adjusts the invoice (removes or credits the line items).
Releases the room back to available status.

WARNING

A booking must always have at least one room. If you need to remove all rooms, cancel the booking instead.

Checkout

Checkout finalizes the booking and triggers invoice settlement.

Individual Room Checkout

For bookings with multiple rooms, check out rooms individually as different guests may depart at different times:

http

PATCH /api/bookings/:bookingId/checkout/room/:roomId
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "departureTime": "2026-03-05T11:00:00Z"
}

Each room checkout:

Sets the room status to available.
Records the departure time.
Emits a booking:checkout event for that room.

Overall Checkout

When all rooms are vacated (or to check out all at once):

http

PATCH /api/bookings/:bookingId/checkout
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "departureTime": "2026-03-05T11:00:00Z"
}

Checkout Flow

At checkout:

Booking status changes to checked-out.
All associated rooms are released.
The invoice is finalized (no more line items can be added).
Outstanding balance is calculated and shown for settlement.

Cancellation

Cancel a booking that hasn't been fully checked out:

http

PATCH /api/bookings/:bookingId/cancel
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "reason": "Guest requested cancellation",
  "refundAmount": 5000
}

Cancellation Behavior

Booking status changes to cancelled.
All reserved rooms are released.
If payments were already made, a credit note is generated for the refund amount.
The invoice is marked as cancelled.
Already-checked-in rooms are force-released.

WARNING

Cancellation is irreversible. A cancelled booking cannot be reactivated. If a guest returns, create a new booking.

Guest Change

Transfer a booking to a different guest (in case of a name error or actual guest change):

http

PATCH /api/bookings/:bookingId/guest
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "newGuestId": "guest_789"
}

The booking's guestId is updated.
The linked invoice's guest reference is also updated.
An audit log entry records the change with both old and new guest IDs.

Invoices

Every booking automatically creates an invoice. The invoice contains line items for:

Room charges (rate × nights per room)
Taxes (applied based on the organization's tax configuration)
Additional charges (minibar, room service — if added manually)

The invoice updates dynamically as rooms are added/removed from the booking.

Payments

Payments are recorded against invoices:

http

POST /api/payments
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "invoiceId": "inv_789",
  "amount": 15000,
  "method": "upi",
  "reference": "UPI-TXN-123456"
}

Payment methods supported: cash, card, upi, bank_transfer, other.

Credit Notes

If an overcharge or cancellation requires a refund, credit notes are issued against the invoice. They reduce the outstanding balance without deleting payment history.

Booking Permissions

Permission	Allows
`booking:create`	Create new bookings
`booking:read`	View booking list and details
`booking:update`	Modify bookings (add/remove rooms, change guest)
`booking:checkin`	Perform check-in
`booking:checkout`	Perform checkout
`booking:cancel`	Cancel bookings
`booking:delete`	Permanently delete booking records

Permissions are assigned through roles. See the Architecture guide for details on the RBAC system.

Bookings ​

Booking Lifecycle ​

Creating a Booking ​

Step-by-Step ​

API: Create Booking ​

What Happens on Create ​

Room Availability ​

API: Check Availability ​

Check-In (Arrival) ​

API: Check In ​

Check-In Behavior ​

Managing Rooms During a Stay ​

Adding a Room ​

Removing a Room ​

Checkout ​

Individual Room Checkout ​

Overall Checkout ​

Checkout Flow ​

Cancellation ​

Cancellation Behavior ​

Guest Change ​

Related Entities ​

Invoices ​

Payments ​

Credit Notes ​

Booking Permissions ​

Bookings

Booking Lifecycle

Creating a Booking

Step-by-Step

API: Create Booking

What Happens on Create

Room Availability

API: Check Availability

Check-In (Arrival)

API: Check In

Check-In Behavior

Managing Rooms During a Stay

Adding a Room

Removing a Room

Checkout

Individual Room Checkout

Overall Checkout

Checkout Flow

Cancellation

Cancellation Behavior

Guest Change

Related Entities

Invoices

Payments

Credit Notes

Booking Permissions