Booking Management

Appearance

Bookings API ​

Full booking lifecycle — creation, availability checks, room management, check-in, checkout, and cancellation.

Authentication

All booking endpoints require a valid PASETO token:

http
Authorization: Bearer <token>

Endpoints ​

MethodPathDescription
POST/api/bookings/:orgId/createCreate a new booking
GET/api/bookings/:orgId/listList bookings (paginated)
GET/api/bookings/:orgId/overviewBooking overview / dashboard stats
GET/api/bookings/:orgId/by-code/:codeGet booking by code
POST/api/bookings/:orgId/check-availabilityCheck room availability
GET/api/bookings/:orgId/:bookingIdGet booking by ID
PUT/api/bookings/:orgId/:bookingId/stayUpdate stay details
PUT/api/bookings/:orgId/:bookingId/arrivalUpdate arrival details
POST/api/bookings/:orgId/:bookingId/add-roomAdd room to booking
POST/api/bookings/:orgId/:bookingId/checkout-roomsCheckout specific rooms
PUT/api/bookings/:orgId/:bookingId/update-guestUpdate guest information
PUT/api/bookings/:orgId/:bookingId/checkoutFull checkout
POST/api/bookings/:orgId/:bookingId/arrivalRecord guest arrival
PUT/api/bookings/:orgId/:bookingId/cancelCancel booking
PUT/api/bookings/:orgId/:bookingId/change-guestChange primary guest

Common Path Parameters ​

ParameterTypeDescription
orgIdstringOrganisation ID
bookingIdstringBooking document ID
codestringHuman-readable booking code (e.g. BK-0042)

POST /api/bookings/:orgId/create ​

Create a new booking.

Request Body ​

json
{
  "guestId": "guest_abc123",
  "guestName": "Jane Smith",
  "guestEmail": "jane@example.com",
  "guestPhone": "+919876543210",
  "checkIn": "2026-03-15",
  "checkOut": "2026-03-18",
  "rooms": [
    {
      "roomId": "room_101",
      "roomNumber": "101",
      "roomType": "Deluxe",
      "ratePerNight": 3500,
      "adults": 2,
      "children": 1
    }
  ],
  "source": "walk-in",
  "notes": "Early check-in requested",
  "specialRequests": "Extra pillows",
  "mealPlan": "CP",
  "totalAmount": 10500,
  "advanceAmount": 3000,
  "paymentMethod": "cash"
}
FieldTypeRequiredDescription
guestIdstringNoExisting guest ID (omit to create new)
guestNamestringYesGuest full name
guestEmailstringNoGuest email
guestPhonestringYesGuest phone number
checkInstringYesCheck-in date (YYYY-MM-DD)
checkOutstringYesCheck-out date (YYYY-MM-DD)
roomsarrayYesArray of room objects
rooms[].roomIdstringYesRoom ID
rooms[].roomNumberstringYesDisplay room number
rooms[].roomTypestringYesRoom type / category
rooms[].ratePerNightnumberYesNightly rate
rooms[].adultsnumberYesNumber of adults
rooms[].childrennumberNoNumber of children
sourcestringNoBooking source (walk-in, phone, online, ota)
notesstringNoInternal notes
specialRequestsstringNoGuest special requests
mealPlanstringNoMeal plan code (EP, CP, MAP, AP)
totalAmountnumberNoTotal booking amount
advanceAmountnumberNoAdvance payment received
paymentMethodstringNoPayment method for advance

Response — 201 Created ​

json
{
  "success": true,
  "message": "Booking created successfully",
  "data": {
    "bookingId": "bk_xyz789",
    "code": "BK-0042",
    "status": "confirmed",
    "guestName": "Jane Smith",
    "checkIn": "2026-03-15",
    "checkOut": "2026-03-18",
    "rooms": [
      {
        "roomId": "room_101",
        "roomNumber": "101",
        "roomType": "Deluxe",
        "ratePerNight": 3500
      }
    ],
    "totalAmount": 10500,
    "createdAt": "2026-02-23T10:30:00.000Z"
  }
}

Error — 400 Bad Request ​

json
{
  "success": false,
  "message": "Validation failed: checkIn must be before checkOut"
}

GET /api/bookings/:orgId/list ​

List bookings with pagination and optional filters.

Query Parameters ​

ParameterTypeDefaultDescription
pagenumber1Page number
limitnumber20Items per page
statusstring—Filter by status (confirmed, checked-in, checked-out, cancelled)
fromstring—Filter check-in from date (YYYY-MM-DD)
tostring—Filter check-in to date (YYYY-MM-DD)
searchstring—Search by guest name, code, or phone

Response — 200 OK ​

