EasyRoutes Routes API

EasyRoutes API is currently in closed beta. Please contact us if you are interested in early access!

Please see our API Getting Started Guide to enable API access and set up your client key.

Endpoints

Authenticate

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

Authenticate a client to obtain an access token using a client ID and secret key. The access token is required to make authenticated requests to the API. The token will expire after the duration specified in the response.

 curl -X POST -H "Content-Type: application/json" \
 -d '{"clientId": "...", "clientSecret": "..."}' \
 https://easyroutes.roundtrip.ai/api/2024-07/authenticate

Request Body

Field Type Description
clientId string The client ID from EasyRoutes settings.
clientSecret string The client secret from EasyRoutes settings.

Response

Field Type Description
accessToken string The access token to use for authenticated requests.
expiresInSeconds int64 (encoded as string) The duration in seconds until the access token expires.
organization string The unique organization identifier. For EasyRoutes on shopify, this will be the shopify shop. For EasyRoutes on web, this is a unique identifier based on the organization name.

ListRoutes

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

Fetch a list of routes based on the provided query. The query may include a limit, sort key, timestamp bounds, and whether to include archived routes. The response will include a list of routes and a cursor to fetch the next page of results. Subsequent requests should include the cursor only and no list query arguments (which are encoded in the cursor). This request requires authentication via an access token provided in the Authorization: Bearer ... header.

 curl -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/routes?query.sortKey=UPDATED_AT&query.limit=10

Query Parameters

Field Type Description
query.limit int32 Maximum number of routes to return. Must be less than or equal to 200. Defaults to 20.
query.sortKey RouteSortKey Sort key for the returned routes. This determines the ordering of returned routes.
query.timestampStart string (RFC3339 format) Lower bound timestamp for the returned routes. This bound is applied to either the route created time or updated time, depending on the sort key.
query.timestampEnd string (RFC3339 format) Upper bound timestamp for the returned routes. This bound is applied to either the route created time or updated time, depending on the sort key.
query.includeArchived bool Whether to include archived routes in the results.
cursor string Must be empty on initial request, must be set on subsequent.

Response

Field Type Description
routes Route[] List of routes.
nextCursor string Cursor to fetch the next page of results (if available).

GetRoute

GET https://easyroutes.roundtrip.ai/api/2024-07/routes/{id}

Fetch a single route by ID. This request requires authentication via an access token provided in the Authorization: Bearer ... header.

 curl -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/routes/rte-cb93e344-fb1d-4d34-b8a8-8df5cdd9e939

Path Parameters

Field Type Description
id string The ID of the route to fetch.

Response

Route

GetRouteStop

GET https://easyroutes.roundtrip.ai/api/2024-07/routes/{route_id}/stops/{stop_id}

Fetch a single stop on a route by route ID and stop ID. A route stop can be crated from a Shopify order or a copy of an imported stop that has been added to a route and may have additional route-specific information, such as status. It can also be a break or a custom stop that is not associated with an imported stop. This request requires authentication via an access token provided in the Authorization: Bearer ... header.

 curl -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/routes/rte-cb93e344-fb1d-4d34-b8a8-8df5cdd9e939/stops/rst-9817a456-e6fd-4652-b918-5dc89d3621d3

Path Parameters

Field Type Description
routeId string The route ID containing the stop.
stopId string The stop ID to fetch.

Response

RouteStop

AddRouteStops

POST https://easyroutes.roundtrip.ai/api/2024-07/routes/{route_id}/stops

Adds stops to a route by route ID. The added stops are references to previously imported stops by ID (or client-provided ID). The resulting RouteStops inherit most attributes from the imported stop, while optionally inheriting some defaults from the route. Specifically, if the stop does not have a duration set, it will inherit the default duration from the route options. Additionally, tasks configured on the imported stops will be merged with the configured stop tasks on the route. This request requires authentication via an access token provided in the Authorization: Bearer ... header. The request body should include a list of stop IDs to add to the route. The response will include the updated route with the added stops. All new stops are appended to the end of the existing route. The route will not be optimized automatically after adding stops, so the caller should reoptimize the route if needed via ReoptimizeRoute.

 curl -X POST -H "Authorization: Bearer ..." \
 -H "Content-Type: application/json" \
 -d '[
       {
         "importedStopId": "ist-123e4567-e89b-12d3-a456-426614174000",
       },
       {
         "importedStopId": "my-client-stop-123",
       },
       {
         "importedStopId": "ist-456e4567-e89b-12d3-a456-426614174000",
         "deliveryStatus": "OUT_FOR_DELIVERY",
       },
     ]' \
 https://easyroutes.roundtrip.ai/api/2024-07/routes/rte-cb93e344-fb1d-4d34-b8a8-8df5cdd9e939/stops

