Overview

EasyRoutes is a route optimization and delivery management platform for last-mile delivery, built for e-commerce businesses. The API lets you integrate EasyRoutes with your existing systems — import orders, create and manage routes, assign and dispatch drivers, and react to delivery events in real time.

What you can do

Core concepts

Routes

A planned sequence of stops for a driver on a given day. Includes start/end locations, assigned driver, optimization status, and dispatch status (dispatchedUntil indicates when the current dispatch expires).

ID format: rte-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Route Stops

Individual deliveries on a route. Contains address, customer info, delivery status, and proof of delivery (photos, signature, notes).

ID format: rst-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Imported Stops

Orders you've sent to EasyRoutes via API that haven't been added to a route yet. They appear in your Orders page, ready for route planning.

ID format: ist-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Drivers

Team members who deliver routes. Includes contact info and current status.

ID format: drv-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Webhooks

Real-time notifications when things happen — routes dispatched, stops delivered, drivers updated. Register webhooks in Settings > API.

Authentication

1. Get your Client ID and Secret from Settings > API
2. Exchange them for an access token via POST /authenticate
3. Include the token in all requests: Authorization: Bearer {token}

Tokens expire after 1 hour. See the Getting Started Guide for details.

Base URL

The API uses date-based major versioning. New endpoints and improvements ship as backwards-compatible additions to the current major version. If a future change would break existing integrations, it will ship under a new major version.

https://easyroutes.roundtrip.ai/api/2024-07/

Common workflows

Build and dispatch a route end-to-end

1. Authenticate
2. POST /stops/imports with your order data
3. POST /routes to create a route with start/end locations and optional constraints (max duration, max stops, max weight, toll/U-turn avoidance)
4. POST /routes/{id}/stops to add imported stops to the route
5. POST /routes/{id}/reoptimize to optimize stop ordering
6. PUT /routes/{id}/driver to assign a driver
7. POST /routes/{id}/dispatch to dispatch the route to the driver

Working with Shopify orders

The workflow above applies to orders imported via the API. If you're using EasyRoutes' native Shopify integration, orders sync automatically — add them to routes in the app or use Workflows to assign them automatically. Once on a route, you can manage that route entirely via the API (assign drivers, dispatch, reoptimize, read delivery status, etc.).

If you need full programmatic control over Shopify orders, you can also import them as imported stops using POST /stops/imports with a clientStopId (e.g. the Shopify order ID or order number) to maintain the link between systems, and use webhooks to sync delivery status back. This gives you more flexibility but means you own the integration.

Import orders and let Workflows handle the rest

1. Authenticate
2. POST /stops/imports with your order data
3. Stops appear in EasyRoutes Orders page
4. Workflows automatically assign them to routes on creation

Sync delivery status to your system

1. Register a webhook for STOP_STATUS_UPDATED
2. When a stop is delivered, you receive the event
3. Update your order management system

Track proof of delivery

1. Subscribe to STOP_UPDATED webhook
2. Access photos, signatures, and notes from the payload
3. Store or display in your system

Reoptimize an in-progress route

1. POST /routes/{id}/reoptimize with ignoreCompletedStops: true to skip delivered/attempted stops
2. Optionally set ignoreRoutingConstraints: true to override max duration, weight, and other constraints during reoptimization

Best Practices

Consider the following when building solutions or integrations with the EasyRoutes API.

Security

• Store credentials securely: Never commit API keys to version control
• Use HTTPS: All API requests must use HTTPS
• Rotate tokens: Implement token refresh logic before expiration (tokens expire after 1 hour)
• Validate webhooks: Verify webhook signatures using HMAC-SHA256 (sent in X-EasyRoutes-Hmac-Sha256 header)

Performance

• Cache access tokens: Reuse tokens until they expire (1 hour)
• Batch operations: Import or add multiple stops in a single request when possible
• Use webhooks: Prefer event-driven updates over polling
• Implement pagination: Don't request all records at once

Reliability

• Idempotent imports: Use client_stop_id when importing stops — existing stops with the same ID will be replaced instead of duplicated
• Reoptimize after changes: After adding or removing stops, call ReoptimizeRoute — the route is not automatically reoptimized
• Retry logic: Implement retries with exponential backoff for transient errors
• Monitor webhooks: Track webhook delivery success and implement retry logic for failed deliveries
• Validate inputs: Check data constraints before sending requests
• Log requests: Maintain request/response logs for debugging

Data Quality

• Geocode addresses: Ensure stops have valid addresses that can be matched to a geolocation
• Structured phone numbers: When inputting phone numbers, ensure they are in the expected E.164 format
• Use custom IDs: Include your order IDs in the client_stop_id field for reference and idempotent updates
• Add metadata: Use tags and attributes for filtering and reporting, and add a delivery date or time window if those constraints are required for route planning.

Data formats

Timestamps: RFC3339 with timezone — "2024-12-15T14:30:00Z"

Durations: Seconds as string — "300s" (5 minutes)

Coordinates:

{ "latitude": 43.6532, "longitude": -79.3832 }

Addresses:

{
  "address1": "123 Queen St W",
  "city": "Toronto",
  "provinceCode": "ON",
  "countryCode": "CA",
  "zip": "M5H 2M9"
}

Error handling

Error responses include a message field explaining what went wrong.

Pagination

List endpoints return up to 20 items by default. Use cursor-based pagination for more:

GET /routes?limit=20&cursor=eyJsYXN0X2lkIjoiMTIzIn0=

Response includes nextCursor — pass it in subsequent requests.

Next steps