Reservation

The Reservation page is used to create, manage, assign, and track restaurant reservations for each branch.

Use Reservations when staff need to:

• record a booking for a guest
• choose the branch, date, time, duration, and guest count
• capture customer contact information
• assign tables immediately, assign tables automatically, or leave assignment for later
• check table availability against branch rules
• track reservation status from pending through completion or cancellation
• manage deposit requirements when branch deposit settings are enabled
• review status history, assigned tables, notes, and payment context

Reservations are an internal admin workflow. They follow the branch Reservation Settings, seating-plan tables, table blocks, and system notification rules already configured in Forkiva.

Where to Find It

In the admin panel, open:

Reservations > Reservations

From there, staff can:

• view all reservations
• search, filter, sort, and export the reservation list
• create a reservation
• open the reservation details page
• edit an editable reservation
• open the calendar view
• change reservation status from the details page
• assign or auto-assign tables from the details page

What the Reservation Module Includes

The Reservation documentation currently covers:

1. Reservation List
2. Reservation Calendar
3. Create Reservation
4. Edit Reservation
5. Reservation Details
6. Status Actions
7. Table Assignment
8. Deposit Details
9. Status History

Reservation Lifecycle

Reservations use operational statuses that control editing, table assignment, and status transitions.

Available Statuses

Status	Meaning
Pending	The reservation has been created but is not yet confirmed.
Confirmed	The reservation is accepted and expected to happen.
Arrived	The guest has arrived at the branch.
Seated	The guest has been seated at assigned table(s).
Completed	The reservation visit is finished.
Cancelled	The reservation was cancelled.
Rejected	The reservation was rejected and will not proceed.
No-Show	The guest did not arrive.
Expired	The reservation is no longer valid, usually because it remained pending too long.

Status Flow

Current Status	Allowed Next Statuses
Pending	Confirmed, Cancelled, Rejected, or Expired by the system
Confirmed	Arrived, Seated, Cancelled, No-Show
Arrived	Seated, Cancelled, No-Show
Seated	Completed
Completed	No further status changes
Cancelled	No further status changes
Rejected	No further status changes
No-Show	No further status changes
Expired	No further status changes

Status Behavior

• Pending, Confirmed, and Arrived reservations can be edited.
• Pending, Confirmed, and Arrived reservations can have table assignments changed.
• Terminal statuses cannot be edited or changed again.
• Expired is system-owned. Staff cannot select it from the Change Status action; automation applies it when the configured expiry rule is met.
• Status changes are recorded in the reservation status history.
• When a reservation is confirmed or arrived, assigned tables can be marked as reserved.
• When a reservation is seated, assigned tables can be marked as occupied.
• When a reservation is completed, cancelled, rejected, marked no-show, or expired, assigned tables can be released back to available.

Reservation List

The Reservation list page displays reservations in a data table for daily operations.

Main Columns

Column	Purpose
Reservation Number	The unique reservation reference generated by the system. Staff can use it to identify or search a reservation quickly.
Branch	Shows which branch owns the reservation. This may be hidden for users assigned to a single branch.
Customer Name	Shows the guest name stored on the reservation.
Customer Phone	Shows the formatted phone number used for guest communication.
Reservation Date	Shows the booking date.
Start Time	Shows when the reservation begins.
Guests	Shows the total number of expected guests.
Status	Shows the current reservation status with status color.
Table Assignment Status	Shows whether tables are unassigned, assigned, partially assigned, or not required.
Created At	Shows when the reservation record 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 Reservation Type
• filter by From date
• filter by To date
• sort by reservation number
• sort by branch
• sort by customer name
• sort by customer phone
• sort by reservation date
• sort by start time
• sort by guest count
• sort by status
• sort by table assignment status
• sort by created date

List Actions

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

Action	Purpose
Show	Opens the reservation details page.
Edit	Opens the edit page when the reservation status allows editing.
Delete	Deletes the reservation when permission allows it.
Calendar	Opens the reservation calendar using the same reservation list permission.
Export	Exports reservation rows through the system export flow when export permission is available.

Row Click Behavior

Clicking a reservation row opens the details page only when the user has permission to view reservation details.

Reservation Calendar

The calendar view gives staff a month-based schedule for reservations.

Calendar Purpose

Use the calendar to:

• view reservations by date
• move between months
• return quickly to the current month
• see reservation start time, title, guest count, and status color
• open a reservation details page from a calendar event when permitted
• open a day dialog when a date has more reservations than the cell can show

