HyperTrackDocs
Orders

Get Routes

Retrieve routes based on the filter parameters provided ### Planning failure reasons When an order is left unplanned by automated planning, `planning_failure_reason` may contain one of these values: - `No Worker was available for this plan.` - `No Worker schedule overlaps with this order's time window.` - `This order is outside the available Worker working hours.` - `Worker location is unavailable, so travel time could not be evaluated.` - `Worker start location is unavailable for the configured route start setting.` - `No Worker supports the required product type for this order.` - `Route was being modified concurrently and this order needs to be re-planned.` - `The optimizer dropped this order to satisfy planning constraints for the overall plan.` - `The optimizer could not find a feasible plan for the provided constraints.` - `Travel time calculation failed for this planning attempt.` - `Ops group configuration is incomplete for automated planning.` - `Assigning this order would exceed route or Worker capacity.` - `No Worker can reach this order before scheduled_at.` - `Assigning this order would delay an already planned downstream order.` - `Assigning this order would exceed the Worker's shift end time.` - `Automated planning could not assign this order with the provided constraints.`

GET
/orders/routes/

Retrieve routes based on the filter parameters provided

Planning failure reasons

When an order is left unplanned by automated planning, planning_failure_reason may contain one of these values:

  • No Worker was available for this plan.
  • No Worker schedule overlaps with this order's time window.
  • This order is outside the available Worker working hours.
  • Worker location is unavailable, so travel time could not be evaluated.
  • Worker start location is unavailable for the configured route start setting.
  • No Worker supports the required product type for this order.
  • Route was being modified concurrently and this order needs to be re-planned.
  • The optimizer dropped this order to satisfy planning constraints for the overall plan.
  • The optimizer could not find a feasible plan for the provided constraints.
  • Travel time calculation failed for this planning attempt.
  • Ops group configuration is incomplete for automated planning.
  • Assigning this order would exceed route or Worker capacity.
  • No Worker can reach this order before scheduled_at.
  • Assigning this order would delay an already planned downstream order.
  • Assigning this order would exceed the Worker's shift end time.
  • Automated planning could not assign this order with the provided constraints.

Authorization

AuthorizationBasic <token>

In: header

Query Parameters

completed_at_date?|

Filter for routes completed on specified date (YYYY-MM-DD)

completed_at_from?|

Filter for routes completed after specified timestamp (YYYY-MM-DD HH:mm:ss)

completed_at_to?|

Filter for routes completed before specified timestamp (YYYY-MM-DD HH:mm:ss)

created_at_date?|

Filter for routes created on specified date (YYYY-MM-DD)

created_at_from?|

Filter for routes created after specified timestamp (YYYY-MM-DD HH:mm:ss)

created_at_to?|

Filter for routes created before specified timestamp (YYYY-MM-DD HH:mm:ss)

worker_handle?|

Unique customer provided identifier of the worker to used retrieve routes associated with the specified worker

driver_handle?|
Deprecated

Unique customer provided identifier of the driver to used retrieve routes associated with the specified driver

ops_group_handle?|

Filter for routes on specified ops group handle or list of comma separated handles

plan_mode?|

Filter for routes on specified plan mode (manual -> routes created manually, scheduled -> routes created automatically)

planned_at_date?|

Filter for routes planned on specified date (YYYY-MM-DD).

planned_at_from?|

Filter for routes planned after specified timestamp (YYYY-MM-DD HH:mm:ss)

planned_at_to?|

Filter for routes planned before specified timestamp (YYYY-MM-DD HH:mm:ss)

region_filter?|

JSON object containing city, state, or country used to filter routes

route_metadata_filter?|

JSON object representing route metadata to be used to filter routes

sort_direction?|

Sort route responses by asc or desc on the created_at timestamp

start_by_date?|

Date (YYYY-MM-DD) used as a filter to retrieve routes that need to start by the given date

start_by_from?|

Timestamp (YYYY-MM-DD HH:mm:ss) of the start of window to retrieve routes that need to start within a timeframe

start_by_to?|

Timestamp (YYYY-MM-DD HH:mm:ss) of the end of window to retrieve routes that need to start within a timeframe

started_at_date?|

Date (YYYY-MM-DD) used as a filter to retrieve routes that started on a given date

started_at_from?|

Timestamp (YYYY-MM-DD HH:mm:ss) of the start of window to retrieve routes that started within a timeframe

started_at_to?|

