Admin — Bookings - Royal Glow Salon & Spa

Admin-side booking management. Every endpoint here calls requireRole(...), which first resolves the Better Auth session (UNAUTHENTICATED 401 when there is none) and then checks the caller’s role against the hierarchy customer < staff < receptionist < manager < owner < developer (FORBIDDEN 403 when the level is too low).

Base URL: admin.theroyalglow.in · Auth: Better Auth session; minimum role receptionist on every endpoint on this page. These paths carry no /admin prefix — the admin subdomain is the namespace, so the full URL is e.g. admin.theroyalglow.in/api/bookings. The customer app exposes its own, distinct /api/bookings on theroyalglow.in (see Bookings). Money is an integer in paise; bookingDate filters use YYYY-MM-DD; stored times render as HH:mm:ss. Timestamps are ISO-8601 UTC.

GET /api/bookings

Lists all bookings across customers (admin view), newest first (bookingDate then createdAt descending). Each booking is returned with the customer’s name and email and its booking_service snapshot rows (ordered by displayOrder). Optional query filters narrow the result set; this endpoint returns the full filtered list and does not paginate (no meta). Minimum role: receptionist (requireRole('receptionist'))

GET /api/bookings?status=pending&serviceType=salon&date=2026-06-15

Query parameters

All optional. Filters are applied with exact equality; omitting a parameter skips that filter.

Name	Type	Required	Description
`status`	`string`	No	Booking status, e.g. pending, confirmed, in_progress, completed, cancelled, no_show, rejected.
`serviceType`	`string`	No	salon or spa.
`date`	`string`	No	YYYY-MM-DD. Matches the bookingDate exactly.

Response

{
  "success": true,
  "data": {
    "bookings": [
      {
        "id": "bk_8f2a1c9e4d",
        "bookingNumber": "BK-RS-2606-H-38291",
        "branchId": "br_rayasandra01",
        "customerId": "usr_abc123",
        "status": "pending",
        "serviceType": "salon",
        "bookingDate": "2026-06-15",
        "startTime": "11:00:00",
        "endTime": "12:00:00",
        "totalAmountPaise": 130000,
        "totalDurationMinutes": 60,
        "notes": "Prefer a window seat if available.",
        "isWalkin": false,
        "isMembershipSession": false,
        "offerId": null,
        "spaMembershipId": null,
        "confirmedAt": null,
        "completedAt": null,
        "cancellationReason": null,
        "cancelledAt": null,
        "rejectionReason": null,
        "rejectedAt": null,
        "rescheduleCount": 0,
        "createdAt": "2026-06-01T06:15:00.000Z",
        "updatedAt": "2026-06-01T06:15:00.000Z",
        "customerName": "Aarav Sharma",
        "customerEmail": "aarav@example.com",
        "services": [
          {
            "id": "bs_1",
            "bookingId": "bk_8f2a1c9e4d",
            "serviceId": "svc_haircut001",
            "staffId": null,
            "serviceNameSnapshot": "Signature Haircut",
            "priceAtBookingPaise": 80000,
            "durationMinutes": 45,
            "displayOrder": 0
          }
        ]
      }
    ]
  }
}

Errors

UNAUTHENTICATED — 401

No active session.

FORBIDDEN — 403

Caller’s role is below receptionist.

INTERNAL_ERROR — 500

Unexpected/transient failure. retryable: true.

GET /api/bookings/[id]

Returns a single booking (any customer) with the customer’s name and email and its services snapshot rows. Minimum role: receptionist (requireRole('receptionist'))

GET /api/bookings/bk_8f2a1c9e4d

Path parameters

Name	Type	Required	Description
`id`	`string`	Yes	Path. The booking id.

Response

{
  "success": true,
  "data": {
    "booking": {
      "id": "bk_8f2a1c9e4d",
      "bookingNumber": "BK-RS-2606-H-38291",
      "branchId": "br_rayasandra01",
      "customerId": "usr_abc123",
      "status": "confirmed",
      "serviceType": "salon",
      "bookingDate": "2026-06-15",
      "startTime": "11:00:00",
      "endTime": "12:00:00",
      "totalAmountPaise": 130000,
      "totalDurationMinutes": 60,
      "notes": null,
      "isWalkin": false,
      "isMembershipSession": false,
      "offerId": null,
      "spaMembershipId": null,
      "confirmedAt": "2026-06-01T07:00:00.000Z",
      "completedAt": null,
      "cancellationReason": null,
      "cancelledAt": null,
      "rejectionReason": null,
      "rejectedAt": null,
      "rescheduleCount": 0,
      "createdAt": "2026-06-01T06:15:00.000Z",
      "updatedAt": "2026-06-01T07:00:00.000Z",
      "customerName": "Aarav Sharma",
      "customerEmail": "aarav@example.com",
      "services": [
        {
          "id": "bs_1",
          "bookingId": "bk_8f2a1c9e4d",
          "serviceId": "svc_haircut001",
          "staffId": "stf_priya01",
          "serviceNameSnapshot": "Signature Haircut",
          "priceAtBookingPaise": 80000,
          "durationMinutes": 45,
          "displayOrder": 0
        }
      ]
    }
  }
}