Calendar Loading

The calendar loads reservations only for the visible month. When staff move to the previous or next month, the page requests reservations for that month’s date range.

Calendar Event Fields

Event Field	Purpose
Title	Shows the reservation number and customer name.
Start Time	Shows the reservation start time in the active locale format.
Guest Count	Shows how many guests are expected.
Status Color	Uses the reservation status color as a visual marker.

Create and Edit Form

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

The form is organized into these sections:

1. Reservation Information
2. Customer Information
3. Deposit
4. Table Assignment

The Deposit section appears only when deposit rules are enabled for the selected branch.

When creating a reservation, branch selection appears if the current user is not already assigned to a branch. When editing, the branch is not intended to be changed.

Field-by-Field Explanation

Reservation Information

Branch

Field	Purpose
Branch	Selects which branch owns the reservation. It controls the reservation settings, available tables, working hours, currency, deposit rules, and availability checks used for the booking.

Branch Notes

• Branch is required when the current user is not assigned to a branch.
• If the user is branch-assigned, the branch is taken from the user context.
• On update, branch is not intended to be changed.

Reservation Type

Field	Purpose
Reservation Type	Classifies the reservation for staff and reporting.

Available types:

Type	Purpose
Standard	Normal planned reservation.
Walk-In	Guest arrived or requested service without advance booking.
Large Party	Higher guest count reservation that may require stricter handling or a deposit.
Private Room	Reservation intended for a private room or dedicated seating area.
Event	Reservation tied to a special event or larger arrangement.
VIP	Reservation that requires special attention or priority handling.

Walk-in reservations are only allowed when the branch settings allow walk-ins.

Status

Field	Purpose
Status	Sets the initial operational status when creating a reservation.

The status field appears on create. On edit, status changes are handled from the details page using the Change Status dialog so the system can validate the transition and store history.

Reservation Date

Field	Purpose
Reservation Date	The date the guest is expected to come to the branch.

This field is required and must match the branch reservation settings:

• reservations must be enabled for the branch
• the date must be inside the allowed advance booking window
• the day must be enabled in branch working hours

Start Time

Field	Purpose
Start Time	The time the reservation begins.

The form can accept the admin time picker value, including 12-hour display. The backend normalizes it before validation and stores the operational time consistently.

Duration

Field	Purpose
Duration	The reservation length in minutes.

Duration affects:

• calculated end time
• availability checks
• table overlap checks
• buffer rules from Reservation Settings

The value must be at least one minute and cannot exceed one full day.

Guests

Field	Purpose
Guests	Total number of expected guests.

This value is required and affects:

• guest limit validation
• table capacity checks
• suggested table combinations
• large-party deposit rules

Adults

Field	Purpose
Adults	Optional number of adult guests.

Use this when staff want more detail than the total guest count.

Children

Field	Purpose
Children	Optional number of child guests.

Use this for service planning, seating setup, or child-friendly preparation.

Customer Information

Customer Name

Field	Purpose
Customer Name	Stores the guest name used throughout the reservation list, calendar, and details page.

This field is required and is used even when the reservation 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 and useful for follow-up, notification routing, and audit context.

Phone Country

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

The selected country works together with Customer Phone so phone validation can be accurate.

Customer Phone

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

This field is required and validated using the selected phone country.

Occasion

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

This helps staff prepare the correct service experience.

Special Requests

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

These notes are visible in reservation details and help staff prepare before the guest arrives.

Internal Notes

Field	Purpose
Internal Notes	Stores staff-only notes for handoff, operations, risk notes, or manager context.

Use this for information that should help the team but is not intended as a guest request.

Deposit

The Deposit card appears when Deposit Enabled is active in Reservation Settings for the selected branch.

Deposit Required

Field	Purpose
Deposit Required	Indicates whether this reservation requires a deposit.

If the reservation qualifies for the branch large-party deposit rule, this field is applied automatically and cannot be cleared manually.

Deposit Amount

Field	Purpose
Deposit Amount	The fixed deposit amount required for the reservation.

The amount uses the selected branch currency. When the large-party deposit rule applies, the amount comes from the branch Reservation Settings.

Deposit Paid Amount

Field	Purpose
Deposit Paid Amount	A read-only summary of deposit value recorded in the deposit ledger.

The form uses this value to calculate whether the deposit is unpaid, partially paid, paid, or overpaid. It cannot be entered or edited directly on the reservation form.

Deposit Summary

