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. The grid lists routes by route ID until you choose another sort, and Shift-click on a column header adds a second sort to break ties. Drag columns into the order you want in the column picker; Reset puts them back. A route whose orders don’t all have an item count shows its boxes as a lower bound, such as ≥ 6, instead of leaving the column blank. The map draws the route you clicked, outlined, together with any you’ve ticked, and labels each drawn route with its name in its own color. Drop ticked stops on Unassigned to take them off their routes; on a live route, the grid asks first. Hold a dragged order over the Routes tab and the route rows come up, so you can drop it on one. Adding orders to a route that is over capacity asks a second time before it goes through. The grid counts trucks and drops. A route’s stop count is its customer drops: pickups, depot stops, and breaks still appear in its stop list but aren’t counted. A truck that goes back to the depot to reload is one row, marked 1 reload, with its stops, orders, distance, time, and size added up from the first trip’s start to the last trip’s finish, and the summary counts it once beside the loads it runs, such as 2 loads. A stop served in one of the order’s other delivery windows shows that window marked Alt. and isn’t counted as late. Routes start with start time, duration, distance, and size showing, and Planned Complete hidden until you add it back; a column choice you’ve already saved is kept. Each display field gets its own column in the stops table, and a numeric one, such as pallets, also gets a column in the route table that totals each route, with the total in the footer. A total that’s missing some orders’ values shows as a lower bound, such as ≥ 36. Stops CSV, beside the export button, downloads every stop of the ticked routes, or of every listed route, with a column for each display field and times in the grid’s time zone. Park routes. To set routes aside while you plan the rest, tick them and choose Park routes from Route Actions. A parked route leaves the list, the counts, and the summary, and the map draws it only with the Parked routes layer on. Bring it back from the Parked tab with Unpark. Parking is kept in your browser, not shared with your team, and it needs permission to edit routes. Take a route off the road. When a truck breaks down or a driver calls out, tick the route and choose Take off the road from Route Actions. Say why it can’t run, Truck out or Driver out, and the grid lists the day’s nearest routes that haven’t been dispatched, with the three closest ticked. Nash re-optimizes the stranded orders across the routes you keep ticked, and you review the result before applying it. 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. Find an order from the map. The Routes map’s search, Search customer, order, route, or driver, finds orders as well as routes. Matches on routes are listed first, then unassigned ones. Pick one to open its order, with Move to route or Add to route at hand. Routes that don’t match fade, and a chip on the map steps through the matches. 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, including the package value, tip, weight, and dropoff instructions, 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 how long each step took. Hover a status on Execute, or on the Deliveries list, and a Time in status card shows how long the delivery or route spent in each status, a bar of those spans, the total, and the failure reason when there is one. A canceled route says who canceled it: Canceled · Customer, Provider, Merchant, Nash, or Reassigned. 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. The route’s Activity tab keeps them too: when each was raised, at what severity, and who resolved it, including an exception an agent closed on its own. An exception nobody owns closes by itself when its route completes or is canceled, and reads Closed when the route ended. One someone owns, one raised by hand, and one on a route that failed stay open. 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.