Errors

UNAUTHENTICATED — 401

No active session.

FORBIDDEN — 403

Caller’s role is below receptionist.

NOT_FOUND — 404

No booking with that id.

INTERNAL_ERROR — 500

Unexpected/transient failure. retryable: true.

PATCH /api/bookings/[id]

A single endpoint that performs one of three actions, selected by the action discriminator. The body is validated by adminBookingActionSchema (@rgss/types), a discriminated union over action:

approve — only valid on a pending booking. Assigns staffId to every service on the booking, then transitions pending → confirmed and stamps confirmedAt.
reject — only valid on a pending booking. Transitions pending → rejected, storing rejectionReason and rejectedAt.
assign — (re)assigns staffId to every service on the booking, regardless of status.

Minimum role: receptionist (requireRole('receptionist'))

PATCH /api/bookings/bk_8f2a1c9e4d
Content-Type: application/json

Path parameters

Name	Type	Required	Description
`id`	`string`	Yes	Path. The booking id.

Request body

Name	Type	Required	Description
`action`	`enum`	Yes	approve, reject, or assign. Determines which other fields are required.
`staffId`	`string`	No	Required for approve and assign. Non-empty staff_profile id assigned to all services.
`rejectionReason`	`string`	No	Required for reject. 1–500 characters. Customer-facing reason.

approve
reject
assign

{
  "action": "approve",
  "staffId": "stf_priya01"
}

{
  "action": "reject",
  "rejectionReason": "No therapist available for the requested slot."
}

{
  "action": "assign",
  "staffId": "stf_priya01"
}

Response

approve / reject
assign

The updated booking row is returned.

{
  "success": true,
  "data": {
    "booking": {
      "id": "bk_8f2a1c9e4d",
      "bookingNumber": "BK-RS-2606-H-38291",
      "branchId": "br_rayasandra01",
      "customerId": "usr_abc123",
      "status": "confirmed",
      "serviceType": "salon",
      "bookingDate": "2026-06-15",
      "startTime": "11:00:00",
      "endTime": "12:00:00",
      "totalAmountPaise": 130000,
      "totalDurationMinutes": 60,
      "notes": null,
      "isWalkin": false,
      "isMembershipSession": false,
      "offerId": null,
      "spaMembershipId": null,
      "confirmedAt": "2026-06-01T07:00:00.000Z",
      "completedAt": null,
      "cancellationReason": null,
      "cancelledAt": null,
      "rejectionReason": null,
      "rejectedAt": null,
      "rescheduleCount": 0,
      "createdAt": "2026-06-01T06:15:00.000Z",
      "updatedAt": "2026-06-01T07:00:00.000Z"
    }
  }
}

The booking id and the updated booking_service rows are returned.

{
  "success": true,
  "data": {
    "bookingId": "bk_8f2a1c9e4d",
    "services": [
      {
        "id": "bs_1",
        "bookingId": "bk_8f2a1c9e4d",
        "serviceId": "svc_haircut001",
        "staffId": "stf_priya01",
        "serviceNameSnapshot": "Signature Haircut",
        "priceAtBookingPaise": 80000,
        "durationMinutes": 45,
        "displayOrder": 0
      }
    ]
  }
}

Errors

UNAUTHENTICATED — 401

No active session.

FORBIDDEN — 403

Caller’s role is below receptionist.

VALIDATION_ERROR — 400

Body fails adminBookingActionSchema (unknown action, missing staffId/rejectionReason, etc.). details carries field errors.

NOT_FOUND — 404

No booking with that id.

BOOKING_INVALID_STATUS_TRANSITION — 409

approve/reject attempted on a booking that is not pending.

INTERNAL_ERROR — 500

Unexpected/transient failure. retryable: true.

POST /api/bookings/[id]/complete

Completes a booking at the counter: collects the in-person payment method, transitions the booking to completed, generates a GST-inclusive service invoice, awards loyalty gems, and (optionally) applies an offer. Only confirmed or in_progress bookings can be completed. Minimum role: receptionist (requireRole('receptionist'))

POST /api/bookings/bk_8f2a1c9e4d/complete
Content-Type: application/json

Path parameters

Name	Type	Required	Description
`id`	`string`	Yes	Path. The booking id.

Request body

paymentMethod is validated by completeBookingSchema (@rgss/types). The offer/gems fields are read defensively from the raw body alongside the parsed payload.

Name	Type	Required	Description
`paymentMethod`	`enum`	Yes	cash, upi, or card.
`offerId`	`string`	No	Apply a salon-only offer to the total. Validated as active and within its date range; cannot be combined with gems; one offer per customer per day.
`gemsRedeemedServiceId`	`string`	No	Presence signals a gems redemption on this booking. Mutually exclusive with offerId.
`redeemGems`	`boolean`	No	Truthy value also signals a gems redemption (mutually exclusive with offerId).

{
  "paymentMethod": "upi",
  "offerId": "off_monsoon20"
}