The Deposit card also shows:

Summary Item	Purpose
Deposit Amount	Shows the required amount formatted with currency.
Deposit Paid Amount	Shows how much has been recorded as paid.
Remaining Amount	Shows the unpaid difference when the paid amount is lower than the required amount.
Overpaid Amount	Shows the extra amount when the paid amount is greater than the required amount.
Payment Status	Shows the computed reservation payment status.
Currency Context	Shows the deposit currency and currency rate used by the reservation.

Recording a Deposit

Deposit money is recorded through the Reservation Deposit Transactions workflow, not by editing the reservation’s paid amount. This creates an append-only financial ledger and keeps the reservation payment summary in sync.

Transaction	Effect on held deposit	When to use it
Collection	Increases	Record money collected from the guest. A tender method is required.
Application	Decreases	Apply held deposit to an eligible order. An order is required.
Refund	Decreases	Return held deposit to the guest. A tender method is required.
Forfeiture	Decreases	Record a deposit retained under the business policy.
Reversal	Compensates the original transaction	Correct an eligible posted deposit transaction without changing its original record.

Every deposit action requires a positive amount, an economic date that is not in the future, a note, and an idempotency key supplied by the application. Reversals require an economic date, reason, and idempotency key. Use the deposit transaction list and its detail view to audit the reservation, linked order, tender method, balance changes, and any reversal.

Table Assignment

Table Assignment controls how tables are connected to the reservation.

Assignment Modes

Mode	Purpose
Assign Later	Saves the reservation without selected tables. Staff can assign tables later from the details page.
Assign Now	Requires staff to select one or more tables before saving.
Auto Assign	Lets the system choose the first available table combination that can fit the guest count.

Tables

Field	Purpose
Tables	Selects one or more seating-plan tables for manual assignment.

This field is available only when Assign Now is selected.

Capacity Summary

The form shows selected table capacity and compares it with the guest count.

Summary	Purpose
Guests	Shows the required capacity target.
Selected Tables	Shows how many tables are selected.
Selected Capacity	Shows the combined capacity of selected tables.
Capacity Warning	Warns staff when selected tables do not have enough capacity.

Check Availability

The Check Availability action validates the selected date, time, duration, guest count, assignment mode, and selected tables.

Availability checks include:

• branch reservation enablement
• advance booking window
• working hours
• duration limits
• guest limits
• table capacity
• table blocks
• overlapping reservations
• configured blocking statuses
• pending capacity behavior from Reservation Settings

Suggested Tables

When availability can be checked, the system can return suggested table combinations. Staff can apply a suggested combination when using manual assignment.

Reservation Details Page

The details page organizes the reservation into professional cards so staff can review all important information quickly.

Details Cards

Card	Purpose
Reservation Information	Shows reservation number, branch, status, reservation type, table assignment status, and assignment mode.
Schedule Details	Shows reservation date, start time, end time, start/end timestamps, duration, and lifecycle timestamps.
Customer Information	Shows guest contact details, guest counts, and occasion.
Table Assignment	Shows assigned tables, table capacity, table status, assignment user, assignment time, and assignment actions when allowed.
Payment Details	Shows payment status, deposit requirement, deposit amounts, remaining or overpaid amount, currency, and currency rate.
Notes	Shows special requests, internal notes, cancellation reason, rejection reason, and no-show reason when available.
Status History	Shows all recorded status changes with old status, new status, reason, note, changed by, and changed time.
System Information	Shows external reference, created by, created at, and updated at.

Status Actions on Details Page

The details page uses a Change Status action. Clicking it opens a dialog where staff choose the next valid status and optionally enter a reason or note.

Status Reason Fields

Field	Purpose
Status	The next status selected from the statuses allowed for the current reservation.
Reason	Explains why the status is being changed. Required for cancellation when branch settings require a cancellation reason.
Note	Optional internal note stored with the status log.

Status Validation Rules

• Terminal reservations cannot change status.
• Expired is created by system automation and is not available as a manual target status.
• Invalid status jumps are rejected.
• Cancellation must be allowed by branch settings.
• Cancellation can be blocked after the configured cancellation deadline.
• Cancellation reason is required when branch settings require it.
• Confirming, arriving, or seating can require an assigned table depending on Reservation Settings.

Table Assignment on Details Page

If the reservation status allows table assignment, staff can update tables from the details page.

Assigned Tables

Each assigned table shows:

