# Delivery Route Planner User Guide
This guide explains how to use Delivery Planner to create daily routes, assign work, and track delivery progress.
## Quick Start
1. Open Delivery Planner in Admin.
2. Choose the date using Today, Tomorrow, or the date picker.
3. Create one or more lists using the + button in Lists For The Day.
4. Set each list name, status, and driver.
5. Drag deliveries from Unassigned Deliveries into lists.
6. Open a list menu and select Suggest Route.
7. Review the route preview and click Accept Route.
8. Keep the page open for automatic 5-minute refresh updates.
## What You See On The Page
The planner has two main panels:
- Lists For The Day: Delivery lists for the selected date.
- Unassigned Deliveries: Orders not yet assigned to any list.
Each list card includes:
- List name
- List status
- Assigned driver
- Item count
- List actions menu
Each delivery item card includes:
- Order number, or Manual for manually added items
- Delivery time window
- Recipient and phone
- Address
- Product or notes summary
- Item actions menu
## Dates And Refresh
- The selected date controls all lists and deliveries shown.
- The planner refreshes every 5 minutes when left open.
- Auto-refresh is skipped while a save is in progress or a modal window is open.
## Daily Tasks
### Create A List
1. Click + in Lists For The Day.
2. A new draft list is created for the selected date.
3. Rename it if needed.
### Update List Details
You can edit directly on each list card:
- List name
- Status: Draft, Ready, With Driver, Complete
- Driver assignment
Changes save automatically.
### Add A Manual Delivery
1. Click + in Unassigned Deliveries.
2. Enter recipient, contact, address, delivery time, and notes.
3. Click Add Delivery.
Manual entries appear as Manual in the list.
### Assign And Reorder Deliveries
- Drag deliveries from Unassigned to a list.
- Drag deliveries between lists.
- Drag deliveries up or down within the same list.
When order changes, existing route snapshots for affected lists are cleared and should be regenerated.
## Menus And Actions
### List Menu Actions
| Action | What It Does |
|---|---|
| Suggest Route | Optimizes stop order for the list |
| Route From List Order | Builds a route using current list order |
| Delete List | Deletes the list only when it has no items |
### Delivery Item Actions
| Action | What It Does |
|---|---|
| Open Order | Opens order details in a new tab |
| Unassign Delivery | Moves the item back to Unassigned |
| Mark Order Delivered | Marks the delivery item as delivered |
## Route Preview And Save
After generating a route:
1. A preview modal shows map, stop order, distance, and estimated duration.
2. Click Accept Route to apply the route order.
3. A route snapshot is saved on the list card.
4. Approximate drive time is shown under the route image.
### Start And End Point Rules
- The planner uses the first configured shop address as the depot.
- Routes start at the shop and return to the shop.
- Snapshot map markers show the start in green and delivery stops in orange.
## Delivery Status Labels
- Awaiting
- On Van
- Delivered
- Returned
## Mobile App Status Sync
When a mobile app update changes a delivery list item:
- If changed to Delivered, the linked order status is set to Delivered.
- If changed from Delivered to anything else, the linked order status is set to Received.
## Troubleshooting
### Route generation shows a configuration warning
Cause: Mapbox is not configured.
Action: Ask your administrator to configure mapbox.api.
### Cannot delete a list
Cause: The list still has deliveries.
Action: Move or unassign all items first, then delete.
### Route image disappeared after moving items
Cause: Route snapshots are cleared after reorder and assignment changes.
Action: Regenerate and accept a new route.
### Open Order is missing for an item
Cause: Manual or non-standard items may not have a standard order ID.
Action: Open the order from regular order management screens if needed.
## Glossary
- Delivery List: A group of deliveries for a specific date.
- Unassigned: Deliveries not attached to any list.
- Route Snapshot: Saved static map image of an accepted route.
- Depot: Shop location used as route start and end point.