Response

Returns the completed booking plus an invoice summary, gems earned, and any discount applied (all amounts in paise).

{
  "success": true,
  "data": {
    "booking": {
      "id": "bk_8f2a1c9e4d",
      "bookingNumber": "BK-RS-2606-H-38291",
      "branchId": "br_rayasandra01",
      "customerId": "usr_abc123",
      "status": "completed",
      "serviceType": "salon",
      "bookingDate": "2026-06-15",
      "startTime": "11:00:00",
      "endTime": "12:00:00",
      "totalAmountPaise": 130000,
      "totalDurationMinutes": 60,
      "notes": null,
      "isWalkin": false,
      "isMembershipSession": false,
      "offerId": null,
      "spaMembershipId": null,
      "confirmedAt": "2026-06-01T07:00:00.000Z",
      "completedAt": "2026-06-15T06:30:00.000Z",
      "cancellationReason": null,
      "cancelledAt": null,
      "rejectionReason": null,
      "rejectedAt": null,
      "rescheduleCount": 0,
      "createdAt": "2026-06-01T06:15:00.000Z",
      "updatedAt": "2026-06-15T06:30:00.000Z"
    },
    "invoice": {
      "invoiceNumber": "INV-1-2627-92921",
      "totalPaise": 104000,
      "gstPaise": 15864
    },
    "gemsEarned": 10,
    "discountPaise": 26000
  }
}

Gems are earned on the discounted total at 1 gem per ₹100 (floor) and expire 365 days from earn date. The invoice subtotal is the original (pre-discount) base; the taxable value and GST are split from the discounted total. With no offerId, discountPaise is 0 and the total is unchanged.

Errors

UNAUTHENTICATED — 401

No active session.

FORBIDDEN — 403

Caller’s role is below receptionist.

VALIDATION_ERROR — 400

Body fails completeBookingSchema (invalid/missing paymentMethod). details carries field errors.

NOT_FOUND — 404

Booking not found, its branch not found, or a supplied offerId not found.

BOOKING_INVALID_STATUS_TRANSITION — 409

Booking is not confirmed or in_progress.

OFFER_EXPIRED — 409

Supplied offer is inactive or outside its date range.

OFFER_NOT_APPLICABLE — 409

Offer applied to a spa booking, combined with a gems redemption, or the customer already redeemed an offer today.

INTERNAL_ERROR — 500

Unexpected/transient failure. retryable: true.

POST /api/bookings/[id]/noshow

Marks a booking as no_show. Only a confirmed booking can be marked no-show (intended for use after the appointment window). No request body is required. No-show tier escalation is handled separately by a background job. Minimum role: receptionist (requireRole('receptionist'))

POST /api/bookings/bk_8f2a1c9e4d/noshow

Path parameters

Name	Type	Required	Description
`id`	`string`	Yes	Path. The booking id.

Response

{
  "success": true,
  "data": {
    "booking": {
      "id": "bk_8f2a1c9e4d",
      "bookingNumber": "BK-RS-2606-H-38291",
      "branchId": "br_rayasandra01",
      "customerId": "usr_abc123",
      "status": "no_show",
      "serviceType": "salon",
      "bookingDate": "2026-06-15",
      "startTime": "11:00:00",
      "endTime": "12:00:00",
      "totalAmountPaise": 130000,
      "totalDurationMinutes": 60,
      "notes": null,
      "isWalkin": false,
      "isMembershipSession": false,
      "offerId": null,
      "spaMembershipId": null,
      "confirmedAt": "2026-06-01T07:00:00.000Z",
      "completedAt": null,
      "cancellationReason": null,
      "cancelledAt": null,
      "rejectionReason": null,
      "rejectedAt": null,
      "rescheduleCount": 0,
      "createdAt": "2026-06-01T06:15:00.000Z",
      "updatedAt": "2026-06-15T07:00:00.000Z"
    }
  }
}

Errors

UNAUTHENTICATED — 401

No active session.

FORBIDDEN — 403

Caller’s role is below receptionist.

NOT_FOUND — 404

No booking with that id.

BOOKING_INVALID_STATUS_TRANSITION — 409

Booking is not in confirmed status.

INTERNAL_ERROR — 500

Unexpected/transient failure. retryable: true.

​GET /api/bookings

​Query parameters

​Response

​Errors

​GET /api/bookings/[id]

​Path parameters

​Response

​Errors

​PATCH /api/bookings/[id]

​Path parameters

​Request body

​Response

​Errors

​POST /api/bookings/[id]/complete

​Path parameters

​Request body

​Response

​Errors

​POST /api/bookings/[id]/noshow

​Path parameters

​Response

​Errors

GET /api/bookings

Query parameters

Response

Errors

GET /api/bookings/[id]

Path parameters

Response

Errors

PATCH /api/bookings/[id]

Path parameters

Request body

Response

Errors

POST /api/bookings/[id]/complete

Path parameters

Request body

Response

Errors

POST /api/bookings/[id]/noshow

Path parameters

Response

Errors