Query Parameters

Field Type Description
routeId string The ID of the route to add stops to.

Request Body

ImportedStopToAdd[]

Response

Route

DeleteRouteStops

DELETE https://easyroutes.roundtrip.ai/api/2024-07/routes/{route_id}/stops/{stop_ids}

Deletes one or more stops from a route by route ID and stop IDs. Note that the route may be in progress, completed, or archived and it is therefore up to the caller to decide when it is appropriate to delete stops from a route. The request requires authentication via an access token provided in the Authorization: Bearer ... header. The response will include the updated route with the stops removed. If a stop is not found, it will be ignored and the route will be returned without that stop. The route will not be optimized automatically after adding stops, so the caller should reoptimize the route if needed via ReoptimizeRoute.

 curl -X DELETE -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/routes/rte-cb93e344-fb1d-4d34-b8a8-8df5cdd9e939/stops/rst-9817a456-e6fd-4652-b918-5dc89d3621d3,rst-123e4567-e89b-12d3-a456-426614174000

Query Parameters

Field Type Description
routeId string The ID of the route to delete stops from.
stopIds string[] The IDs of the stops to delete from the route. Multiple stop IDs can be provided as a comma-separated list in the URL.

Response

Route

ReoptimizeRoute

POST https://easyroutes.roundtrip.ai/api/2024-07/routes/{id}/reoptimize

Reoptimizes a route according to the currently configured route options. If a route is already optimized, this is a no-op. This request requires authentication via an access token provided in the Authorization: Bearer ... header. The returned response is the reoptimized route.

 curl -X POST -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/routes/rte-cb93e344-fb1d-4d34-b8a8-8df5cdd9e939/reoptimize

Query Parameters

Field Type Description
id string The ID of the route to reoptimize.

Response

Route

ImportStops

POST https://easyroutes.roundtrip.ai/api/2024-07/stops/imports

Import stops into EasyRoutes from an external source. The request requires authentication via an access token provided in the Authorization: Bearer ... header. The request body should include a list of stops to import. The response will include a list of imported stops with generated IDs. The maximum number of stops to import in a single request is 200. Imported stops will show up in EasyRoutes as orders that can be used to create routes.

 curl -X POST -H "Authorization: Bearer ..." \
 -H "Content-Type: application/json" \
 -d '[
       {
         "address": {
           "address1": "123 Main St",
           "city": "New York",
           "provinceCode": "NY",
           "countryCode": "US",
           "zip": "10001"
         },
         "contact": {
           "firstName": "John",
           "lastName": "Doe",
           "phone": "+14165551000",
           "email": "john.doe@roundtrip.ai"
         },
         "items": [
           {
             "name": "Bananas",
             "quantity": 5,
             "grams": 500
           }
         ],
         "note": "Leave at front door",
         "duration": "300s",
         "priority": 5,
         "orderName": "#123"
       }
     ]' \
 https://easyroutes.roundtrip.ai/api/2024-07/stops/imports

Request Body

StopToImport[]

Response

Field Type Description
stops ImportedStop[] The list of imported stops with generated IDs.

ListImportedStops

GET https://easyroutes.roundtrip.ai/api/2024-07/stops/imports

Fetch a list of imported stops. The request requires authentication via an access token provided in the Authorization: Bearer ... header. The response will include a list of imported stops and a cursor to fetch the next page of results. Subsequent requests should include the cursor only and no list query arguments (which are encoded in the cursor).

 curl -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/stops/imports?query.limit=10

Query Parameters

Field Type Description
query.limit int32 Maximum number of imported stops to return. Must be less than or equal to 200. Defaults to 20.
cursor string Cursor to fetch the next page of results (if available). Should only be set on subsequent requests.

