Skip to content

Routes Documentation

Menu Location: Settings > Routes

Access Level: Manager / Administrator

Last Updated: 2026-03-01

Overview

The Routes page manages delivery routes and service areas for your subscription business. Routes determine which customers can be served, what day they receive deliveries, and how orders are organized for fulfillment and driver assignments.

Primary Functions:

  • Create and manage delivery routes with specific days
  • Define service areas using zip codes or geofencing
  • Assign delivery days to customer locations
  • Configure route capacity and limits
  • Link routes to drivers and delivery windows

Page Layout

Header Section

  • Page Title: Routes management
  • Add New Button: Create new routes
  • Bulk Actions: Tools for managing multiple routes

Main Content Area

Routes are displayed in a sortable table showing route name, delivery day, service area details, and assigned drivers. Each route can be edited inline or through a detailed edit view.

Route Configuration

Individual route settings include delivery day, service area definition, capacity limits, auto-routing settings, and driver assignments.

Route Types & Configuration

Basic Route Settings

Routes are the core organizational unit for deliveries and determine what day customers receive their orders.

Key Fields:

  • Name: Identifier for the route (e.g., "Monday Downtown", "Tuesday North")
  • Day: Which day of the week deliveries occur (1-7 for Monday-Sunday)
  • Auto Route: Whether this route is automatically assigned during signup
  • Active Status: Whether route accepts new customers

Service Area Definition

Routes define service areas in two ways:

Zip Code Assignment (Most Common)

  • Customers in specific zip codes are assigned to the route
  • Managed through the Zip Codes page
  • Each zip can be assigned to one route

Geofencing (Advanced)

  • GPS boundaries define the service area
  • Customers' addresses are checked against polygon boundaries
  • Useful for complex service areas not defined by zip codes
  • Requires zone_boundaries GeoJSON data in routes table

Route Day Assignments

How Route Days Work

The day field determines delivery day:

  • 1 = Monday
  • 2 = Tuesday
  • 3 = Wednesday
  • 4 = Thursday
  • 5 = Friday
  • 6 = Saturday
  • 0 or 7 = Sunday (varies by system)

Master Day Routes

Each delivery day should have one "master" route named after the day (e.g., route named "Monday" for Monday deliveries). The system uses these master routes for certain automated processes.

Special Routes

  • Pending Route: Usually ID 1, for customers without assigned route
  • Shipped Route: For orders fulfilled via shipping instead of delivery
  • Hold Routes: Temporary holding areas during route changes

Auto-Routing System

How Auto-Routing Works

When customers sign up, the system automatically assigns them to a route based on their address:

  1. Zip Code Match: System looks up zip in zip_codes table
  2. Route Assignment: Returns associated route ID
  3. Geofence Check (if enabled): Validates address is within route boundaries
  4. Fallback: If no match, customer goes to pending/default route

Auto-Route Flag

Routes with auto_route = 1 are available for automatic assignment. Routes with auto_route = 0 are manual-only (useful for special routes or areas under construction).

Route Limits & Capacity

Configuring Route Capacity

Routes can have maximum order limits to prevent overloading:

Limit Types:

  • Order Count Limit: Maximum orders per delivery day
  • Box Count Limit: Maximum total boxes (accounts for customers ordering multiple boxes)
  • Stop Count Limit: Maximum delivery stops
  • Time-Based Limits: Routes close when capacity reached

When Limits Are Reached

The system can:

  • Prevent new signups in that zip code
  • Offer alternative delivery days
  • Show "Service area full" message
  • Add customers to waitlist

Driver Assignment

Linking Routes to Drivers

Routes can be assigned to specific drivers for the delivery app and reports:

Assignment Methods:

  • Fixed Assignment: Driver always assigned to route
  • Weekly Assignment: Driver assigned per weekly cycle
  • Dynamic Assignment: Driver chosen day-of-delivery

Driver Data Location:

  • routes_data table stores weekly driver assignments
  • Links route to driver for specific weekly_cycle_id
  • Used by driver report and delivery app

Common Use Cases

Use Case 1: Create New Route for Expansion Area

Goal: Add a new Tuesday route for a newly serviced neighborhood

Steps:

  1. Go to Settings > Routes
  2. Click "Add New Route"
  3. Enter name: "Tuesday Westside"
  4. Set Day: 2 (Tuesday)
  5. Set Auto Route: 1 (enabled)
  6. Set Active: Yes
  7. Save route
  8. Go to Settings > Zip Codes
  9. Assign relevant zip codes to the new route
  10. Test with a sample signup address

Example: You're expanding to serve zip code 90210. Create route "Tuesday Hills", set day = 2, then assign zip 90210 to this route in the Zip Codes page.

Use Case 2: Balance Overloaded Route

Goal: Split a busy route into two routes on different days

Steps:

  1. Identify zip codes in the overloaded route
  2. Create new route on less busy day
  3. Reassign half the zip codes to new route
  4. Run route restoration to move existing customers
  5. Communicate change to affected customers
  6. Monitor order counts on both routes

Tips:

  • Choose zip codes geographically clustered
  • Consider keeping neighborhoods together
  • Update delivery day in customer emails before change
  • Use route limits to prevent future overload

