Skip to main content
A route represents a planned sequence of stops for a vehicle or driver. Where a single job is one pickup-to-dropoff delivery, a route bundles many stops into one ordered itinerary — the unit you use when a driver completes several deliveries in a single trip.

​
What a route is

The core of a route is its stops 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)
A route also carries travel metrics and the orders associated with each stop. Retrieve a single route, including its stops, travel metrics, and associated orders, with Get Route (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. Route timing is turned on per organization; where it isn’t, the request returns a 400 whose reason is route_timing_not_enabled.
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 optional name — 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. 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. 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. 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. 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. 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: Both operations cancel the order’s active delivery attempt, remove the order from its route, update the linked batch, and return the order with 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.
A typical optimized flow is: submit orders for optimization, poll until it completes, then either dispatch the optimized orders directly or save them as route objects and dispatch those routes. For the full walkthrough, see the Route optimization guide.

​
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.