Response

Field Type Description
stops ImportedStop[] List of imported stops.
nextCursor string Cursor to fetch the next page of results (if available).

GetImportedStop

GET https://easyroutes.roundtrip.ai/api/2024-07/stops/imports/{id}

Fetch a single imported stop by ID. The request requires authentication via an access token provided in the Authorization: Bearer ... header. The ID can be the EasyRoutes id returned on import or the client-provided client_stop_id.

 curl -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/stops/imports/ist-123e4567-e89b-12d3-a456-426614174000
or 
 curl -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/stops/imports/mystopid-123

Path Parameters

Field Type Description
id string The ID of the imported stop to fetch. You provide the EasyRoutes id returned on import or the client-provided client_stop_id.

Response

ImportedStop

DeleteImportedStop

DELETE https://easyroutes.roundtrip.ai/api/2024-07/stops/imports/{id}

Delete an imported stop by ID. The request requires authentication via an access token provided in the Authorization: Bearer ... header. The ID can be the EasyRoutes id returned on import or the client-provided client_stop_id.

 curl -X DELETE -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/stops/imports/ist-123e4567-e89b-12d3-a456-426614174000
or 
 curl -X DELETE -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/stops/imports/mystopid-123

Query Parameters

Field Type Description
id string The ID of the imported stop to delete. You provide the EasyRoutes id returned on import or the client-provided client_stop_id.

Response

Empty

GetImportedStopRouteInfo

GET https://easyroutes.roundtrip.ai/api/2024-07/stops/imports/{id}/routes

Fetch the route and stop IDs for an imported stop that has been added to one or more routes. The request requires authentication via an access token provided in the Authorization: Bearer ... header. The ID can be the EasyRoutes id returned on import or the client-provided client_stop_id. Note that only non-deleted routes are returned.

 curl -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/stops/imports/ist-123e4567-e89b-12d3-a456-426614174000/routes
or 
 curl -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/stops/imports/mystopid-123/routes

Path Parameters

Field Type Description
id string The ID of the imported stop to fetch route info. You provide the EasyRoutes id returned on import or the client-provided client_stop_id.

Response

Field Type Description
id string The ID of the imported stop.
routeInfo ImportedStopRouteInfo[] The route and stop IDs for the imported stop that has been added to a route.

GetShopifyStopRouteInfo

GET https://easyroutes.roundtrip.ai/api/2024-07/stops/shopify/{id}/routes

Fetch the route and stop IDs for a shopify order that has been added to one or more routes. The request requires authentication via an access token provided in the Authorization: Bearer ... header. The ID should be the shopify order ID (int64). Note that only non-deleted routes are returned.

 curl -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/stops/shopify/6229749334323/routes

Path Parameters

Field Type Description
id string The Shopify order ID to fetch route info for.

Response

Field Type Description
routeInfo ImportedStopRouteInfo[] The route and stop IDs for the shopify order that has been added to a route.

ListDrivers

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

Fetch a list of all drivers associated with the shop. By default this returns all drivers but can optionally filter to specific statuses (i.e. ACTIVE, INACTIVE, or ARCHIVED). Invited drivers that are still pending sign-up are not returned by this API. This request requires authentication via an access token provided in the Authorization: Bearer ... header.

 curl -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/drivers

Query Parameters

Field Type Description
query.limit int32 Maximum number of drivers to return. Must be less than or equal to 200. Defaults to 20.
query.status DriverStatus[] Filter drivers by status. You can specify multiple statuses to filter by by repeating the query parameter, i.e. ?status=ACTIVE&status=INACTIVE.
cursor string Cursor to fetch the next page of results (if available). Should only be set on subsequent requests.

Response

Field Type Description
drivers Driver[] List of drivers.
nextCursor string Cursor to fetch the next page of results (if available).

GetDriver

GET https://easyroutes.roundtrip.ai/api/2024-07/drivers/{id}

Fetch a single driver by ID. This request requires authentication via an access token provided in the Authorization: Bearer ... header.

 curl -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/drivers/drv-cb93e344-fb1d-4d34-b8a8-8df5cdd9e939