Timestamp (YYYY-MM-DD HH:mm:ss) of the end of window to retrieve routes that started within a timeframe

scheduled_start_at_from?|

Timestamp (YYYY-MM-DD HH:mm:ss) of the start of window to retrieve routes that scheduled start within a timeframe

scheduled_start_at_to?|

Timestamp (YYYY-MM-DD HH:mm:ss) of the end of window to retrieve routes that scheduled start within a timeframe

status?|

Filter for routes that are planned, assigned, tracking, or completed, to filter for multiple statuses, pass them as comma separated values

track_mode?|

Filter for routes that are on_time, flex, on_shift, pre_shift or full_shift

pagination_token?|

Encoded value provided by our API to retrieve the next page of routes

search_term?|

String representing the search term. Search will be done on route_handle, ops_group_handle, worker_handle and metadata fields.

limit?|

Max results to fetch

device_switch_mode?unknown

Filter for routes with a device_switch_mode

plan_id?|

Filter by plan id

device_id?|

Filter by device id

device_metadata_filter?|

JSON object representing device metadata to be used to filter routes

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/orders/routes/"

{  "routes": [    {      "route_handle": "afb94d64-2702-4efa-b938-d1facfd7832e",      "status": "completed",      "version": 1,      "embed_url": null,      "orders": [        {          "order_handle": "order-1",          "status": "cancelled",          "type": "drop",          "type_index": 0,          "estimate": {            "distance": 73863,            "duration": 3614,            "start_by": "2023-10-31T02:59:46.000Z"          },          "cancelled_at": "2023-10-31T00:12:56.688Z",          "expected_service_time": 0        },        {          "order_handle": "order-2",          "status": "cancelled",          "type": "pick",          "type_index": 0,          "estimate": {            "distance": 75766,            "duration": 3732,            "start_by": "2023-10-31T00:57:48.000Z"          },          "cancelled_at": "2023-10-31T00:13:01.073Z",          "expected_service_time": 0        }      ],      "ops_group_handle": "store-SF",      "started_at": "2023-10-31T00:57:48.000Z",      "created_at": "2023-10-31T00:12:22.767Z",      "region": {        "country": "United States",        "city": "San Jose",        "state": "California"      },      "completed_at": "2023-10-31T00:13:01.255Z",      "plan_mode": "manual",      "plan_id": "a7a9c72e-bf31-44f5-8a59-c4fffb5fb9d4"    },    {      "route_handle": "a3f6e79c-c830-4766-8a3d-9eeaa5099ce1",      "status": "completed",      "version": 1,      "embed_url": "https://embed.hypertrack.com/trips/a3f6e79c-c830-4766-8a3d-9eeaa5099ce2?publishable_key=a5pvd2PekFvSSuZrwivgJS_Ssd6irX1n9qRBIn9nl3PTK-5y3BO56rolpGuzhp1pIoH4TiDyqWIq8IEkOJCqeg",      "orders": [        {          "order_handle": "order-3",          "status": "cancelled",          "type": "pick",          "type_index": 0,          "estimate": {            "distance": 75766,            "duration": 3732,            "start_by": "2023-10-31T00:57:48.000Z"          },          "cancelled_at": "2023-10-31T23:13:13.926Z",          "expected_service_time": 0        },        {          "order_handle": "order-4",          "status": "completed",          "type": "drop",          "type_index": 0,          "estimate": {            "distance": 73514,            "duration": 3571,            "start_by": "2023-10-31T03:00:29.000Z"          },          "completed_at": "2023-10-31T23:13:21.287Z",          "expected_service_time": 0        }      ],      "ops_group_handle": "store-SF",      "started_at": "2023-10-31T03:00:29.000Z",      "assigned_at": "2023-10-31T23:13:03.788Z",      "created_at": "2023-10-31T23:12:55.529Z",      "device_id": "52223948-1A79-47CC-AB81-2FB0A59536D2",      "worker_handle": "james@ht.com",      "region": {        "country": "United States",        "city": "San Jose",        "state": "California"      },      "completed_at": "2023-10-31T23:13:21.647Z",      "plan_mode": "manual"    }  ]}

{  "detail": {},  "message": "string"}
{  "detail": {    "<location>": {      "<field_name>": [        "string"      ]    }  },  "message": "string"}

Create an order export job POST

Creates an asynchronous job to export orders to CSV.gz file. Returns a job_id that can be used to check status. Download link will be sent via email when ready.

Create Route POST

This API is used to plan a set of unplanned orders into a route