API Reference

All API requests are authenticated with a bearer token issued from your Hotel Admin settings screen. Tokens are scoped per property and per role — a staff token can create bookings but cannot change GST slabs; a hotel admin token can do both. Include the token in the Authorization: Bearer <token>header on every call. Rotate tokens anytime; the old token is revoked instantly.

Base URL: https://api.theoretichotels.com/v1. Rate limit is 600 requests per minute per token, with a burst of 50. Responses include X-RateLimit-Remainingand X-RateLimit-Resetheaders. Bulk operations accept batches of up to 100 records per call to reduce request volume.

GET /bookings,POST /bookings,GET /bookings/:id,PATCH /bookings/:id,POST /bookings/:id/check-in,POST /bookings/:id/check-out. Supports multi-room bookings, custom DR-format IDs, advance payments, and additional charges. The check-out endpoint runs the checkout guard and returns a structured error if any charge is unsettled.

GET /guests?phone=...auto-fetches a guest profile by phone or email — the same auto-fetch used by the booking screen. Create, update, list, and merge duplicate guests. ID numbers (Aadhaar / Passport / State ID / Govt Issued) are returned masked unless the token has the guests.id.readscope.

GET /rooms andGET /rooms/availability?from=&to=return room inventory and availability by date range. Supports custom room types, attributes (sea view, private pool, pet-friendly), and per-room housekeeping status. Perfect for building a custom booking widget on your own website.

POST /pos/orderscreates a restaurant order, optionally routed to a room folio.POST /pos/bills/:id/settlesettles a bill with a Restaurant payment type (Cash / Card / UPI / Bank / Room).GET /pos/billsreturns the searchable bill log with date, time, server, and amount.

POST /paymentscaptures a payment against a booking or folio in Cash / Card / UPI / Bank Transfer modes. POST /payments/refundissues a refund with reason and audit trail. All payments are immediately visible on the dashboard and the folio.

POST /invoicesgenerates a GST-compliant invoice with CGST / SGST or IGST breakdown based on the guest GSTIN and place of supply.GET /invoices/:id/pdfreturns a PDF. POST /invoices/:id/senddispatches the invoice by both email and WhatsApp in a single call.

GET /reports/revenue?from=&to=&group_by=returns aggregated revenue by day, week, month, room type, or source.GET /reports/occupancy,/reports/adr,/reports/revparreturn the headline KPIs. Every report is also exportable as XLS / CSV / PDF via the /reports/exportendpoint.

Standard HTTP status codes — 200success, 201 created,400 bad request,401 unauthenticated,403 forbidden,404 not found,409 conflict (e.g. duplicate guest), 422checkout guard tripped, 429rate limited, 500 server error. Every error response includes a structured { error, code, message, details }body.