Path Parameters

Field Type Description
id string The ID of the driver to fetch.

Response

Driver

SubscribeWebhook

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

Creates a new webhook subscription to receive events from EasyRoutes. The request requires authentication via an access token provided in the Authorization: Bearer ... header. The request body should include the URL to send webhook events to and the topics to subscribe to. The response will include the created webhook subscription with its ID and the list of subscribed topics. You may have a maximum of 5 webhook subscriptions per organization. The webhook URL must be publicly accessible and able to handle POST requests with JSON payloads. The response will include the created webhook subscription with a unique ID.

 curl -X POST -H "Authorization: Bearer ..." \
 -H "Content-Type: application/json" \
 -d '{
       "url": "https://example.com/webhook",
       "topics": [
         "ROUTE_CREATED",
         "ROUTE_UPDATED",
       ],
     }' \
 https://easyroutes.roundtrip.ai/api/2024-07/webhooks

Request Body

Field Type Description
url string The URL to send webhook events to. This must be a publicly accessible URL that can handle POST requests with JSON payloads. See https://support.roundtrip.ai/article/602-easyroutes-webhooks
topics Topic[] The topics to subscribe to.

Response

WebhookSubscription

ListWebhookSubscriptions

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

Fetch a list of all webhook subscriptions. The request requires authentication via an access token provided in the Authorization: Bearer ... header. The response will include a list of webhook subscriptions with their IDs, URLs, subscribed topics, and active status.

 curl -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/webhooks

Response

Field Type Description
webhooks WebhookSubscription[] The list of webhooks that are currently subscribed.

UnsubscribeWebhook

DELETE https://easyroutes.roundtrip.ai/api/2024-07/webhooks/{id}

Unsubscribe from a webhook by ID. The request requires authentication via an access token provided in the Authorization: Bearer ... header. The ID should be the webhook subscription ID returned when the webhook was created. The response will be empty on success.

 curl -X DELETE -H "Authorization: Bearer ..." \
 https://easyroutes.roundtrip.ai/api/2024-07/webhooks/sub-123e4567-e89b-12d3-a456-426614174000

Query Parameters

Field Type Description
id string The ID of the webhook to unsubscribe.

Response

Empty

Data Types

Address

Field Type Description
address1 string Street address line 1 (e.g. "123 Main St").
address2 string Street address line 2 (e.g. "Apt 101").
city string City name (e.g. "New York").
provinceCode string Province or state (e.g. "NY") as subdivision codes in ISO 3166-2 format without the country prefix (e.g. NY for New York).
countryCode string Country code (e.g. "US").
zip string Postal or ZIP code (e.g. "10001").

AttemptedReason

Value Description
UNKNOWN Unknown reason for marking stop as attempted.
NOT_AVAILABLE Reason for attempted was customer was not available.
ACCESS_DENIED Reason for attempted was Access denied.
INCORRECT_ADDRESS Reason for attempted was incorrect address.
SAFE_PLACE_UNAVAILABLE Reason for attempted was that no safe place to leave package(s).
REFUSED Reason for attempted was delivery refused.
EXTERNAL Reason for attempted was external factors (weather, traffic, etc.).
INCORRECT_ITEMS Reason for attempted was incorrect or missing item(s).
OTHER Reason for attempted was other.

Attribute

Field Type Description
key string Attribute key. Must be non-empty.
value string Attribute value.

BreakStatus

Value Description
UNKNOWN Unknown break status (not completed).
COMPLETED Break stop has been completed.

Contact

Field Type Description
firstName string First name (e.g. "John").
lastName string Last name (e.g. "Doe").
company string Company name (e.g. "Roundtrip Systems Inc").
phone string Phone number in E.164 format (e.g. "+14265551000").
email string Email address (e.g. "john.doe@roundtrip.ai")

CustomerRating

Field Type Description
rating int32 Rating from 1-5
comment string Customer comment related to rating
createdAt string (RFC3339 format) Timestamp when rating was left by customer.

Date

Field Type Description
year int32 Year of the date. Must be from 1 to 9999.
month int32 Month of a year. Must be from 1 to 12.
day int32 Day of a month. Must be from 1 to 31.

DeliveryStatus

