Skip to main content

Facility Reservations

Facilities exposes booking endpoints for reserving resources (courts, simulators, carts, rooms). Reservations are scoped by tenantId and optionally clubId. All timestamps are ISO-8601 strings in UTC unless otherwise noted.

Reservation Model​

  • status: ACTIVE, CANCELLED, NO_SHOW
  • version: optimistic lock integer required for mutations
  • externalBookingId: optional idempotency key for upstream systems (e.g., SCL)

Reservation Series Model​

  • status: ACTIVE, PAUSED, CANCELLED
  • rule: RRULE string (e.g., FREQ=WEEKLY;BYDAY=MO,WE,FR)
  • timeZone: IANA time zone used for recurrence expansion
  • version: optimistic lock integer required for updates and lifecycle changes

Endpoints​

List Reservations​

GET /facility-reservations?tenantId=1&clubId=10&resourceId=42&status=ACTIVE&startFrom=2025-01-15T08:00:00Z

Query params:

  • tenantId (required)
  • clubId, resourceId, memberId (optional)
  • status: ACTIVE, CANCELLED, NO_SHOW
  • startFrom, startTo: ISO timestamps
  • skip, take: pagination

Create Reservation​

POST /facility-reservations
{
  "tenantId": "t-1",
  "clubId": "c-1",
  "resourceId": "r-42",
  "memberId": "m-9",
  "guestCount": 2,
  "startTime": "2025-01-15T10:00:00Z",
  "endTime": "2025-01-15T11:00:00Z",
  "source": "WEB",
  "externalBookingId": "scl-booking-123",
  "notes": "Prefer simulator with left-handed bay"
}

Notes:

  • externalBookingId makes create idempotent for upstream systems.
  • Overlap constraints reject conflicting ACTIVE reservations.

Reschedule Reservation​

POST /facility-reservations/:id/reschedule?tenantId=1&clubId=10
{
  "startTime": "2025-01-15T11:00:00Z",
  "endTime": "2025-01-15T12:00:00Z",
  "reason": "Member request",
  "version": 3
}

Cancel Reservation​

POST /facility-reservations/:id/cancel?tenantId=1&clubId=10
{
  "reason": "Member cancelled",
  "version": 3
}

Mark No-show​

POST /facility-reservations/:id/no-show?tenantId=1&clubId=10&version=3

Reservation Series​

List Series​

GET /facility-reservations/series?tenantId=1&clubId=10&status=ACTIVE

Create Series​

POST /facility-reservations/series
{
  "tenantId": "t-1",
  "clubId": "c-1",
  "resourceId": "r-42",
  "memberId": "m-9",
  "rule": "FREQ=WEEKLY;BYDAY=MO,WE,FR",
  "timeZone": "Africa/Johannesburg",
  "startTime": "2025-01-15T10:00:00Z",
  "endTime": "2025-01-15T11:00:00Z"
}

Update Series​

PUT /facility-reservations/series/:id?tenantId=1&clubId=10
{
  "rule": "FREQ=WEEKLY;BYDAY=TU,TH",
  "version": 2
}

Cancel / Pause / Resume​

POST /facility-reservations/series/:id/cancel?tenantId=1&clubId=10&version=2
POST /facility-reservations/series/:id/pause?tenantId=1&clubId=10&version=2
POST /facility-reservations/series/:id/resume?tenantId=1&clubId=10&version=3