What a route is
The core of a route is itsstops array, which lists the locations to visit in order. Each stop details:
- The kind of stop (
stopType) - Associated items (
objectIds) - Timing estimates (
arrivalTime,departTime,serviceTime) - Travel details from the prior stop (
distanceFromPrevious,durationFromPrevious) - The physical coordinates (
location)
GET /v1/routes/{id}).
Creating & updating routes
Use Create or Update Route (POST /v1/routes) to create a new route or update an existing one by providing the route configuration and its stop details. This is the manual path: you supply the ordered stops yourself.
In the Portal, you can start a route before its orders are ready. Create route on the Routes page asks for a Route name (up to 128 characters) and, optionally, a Start location and an End location from your store locations, then opens the new, empty route so you can add orders to it. It needs Routes turned on for your organization, a role that can edit orders and deliveries, and a user who isn’t scoped to a single store location or driver group. An empty route is listed under the day it was created. Give it a start location if you plan to move stops onto it from another route: Move to route needs to know where the destination loads (see Plan routes on the Orders map).
You can recalculate timing for a route with POST /v1/routes/{id}/calculate-timing, which computes per-stop ETAs and a polyline using truck routing, updating each stop’s arrival and departure times and returning the route polyline. Timing runs from the route’s planned departure from its start, falling back to the first order’s pickup window when the route has no planned departure. It works for every organization with Routes; the route_timing_not_enabled error some organizations used to get is gone.
You don’t have to build routes by hand. Route optimization generates routes for you from a set of orders, and can save them as route objects you then dispatch.
Naming a route
A route carries an optionalname — a label a dispatcher recognizes, as opposed to the generated identifier. Set it on Create or Update Route, or from the Portal: the Execute page has a Rename route action, and splitting stops into a new route lets you name that route as you create it. Renaming works after dispatch too, so a route can be relabeled once you see how the day is actually running. Clear the name and displays fall back to the route’s external identifier.
Plan routes on the Orders map
The Orders and Routes pages each have a map view, and it’s a working surface: you can select work on it, put that work on a route, and compare routes without going back to the table between steps. Route changes here apply to routes that haven’t been dispatched. They need Routes turned on for your organization, a role that can edit deliveries, and a user who isn’t scoped to a single store location or driver group. Select orders the way you think about them. Click a pin to select every order at it — a single order, a shared address, or a cluster — and Shift+click to look at the pin’s orders without selecting them. Select all takes every order behind the current filters, not only the ones drawn. For a shape, open Tools, choose Select area, and pick Lasso or Polygon: drag a ring, or click corners and close the shape on the first one. An area adds to the selection you already have, it covers the orders loaded on the map, and Esc cancels it. The bar of bulk actions that appears is the table’s own, acting on exactly what the map shows as selected. Put a selection on a route. With unassigned orders selected, Add to route opens the route chooser for the whole selection and assigns every order in one step. Candidate routes are ranked by how close their stops are to the orders you picked. Nearby routes leaves out a route whose vehicle lacks a capability the orders require and says how many it hid; a route whose vehicle meets every preference is marked Preferred. The full list of routes stays unfiltered, with a Can’t carry note on the ones that don’t fit. Move stops between routes. Select route stops — by click, with the same area tools, or by ticking dropoffs in the route cards to gather them from several routes — and choose Move to route. Moved stops join the destination ahead of its route end, and any you selected that are already on the destination stay where they are. You can move every stop off a route that hasn’t been dispatched; the emptied route stays in the list, so you can move stops back onto it or archive it. Routes that load at their start (a depot) can exchange stops even when they leave from different depots, while a route that collects from a separate pickup location exchanges stops only with routes that load at the same place. Nash refuses a move from a route that’s already dispatched, one onto a route with no start or pickup to load from, and one whose stops changed after you selected them. The chooser behind Add to route and Move to route lists the routes you’ve focused on the map first, marked Focused on map, and its search matches the text on the route cards. When it can’t confirm yet, it says why beside the button. Resequence without losing stops. Resequence re-solves a route that hasn’t been dispatched using the route’s own vehicle, routing, service times, and driver breaks, and it keeps every stop you put on the route. To do that it relaxes the limits that would otherwise push a stop off — the length of the day, distance, capacity, vehicle capabilities, the end of the shift, and dropoff windows; pickup windows still hold — and records what the route now breaks. The result reads Every stop kept · N constraint violations, the route card shows the count, and the route’s details show Route health: late stops, time past the shift end, over-capacity loads, and orders needing a capability the vehicle doesn’t have, each linked to its stop, with Acknowledge to record that you’ve seen them. If the optimizer still can’t place a stop, the route isn’t changed and you’re told so. A resequenced route keeps its name, number, and vehicle, and a route with no orders can’t be resequenced. Tell the optimizer what order matters. Edit sequencing, in a stop’s menu on a route card or in the route’s details, sets three things on the order behind that stop: a Sequence Priority from 0 to 499, where a smaller number is visited earlier; a Sequence Group, which limits that ordering to orders in the same group and keeps the group on one route; and a Mutually Exclusive Label. The values show as badges on the stop and take effect the next time the route is optimized. They can’t be changed once the route is dispatched. Act from the route card. Each route’s card carries Dispatch, Resequence, and Edit, which opens the same editor the Routes table does, with Archive, Calculate timing, Split, and the copy actions in its menu. They drop out once the route is dispatched. Provider and driver can be set from the card before dispatch, and the Routes table shows each in its own column. Recalculate after an edit. Changing the order of a planning route’s stops leaves its arrival times describing a route that no longer exists. The route’s card and its details say so, with Times are out of date, and Recalculate works the times out again from the new sequence. Times aren’t recalculated on their own, so a route you’ve edited keeps the mark until you do. Switch Routes to a grid. Under Settings → Preferences → Routing, Routing UI chooses the layout everyone in your organization gets when they open Routes: Cards, the default, with route cards beside the map, or Grid, with a table of routes and a table of the selected routes’ stops beside it. The grid suits planning by the numbers: the route table carries stops, service time, size, and percent of capacity, with a totals row, and the stop table carries each stop’s sequence, time window, and departure. Tick stops to Move Stops… or Set Priority…, or drag them to reorder or onto another route. The stop panel can also draw each stop as a Timeline against its window, showing where a driver waits for a window to open or arrives after it closes. Above the tables, the grid’s summary totals the day’s routes, stops, orders, unassigned orders, distance, time, and capacity, and marks routes that are Late, Over capacity, or have no driver; click Late or Over capacity to list only those routes. Show plan metrics adds Window compliance, cost, cost per drop, and drops per hour, each compared with the plan and with your last change. Plan check lists what still needs fixing before you dispatch: unassigned orders, routes with late stops, routes over capacity, routes with no driver or vehicle, and empty routes. From the route table you can assign a driver or vehicle in place (the grid warns when a driver is already on another route), and tick routes to Dispatch Routes or Archive empty routes. On the map, drop unassigned orders or ticked stops and they join the nearest drawn route, or drag a stop’s pin onto another route. On more than one monitor, move the summary, stops, or routes panel to a New window, or open the map in its own window; each stays in step with the others. Compare routes. Shift+click route cards or route lines to hold several in focus, and the map frames all of them. Hover a route line for its driver, vehicle, planned time, distance, and stop count. Colors are assigned across the routes on screen from a palette of 48, so two routes in view don’t share one; past 48, a color repeats only between routes that are far apart. Choose what the map shows. The Layers control, on every Portal map, switches to a Satellite view — imagery with street names — and on the Orders map holds the Routes, Orders, Customers, and Order labels layers. Orders shows unassigned orders by default and can switch to Needs Attention, Ready to Dispatch, Dispatched, or All orders; selecting orders to plan still works on unassigned ones. Sort routes orders the route list by Date created or by Route ID, which reads the numbers in an ID the way you do, so D2 comes before D10. Times and date ranges on the map follow the time zone shown on its toolbar, which defaults to your organization’s; Use organization timezone at the top of its list switches back to it. Tools → Filters filters the map from the map: it holds the table’s filters, such as pickup and dropoff store, tags, and dispatch status, and a filter set in either place applies in both. Its Route metrics conditions narrow routes by Boxes, Distance, Duration, and Stops, in your display units; a route missing a number a condition needs is set aside behind a Show link rather than dropped. Sort routes can order by the same four numbers. Filtering or sorting on a metric loads every route first, so the result is complete. Display fields, set by an owner or admin for the whole organization, picks the order details, metadata, and tags shown on stop cards, with up to two of them printed on the map itself. Those labels appear on every stop that has its own pin, focused route or not; stops merged into one pin are labeled once you zoom in.Dispatching routes
Once a route is planned, dispatch it with Dispatch Routes (POST /v1/routes/dispatch). This creates jobs for each route and assigns them based on your organization’s dispatch strategy.
Pass the route IDs to dispatch:
When
autoDispatch is true, the resulting jobs are sent to a provider immediately according to your dispatch strategy. Set it to false to create the jobs without dispatching them right away.
Watching routes on the Execute page
Once routes are dispatched, the Execute page in the Portal is where you watch them run. It lists dispatched routes for a date range, and every part of it exists to be narrowed until it shows the routes you’re responsible for. Pick the day first. Execute opens on today. The date control leads with your organization’s date range presets — Today, Yesterday, Tomorrow, and This week unless an admin has chosen others (see Display preferences) — each applying the moment you choose it. Custom range opens a calendar, and nothing moves until you apply the range. A link carrying its own dates still wins over the default, and so does a saved view. Then narrow it. Filters are grouped by what a dispatcher is deciding — route operations, assignment, orders and locations, and package — rather than by which object each field happens to belong to. Among them are driver group and courier, so someone who owns one group can work only their own routes. Selections are held in the URL and in saved views, which makes a narrowed queue something you can send to a colleague. Check whether the driver is moving. Each assigned driver carries a location freshness reading beneath their name, both in the table and in the route detail panel. A location counts as live through 15 minutes and after that reads as not live, with its age — the same rule the delivery map uses. Select the reading to open a small map at the driver’s last known position. Read the day as a timeline. The timeline view draws each route as drive, service, waiting, and break segments in proportion to the time they take, with the shift’s end marked and any overrun called out — the same drawing the Optimize review uses to show how much of a shift a proposed route consumes. Select a dropoff on it to open the route panel at that stop. See what the driver did with a stop. When a driver skips a stop and comes back to it, both show on the route’s detail panel, the order drawer, and the delivery timeline as Skipped and Resumed events, with the driver’s reason when they gave one. Work the exceptions. Add exception records what happened on a route, with a Severity you can leave on Auto for Nash to rate or set from P0 to P3. In the route’s details, each exception’s card sets its status — Needs Triage, Acknowledged, or Resolved — or removes it, and resolved exceptions stay listed, read-only. To hand out a batch, select routes in the table and choose Assign to or Clear assignee; it applies to those routes’ open exceptions and skips routes that have none. Turn off what you don’t use. The map view, the timeline view, and the KPI cards at the top of the page can each be switched off for the whole organization under Organization settings → Products → Execute. All three start on, so turning one off is the opt-out — for teams who find the full page busier than their work needs. A link that asks for a view you’ve turned off still resolves; it falls back to the table.Who can open Execute
Execute is gated by two permissions —execute.view to open the page and read a route, and execute.act to change one. An organization admin grants either one on a role, from the Add role and Edit role drawers in the Portal. The two rows appear there once your organization has Execute turned on.
A user scoped to a single store location can hold those permissions too. Execute then behaves the same way it does for anyone else, narrowed to the routes that touch their store: the queue, the header counts, and the route detail panel all apply the scope server-side, and a route outside it returns a FORBIDDEN error rather than a partly-filled page. What they can do still comes from their role — with execute.act, a store operator can reassign a route’s courier and record what happened on a route (a breakdown, an ad-hoc break, an overweight or oversize load, a refuel, a late departure, a customer not home, a catchment or break-compliance violation) without an org admin doing it for them. Vehicle assignment stays with unscoped users.
Driver and vehicle pickers only open on a route that Nash is running with your own fleet. On a route assigned to an external provider, the driver and vehicle are the provider’s to set, so Execute shows them read-only; a route with no provider chosen yet reads Assign provider until you pick one.
Remove an order from dispatch
You can remove a dispatched, route-based order by either identifier:- Remove by external ID:
POST /v1/orders/external-identifier/{external_id}/undispatch - Remove by Nash order ID:
POST /v1/orders/{order_id}/undispatch
status: valid. The request has no body.
These operations apply only to an order that is currently dispatched and associated with a route. A standalone order or an order that has not been dispatched returns an error.
Routes vs. route optimization
It’s worth separating two related concepts:- A route is the data object — a defined, ordered sequence of stops. You can author routes directly via the API.
- Route optimization is the engine that produces routes. Given a set of orders and your fleet constraints, the optimizer solves the Vehicle Routing Problem (VRP) — balancing capacity, time windows, driver shifts and breaks, vehicle profiles, traffic, and cost — and returns efficient routes.
Next steps
Create or update route
Build or modify a route and its stops.
Get route
Retrieve a route’s stops, metrics, and orders.
Dispatch routes
Turn routes into jobs and dispatch them.
Remove an order from dispatch
Return a route-based order to a valid, pre-dispatch state.
Route optimization
Generate optimized routes from a set of orders.