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

​
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 Today, Yesterday, Tomorrow, and This week, each applying the moment you choose it. Custom 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. 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.

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