Dispatch Route

Dispatch routes are daily operational routes assigned to drivers. A route has a date, route type, status, optional driver/equipment/division assignment, and an ordered list of stops. Routes can be created manually or generated from dispatch route templates.

DispatchRoute

Property	Type	Required	Description
DispatchRouteId	int	Yes	Primary key
OrganizationId	int	Yes	Tenant scope
Name	string	Yes	Route name
RouteType	DispatchRouteType	Yes	Delivery or Pickup
RouteDate	Date	Yes	Operational route date (yyyy-MM-dd)
DispatchRouteStatusId	int	Yes	Current route status
DispatchRouteTemplateId	int?	No	Source template when generated
DivisionId	int?	No	Optional division assignment
DriverContactId	int?	No	Assigned driver contact; must be a driver contact
EquipmentId	int?	No	Assigned equipment
IsDraft	bool	Yes	New/generated routes start as drafts
IsInactive	bool	Yes	Soft-delete flag
CollapsedIntoDispatchRouteId	int?	No	Route this route was merged into
Stops	DispatchRouteStop[]	No	Ordered route stops
CustomValues	Dictionary	No	Extensible custom properties

DispatchRouteStop

Property	Type	Required	Description
DispatchRouteStopId	int	Yes	Primary key
DispatchRouteId	int	Yes	Parent route
StopContactId	int?	No	Store/location contact (nullable; use with or without contactAddressId)
ContactAddressId	int?	No	Specific stop address
StopType	DispatchRouteType	Yes	Defaults to the parent route type when omitted
PlannedSequence	int	Yes	1-based planned stop order
ActualSequence	int?	No	Final execution order
EstimatedServiceMinutes	int?	No	Planned dwell/service time
ActualArrivalTime	DateTime?	No	Actual arrival timestamp
ActualCompletionTime	DateTime?	No	Actual completion timestamp
OrderIds	int[]	No	Attached order IDs for this stop
Orders	DispatchRouteStopOrder[]	No	Attached order links; expand order when full order data is needed
CustomValues	Dictionary	No	Extensible custom properties (use for ad-hoc stop address when not using a contact)

DispatchRouteStopOrder

Property	Type	Required	Description
DispatchRouteStopOrderId	int	Yes	Primary key
DispatchRouteStopId	int	Yes	Parent stop
OrderId	int	Yes	Attached order
Order	Order?	No	Optional expanded order
CustomValues	Dictionary	No	Extensible custom properties for the stop/order link

Behavior

• Create accepts nested stops; planned sequences are assigned contiguously in input order. Stops may attach orders through orderIds.
• Route updates can replace the nested stops array. Existing stops with dispatchRouteStopId are sparse-updated and resequenced by array order; new stops are added; omitted existing stops are soft-deleted. Stop orderIds reconcile the attached orders to exactly the provided IDs when present. Stop-specific mutations remain available for targeted changes.
• Draft routes become operational through activateDispatchRoute.
• Stops cannot be removed, and routes cannot be deleted, when stops have attached orders.
• Removing or reordering a stop resequences remaining active stops.
• Generated routes copy template name, route type, division, and stops; driver/equipment assignment happens later.
• Stop location/order anchor: A stop's location is either a contact address (contactAddressId, optionally with stopContactId) or an ad-hoc address placed in customValues; alternatively, an order-attached stop can be created with orderIds. A stop must have at least one of stopContactId / contactAddressId / non-empty customValues / non-empty orderIds.