Value Description
UNKNOWN Unknown delivery status (not marked as ready).
DELIVERED Stop was delivered.
OUT_FOR_DELIVERY Stop is out for delivery.
ATTEMPTED_DELIVERY Stop delivery was attempted.
READY_FOR_DELIVERY Stop is ready for delivery.

Driver

Field Type Description
id string Driver ID (e.g. "drv-123e4567-e89b-12d3-a456-426614174000").
firstName string Driver first name (e.g. "John").
lastName string Driver last name (e.g. "Doe").
phone string Driver phone number in E.164 format (e.g. "+14265551000").
status DriverStatus Shop driver status. (e.g. ACTIVE).

DriverStatus

Value Description
UNKNOWN Unknown driver status.
ACTIVE Driver is active.
INACTIVE Driver is deactivated.
ARCHIVED Driver is archived.

ImportedStop

Field Type Description
id string The ID of the imported stop, generated by EasyRoutes (e.g. "ist-123e4567-e89b-12d3-a456-426614174000").
clientStopId string The client-provided ID associated with the imported stop, if provided.
address Address The address for the stop.
contact Contact The contact information for the stop.
coordinates LatLng The coordinates to use for the stop, if provided on import.
items StopItem[] The items to deliver at the stop.
note string A note for the stop.
duration string Planned duration of the stop.
priority int32 Priority of the stop for route planning.
orderName string The name of the order associated with the stop.
importedAt string (RFC3339 format) The timestamp at which the stop was imported.
timeWindows TimeWindow[] The time window for the stop. Note that we currently support at most one time window but may support multiple time windows in the future.
deliveryDate Date The delivery date for the stop.
attributes Attribute[] The additional key-value attributes set on the imported stop.
tags string[] The tags for the stop.
tasks TaskTemplate[] The tasks for the stop.
type StopType The type of stop (DELIVERY, PICKUP, or TASK). Defaults to DELIVERY if not provided.
customSignatureDisclosure string Custom signature disclosure for the stop. Only populated if stop type is DELIVERY, PICKUP, or TASK.

ImportedStopRouteInfo

Field Type Description
routeId string The ID of the route the stop is associated with (e.g. "rte-123e4567-e89b-12d3-a456-426614174000").
stopId string The ID of the stop on the route (e.g. "rst-123e4567-e89b-12d3-a456-426614174000").
deliveryStatus DeliveryStatus The status for the stop on the route.

ImportedStopToAdd

Field Type Description
importedStopId string The ID of the existing imported stop to add to the route (required). The imported stop is fetched and converted into a route stop.
deliveryStatus DeliveryStatus The delivery status to set on the stop (optional).

LatLng

Field Type Description
latitude double The latitude in degrees. It must be in the range [-90.0, +90.0].
longitude double The longitude in degrees. It must be in the range [-180.0, +180.0].

Route

Field Type Description
id string Route ID (e.g. "rte-123e4567-e89b-12d3-a456-426614174000").
name string Route name (e.g. "Morning route").
driver Driver Assigned driver for the route.
start RouteStart Route start address and tasks.
end RouteEnd Route end address and tasks.
stops RouteStop[] Route stops. See RouteStop for stop fields.
createdAt string (RFC3339 format) Timestamp when the route was created.
updatedAt string (RFC3339 format) Timestamp when the route was last updated (by the planner).
archivedAt string (RFC3339 format) Timestamp when the route was archived.
scheduledFor string (RFC3339 format) Timestamp when the route is scheduled for.
totalDistanceMeters double The distance in meters for the entire route.
totalItemQuantity int32 The total quantity of items to deliver on the route.
totalItemGrams int64 (encoded as string) The total weight in grams for the items on the route.
optimized bool Whether the route has been optimized. Adding or removing stops, reordering stops, or changing route options generally set this field to false until the route is reoptimized.

RouteEnd

Field Type Description
address Address The end address of the route.
tasks Task[] Tasks to complete before finishing the route.
plannedArrival string (RFC3339 format) Planned arrival time at the end of the route.
distanceMeters double The distance in meters from the previous stop.
updatedArrival string (RFC3339 format) Estimated arrival time at the end of the route. If the route is completed, this will be the actual arrival time.
status RouteEndStatus Status indicating whether the route has been completed.