Use Case 3: Seasonal Route Adjustment

Goal: Temporarily adjust route capacity for holiday season

Steps:

  1. Navigate to Routes page
  2. Edit busy routes
  3. Adjust route limits upward for holiday period
  4. Save changes
  5. After holiday, restore normal limits

Tips:

  • Track route performance with Driver Report
  • Consider adding temporary weekend routes
  • Communicate expected delivery windows to customers

Integration with Other Pages

Routes are connected to:

  • Zip Codes Page (admin-edit.php?table=zip_codes): Assigns zip codes to routes
  • Subscriptions: Customers are assigned to routes
  • Orders (cust_order table): Orders inherit route from subscription
  • Drivers: Routes assigned to drivers for delivery
  • Delivery Windows: Time slots available by route
  • Weekly Cycle: Routes used to batch orders by delivery day

Typical Workflow:

  1. Create route on Routes page
  2. Assign zips on Zip Codes page
  3. Customers sign up and auto-assigned to route
  4. Orders generated with route assignment
  5. Driver Report shows orders by route

Troubleshooting

Customer Not Getting Assigned to Route

Symptoms: Customer signup shows "outside delivery area" or goes to pending route

Solutions:

  1. Check zip code is in zip_codes table
  2. Verify zip code has route assigned
  3. Ensure route has auto_route = 1
  4. If using geofencing, verify address geocodes correctly
  5. Check route is active

Common Causes:

  • Zip code not in system
  • Typo in zip code entry
  • Geofence boundaries incorrect
  • Route set to manual-only

Orders Appearing on Wrong Day

Symptoms: Customer assigned to Tuesday route but order shows Wednesday

Check:

  1. Customer's current route assignment in subscriptions table
  2. Route's day field is correct
  3. No manual route overrides on order
  4. Weekly cycle generated correctly

If Problem Persists: May need to run route restoration function to reset customers to master day routes

Route Changes Not Reflecting

Symptoms: Changed route settings but customers still assigned to old route

Solutions:

  1. Clear APC cache (route data is cached)
  2. Check if changes saved (verify in database)
  3. Existing customers need manual route update
  4. New zip assignments only affect new signups
  • Zip Codes (admin-edit.php?table=zip_codes) - Assign zip codes to routes
  • Drivers (admin-edit.php?table=drivers) - Manage delivery drivers
  • Delivery Windows (delivery-windows.md) - Set time slots by route
  • Driver Report (driver-report.php) - View orders and performance by route
  • Weekly Cycle (weekly-cycle.php) - Batch orders for delivery
  • Subscriptions (subscriptions.php) - View customer route assignments

Permissions & Access

Required Access Level: Manager or higher

Access Level Capabilities:

  • Customer Service: View only, cannot edit routes
  • Manager: Create and edit routes, assign zips
  • Administrator: All manager capabilities + delete routes
  • Kiva Admin: All features + geofencing configuration

Restricted Features:

  • Delete Route: Requires Administrator
  • Geofencing Setup: Requires Kiva Admin
  • Route Formula Changes: Requires Kiva Admin

Best Practices

Route Planning

  1. Name routes clearly (include day and area)
  2. Keep geographic areas logical and contiguous
  3. Plan for future growth when setting boundaries
  4. Use route limits to maintain service quality

Capacity Management

  • Monitor weekly order counts by route
  • Adjust limits seasonally
  • Split routes before reaching 80% capacity
  • Consider driver efficiency when setting limits

Route Organization

  • One master route per delivery day
  • Special routes clearly labeled (Shipped, Pending, Hold)
  • Geographic clustering for efficiency
  • Balance routes across week for even workload

Things to Avoid

  • Don't delete routes with active customers
  • Don't change route days without customer notification
  • Don't overlap zip codes across same-day routes
  • Don't set limits too tight (allow for growth)

Quick Reference Card

Task Action/Location
Create new route Settings > Routes > Add New
Assign zip to route Settings > Zip Codes > Edit zip
Check route assignments Subscriptions page, filter by route
View route performance Reports > Driver Report
Change customer's route Customer Info > Subscription > Edit Route
Enable geofencing Requires Kiva Admin - contact support
Set route capacity Edit route > Set limits
Balance routes Reassign zips between routes

FAQs

Can a customer have multiple routes?

No, each subscription is assigned to one route. However, a customer could have multiple subscriptions on different routes.

What happens when we change a zip code's route?

Only new customers signing up will get the new route. Existing customers keep their current route unless manually changed.

Can routes have different delivery windows?

Yes, delivery windows are configured separately and can be assigned per route or globally.

How does the system choose which route for a zip code?

If multiple routes are assigned to a zip (rare), the system returns the first match. Best practice is one route per zip code.

What is the "Pending" route?

A holding area for customers who signed up without a valid route assignment. Review these customers and assign proper routes.

Change Log

2026-03-01

  • Initial documentation created
  • Covered basic route configuration
  • Documented auto-routing and geofencing
  • Added integration points and workflows

End of Documentation

For additional help, contact your system administrator or Kiva Logic support.