Delivery Add-on

The Delivery add-on manages branch delivery setup, delivery operations, own-fleet drivers, external courier providers, COD settlement, driver earnings, payout batches, HR payroll export, and driver payout issue review.

This documentation is written for end users, branch managers, dispatchers, finance users, payroll users, and delivery administrators. It explains how the feature works, how each section is used, and how to set up the add-on for real daily operations.

Who Can Access This Add-on

Access is permission-based. A user only sees pages and actions allowed by their role.

Core permission areas:

Area	Purpose
Operations	Delivery list, delivery details, dispatch monitor, assignment, retry, pause, and resume.
Driver Team	Driver records and driver earning rules.
Financials	COD settlements, driver earnings, payout batches, payout issues, payroll export, and financial analytics.
External Courier	Courier providers, provider settings, quotes, and dispatch request logs.
Configuration	Delivery settings, zones, pricing rules, and peak surcharge rules.
Driver Panel	Driver dashboard, assigned deliveries, delivery history, earnings, and payout issue history.

Navigation Map

In Admin > Delivery, the add-on is grouped into:

• Delivery Dashboard
• Operations
  • Deliveries
  • Dispatch Monitor
• Driver Team
  • Drivers
  • Driver Earning Rules
• Financials
  • COD Settlements
  • Provider Settlements
  • Driver Earnings
  • Payout Batches
  • Payout Issues
  • Financial Analytics
• External Courier
  • Courier Providers
  • Provider Settings
  • Quote History
  • Dispatch Request Log
• Configuration
  • Delivery Settings
  • Delivery Zones
  • Pricing Rules
  • Peak Surcharges

In the Driver Panel, drivers use:

• Driver Dashboard
• My Deliveries
• Delivery History
• Earnings
  • My Earnings
  • Issue History

Recommended Setup Workflow

Follow this order for a clean setup:

1. Configure branch-level Delivery Settings.
2. Create Delivery Zones.
3. Create Pricing Rules for delivery fees.
4. Add optional Peak Surcharges for busy windows.
5. Configure Courier Providers and Provider Settings if external courier dispatch is used.
6. Create or link Drivers for own-fleet delivery.
7. Create Driver Earning Rules if drivers are paid delivery incentives.
8. Configure HR Payroll Components if delivery earnings will be exported to payroll.
9. Assign Delivery permissions to admin roles and driver-panel access to drivers.
10. Test the full flow with one order: create delivery, assign or dispatch, complete delivery, review earnings, approve earnings, and settle payout.

Delivery Workflows At A Glance

Current external provider status

Own-fleet delivery is the currently complete operational delivery path. External courier provider settings and setup screens are available, but live external provider integration is not fully completed yet because integration information and credentials from external courier companies were not available. The system is prepared for adding external providers once those integration details are obtained.

Production Recommendation Options

Choose one of these options before using Delivery in a live environment.

Option	Recommendation	Best For
Own-fleet only	Recommended for production now.	Businesses using internal delivery drivers.
Own-fleet with payroll	Recommended for production when HR payroll is configured.	Businesses that pay drivers through HR payroll runs.
Own-fleet with payout batches	Recommended for production when finance settles drivers directly from Delivery.	Businesses that do not want HR payroll posting yet.
External courier framework	Use for setup/testing only until real provider integration details are available.	Businesses preparing future courier integrations.
Live external courier	Do not enable for production until provider API credentials, quote/dispatch contract, webhook contract, and status mapping are implemented and tested.	Businesses with confirmed courier integration agreements.

Operational recommendation:

• The Laravel Scheduler must be running in production. If the scheduler is not running, assignment timeouts, automation recovery, and SLA sweeps will not execute.
• Run delivery:sweep-driver-assignment-timeouts every minute so ignored driver assignments are released quickly.
• Run delivery:sweep-automation-timeouts every five minutes for provider timeout recovery and own-fleet retry recovery.
• Run delivery:sweep-sla every five minutes for SLA monitoring.
• Monitor scheduler failures in production; assignment timeout processing is operationally important for own-fleet delivery.

Own-fleet delivery

1. Order creates a delivery.
2. Delivery is assigned to an internal driver.
3. Driver accepts, picks up, and completes the delivery.
4. Driver earning rules create pending earning entries.
5. Admin approves earning entries.
6. Finance settles through payout batch or HR payroll export.

External courier delivery

1. Order creates a delivery.
2. System requests quote or dispatch from configured provider.
3. Provider accepts or rejects the request.
4. Provider status is tracked through request logs, sync, or webhooks.
5. COD settlement is reviewed if provider collected cash.

Driver payout

1. Earnings start as pending.
2. Admin approves valid earnings.
3. Approved earnings are paid directly through payout batches or exported to HR payroll.
4. Exported payroll earnings become paid only after manual Delivery sync from a paid HR payroll run.
5. Drivers can report payout issues on approved, exported-to-payroll, or paid entries.

Feature Pages

Use the pages below for detailed setup and daily workflow instructions.

Page	Use It For
Delivery Dashboard	Operational KPIs, status monitoring, and SLA visibility.
Configuration	Delivery settings, zones, pricing rules, and peak surcharges.
Operations	Deliveries, delivery statuses, dispatch monitor, and own-fleet delivery flow.
External Courier	Providers, provider settings, quote history, and dispatch request logs.
Drivers and Earning Rules	Driver setup and advanced driver earning rule configuration.
COD Settlements	Driver/provider COD declaration, reconciliation, disputes, and finalization.
Provider Settlements	Provider COD and fee settlement batches, posting, and controlled reversal.
Driver Earnings	Earning entries, approval, voiding, exports, and activity history.
Payout Batches	Grouping approved earnings, approval, cancellation, history, and direct payout.
Payroll Integration	Exporting delivery earnings to HR payroll and syncing paid payroll runs.
Payout Issues	Driver issue reporting and admin review workflow.
Driver Panel	Driver dashboard, deliveries, history, My Earnings, and Issue History.

Best Practices

• Configure branch settings, zones, and pricing before accepting delivery orders.
• Test external provider credentials in sandbox before production use.
• Keep driver records linked to HR employees if payroll export will be used.
• Use clear earning rule scopes and avoid overlapping active rules.
• Approve driver earnings regularly so payout balances stay accurate.
• Use payout batches when finance reviews many earnings together.
• Use payroll export only after HR payroll periods and runs are prepared.
• Keep COD settlements reconciled before finance close.
• Resolve payout issues with clear resolution notes for audit history.