How the rolling-window generation engine creates daily routes from master templates — cron jobs, manual generation, and preview.

Route Generation

The route generation engine transforms your master route templates into concrete daily routes. It can run automatically on a schedule or be triggered manually.

How It Works

The generation engine processes a date range and, for each date:

Finds matching templates — active templates where day_of_week matches the target date's day
Filters stops by frequency — determines which template stops should appear based on their frequency, week parity, and month week settings
Applies exclusions — removes stops for:
- Customers with active vacation holds covering the date
- Customers with service skips on the date
- Dates that are blackout dates
Checks for duplicates — skips generation if a route already exists for that template and date (unless force mode is used)
Creates draft routes — one route per template per date, with the filtered stops in template sequence

Automatic Generation (Cron)

When auto_generate_routes is enabled in tenant settings, a daily cron job runs and generates routes for upcoming dates.

Rolling Window

The auto_generate_days setting controls how many days ahead the engine looks. For example:

Setting	Behavior
`auto_generate_days = 7`	Routes are generated 7 days in advance
`auto_generate_days = 14`	Routes are generated 14 days in advance
`auto_generate_days = 30`	Routes are generated 30 days in advance

Each cron run generates any missing routes within the window. Routes already created for a date are not duplicated.

Enabling Auto-Generation

Go to Settings > Routes & Scheduling
Toggle Auto-generate routes on
Set the Days ahead value
Save

Manual Generation

You can generate routes on-demand from the dashboard or API.

From the Dashboard

Go to Daily Routes
Click Generate Routes
Select the start and end date
Optionally filter to a specific template
Click Generate

From the API

POST https://api.nextroute.app/api/generate-routes
Authorization: Bearer <token>
Content-Type: application/json

{
  "start_date": "2026-03-24",
  "end_date": "2026-03-28"
}

Optional parameters:

Parameter	Description
`template_id`	Generate only for a specific template
`force`	If `true`, regenerates even if routes already exist for the date

The response includes the count of routes and stops created:

{
  "routes_created": 3,
  "stops_created": 47,
  "skipped_dates": ["2026-03-25"]
}

Note: The date range is capped at 60 days to prevent excessive generation.

Preview (Dry Run)

Before committing, you can preview what the engine would generate:

POST https://api.nextroute.app/api/generate-routes/preview
Authorization: Bearer <token>
Content-Type: application/json

{
  "start_date": "2026-03-24",
  "end_date": "2026-03-28"
}

The response shows the same output structure but with "preview": true — no routes are actually created.

Frequency Filtering Logic

Frequency	Inclusion Rule
Weekly	Always included for matching day
Biweekly	Included if current week matches stop's `week_parity` (A or B)
Monthly	Included if the occurrence matches `month_week` (1st, 2nd, 3rd, 4th, last)
Quarterly	Included in months 1, 4, 7, 10 (first month of each quarter)
Annually	Included once per year
Seasonal	Included only during `seasonal_active_months` (configurable per tenant)
One-time	Included once, then deactivated on the template

Cascading Effects

Changes to scheduling data automatically affect generation:

Adding a blackout date → soft-deletes stops from draft routes on that date
Adding a vacation hold → soft-deletes the customer's stops from draft routes in the hold range
Adding a service skip → soft-deletes the customer's stop from the draft route on that date
Removing a blackout/hold/skip → triggers regeneration for the affected dates to restore stops

Master Routes — the templates that drive generation
Blackout Dates — excluding dates from generation
Vacation Holds — per-customer date exclusions
Skip & Reschedule — stop-level skips and rescheduling

Route Generation

On this page