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.

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

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