HandyCafe Docs
owner cashier

Orders

The Orders tab is the live dashboard for every cafeteria order placed by your customers. It polls the cloud every 3 seconds and shows new activity with a desktop notification, an audio alert, and a pending-count badge on the tab header.

Layout

The Orders page has two areas:

Area Purpose
Status Tabs Filter by order state: all, placed, confirmed, preparing, ready, served. Cancelled and refunded orders are filtered out by default.
Order List One card per order, grouped by most recent first. Each card shows the table code, customer phone if provided, items, totals, and action buttons.

Live Polling

The Orders dashboard polls /v1/cafeteria/admin/orders/poll every 3 seconds. Every new order triggers:

  1. A desktop notification with the table code and item count.
  2. An audio alert on the server speakers if sound notifications are enabled in Settings > Cafeteria.
  3. An increment of the pending-count badge on the Orders tab.
  4. An auto-print of the receipt if the printer is configured with Auto Print on New Order.

The badge remains visible until every order with placed or confirmed status is advanced to a later state or dismissed. The badge is globally visible on the Cafeteria section of the sidebar; you do not have to keep the Orders tab open to see it.

Order Lifecycle

Every order moves through a defined sequence of states.

State Meaning
placed The customer submitted the order. No staff action yet.
confirmed Staff acknowledged the order.
preparing The kitchen is working on the order.
ready The order is ready for service or pickup.
served The order has been delivered to the customer.
cancelled The order was cancelled by staff. It is removed from live views but retained for history.
refunded A post-payment refund has been issued.

The action bar on each order card shows the next available state. Advancing is one click. The UI uses an optimistic update pattern: the new status is displayed immediately. If the server rejects the change, the status reverts and an error notification appears.

Per-Item Status

Some orders have multiple items that finish at different times. For example, a burger is ready before a pizza. Per-item status lets you track each line independently.

Each item has its own dropdown with five options: placed, preparing, ready, served, cancelled. Each item also carries three timestamps:

  • created_at is set when the order arrives.
  • ready_at is set the first time the item enters ready.
  • served_at is set when the item enters served.

The customer menu shows a badge next to each line so the customer can see which items are ready or on the way.

Cancelling an Order

  1. Open the order card.
  2. Click Cancel.
  3. Confirm in the dialog that appears.
  4. The order transitions to cancelled. It remains in the history but disappears from the default live view.

Cancellation is a full-order action. To cancel a single line, change that line's per-item status to cancelled instead.

Settlement (Settle Check)

Settlement closes every open order on a table in one step. Use this when the customer is leaving and wants to pay the whole bill.

  1. Open the table from the Tables page or the Floor Plan action menu.
  2. Click Settle Check.
  3. The modal lists every order on the table that is not already served.
  4. Pick a payment method. Options are: Cash, Card, Online, Other.
  5. Confirm.

The server performs the following actions atomically:

  • Every open order on the table transitions to served with payment_status=paid.
  • A cafeteria_settlements record is created with the total amount, payment method, and creation time.
  • A settlement-orders audit trail records which orders belong to this settlement.
  • The table security code is expired so the QR becomes invalid.
  • The table returns to idle.

If you chose Online as the payment method, the settlement record is marked as online-paid. No Stripe charge is triggered by this action. Online payment on the customer side is handled at order placement; the settlement action records the cash flow for your books.

Opened-At Timer

Each table carries an opened_at timestamp set when the customer is seated. The Floor Plan and Tables pages display a live timer since that moment. This helps staff spot tables that have been active for a long time without ordering, or tables that might be approaching a session end.

The timer resets to zero on Close Table or Settle Check.

Dynamic Preparation Time Display

When dynamic preparation time is active for a product, the order card shows the estimate next to the item name. Staff see the estimate even when the Show Prep Time on Menu toggle is off for customers.

The estimate updates every time a new order is placed and every time an order completes. The system learns from your actual kitchen pace.

New Order Notification Behavior

Notifications are triggered app-wide, not per-tab. This means you receive alerts when you are browsing another part of the HandyCafe server, for example the Admin Panel or Settings. The audio alert is enabled or disabled from Settings > Cafeteria > Sound Notification.

Desktop notifications require that the operating system has granted notification permission to HandyCafe. If you do not see a notification after a new order, check your OS notification settings.

Tips

  • Use the Status Tabs to split workload. One screen filtered to preparing shows the kitchen queue. Another screen on ready shows what needs delivery.
  • Settle Check is the fastest way to close a table. Use Cancel on individual orders only for explicit mistakes.
  • Train staff to advance status consistently. The dynamic preparation time estimator learns from these signals, so skipping states reduces its accuracy.
  • Audit cancelled and refunded orders periodically from the admin endpoint to catch staff error patterns.