> ## Documentation Index
> Fetch the complete documentation index at: https://ecommos.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Notifications and queue configuration

> Enable push and in-app alerts for order assignments and queue activity.

# Notifications and queue configuration

Fast alerts reduce order latency. Without them, reps have to poll the queue. Get push working for every active user before you go live.

## In-app notifications

Every order assignment creates a notification record. The notifications inbox:

* Lists all notifications for the current user
* Supports unread filter and unread count
* Cursor-paginates through history
* Marks one or all notifications as read
* Deep-links to the related order workflow

Open the bell icon in the app shell to see your inbox.

## Push notifications

To get push on your device:

1. Open the app.
2. Accept the push permission prompt (or enable it in your browser/site settings if you missed the prompt).
3. The system registers a push token for your user.
4. The onboarding checklist item "Turn on order alerts" clears once a token is registered.

Push tokens are upserted by subscription token, so re-registering the same device does not create duplicates.

Handing a push to the browser's push service is not the same as the phone showing it. Once the service accepts the message, delivery and display are out of the app's hands — an Android phone in battery saver can hold a notification for hours. Alerts are sent at high urgency to ask for prompt delivery even while the phone is idle, but no push is guaranteed.

## Email backup for unread alerts

Because push can be delayed or dropped, low stock and overdue remittance alerts fall back to email. If one of those is still unread 15 minutes after it was created, the worker sends it to the recipient's verified email address.

* It only applies to low stock and overdue remittance. High-volume alerts like new orders stay in-app and push only.
* Read the alert within 15 minutes and no email is sent, so working the inbox normally costs you nothing.
* You can turn the email off per alert type on the notifications settings page.
* Only verified email addresses receive it.
* One person gets at most 10 of these emails a day. Bulk work like stocking many agents at once can produce a burst of alerts, and the cap keeps that burst out of your inbox. Anything held back still sits unread in the notifications inbox.

A repeated `unacknowledged_emails` count in the worker sweep log is worth investigating: it means alerts are reaching the push service but nobody is acting on them in the app.

## How assignment notifications are produced

When an order is assigned (or reassigned) to a rep:

1. The system writes an `order.assigned` (or `order.reassigned`) event to the order timeline.
2. The system creates an in-app notification for the rep.
3. The system creates an outbox record for the `notification.order_assigned` event.
4. A worker processes the outbox record and sends the push.
5. If push delivery fails, the worker marks the event as `failed` and can be retried.

The worker also resets stale `processing` events, so a crashed worker does not permanently block a notification.

## If notifications are not arriving

Walk this checklist in order:

1. **App permission for push** — the device/browser must allow notifications from the app origin.
2. **Push token registered** — check the notifications settings page for the current user's token status. If none, re-trigger registration by toggling notifications off and on.
3. **Staff is active** — inactive or on-probation staff do not receive assignment notifications.
4. **Product scope** — staff without product scope are skipped by round-robin, so no assignment event is produced.
5. **Outbox processing** — if the worker is backed up or `failed`, the in-app notification still appears, but push may lag. Check the notifications inbox first.
6. **VAPID / environment** — push delivery depends on VAPID configuration on the server. If only in-app works and push never fires across all users, this is a server-side config issue, not a device issue.
7. **Push arrived late, not never** — if the alert is in the inbox at the right time but reached the phone hours later, the app did its part and the phone held the notification. Check battery saver and background data for the browser, and keep the app installed to the home screen. For low stock and overdue remittance, the email backup covers this.

## What's next

* [Work the order queue](./order-queue)
* [Add staff and set product access](./staff-onboarding)