Skip to main content
Version: 3.0

Appointment Booking

A booking claims a specific time slot on a practitioner, location, or service's calendar for one patient, and tracks that appointment from the moment it is requested until the patient is seen or the slot is released. It is how published availability becomes an accountable commitment between a patient and the facility.

What it represents​

In Care's FHIR-aligned model, a booking maps to the Appointment resource, and the time slot it occupies maps to the Slot resource. Care's field names may differ from the FHIR element names, but the lifecycle maps directly. Together the two capture:

  • Who and when — the patient, the chosen time slot, and who created the booking
  • Where it lands — the slot belongs to a schedulable resource: a practitioner, a location, or a healthcare service
  • Status — where the appointment sits in its lifecycle, from proposed through fulfilled, cancelled, or no-show

The key distinction: a booking is not the schedule it came from. A Schedule defines recurring availability and generates bookable slots; a booking is one patient claiming one of those slots. Each slot has a fixed capacity, so once it fills, no further bookings can be made against it — availability is a shared resource, and a booking is a reservation against it.

Lifecycle​

A booking is created as booked — the slot is reserved the moment the appointment exists. From there it advances as the patient arrives and is seen, then settles into a terminal state. Cancelling and rescheduling are deliberate, separate actions, never ordinary edits to the status field.

proposed → pending → booked → arrived → checked_in → in_consultation → fulfilled
                       │
                       ├──→ cancelled / entered_in_error / rescheduled
                       └──→ noshow
  • proposed / pending — a tentative or unconfirmed request, before the slot is firmly held
  • booked — the appointment exists and the slot is reserved for the patient (the default on creation)
  • waitlist — the patient is waiting for a slot to open up
  • arrived / checked_in — the patient has reached the facility and been registered for the visit
  • in_consultation — the patient is being seen; a booking in this state cannot be cancelled
  • fulfilled / noshow — terminal: the visit was completed, or the patient did not turn up
  • cancelled / entered_in_error / rescheduled — the appointment was called off, logged in error, or moved; these are set only through the dedicated cancel and reschedule actions

Anything that ends a booking early — cancelling, marking an error, or rescheduling — releases the slot's capacity so it can be offered to someone else. Rescheduling does this by closing the original booking and creating a fresh one on the new slot.

How it connects​

A booking sits at the centre of several scheduling and clinical primitives:

  • Patient — every booking belongs to exactly one patient; one patient can hold many bookings over time
  • Slot and schedule — the booking occupies a slot generated by a Schedule; the slot caps how many patients can book the same window
  • Encounter — when the patient is seen, the booking links to the Encounter that documents the visit
  • Token — a queue token can be generated for the booking to manage walk-in and waiting-room flow
  • Charge item — if the schedule is priced, booking automatically raises a charge item so the appointment can be billed; cancelling the booking aborts it

Permissions​

Bookings are governed by the schedule permission set. Access is granted to staff working within the facility that owns the schedule.

PermissionDescriptionSystem Roles
can_write_bookingUpdate a booking, and run the cancel, reschedule, and generate-token actions on itAdmin, Staff, Facility Admin, Doctor, Nurse
can_list_bookingList and retrieve the bookings on a schedulable resourceAdmin, Staff, Facility Admin, Doctor, Nurse, Administrator
can_write_scheduleFilter a booking list by organisation (checked when listing bookings scoped to a facility organisation)Admin, Staff, Facility Admin, Doctor, Nurse
can_reschedule_bookingMove a booking to a different slot via the reschedule actionDoctor, Staff, Nurse, Administrator, Facility Admin, Admin

Roles come from a user's facility and organization memberships, and permissions cascade down the organization tree — a role held higher up applies to the facilities and resources beneath it.