RouteEndStatus

Value Description
UNKNOWN Unknown route end status (not complete).
COMPLETED Route has completed.

RouteSortKey

Value Description
UNKNOWN Unknown sort key (not provided or unrecognized).
CREATED_AT Sort by route creation time.
UPDATED_AT Sort by route update time.

RouteStart

Field Type Description
address Address The start address of the route.
tasks Task[] Tasks to complete before starting the route.
status RouteStartStatus Status indicating wheter the route has been started.

RouteStartStatus

Value Description
UNKNOWN Unknown route start status (not started).
STARTED Route has started.

RouteStop

Field Type Description
id string Stop ID (e.g. "rst-123e4567-e89b-12d3-a456-426614174000").
type StopType The type of stop (DELIVERY, BREAK, PICKUP, or TASK).
deliveryStatus DeliveryStatus The status for DELIVERY, PICKUP, or TASK stops.
breakStatus BreakStatus The status for BREAK stops.
updatedAt string (RFC3339 format) Timestamp when the stop status was last updated. Note that this timestamp corresponds only to major status updates (i.e. stop marked as DELIVERED). Minor updates like task completion or adding proof of delivery will not advance this timestamp. For those events, use the timestamps on the task or proof of delivery attachment.
duration string Planned duration of the stop in seconds.
plannedArrival string (RFC3339 format) Planned arrival time at the stop.
note string Top-level note for the stop, as entered manually by route planners, inherited from a saved or imported stop, or set by order import automation rules.
address Address Delivery address for the stop.
contact Contact Contact information for the stop delivery recipient.
plannedCoordinates LatLng Planned coordinates for the stop.
items StopItem[] Items to deliver at the stop.
source StopSource The source of the stop, which may be populated for DELIVERY stops. The source can be a SHOPIFY_ORDER, an EasyRoutes SAVED_STOP, or an IMPORTED_STOP from an external source (such as CSV file).
shopifyOrderId int64 (encoded as string) The Shopify order ID, populated when the stop source is a SHOPIFY_ORDER.
savedStopId string The saved stop ID, populated when the stop source is a SAVED_STOP.
deliveredCoordinates LatLng Delivered coordinates for the stop.
proofOfDeliveryNote string Proof of delivery note for the stop.
proofOfDeliveryPhotos StopAttachment[] Proof of delivery photos for the stop. Photos may be fetched using the URLs on the attachments.
proofOfDeliverySignatures StopAttachment[] Proof delivery signatures for the stop. Signatures may be fetched using the URLs on the attachments.
tasks Task[] Driver tasks for the stop, included completed items and any input from the driver.
priority int32 Priority of the stop for route planning. The valid range for stop priority is between 1 (low) and 10 (high), with default priority corresponding to a value of 5. A priority value of 0 is considered unset and is treated the same as "default" priority. Stops with higher priority will be preferred when generating routes with constraints.
importedStopId string The imported stop ID, populated when the stop source is IMPORTED_STOP.
orderName string The name of the order associated with the stop. For Shopify orders, the name is generated by combining the order_number property with the order prefix and suffix that are set in the merchant's general settings. For EasyRoutes imported orders, this field is populated with the order name provided on import.
distanceMeters double The distance in meters from the previous stop.
updatedArrival string (RFC3339 format) Estimated arrival time at the stop. If the stop is completed, this will be the actual arrival time.
timeWindows TimeWindow[] The time window for the stop. Note that we currently support at most one time window but may support multiple time windows in the future.
deliveryDate Date The planned delivery date for the stop.
attributes Attribute[] Additional attributes for the stop. Attributes are key-value pairs for storing additional structured data on stops. These may be populated from the Shopify order or set on import.
clientStopId string The client-provided ID associated with the stop, if provided on import.
tags string[] The tags for the stop. Tags are used to categorize stops and can be used for filtering and grouping stops in the EasyRoutes web app. These may be populated from the Shopify order or set on import.
attemptedReason AttemptedReason The reason for marking the stop as attempted. This is only populated when delivery_status = ATTEMPTED_DELIVERY.
attemptedNote string Optional note related to the reason for marking the stop as attempted. This is optionally populated when delivery_status = ATTEMPTED_DELIVERY.
customerRating CustomerRating Rating left by customer. This can only be populated once delivery_status = DELIVERED.
customSignatureDisclosure string Optional custom signature disclosure that is shown to customers in the driver app.
shopifyOrder ShopifyOrder Information from the associated Shopify order, if applicable. Populated if stop source is SHOPIFY_ORDER

