Order Notifications

TimberCloud keeps your team and customers informed with a comprehensive notification system. Notifications are sent automatically when key order events occur, through multiple channels based on user preferences.

Notification Channels

TimberCloud supports three notification channels:

Each user can configure their preferences for each channel and notification type.

Notification Events

Order Lifecycle Notifications

These notifications are triggered automatically when order events occur:

Payment Notifications

Who Receives Notifications

Notification Recipients

When an order event occurs, notifications are sent to:

1. Customer Users — All users linked to the customer profile
2. Company Users — Based on role and settings:
   • Admins — All order notifications (unless disabled)
   • Sales Reps — Only for their assigned customers' orders
   • Production Staff — Based on notification preferences
   • Shipping Staff — Shipping-related events only

Sales Rep Filtering

Sales representatives only receive notifications for:

• Orders assigned to them directly
• Their customers' orders (via sales_rep_instance)

This prevents notification overload and keeps focus on relevant orders.

Real-Time Delivery

Socket-Based Notifications

In-app notifications are delivered instantly via WebSocket connections:

1. Event Occurs — Order status changes, payment received, etc.
2. Notification Created — Record stored in database
3. Socket Emission — Pushed to all connected clients
4. UI Update — Bell icon shows new notification count
5. Notification Panel — User can view and dismiss notifications

How Socket Delivery Works

Server: Order status changed to "Shipped"
   │
   ├─▸ Create notification record in database
   │
   ├─▸ Find all connected sockets for recipient users
   │
   ├─▸ Emit "notification" event to each socket
   │
   └─▸ Client receives and displays notification

Real-Time Updates to Storefront

Customer-facing notifications also flow to the embedded storefront:

• Order status changes update instantly
• Customers see real-time order tracking
• No page refresh required

Configuring Notifications

User Notification Settings

Each user configures their own notification preferences:

1. Navigate to Settings → Account → Notifications
2. For each notification type, toggle:
   • In-App — Show in notification bell
   • Email — Send to registered email
   • SMS — Text to mobile number

Per-Company Settings

Notification preferences are stored per company, allowing users who work with multiple companies to have different settings for each.

Notification Types

Configure notifications for these event categories:

Email Notifications

Email Templates

Email notifications use designed templates that include:

• Company branding (logo, colors)
• Order summary and status
• Customer and shipping information
• Action buttons (View Order, Track Shipment)
• Unsubscribe link

Email Content

A typical order notification email contains:

Subject: Order #12345 was created

Hi [Customer Name],

Your order #12345 has been created and is pending review.

Order Summary:
- Product A (qty: 5)
- Product B (qty: 10)

Total: $1,250.00

[View Order Button]

Thank you for your business!
[Company Name]

Reply-To Address

Emails are sent from TimberCloud's platform but:

• Reply-to is set to the company's email address
• Customer replies go directly to your company
• Ensures seamless communication

SMS Notifications

Setting Up SMS

To receive SMS notifications:

1. Add mobile number to your user profile
2. Enable SMS for desired notification types
3. Verify your phone number

SMS Content

SMS messages are concise:

TimberCloud: Order #12345 was shipped!
Track at: [tracking link]

SMS Limitations

• Limited to text content only
• Shorter messages than email
• Standard carrier rates may apply

In-App Notifications

Notification Bell

The notification bell in the Admin Panel header shows:

• Red badge — Number of unread notifications
• Dropdown panel — List of recent notifications
• Mark as read — Click to dismiss

Notification Panel Contents

Each notification displays:

• Notification message
• Timestamp (relative: "2 hours ago")
• Source user (who triggered it)
• Order link (click to open order)

Managing Notifications

• Mark Individual as Read — Click the notification
• Mark All as Read — Button in notification panel
• Notification History — View older notifications

Seen/Unseen Logic

Notification Marking

Notifications use intelligent seen/unseen logic:

• Initiator sees as "seen" — If you create an order, you don't get an "unread" notification for it
• Others see as "unseen" — Team members get unread notifications
• In-app disabled = seen — If user disabled in-app, marked as seen

Why This Matters

This prevents:

• Getting notified for your own actions
• Notification clutter from your own activity
• Confusion about what needs attention

Notification Flow Example

Here's what happens when a customer places an order via the storefront:

1. Customer completes checkout
   │
   ├─▸ Order created in database (status: "Ordered" or "Quote")
   │
   ├─▸ orderNotification() called with "order_created" type
   │
   ├─▸ Find all associated users:
   │   ├─▸ Customer users (linked to customer profile)
   │   └─▸ Company users (non-customer roles)
   │
   ├─▸ For each user:
   │   │
   │   ├─▸ Check notification_settings for this company
   │   │
   │   ├─▸ If in_app enabled:
   │   │   ├─▸ Create notification record
   │   │   ├─▸ Emit to user's socket(s)
   │   │   └─▸ User sees bell icon update
   │   │
   │   ├─▸ If email enabled:
   │   │   └─▸ Send templated email
   │   │
   │   └─▸ If SMS enabled:
   │       └─▸ Send text message
   │
   └─▸ Emit order update to company room (storefront real-time)

Admin Panel Real-Time Updates

New Order Alerts

When a new order is placed:

1. Socket Event — admin:new-order emitted
2. Toast Notification — Brief popup shows "New Order!"
3. Order List Update — New order appears at top
4. Bell Badge — Count increments

Order Status Updates

When order status changes:

1. Socket Event — admin:order-status-update emitted
2. Status Badge — Updates in order list
3. Order Detail — Timeline updates
4. Dashboard — Production board refreshes

Storefront Real-Time Updates

Customer Portal

Customers see real-time updates in their order portal:

• Status changes update instantly
• Tracking information appears when added
• No page refresh needed

Event Types

Troubleshooting

Not Receiving Notifications

If you're not getting notifications:

1. Check Settings — Verify notifications are enabled for that type
2. Check Channel — Ensure email/SMS is configured
3. Check Role — Sales reps only get their customers' notifications
4. Check Connection — In-app requires active socket connection

Email Not Arriving

If emails aren't being received:

1. Check spam/junk folder
2. Verify email address in profile
3. Ensure email notifications are enabled
4. Check company email configuration

SMS Not Arriving

If SMS messages aren't being received:

1. Verify mobile number format (include country code)
2. Ensure SMS is enabled for that notification type
3. Check carrier isn't blocking messages
4. Verify phone number is verified

Too Many Notifications

If you're getting too many notifications:

1. Review notification settings
2. Disable types you don't need
3. Consider using in-app only for less critical events
4. Sales reps: Only assigned orders trigger notifications

Best Practices

For Company Admins

1. Configure defaults — Set sensible defaults for new users
2. Train staff — Ensure everyone understands notification settings
3. Monitor delivery — Check that emails are arriving
4. Review templates — Customize email templates with branding

For Sales Teams

1. Enable order notifications — Stay informed about customer activity
2. Use SMS for urgent — Critical orders sent via text
3. Check regularly — Don't let notifications pile up
4. Respond quickly — Customers expect fast responses

For Customers

1. Configure preferences — Set channels that work for you
2. Keep contact info current — Ensure email and phone are accurate
3. Check order portal — Real-time status available anytime

Next Steps

• Order Settings
• Account Settings
• Customer Management
• Embedded Storefront