Notifications

Overview

Notifications configure how customers and staff receive updates about orders. Includes email notifications, SMS, and push notifications.

Key Purpose: Configure order notification settings.

Purpose

This system delivers real-time order notifications to KDS devices via Firebase Cloud Messaging (FCM) and sends transactional emails to customers for order status updates.

Key Concepts

• Firebase Cloud Messaging (FCM): Push notification service used to alert KDS devices about new and updated orders, using the Kreait SDK with device-specific tokens
• FCM Tokens: Device registration tokens stored in MongoDB (logs collection) linked to device IDs with platform info (Android/iOS) and last_used_at timestamps — stale tokens are auto-cleaned
• Push Order Event: The PushOrderEvent fires after payment completion, triggering the SendOrderNotification listener which runs asynchronously with 3 retries and 10-second backoff
• Firebase Realtime Database (RTDB): Used as a signaling layer — triggerKDSUpdate writes timestamps to /devices/{deviceId}/latest-order-timestamp for real-time KDS updates
• Transactional Emails: Order lifecycle emails (receipt, ready for pickup, out for delivery, delivered, missed delivery) sent via queued Mail jobs with CC support via receipt settings

Actions

Register FCM Token

Automatic — when a KDS device authenticates, its FCM token is registered via FCMService::registerToken(token, deviceId, platform). Duplicate tokens are deduplicated by token or device_id + platform.

Send Order Notification to KDS

Automatic — ProcessOrderJob fires PushOrderEvent after payment for non-Kassanet, non-Square orders. The SendOrderNotification listener sends FCM messages to all KDS devices at that location.

Send Customer Email

Automatic — EmailService sends queued emails for each order lifecycle event: receipts (with CC support), ready for pickup, out for delivery, delivered, missed delivery, verification codes, and more.

Trigger Menu Reload

The TriggerMenuReload listener handles ReloadMenu events by updating Cloudflare D1 constants and writing timestamps to Firebase RTDB for instant device updates.

Location

• Backoffice Route: /settings/notifications
• Backend Controller: app/Http/Controllers/Api/NotificationController.php

Customer Notifications

Order Confirmation Email

Property	Value
Field ID	order_confirmation_email
Label	Send Order Confirmation
Type	Toggle
Default	true

Description: Send email when order is placed.

Content Includes:

• Order number
• Items ordered
• Total amount
• Pickup/delivery time
• Location details

---

Order Ready Notification

Property	Value
Field ID	order_ready_notification
Label	Notify When Ready
Type	Toggle
Default	true

Description: Notify customer when order is ready.

Channels:

• Email
• SMS (if phone provided)

---

Order Status Updates

Property	Value
Field ID	status_updates
Label	Send Status Updates
Type	Toggle
Default	false

Description: Send updates as order progresses.

Statuses:

• Order received
• Preparing
• Ready for pickup
• Out for delivery
• Delivered

---

Staff Notifications

New Order Alert

Property	Value
Field ID	new_order_alert
Label	New Order Alerts
Type	Toggle
Default	true

Description: Alert staff when new order arrives.

Channels:

• KDS sound alert
• Email to manager
• Push notification

---

Low Stock Alert

Property	Value
Field ID	low_stock_alert
Label	Low Stock Alerts
Type	Toggle
Default	true

Description: Alert when item stock is low.

---

Email Settings

CC Email

Property	Value
Field ID	cc_email
Label	CC Email Address
Type	Email
Required	No

Description: Send copy of all order emails to this address.

Use Cases:

• Manager oversight
• Record keeping
• Backup notifications

---

Reply-To Email

Property	Value
Field ID	reply_to_email
Label	Reply-To Address
Type	Email
Required	No

Description: Email address for customer replies.

---

Business Logic

Notification Flow

Order placed
    │
    ▼
Send order confirmation email
    │
    ▼
Alert staff (KDS/email)
    │
    ▼
Order status changes
    │
    ▼
Status updates enabled?
├── Yes → Send update notification
└── No → Skip
    │
    ▼
Order ready
    │
    ▼
Send ready notification

---

Relations

Depends On

• Locations: Notifications per location
• Receipts: Email content settings

Affects

• Transactions: Order notifications
• Customers: Customer communication

Related Features

• Receipts
• Transactions

---

Business Rules

• Notifications are only sent to devices of type KitchenDisplay at the order's location — other device types do not receive FCM push notifications
• Invalid/unregistered FCM tokens are automatically removed when Firebase returns a NotFound error, keeping the token database clean
• The SendOrderNotification listener retries up to 3 times with 10-second backoff before failing (errors are logged, not thrown)
• There is no backoffice UI for configuring notification preferences — all notification behavior is hardcoded in the backend event/listener system
• CC recipients for order receipt emails are configured through receipt settings (getCcReceiptEmails()), not through a separate notification settings page

FAQs

• "Is there a notification settings page in the backoffice?" No. The NavBarNotifications component in the backoffice is a placeholder stub. Notification behavior is determined by backend events and listeners, not user-configurable settings.
• "What triggers a push notification to KDS?" When ProcessOrderJob completes for a non-Kassanet, non-Square order, it fires PushOrderEvent, which the SendOrderNotification listener picks up asynchronously.
• "What email notifications does the system send?" Order receipts, ready for pickup, out for delivery, delivered, missed delivery, verification codes, device activation codes, password resets, merchant invitations, backoffice OTP, and loyalty alerts.
• "How does the system handle stale FCM tokens?" When a send fails with UNREGISTERED/NotFound, the token is automatically deleted from the database. Tokens also track last_used_at for monitoring.
• "What is the difference between Firebase RTDB and FCM?" FCM sends push notifications to wake up KDS apps. RTDB provides a real-time signaling mechanism via timestamp writes that KDS apps listen to for immediate updates.

Troubleshooting

• KDS not receiving notifications → Verify the device type is set to KitchenDisplay. Check that the device's FCM token is registered and not stale. Confirm the order was processed successfully (not a Kassanet or Square order, which use different notification paths).
• Customer not receiving emails → Check the email service logs for delivery failures. Verify the customer's email address is valid. Check that SendGrid/SMTP is properly configured in environment variables.
• Duplicate notifications on KDS → FCM tokens may be registered multiple times. The system deduplicates by device_id + platform, but if a device re-registers with a new token without clearing the old one, duplicates can occur.

---

Examples

Standard Setup

{
  "order_confirmation_email": true,
  "order_ready_notification": true,
  "status_updates": false,
  "new_order_alert": true,
  "low_stock_alert": true,
  "cc_email": "manager@restaurant.com"
}

Full Notifications

{
  "order_confirmation_email": true,
  "order_ready_notification": true,
  "status_updates": true,
  "new_order_alert": true,
  "low_stock_alert": true,
  "cc_email": "orders@restaurant.com",
  "reply_to_email": "support@restaurant.com"
}