Table QR Ordering
The Table QR Ordering feature lets dine-in customers scan a table QR code, browse the active menu for that table's branch, build a cart, and send an order into the existing POS workflow.
This feature is designed for table service. Payments remain handled by staff through the normal POS and table workflow.
Where It Fits
Table QR Ordering connects these parts of Forkiva:
- Tables – Each table has a QR link with a table UUID and token.
- Menus – Customers see products from the active menu for the table's branch.
- POS Sessions – A POS session is required only when the customer sends the order.
- Orders – Submitted QR orders become dine-in orders linked to the table.
- Kitchen Viewer – Confirmed QR orders can appear in the kitchen workflow.
- Settings – Admins control whether QR ordering, notes, discounts, guest count, and auto-send behavior are enabled.
Setup Checklist
Before printing QR codes for guests, confirm the following:
- The table is active and assigned to the correct branch, floor, and zone.
- The branch has an active menu with visible products and categories.
- Settings > Table QR Ordering is configured.
- At least one POS register session can be opened for the branch before customers submit orders.
- The table QR code is printed from the table QR card or table show page.
Table QR Ordering Settings
Open Settings > Table QR Ordering to configure the feature.
| Setting | Description |
|---|---|
| Enable table QR ordering | Turns customer QR ordering on or off globally. |
| Auto-send QR orders to kitchen | When enabled, submitted orders are created as confirmed and can go to the kitchen. When disabled, orders wait for staff confirmation. |
| Require guest count | Requires customers to enter the number of guests before submitting. |
| Allow customer notes | Allows customers to add a note for staff. Notes are limited to a safe length. |
| Allow discount code | Shows or hides the discount-code field in the customer cart. |
| POS session selection | Controls which open POS session is used when submitting: latest opened by default, or earliest opened. |
| QR cart expiry minutes | Controls how long the customer's QR cart remains valid. The default is 120 minutes. |
QR Code Management
Admins can manage table QR codes from the tables list or table show page.
The QR card shows:
- QR status.
- Masked token.
- Last regenerated date.
- QR code preview.
- Copy QR link.
- Print QR.
- Download QR.
- Regenerate QR.
When Regenerate QR is used, previously printed or shared links for that table become invalid. Print and place the new QR code after regeneration.
Customer Ordering Flow
Customers open:
text
/table-order/{table_uuid}?token=...From the mobile-friendly ordering page, customers can:
- View the branch and table name.
- Browse categories and products from the table branch's active menu.
- Select product options and modifiers.
- Add, update, and remove only items in their current QR cart.
- Apply a discount code if the setting is enabled.
- Enter guest count if required.
- Add a customer note if allowed.
- Send the order.
- Track the active table order after submission.
The customer cannot edit older POS items already attached to the table order. The public page shows only the current QR cart plus a read-only tracking view for the active table order.
Submit Rules
Submitting an order requires an open POS session for the table branch. Customers can still browse and build a cart before the session is opened, but sending the order is blocked until a session is available.
Forkiva handles table status as follows:
| Table state | Result |
|---|---|
| Available table | Creates a new unpaid dine-in order. |
| Occupied table with exactly one active unpaid dine-in order | Appends the current QR cart items to that order. |
| Occupied table with no active unpaid dine-in order | Rejects the submit and asks the customer to contact staff. |
| More than one active unpaid dine-in order | Rejects the submit and requires staff help. |
| Merged, reserved, cleaning, inactive, or unavailable table | Rejects the submit. |
Order Status Behavior
The Auto-send QR orders to kitchen setting controls the created order status:
- Enabled – The order is created as confirmed and can appear in Kitchen Viewer.
- Disabled – The order is created as pending and waits for staff confirmation in POS.
In both cases, the table is treated as occupied after a successful dine-in order.
Staff Visibility
QR orders are marked with the Table QR source so staff can identify customer-submitted orders.
Staff can see QR-related information in the POS and order workflow, including:
- Order source.
- Guest count.
- Customer note.
- QR-originated order badge or source label where available.
- Kitchen visibility when the order is confirmed.
Tracking an Order
If there is an active unpaid order for the table, the customer page shows a Track order action in the header. The tracking dialog displays:
- Order number.
- Current order status.
- Item count.
- Order total.
- Progress by product status.
- Products, quantities, selected options, and item statuses.
The tracker is read-only. Customers cannot edit submitted or older order items from this view.
Protection and Reliability
Table QR Ordering includes several safeguards:
- Token-protected links – Each table QR link includes a token.
- Regenerate QR – Staff can invalidate old links by regenerating the QR token.
- Rate limits – Public context, cart, and submit endpoints are rate-limited.
- Cart expiry – Customer carts expire based on the configured expiry setting.
- Submit idempotency – Duplicate submit clicks reuse the same response or reject mismatched repeated payloads.
- Cart mutation locks – Cart changes and submit actions are locked to reduce duplicate or conflicting writes.
- Audit events – Important QR events are logged for support and investigation.
Common Issues
Customer Sees "Ordering Is Temporarily Unavailable"
Check:
- Table QR Ordering is enabled in settings.
- The table is active.
- The QR link token is valid.
- The table is not merged, reserved, cleaning, or unavailable.
- A POS session is open if the customer is trying to submit.
Products Are Missing
Check:
- The table belongs to the correct branch.
- The branch has an active menu.
- Products are active and assigned to visible categories.
- Product availability rules allow them to appear.
Customer Cannot Submit
Check:
- A POS session is open for the branch.
- Required guest count is entered.
- Product options are valid.
- The cart has not expired.
- The table does not have conflicting active unpaid orders.
Discount Field Is Hidden
Enable Allow discount code in Settings > Table QR Ordering.
Old Printed QR Code Stops Working
The QR token was likely regenerated. Print the latest QR code from the table QR card.