Self-Booking Flow

Authenticated patients can book, reschedule, and cancel appointments directly through the patient portal. All operations enforce ownership verification — patients can only manage their own appointments.

Creating an Appointment

The booking flow follows these steps:

Patient browses available doctors and time slots
Patient selects a doctor, centre, service, and slot
System creates a DRAFT appointment with a hold timer
Patient confirms the appointment (with payment if required)
Appointment moves to CONFIRMED (or PENDING_APPROVAL if doctor approval is needed)

Draft Appointment Hold

When a draft is created, the selected slot is temporarily held. The hold has an expiry time — if the patient does not confirm within this window, the draft expires and the slot is released for other bookings.

Payment During Booking

Depending on the appointment configuration, payment may be required before confirmation:

NONE: no payment needed — appointment is confirmed immediately
TOKEN: a fixed deposit amount must be paid
ADVANCE: a percentage of the fee is required
FULL: the complete consultation fee must be paid

For online payments, a payment reference is recorded with the confirmation.

Booking Restrictions

Several restrictions control what patients can book:

Active Booking Limit

There is a configurable maximum number of active (non-completed, non-cancelled) appointments a patient can have at any time. If the limit is reached, new bookings are rejected until existing ones are completed or cancelled.

Booking Window Rules

The system enforces time-based booking rules:

Minimum Advance Booking: how far in advance an appointment must be booked (e.g., at least 2 hours before the slot)
Maximum Advance Booking: how far into the future appointments can be booked (e.g., up to 30 days ahead)
Same-Day Booking: whether same-day appointments are allowed, and if so, what the cutoff time is

Cancelling an Appointment

Patients can cancel their own appointments with these rules:

Only appointments in DRAFT, CONFIRMED, or PENDING_APPROVAL status can be cancelled
A configurable cancellation window limits how close to the appointment time a cancellation is allowed (e.g., must cancel at least 24 hours before)
A cancellation reason can be provided
The cancellation actor is recorded as PATIENT (distinguishing from staff or system cancellations)
If payment was made, a refund may be initiated automatically

Rescheduling an Appointment

Patients can reschedule confirmed or checked-in appointments:

A new time slot must be selected (must be available)
Optionally, the doctor or centre can be changed during reschedule
The reschedule count is tracked — there is a configurable maximum number of reschedules per appointment
The old appointment is marked as RESCHEDULED and a new appointment is created with a link to the previous one
Outside the allowed reschedule window, the request is rejected

Viewing Appointments

Patients can view their appointment history with filtering options:

Status Filter: filter by one or more statuses (e.g., CONFIRMED, CHECKED_IN, COMPLETED)
Doctor Filter: see appointments with a specific doctor
Centre Filter: see appointments at a specific centre
Date Range: filter by appointment date (from/to epoch seconds)

Results are paginated with cursor-based navigation (default 20 per page, maximum 50).

Package Usage

Patients can view and use their purchased packages:

List all purchased packages with status filtering (ACTIVE, EXHAUSTED, etc.)
Check which packages are applicable for a specific service at a specific centre
View package details including remaining sessions, validity dates, and redemption history
View per-package redemption history showing when and where sessions were used

Data Isolation

All patient operations enforce strict data isolation:

Every request is filtered by the patient's tenant ID and lead ID
Ownership verification prevents accessing other patients' data
Attempting to view or modify another patient's appointment returns a 403 Forbidden error
Rate limiting is applied per patient session to prevent abuse

self-bookingpatient-bookingonline-bookingportal

Self-Booking Flow