json
{
  "success": true,
  "data": [
    {
      "bookingId": "bk_xyz789",
      "code": "BK-0042",
      "guestName": "Jane Smith",
      "checkIn": "2026-03-15",
      "checkOut": "2026-03-18",
      "status": "confirmed",
      "rooms": ["101"],
      "totalAmount": 10500
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 87,
    "totalPages": 5
  }
}

GET /api/bookings/:orgId/overview ​

Get booking summary statistics for the dashboard.

Response — 200 OK ​

json
{
  "success": true,
  "data": {
    "today": {
      "arrivals": 5,
      "departures": 3,
      "stayovers": 12,
      "available": 8
    },
    "occupancy": {
      "occupied": 20,
      "total": 28,
      "percentage": 71.4
    },
    "revenue": {
      "today": 45000,
      "month": 1250000
    }
  }
}

GET /api/bookings/:orgId/by-code/:code ​

Retrieve a booking using its human-readable code.

Path Parameters ​

ParameterTypeDescription
codestringBooking code (e.g. BK-0042)

Response — 200 OK ​

json
{
  "success": true,
  "data": {
    "bookingId": "bk_xyz789",
    "code": "BK-0042",
    "guestName": "Jane Smith",
    "guestEmail": "jane@example.com",
    "guestPhone": "+919876543210",
    "checkIn": "2026-03-15",
    "checkOut": "2026-03-18",
    "status": "confirmed",
    "rooms": [
      {
        "roomId": "room_101",
        "roomNumber": "101",
        "roomType": "Deluxe",
        "ratePerNight": 3500,
        "adults": 2,
        "children": 1
      }
    ],
    "totalAmount": 10500,
    "advanceAmount": 3000,
    "balanceDue": 7500,
    "source": "walk-in",
    "notes": "Early check-in requested",
    "createdAt": "2026-02-23T10:30:00.000Z"
  }
}

Error — 404 Not Found ​

json
{
  "success": false,
  "message": "Booking not found"
}

POST /api/bookings/:orgId/check-availability ​

Check room availability for a given date range.

Request Body ​

json
{
  "checkIn": "2026-03-15",
  "checkOut": "2026-03-18",
  "roomType": "Deluxe"
}
FieldTypeRequiredDescription
checkInstringYesStart date (YYYY-MM-DD)
checkOutstringYesEnd date (YYYY-MM-DD)
roomTypestringNoFilter by room type

Response — 200 OK ​

json
{
  "success": true,
  "data": {
    "available": true,
    "rooms": [
      {
        "roomId": "room_101",
        "roomNumber": "101",
        "roomType": "Deluxe",
        "ratePerNight": 3500,
        "status": "available"
      },
      {
        "roomId": "room_102",
        "roomNumber": "102",
        "roomType": "Deluxe",
        "ratePerNight": 3500,
        "status": "available"
      }
    ]
  }
}

GET /api/bookings/:orgId/:bookingId ​

Retrieve full booking details by ID.

Response — 200 OK ​

json
{
  "success": true,
  "data": {
    "bookingId": "bk_xyz789",
    "code": "BK-0042",
    "guestName": "Jane Smith",
    "guestEmail": "jane@example.com",
    "guestPhone": "+919876543210",
    "checkIn": "2026-03-15",
    "checkOut": "2026-03-18",
    "status": "confirmed",
    "rooms": [
      {
        "roomId": "room_101",
        "roomNumber": "101",
        "roomType": "Deluxe",
        "ratePerNight": 3500,
        "adults": 2,
        "children": 1
      }
    ],
    "totalAmount": 10500,
    "advanceAmount": 3000,
    "balanceDue": 7500,
    "source": "walk-in",
    "mealPlan": "CP",
    "notes": "Early check-in requested",
    "specialRequests": "Extra pillows",
    "createdAt": "2026-02-23T10:30:00.000Z",
    "updatedAt": "2026-02-23T10:30:00.000Z"
  }
}

PUT /api/bookings/:orgId/:bookingId/stay ​

Update stay details (dates, rooms, meal plan).

Request Body ​

json
{
  "checkIn": "2026-03-15",
  "checkOut": "2026-03-20",
  "mealPlan": "MAP",
  "notes": "Extended stay — 2 extra nights"
}
FieldTypeRequiredDescription
checkInstringNoUpdated check-in date
checkOutstringNoUpdated check-out date
mealPlanstringNoUpdated meal plan
notesstringNoUpdated notes

Response — 200 OK ​

json
{
  "success": true,
  "message": "Stay details updated successfully",
  "data": {
    "bookingId": "bk_xyz789",
    "checkIn": "2026-03-15",
    "checkOut": "2026-03-20",
    "mealPlan": "MAP"
  }
}

PUT /api/bookings/:orgId/:bookingId/arrival ​

Update expected arrival information.

Request Body ​

json
{
  "expectedArrivalTime": "14:00",
  "transportMode": "flight",
  "transportDetails": "AI-302, arriving 13:30"
}
FieldTypeRequiredDescription
expectedArrivalTimestringNoExpected arrival time (HH:mm)
transportModestringNoMode of transport
transportDetailsstringNoFlight/train number, etc.

Response — 200 OK ​

json
{
  "success": true,
  "message": "Arrival details updated"
}

POST /api/bookings/:orgId/:bookingId/add-room ​

Add an additional room to an existing booking.

Request Body ​

json
{
  "roomId": "room_205",
  "roomNumber": "205",
  "roomType": "Suite",
  "ratePerNight": 6000,
  "adults": 2,
  "children": 0
}
FieldTypeRequiredDescription
roomIdstringYesRoom ID to add
roomNumberstringYesRoom number
roomTypestringYesRoom type
ratePerNightnumberYesNightly rate
adultsnumberYesNumber of adults
childrennumberNoNumber of children

Response — 200 OK ​

json
{
  "success": true,
  "message": "Room added to booking",
  "data": {
    "bookingId": "bk_xyz789",
    "rooms": [
      { "roomNumber": "101", "roomType": "Deluxe" },
      { "roomNumber": "205", "roomType": "Suite" }
    ]
  }
}

Error — 400 Bad Request ​

json
{
  "success": false,
  "message": "Room 205 is not available for the selected dates"
}

POST /api/bookings/:orgId/:bookingId/checkout-rooms ​

Checkout specific rooms from a multi-room booking without closing the entire booking.

Request Body ​

json
{
  "roomIds": ["room_101"],
  "reason": "Early departure for room 101"
}
FieldTypeRequiredDescription
roomIdsstring[]YesArray of room IDs to checkout
reasonstringNoReason for partial checkout

Response — 200 OK ​

json
{
  "success": true,
  "message": "Rooms checked out successfully",
  "data": {
    "checkedOutRooms": ["101"],
    "remainingRooms": ["205"]
  }
}

PUT /api/bookings/:orgId/:bookingId/update-guest ​

Update guest details on a booking.

Request Body ​

json
{
  "guestName": "Jane M. Smith",
  "guestEmail": "jane.smith@newmail.com",
  "guestPhone": "+919876543210",
  "idType": "passport",
  "idNumber": "P1234567"
}
FieldTypeRequiredDescription
guestNamestringNoUpdated full name
guestEmailstringNoUpdated email
guestPhonestringNoUpdated phone
idTypestringNoID document type
idNumberstringNoID document number

Response — 200 OK ​

json
{
  "success": true,
  "message": "Guest information updated"
}

PUT /api/bookings/:orgId/:bookingId/checkout ​

Perform full checkout for the booking.

Request Body ​

json
{
  "checkoutTime": "2026-03-18T11:00:00.000Z",
  "finalAmount": 10500,
  "settlementMethod": "card",
  "remarks": "Smooth checkout"
}
FieldTypeRequiredDescription
checkoutTimestringNoActual checkout timestamp (defaults to now)
finalAmountnumberNoFinal settled amount
settlementMethodstringNoPayment method for settlement
remarksstringNoCheckout remarks

Response — 200 OK ​

json
{
  "success": true,
  "message": "Booking checked out successfully",
  "data": {
    "bookingId": "bk_xyz789",
    "status": "checked-out",
    "checkoutTime": "2026-03-18T11:00:00.000Z"
  }
}

POST /api/bookings/:orgId/:bookingId/arrival ​

Record that the guest has arrived.

Request Body ​

json
{
  "arrivalTime": "2026-03-15T14:30:00.000Z",
  "remarks": "Guest arrived on time"
}
FieldTypeRequiredDescription
arrivalTimestringNoActual arrival timestamp (defaults to now)
remarksstringNoArrival remarks

Response — 200 OK ​

json
{
  "success": true,
  "message": "Guest arrival recorded",
  "data": {
    "bookingId": "bk_xyz789",
    "status": "checked-in",
    "arrivalTime": "2026-03-15T14:30:00.000Z"
  }
}

PUT /api/bookings/:orgId/:bookingId/cancel ​

Cancel a booking.

Request Body ​

json
{
  "reason": "Guest requested cancellation",
  "cancellationCharge": 1500,
  "refundAmount": 1500
}
FieldTypeRequiredDescription
reasonstringYesCancellation reason
cancellationChargenumberNoCancellation fee
refundAmountnumberNoAmount to refund

Response — 200 OK ​

json
{
  "success": true,
  "message": "Booking cancelled",
  "data": {
    "bookingId": "bk_xyz789",
    "status": "cancelled",
    "cancellationCharge": 1500,
    "refundAmount": 1500
  }
}

PUT /api/bookings/:orgId/:bookingId/change-guest ​

Change the primary guest on a booking.

Request Body ​

json
{
  "newGuestId": "guest_def456",
  "newGuestName": "Robert Johnson",
  "newGuestEmail": "robert@example.com",
  "newGuestPhone": "+919123456789"
}
FieldTypeRequiredDescription
newGuestIdstringNoExisting guest ID (omit to provide details inline)
newGuestNamestringYesNew guest full name
newGuestEmailstringNoNew guest email
newGuestPhonestringYesNew guest phone

Response — 200 OK ​

json
{
  "success": true,
  "message": "Primary guest changed",
  "data": {
    "bookingId": "bk_xyz789",
    "previousGuest": "Jane Smith",
    "newGuest": "Robert Johnson"
  }
}

Error — 404 Not Found ​

json
{
  "success": false,
  "message": "Booking not found"
}

Released under the MIT License.

Copyright © 2025–2026 Booking Management System