Field	Purpose
Table Name	The seating-plan table connected to the reservation.
Capacity	The capacity of the assigned table.
Table Status	The current seating-plan table status.
Assigned By	The staff user who assigned the table.
Assigned At	The time the table was assigned.

Assignment Actions

Action	Purpose
Save	Saves the manually selected table assignment.
Auto Assign	Asks the system to choose an available table combination.

Table assignment is not available for terminal statuses.

Deposit and Payment Statuses

Reservation payment status is calculated from the deposit requirement and deposit amounts unless a special status is already stored.

Payment Status	Meaning
Not Required	No deposit is required for this reservation.
Unpaid	A deposit is required, but no amount has been paid.
Partially Paid	A deposit is required and some amount has been paid, but it is below the required amount.
Paid	The paid amount is equal to or greater than the required deposit amount.
Refunded	The reservation deposit was marked as refunded by system workflow.
Failed	The reservation deposit workflow failed or was marked failed.

Validation Rules

The reservation form enforces these key rules:

Field	Main Rules
Branch	Required based on user branch context.
Customer	Optional existing customer link.
Phone Country	Required and must be a supported country code.
Reservation Type	Must be one of the supported reservation types.
Status	Must be one of the supported reservation statuses when supplied.
Table Assignment Mode	Must be Assign Later, Assign Now, or Auto Assign.
Reservation Date	Required and must use YYYY-MM-DD.
Start Time	Required and normalized to HH:mm before backend validation.
Duration	Optional integer from 1 to 1440.
Guests	Required integer and must be at least 1.
Adults	Optional integer and cannot be negative.
Children	Optional integer and cannot be negative.
Customer Name	Required text from 2 to 255 characters.
Customer Phone	Required and must be valid for the selected phone country.
Customer Email	Optional valid email up to 255 characters.
Occasion	Optional text up to 255 characters.
Special Requests	Optional text up to 2000 characters.
Internal Notes	Optional text up to 2000 characters.
Tables	Optional array, but required when assignment mode is Assign Now.
Deposit Required	Optional boolean.
Deposit Amount	Optional numeric value and cannot be negative.
Deposit Paid Amount	Read-only ledger summary; it is not submitted by the reservation form.
External Reference	Optional text up to 255 characters.

Table Assignment Validation

• Assign Now requires at least one table.
• Assign Later must not submit table IDs.
• Auto Assign must not submit table IDs.
• Selected tables must exist and belong to the operational table flow.
• Availability must pass before the reservation can be saved.

How Reservation Settings Affect Reservations

Reservation creation and updates are controlled by branch Reservation Settings.

Settings can affect:

• whether reservations are enabled
• whether walk-in reservations are allowed
• default duration
• minimum and maximum duration
• minimum and maximum guest count
• advance booking limits
• working hours
• buffer minutes
• whether pending reservations block capacity
• table requirement on create, confirm, arrival, or seating
• auto-confirm behavior
• cancellation allowance, deadline, and required reason
• deposit enablement, amount, and large-party rules
• reminder and no-show automation

For detailed branch policy configuration, see Reservation Settings.

Recommended Workflow

For a normal staff workflow:

1. Open Reservations > Reservations.
2. Create a reservation or open an existing one.
3. Select the branch, date, start time, duration, and guest count.
4. Enter customer name and phone country/phone.
5. Add email, occasion, special requests, or internal notes when useful.
6. Choose the table assignment mode.
7. Run availability checks when assigning tables.
8. Save the reservation.
9. Use the details page to change status as the guest moves through the visit.
10. Review status history and assigned tables when auditing the reservation.

Practical Examples

Example 1: Standard Reservation

• Type: Standard
• Status: Pending or Confirmed
• Assignment Mode: Assign Later
• Deposit Required: No

This works when staff want to capture the booking first and assign seating closer to arrival.

Example 2: Confirmed Table Booking

• Type: Standard
• Status: Confirmed
• Assignment Mode: Assign Now
• Tables: selected manually

This works when staff already know where the guest should sit and want the table reserved immediately.

Example 3: Large Party With Deposit

• Type: Large Party
• Guest count reaches the branch large-party threshold
• Deposit enabled in Reservation Settings
• Deposit amount applied from the branch policy

This works for larger groups where the restaurant requires extra commitment before holding capacity.

Example 4: Walk-In

• Type: Walk-In
• Status: Arrived or Seated
• Assignment Mode: Assign Now

This works for guests who arrive without advance booking, as long as walk-ins are allowed by branch settings.