Google Sheets Integration API

The Sheets API allows external Google Apps Script to synchronise booking data with an external Google Sheet. These endpoints are authenticated via a shared API key (validated by the validateGsheetKey middleware), not PASETO tokens.

Base Path

/api/sheets

Endpoints

Method	Path	Description
POST	/api/sheets/create	Create a booking from a Google Sheet row
PUT	/api/sheets/update/:bookingId	Update a booking from Sheet
DELETE	/api/sheets/delete/:bookingId	Delete a booking from Sheet
PUT	/api/sheets/:bookingId/:roomId/status-booked	Mark room as booked (from Sheet)
PATCH	/api/sheets/invitations/:invitationId/timeout	Timeout an invitation (from Sheet)
POST	/api/sheets/:orgId/:bookingId/cancel	Cancel a booking (from Sheet)
PUT	/api/sheets/:orgId/:bookingId/cancel	Cancel a booking (alternative method)

---

Authentication

Google Sheets Key

All requests must include a valid API key header:

X-GSheet-Key: YOUR_GSHEET_API_KEY

This key is validated by the validateGsheetKey middleware and is separate from user authentication.

---

Create Booking

POST /api/sheets/create
X-GSheet-Key: YOUR_GSHEET_API_KEY
Content-Type: application/json

Request Body

{
  "orgId": "org_abc123",
  "guestName": "John Doe",
  "guestEmail": "john@example.com",
  "guestPhone": "+919876543210",
  "checkIn": "2025-08-01",
  "checkOut": "2025-08-05",
  "roomIds": ["room_1", "room_2"],
  "notes": "Late arrival expected"
}

Response — 201 Created

{
  "success": true,
  "message": "Booking created from sheet",
  "data": {
    "id": "booking_xyz",
    "bookingCode": "BK-0042"
  }
}

---

Update Booking

PUT /api/sheets/update/:bookingId
X-GSheet-Key: YOUR_GSHEET_API_KEY
Content-Type: application/json

Path Parameters

Parameter	Type	Description
bookingId	string	Booking document ID

Request Body

{
  "checkIn": "2025-08-02",
  "checkOut": "2025-08-06",
  "notes": "Updated dates"
}

Response — 200 OK

{
  "success": true,
  "message": "Booking updated from sheet"
}

---

Delete Booking

DELETE /api/sheets/delete/:bookingId
X-GSheet-Key: YOUR_GSHEET_API_KEY

Path Parameters

Parameter	Type	Description
bookingId	string	Booking document ID

Response — 200 OK

{
  "success": true,
  "message": "Booking deleted from sheet"
}

---

Mark Room as Booked

PUT /api/sheets/:bookingId/:roomId/status-booked
X-GSheet-Key: YOUR_GSHEET_API_KEY

Path Parameters

Parameter	Type	Description
bookingId	string	Booking document ID
roomId	string	Room document ID

Response — 200 OK

{
  "success": true,
  "message": "Room marked as booked"
}

---

Timeout Invitation

PATCH /api/sheets/invitations/:invitationId/timeout
X-GSheet-Key: YOUR_GSHEET_API_KEY

Path Parameters

Parameter	Type	Description
invitationId	string	Invitation document ID

Response — 200 OK

{
  "success": true,
  "message": "Invitation timed out"
}

---

Cancel Booking

POST /api/sheets/:orgId/:bookingId/cancel
X-GSheet-Key: YOUR_GSHEET_API_KEY

Path Parameters

Parameter	Type	Description
orgId	string	Organization ID
bookingId	string	Booking document ID

Response — 200 OK

{
  "success": true,
  "message": "Booking cancelled from sheet"
}

---

Error Responses

All endpoints return the same error format:

{
  "success": false,
  "message": "Error description"
}

Code	Description
400	Bad request / missing required fields
401	Invalid or missing GSheet API key
404	Booking or resource not found
500	Internal server error