ShopifyOrder

Field Type Description
orderNote string The Shopify order note.
customerNote string The Shopify customer note for the order.

StopAttachment

Field Type Description
id string Attachment ID (e.g. "att-123e4567-e89b-12d3-a456-426614174000").
createdAt string (RFC3339 format) Timestamp when the attachment was created.
url string URL to fetch the attachment.

StopItem

Field Type Description
name string Item name (e.g. "Bananas").
quantity int32 Quantity of the item (e.g. 5).
grams int32 Weight of the item in grams (e.g. 500).

StopSource

Value Description
UNKNOWN Unknown stop source.
SHOPIFY_ORDER Stop was created from a Shopify order.
SAVED_STOP Stop was created from a saved stop in EasyRoutes.
IMPORTED_STOP Stop was imported from an external source (i.e. CSV file).

StopToImport

Field Type Description
clientStopId string Optional unique ID to associate with the imported stop. If provided, and a stop with the same client_stop_id already exists, the existing stop will be replaced with the new data. Otherwise, a new stop will be created. Note this ID is distinct from the EasyRoutes-generated stop id.
address Address The address for the stop.
contact Contact The contact information for the stop.
coordinates LatLng (Optional) The coordinates for the stop. If not provided, the coordinates will be geocoded from the address when the stop is added to a route.
items StopItem[] The items to deliver at the stop.
note string A note for the stop.
duration string Planned duration of the stop.
priority int32 Priority of the stop for route planning. The valid range for stop priority is between 1 (low) and 10 (high), with default priority corresponding to a value of 5. A priority value of 0 is considered unset and is treated the same as "default" priority. Stops with higher priority will be preferred when generating routes with constraints.
orderName string The name of the order associated with the stop, which can serve as an external reference to the order name / ID outside of EasyRoutes. This field is optional and EasyRoutes does not enforce uniqueness of order names.
timeWindows TimeWindow[] The time windows for the stop. Note that we currently support at most one time window but accept an array for future compatibility.
deliveryDate Date The delivery date for the stop.
attributes Attribute[] Additional attributes for the stop. Attributes are key-value pairs for storing additional structured data on stops. You may specify up to 50 attributes per stop.
tags string[] The tags for the stop. Tags are used to categorize stops and can be used for filtering and grouping stops in the EasyRoutes web app. You may specify up to 250 tags per stop.
tasks TaskTemplate[] The tasks for the stop. Tasks are used to define the work that needs to be completed at the stop by the driver, when the stop is added to a route.
type StopType The type of stop (DELIVERY, PICKUP, or TASK). Defaults to DELIVERY if not provided.
customSignatureDisclosure string Custom signature disclosure for the stop. Only applicable for stops of type DELIVERY, PICKUP, or TASK.

StopType

Value Description
UNKNOWN Unknown stop type.
DELIVERY Delivery stop.
BREAK Break stop.
PICKUP Pickup stop.
TASK Task stop.

Task

Field Type Description
id string Task ID (e.g. "tsk-123e4567-e89b-12d3-a456-426614174000").
title string Task title (e.g. "Delivery checklist").
type TaskType Task type.
items TaskItem[] Task items (populated for CHECKBOXES and RADIO_BUTTONS).
input TaskInput Task input (populated for TEXT_INPUT and DECIMAL_INPUT).
requiredToMarkStopAsDelivered bool Whether the task is required to mark the stop as completed. In the case of tasks on RouteStart, this represents tasks required for starting the route. In the case of tasks on RouteEnd, this represents tasks required for completing the route.
requiredToMarkStopAsAttempted bool Whether the task is required to mark the stop as attempted.

TaskInput

Field Type Description
value string Input value.
updatedAt string (RFC3339 format) Timestamp when the input was last updated.
inputMethod TaskInputMethod Whether input was scanned (e.g. a scanned barcode)

