Escalation & Alerts

This guide covers how to configure automated order escalation alerts. When enabled, the system monitors your orders at each stage of the delivery pipeline and sends email notifications when orders are stuck longer than your configured thresholds.

Prerequisites

• You are logged in as a courier owner (or a team member with escalation write permission)
• Your courier application has been approved
• You have at least one active country configured
• You can access the Config Hub from the courier home screen

Steps

Step 1: Navigate to Escalation

Open the Config Hub and select the Country Operations tab. Tap Escalation to open the escalation settings screen.

Info

If you operate in multiple countries, use the country dropdown at the top of the Country Operations tab to select the country you want to configure escalation for. Settings are stored per-country — each country has its own escalation configuration.

Step 2: Enable order escalation

The Enable Order Escalation toggle at the top of the screen controls whether escalation monitoring is active. When toggled on, the subtitle reads:

"Receive email alerts when orders are stuck too long"

Toggle the switch to on to enable escalation for the selected country. All other configuration fields appear only when escalation is enabled.

Step 3: Add notification email recipients

Under Notification Emails, add the email addresses that should receive escalation summaries. The field description reads:

"Escalation summaries will be sent to these addresses."

To add an email:

1. Type the email address in the input field
2. Tap the + button or press Enter/Done on your keyboard
3. The email appears as a chip above the input field

To remove an email, tap the × icon on the chip.

Warning

At least one email address is required when escalation is enabled. Emails are stored as a comma-separated list. Each address is validated for correct email format before being added.

Step 4: Select a check schedule

Under Check Schedule, choose how often the system should check for stuck orders. The heading asks:

"How often should we check for stuck orders?"

Select one of the 6 predefined schedule presets:

Preset	Schedule
Daily at 8:00 AM	0 8 * * *
Twice daily (8 AM & 5 PM)	0 8,17 * * *
Every 6 hours	0 */6 * * *
Every 4 hours	0 */4 * * *
Weekdays at 8:00 AM	0 8 * * 1-5
Three times daily (8 AM, 12 PM, 5 PM)	0 8,12,17 * * *

Alternatively, select Custom to enter your own cron expression manually.

Tip

When Custom is selected, a text field appears with the label "Cron Expression" and helper text: e.g. "0 8 * * 1-5" = weekdays at 8 AM. The cron expression is validated on input.

Info

The system checks for overdue orders every 15 minutes internally. Your schedule determines when an email is actually sent if overdue orders are found during a check cycle.

Step 5: Select stages to monitor

Under Stages to Monitor, select which order stages should be watched and set the maximum acceptable wait time for each. The section description reads:

"Select stages and set how long is too long for each."

The 5 monitorable order stages are:

Stage	Label	Description
procurement_completed	Waiting for store delivery	Items bought, waiting to arrive at your depot
at_courier_depot	Sitting at your SA depot	Parcel received, not yet dispatched
in_transit	Taking too long in transit	Dispatched but hasn't reached destination country
at_country_depot	Stuck at destination depot	Arrived in-country, awaiting final delivery
on_route	Out for delivery too long	On the way to customer but overdue

For each stage:

1. Tap the checkbox to enable monitoring for that stage
2. When enabled, a Max wait (hrs) field appears below
3. Enter the number of hours after which the order should be flagged as overdue

Warning

At least one stage must be selected when escalation is enabled. The max wait value must be a positive number for each selected stage.

Step 6: Configure additional alert thresholds

Under Additional Alerts, configure thresholds for logistics blockers. The section description reads:

"Get alerted about logistics blockers"

The available additional thresholds are:

Alert	Description	Default	Unit
Document blockers	Orders blocked by missing passport, invoice, or weight	Toggle (on/off)	—
Shipments returning to source	Alert when return is pending too long	24	hours
Pending handovers	PIN handover not completed	4	hours
Failed deliveries	Unresolved after failed attempt	24	hours
Pickup point collection	Customer hasn't collected	3	days

• Document blockers is a simple on/off toggle
• The remaining four thresholds have a numeric input field where you specify the wait duration before an alert is triggered

Note

Threshold values must be positive numbers. Each threshold's unit is shown as a suffix in the input field — "h" for hours or "d" for days.

Step 7: Save settings

Tap the Save Settings button at the bottom of the screen to persist your escalation configuration. A confirmation message "Escalation settings saved" appears on success.

Info

If you do not have write permission for escalation settings, the button displays "Read Only" and is disabled. Only owners and team members with escalation write permission can modify these settings.

Result

After configuring escalation alerts:

• The system monitors orders in the selected stages for the configured country
• When an order exceeds its max wait threshold during a scheduled check, an email summary is sent to all configured recipients
• Additional alerts fire when their respective thresholds are exceeded (e.g., a pending handover older than 4 hours)
• Document blocker alerts trigger when orders are stuck due to missing passport, invoice, or weight information
• Settings are saved per-country — switching countries loads that country's escalation configuration
• Changes take effect immediately after saving

Troubleshooting

Issue	Cause	Solution
"At least one email is required" error	No email addresses added while escalation is enabled	Add at least one valid email address in the Notification Emails section.
"Select at least one stage to monitor" error	No stages checked while escalation is enabled	Enable at least one stage checkbox under Stages to Monitor.
Max wait threshold error	A selected stage has an empty or zero threshold value	Enter a positive number in the Max wait (hrs) field for each selected stage.
Invalid email format	Typed email doesn't match valid email pattern	Ensure the email follows the format name@domain.ext.
"Read Only" button shown	Your team role lacks escalation write permission	Ask your courier owner to grant escalation write permission to your role.
Cron expression validation error	Invalid custom cron syntax entered	Use standard 5-field cron format (e.g., 0 8 * * 1-5). Select a preset if unsure.
Settings not loading	Network error or service unavailable	Tap the Retry button on the error screen. Check your connection and try again.

Related Guides

• Revenue Reports — configure periodic revenue and performance report delivery