Vacation Holds

A vacation hold pauses service for a specific customer over a date range. While a hold is active, the customer's stops are excluded from route generation and removed from existing draft routes.

How Vacation Holds Work

When a vacation hold is created:

1. The hold is recorded with start_date and end_date
2. Cascade to draft routes: Any pending stops for this customer on draft routes within the hold range are soft-deleted
3. Generation exclusion: The route generation engine skips this customer for dates within the hold range

When a vacation hold is removed:

1. The record is deleted
2. Regeneration: If the hold range includes future dates, the system triggers route generation for those dates to restore the customer's stops

Vacation Hold Fields

Creating a Vacation Hold

From the Dashboard

1. Navigate to the customer's detail page
2. Click Vacation Holds tab
3. Click Add Hold
4. Select the start and end dates
5. Optionally add notes
6. Save

From the API

POST https://api.nextroute.app/api/customers/:customerId/vacation-holds
Authorization: Bearer <token>
Content-Type: application/json

{
  "start_date": "2026-06-15",
  "end_date": "2026-06-29",
  "notes": "Family vacation"
}

Validation:

• start_date must be before or equal to end_date
• Date ranges cannot overlap with existing holds for the same customer (returns 400)

Response:

{
  "id": "hold_123",
  "tenant_id": "tenant_456",
  "customer_id": "cust_789",
  "start_date": "2026-06-15",
  "end_date": "2026-06-29",
  "notes": "Family vacation"
}

Listing Vacation Holds

GET https://api.nextroute.app/api/customers/:customerId/vacation-holds
Authorization: Bearer <token>

Returns all vacation holds for the customer, sorted by start_date ascending.

Removing a Vacation Hold

DELETE https://api.nextroute.app/api/vacation-holds/:id
Authorization: Bearer <token>

If the hold includes future dates, removing it triggers regeneration to restore the customer's stops on routes.

Cascade Behavior

When a Hold is Created

For each draft route within the hold's date range:

1. Find stops belonging to the customer
2. Soft-delete those stops (deleted_at is set)
3. Recount the route's planned_stops_count

When a Hold is Removed

1. Determine the effective date range (start date or today, whichever is later, through end date)
2. Trigger generateRoutesForDateRange for the range
3. The generation engine re-evaluates the customer's template stops and adds them back to routes

Billing Impact

Vacation holds do not automatically adjust invoices. If a customer's service count is reduced because of a hold, the missed-service credit system may apply a credit based on the missed_service_credit_threshold setting.

Alternatively, you can manually pause the customer's billing_status to paused during extended vacations to skip invoice generation entirely.

Related

• Blackout Dates — tenant-wide date exclusions
• Skip & Reschedule — stop-level skips
• Route Generation — how holds affect generation