TaskInputMethod

Value Description
UNKNOWN Unknown input method (e.g. manually entered in the system).
SCANNED Input was scanned in the app.

TaskItem

Field Type Description
id string Item ID (e.g. "itm-123e4567-e89b-12d3-a456-426614174000").
title string Item title (e.g. "Pick up package").
complete bool Whether the item is completed.
updatedAt string (RFC3339 format) Timestamp when the item was last updated.

TaskItemTemplate

Field Type Description
title string Item title (e.g. "Pick up package").

TaskTemplate

Field Type Description
title string Task title (e.g. "Delivery checklist").
type TaskType Task type.
items TaskItemTemplate[] Task items, which are required for CHECKBOXES and RADIO_BUTTONS).
requiredToMarkStopAsDelivered bool Whether the task is required to mark the stop as completed.
requiredToMarkStopAsAttempted bool Whether the task is required to mark the stop as attempted.

TaskType

Value Description
UNKNOWN Unknown task type.
CHECKBOXES Task with checkboxes (multiple items to be completed).
RADIO_BUTTONS Task with radio buttons (single item to be selected).
TEXT_INPUT Task with driver text input (free-form text).
DECIMAL_INPUT Task with driver decimal input.
SCANNER_INPUT Task with scanner input.

TimeOfDay

Field Type Description
hours int32 Hours of day in 24 hour format. Should be from 0 to 23.
minutes int32 Minutes of hour of day. Must be from 0 to 59.
seconds int32 Seconds of minutes of the time. Must be from 0 to 59.

TimeWindow

Field Type Description
start TimeOfDay The start time of the time window (optional).
end TimeOfDay The end time of the time window (optional).

Topic

Value Description
UNKNOWN Unknown event type. This is the default value and should not be used.
TEST For testing webhook endpoints. Payload is empty. You may not subscribe to this topic.
ROUTE_CREATED Route created. Payload is the created Route.
ROUTE_UPDATED Route updated. Payload is the updated Route.
ROUTE_DELETED Route deleted. Payload is empty.
ROUTE_COMPLETED Route has completed. Payload is the completed Route.
STOP_STATUS_UPDATED Stop status updated. This topic is a subset of STOP_UPDATED specifically for status updates. Payload is the updated full Route. The objectId field of the webhook will correspond to the updated Stop.
STOP_UPDATED Stop updated as part of Route delivery. This may include stop status updates, stop attachments (proof of delivery, photos, etc) or task updates. Since this topic encompasses a superset of STOP_STATUS_UPDATED, it is recommended to subscribe to one or the other, but not both. Payload is the updated full Route. The objectId field of the webhook will correspond to the updated Stop.
ROUTE_STARTED Route started. Payload is the started Route.
ROUTE_DISPATCHED Route dispatched. Payload is the dispatched Route.
ROUTE_START_STOP_UPDATED Route start stop updated. Example updates include updating tasks on the route start stop.
ROUTE_END_STOP_UPDATED Route end stop updated. Example updates include updating tasks on the route end stop.
DRIVER_ADDED Driver added to shop. Payload is the added Driver. Note that this is fired after an invited Driver completes sign-up. There is no event for a pending invite.
DRIVER_UPDATED Driver profile updated. Payload is the updated Driver.
DRIVER_ACTIVATED Driver activated. Payload is the activated Driver.
DRIVER_DEACTIVATED Driver deactivated. Payload is the deactivated Driver.
DRIVER_ARCHIVED Driver archived. Payload is empty.
IMPORTED_STOP_DELETED Imported stop deleted. Payload is empty.
IMPORTED_STOP_CREATED Imported stop created. Payload is imported stop.
IMPORTED_STOP_UPDATED Imported stop updated. This event is also fired when an imported stop is re-imported using the same client-assigned ID. Payload is imported stop.

WebhookSubscription

Field Type Description
id string Webhook subscription ID (e.g. "sub-123e4567-e89b-12d3-a456-426614174000").
url string The URL to send webhook events to.
topics Topic[] The list of subscribed topics for webhook events.
active bool Boolean indicating whether the subscription is active.
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Related Articles