Waitlist

The Waitlist page is used to record guests who could not be placed immediately into a reservation but still want a table opportunity.

It helps staff keep a structured queue, follow up with waiting guests, and convert the entry into a reservation when capacity becomes available.

Use Waitlist when you need to:

• record a guest who is waiting for a table or time slot
• keep customer and branch context in one place
• track operational waitlist status
• notify a guest that a slot is available
• convert a waitlist entry into a real reservation
• keep internal notes for handoff between reception, host, or manager staff

The Waitlist feature is an internal admin workflow. It is managed from the admin panel by authorized staff.

Where to Find It

In the admin panel, open:

Reservations > Waitlist

From there, staff can:

• view the waitlist entries
• search and filter the list
• create a new waitlist entry
• open the details page
• edit an active entry
• notify a guest
• cancel an entry
• convert an entry into a reservation
• delete entries when allowed by status and permission

What the Waitlist Module Includes

The Waitlist documentation currently covers these screens and flows:

1. Waitlist List
2. Create Waitlist Entry
3. Edit Waitlist Entry
4. Waitlist Details
5. Notify Action
6. Cancel Action
7. Convert to Reservation

Waitlist Lifecycle

Waitlist entries use a dedicated waitlist status, separate from reservation statuses.

Available Statuses

Status	Meaning
Waiting	The guest is on the waitlist and has not yet been notified or converted.
Notified	Staff notified the guest that a reservation opportunity may be available.
Converted	The waitlist entry was converted into a reservation.
Cancelled	The waitlist entry was cancelled and should no longer be acted on.
Expired	The waitlist opportunity is no longer valid.

Status Behavior

• Waiting is the default starting status.
• Notified is set when staff use the Notify action.
• Converted is set when staff successfully convert the waitlist entry into a reservation.
• Cancelled is set when staff cancel the entry.
• Expired is reserved for entries that are no longer valid based on operational handling or future automation.

Waitlist List

The Waitlist list page displays entries in a table for daily operations.

Main Columns

Column	Purpose
Branch	Shows which branch owns the waitlist entry. This may be hidden for users already assigned to a single branch.
Customer Name	Shows the guest name stored on the waitlist entry.
Customer Phone	Shows the guest phone number used for operational contact.
Preferred Date	Shows the guest’s preferred reservation date.
Preferred Start Time	Shows the preferred start time if one was provided.
Preferred End Time	Shows the preferred end time if one was provided.
Guests	Shows the guest count for the request.
Status	Shows the current waitlist status.
Created At	Shows when the waitlist entry was created.

Search, Filter, and Sort

The list supports operational browsing through:

• search in the table interface
• filter by Branch
• filter by Status
• filter by From date
• filter by To date
• sort by Branch
• sort by Customer Name
• sort by Preferred Date
• sort by Preferred Start Time
• sort by Preferred End Time
• sort by Guests
• sort by Status
• sort by Created At

Index Actions

Depending on permissions and status, the list can expose these actions:

Action	Purpose
Show	Opens the waitlist details page.
Edit	Updates the waitlist entry when editing is still allowed.
Notify	Marks the entry as notified and triggers the notification flow.
Convert to Reservation	Opens the conversion dialog to create a reservation from the waitlist entry.
Cancel	Cancels the waitlist entry.
Delete	Removes the waitlist entry when deletion is allowed.

Important Status Guards

• Edit is hidden for cancelled entries.
• Delete is hidden for cancelled entries.
• Convert to Reservation is hidden for converted, cancelled, and expired entries.
• Cancel is hidden for converted, cancelled, and expired entries.
• Notify is only shown for entries in waiting or notified state.

Create and Edit Form

The create and edit pages use the same main form structure.

The form is currently organized into these cards:

1. Waitlist Information
2. Waitlist Preferences
3. Notes

If the current user is assigned to a branch, branch context is taken from the user and is not meant to be changed during update.

Field-by-Field Explanation

Waitlist Information

Branch

Field	Purpose
Branch	Selects which branch owns the waitlist entry. It controls which customers and tables are loaded in related waitlist operations.

Branch Notes

• This field appears on create when the user is not already restricted to one branch.
• On update, branch is not intended to be changed.
• Branch context affects customer lists and future conversion behavior.

Customer

Field	Purpose
Customer	Links the waitlist entry to an existing customer record when one is available.

Customer Selection Behavior

When a customer is selected, the form automatically fills:

• customer name
• customer phone
• customer email
• phone country ISO code

This reduces manual entry and helps keep customer data consistent.

Customer Name

Field	Purpose
Customer Name	Stores the guest name for the waitlist entry. This is the main operational name shown in list and details screens.

Use this field even if the customer is not linked to a saved customer account.

Customer Email

Field	Purpose
Customer Email	Stores the guest email address when available.

This field is optional, but useful for contact history and follow-up.

Phone Country

Field	Purpose
Phone Country	Stores the ISO country code used to validate and normalize the customer phone number.

This works together with the phone field so the system can handle phone formatting consistently.

Customer Phone

Field	Purpose
Customer Phone	Stores the guest phone number used for operational communication.

The phone field is validated using the selected phone country code.

Waitlist Preferences

Guests

Field	Purpose
Guests	Stores how many guests are expected for the request.

This value is important because it directly affects later reservation conversion and table suitability.

Preferred Date

Field	Purpose
Preferred Date	Stores the date the guest wants to be accommodated.

This is a required field and is part of the main waitlist intent.

Occasion

Field	Purpose
Occasion	Stores an optional event or context for the visit, such as birthday, business dinner, or anniversary.

This helps staff prioritize service and understand guest expectations.

Preferred Start Time

Field	Purpose
Preferred Start Time	Stores the guest’s preferred start time if one is known.

This field is optional. It helps staff place the guest more accurately when availability opens.

Preferred End Time

Field	Purpose
Preferred End Time	Stores the preferred end time if the guest already knows the expected window.

This field is optional and is especially useful for guests asking for a specific time range rather than a single start time.

Notes

Special Requests

Field	Purpose
Special Requests	Stores guest-facing requests or service notes such as seating preference, accessibility needs, or celebration requests.

Internal Notes

Field	Purpose
Internal Notes	Stores staff-only notes for operations, handoff, or follow-up decisions.

This field is also used in operational flows such as cancellation when the cancellation reason is carried into the entry notes.

System-Managed Waitlist Fields

Some waitlist data is not entered directly in the main form but is still important to understand.

Field	Purpose
Status	The current operational state of the waitlist entry.
Created By	The staff user who created the entry.
Converted Reservation	Links the waitlist entry to the reservation created from it, when conversion happens.
Notified At	Stores when the guest was notified.
Converted At	Stores when the entry was converted into a reservation.
Cancelled At	Stores when the entry was cancelled.
Expires At	Stores the operational expiry target if used.
Expired At	Stores when the system or workflow treated the entry as expired.
Priority	Stores internal priority ordering. It currently defaults to 0 unless operational logic sets a different value.
Estimated Wait Minutes	Stores an optional internal estimate for expected waiting time.

Waitlist Details Page

The details page provides the main operational view for a single waitlist record.

What the Details Page Shows

The page currently shows:

• customer name
• current status
• branch
• preferred date
• guest count
• preferred start time
• preferred end time
• customer phone
• customer email
• occasion
• special requests
• internal notes

If the entry has already been converted, the page also shows the linked reservation number.

Details Page Actions

Depending on permission and status, the top action area can show:

• Notify
• Cancel
• Convert to Reservation
• Edit

These actions use per-action loading states so one action can run while the others remain disabled.

Notify Action

The Notify action is used when staff want to contact the guest and tell them that a reservation opportunity may now be available.

What Notify Does

When Notify is confirmed:

• the waitlist status is updated to Notified
• notified_at is stored
• the reservation notification service is called for the waitlist notification flow

When Notify Is Available

Notify is currently available only when the entry status is:

• waiting
• notified

This allows staff to notify again if needed, while still keeping the operational state visible.

Cancel Action

The Cancel action is used when the waitlist entry should no longer remain active.

What Cancel Does

When Cancel is confirmed:

• the waitlist status becomes Cancelled
• cancelled_at is stored
• internal notes may be updated with the cancellation reason payload used by the action

Important Cancel Rules

• Cancel is not available for converted, cancelled, or expired entries.
• Cancelled entries should not remain editable in the normal UI flow.
• Cancelled entries use the not-found behavior on the edit route.

Convert to Reservation

The Convert to Reservation action turns the waitlist entry into an actual reservation.

This is one of the most important operational actions in the module.

Where Conversion Is Available

Conversion is available from:

• the waitlist index action menu
• the waitlist details page header action

Conversion Dialog Fields

The conversion dialog currently uses:

Field	Purpose
Start Time	The reservation start time that should be used for the created reservation.
Tables	Optional table selection used during conversion if tables are assigned at the moment of conversion.

How Conversion Works

When staff confirm conversion:

1. the system creates a reservation using the waitlist data
2. the waitlist entry is updated to Converted
3. the created reservation is linked back to the waitlist record
4. converted_at is stored
5. the waitlist converted event is dispatched

Data Copied Into the Reservation

The conversion flow currently carries over these values from the waitlist entry:

• branch
• customer
• customer name
• customer phone
• customer email
• preferred date as reservation date unless overridden
• preferred start time unless overridden
• guest count
• occasion
• special requests
• internal notes

When Conversion Is Not Allowed

Conversion is hidden for:

• converted
• cancelled
• expired

Validation Notes

The implemented waitlist form currently enforces core validation expectations such as:

• branch is required in the allowed create flow
• customer name is required
• customer phone must match the selected phone country
• preferred date is required
• guest count must be a valid numeric value
• time fields must match the accepted time format

The backend normalizes time values before storage and validates phone input using the selected country code.

Recommended Operational Workflow

For most teams, the clean waitlist process is:

1. Create the waitlist entry with complete customer details.
2. Record the preferred date, guest count, and preferred time range.
3. Add any operational note in internal notes.
4. Notify the guest when a slot becomes available.
5. Convert the entry into a reservation when the guest accepts.
6. Cancel the entry if the guest no longer needs it or if staff close the request.

Practical Example

Example: Busy Evening Overflow

A branch is fully booked for 7:30 PM, but a guest still wants a table.

Staff can:

1. open Reservations > Waitlist
2. create a waitlist entry
3. record the branch, guest, date, party size, and preferred time
4. add notes such as prefers indoor seating
5. later use Notify when a slot opens
6. use Convert to Reservation if the guest accepts the offer

This keeps the guest request visible and traceable instead of relying on informal notes or memory.

Summary

The Waitlist module is the operational buffer between unavailable capacity and confirmed reservations.

It gives staff a structured way to:

• capture overflow demand
• keep customer details organized
• follow up with waiting guests
• promote valid opportunities into reservations
• preserve operational clarity through statuses, timestamps, and notes