---
title: "Track Orders"
method: POST
path: "/orders/track"
tags: ["Orders"]
---

# Track Orders

`POST /orders/track`

## Request

- Base URL: `https://v3.api.hypertrack.com`
- URL: `https://v3.api.hypertrack.com/orders/track`
- Auth: one of:
  - HTTP basic
  - HTTP bearer
- TypeScript: <https://skmtc.dev/hypertrack/apis/hypertrack-api/docs/orders/track/post.ts> (a function with typed inputs; its response is checked against the schema)

This API allows the creation and immediate tracking of order fulfillment. If the route has been planned and exists in the HyperTrack system, then tracking can be initiated using the route_handle.

## Request body

- TrackOrdersRequest
  - `route_handle` string, nullable: Unique Handle of route to be tracked. if provided other parameters are not required and will be ignored if provided
  - `driver_handle` string, nullable: One of device_id or driver handle is mandatory
  - `worker_handle` string, nullable: One of device_id or worker handle is mandatory
  - `ops_group_handle` string, nullable: Unique Handle of Ops Group for which orders are to be tracked
  - `device_id` string, nullable: One of device_id or driver handle is mandatory
  - `orders` TrackOrder[], nullable: List of Orders which are to be tracked. Required if route handle is not provided, i.e. new route will be created
    - `order_handle` string, required: Unique handle for Order
    - `destination` union, required: Object representing destination of the order
      - OrderListPolygonDestination
        - `geometry` PolygonGeometry, required
          - `type` 'Polygon', required: Geometry type
          - `coordinates` array[], required: Location coordinates represented as [[[longitude, latitude], [lon, lat]...]]
            - array[]
              - …
        - `address` string, nullable: Address for the order destination
        - `geofence_id` string, nullable: Geofence ID of the order destination
        - `place_handle` string, nullable: Place Handle of the order destination
        - `place_id` string, nullable: Place ID of the order destination
      - OrderListPointDestination
        - `geometry` PointGeometry, required
          - `coordinates` number[], required: Location coordinates represented as [longitude, latitude]
          - `type` 'Point': Geometry type
        - `address` string, nullable: Address for the order destination
        - `geofence_id` string, nullable: Geofence ID of the order destination
        - `place_handle` string, nullable: Place Handle of the order destination
        - `place_id` string, nullable: Place ID of the order destination
        - `radius` integer: Radius (in meters) of the circular geofence representing the order destination, typically between 25m and 200m
      - OrderListGeofenceIdDestination
        - `geofence_id` string, required: Geofence ID to extract geometry from. This is a legacy feature, prefer using `place_handle` now
        - `address` string, nullable: Address for the order destination
      - OrderListPlaceHandleDestination
        - `place_handle` string, required: Place Handle to extract geometry from
        - `address` string, nullable: Address for the order destination
    - `scheduled_at` string, nullable: Schedule time by which order needs to be fulfilled. When this field is not provided, the ETA for the order is computed and the delay is relative to the first ETA.
    - `scheduled_after` string, nullable: Schedule time after which the worker needs to fulfill order (similar to slot start)
    - `expected_service_time` integer, nullable: Specified in seconds.
    - `metadata` object, nullable: Metadata for order
    - `product_type` string[], nullable: Array of string representing skills required to fulfill the order
    - `type` unknown
    - `capacity_used` integer, nullable: Volumetric units which is to be occupied by the order
    - `priority` unknown
    - `type_index` integer, nullable: Volumetric units which is to be occupied by the order
    - `tasks_list` union: List of task associated with the order
      - OrderTaskList
        - `task_definition_id` string, nullable: Id of task definiton from where to copy tasks to this order
        - `tasks` BaseOrderTask[], nullable: List of additional task that need to be performed in the order
          - `label` string, required: Type of task to be created for the order.
          - `task_definition_id` string, nullable: Id of the tasks definition from which this task is picked
          - `description` string, nullable: Description of the task type.
          - `metadata` object, nullable: Additional metadata for the task.
          - `priority` 'none' | 'low' | 'medium' | 'high' | 'null', nullable: Priority of the task. Valid values are none, low, medium, high.
      - unknown
    - `timesheets` CloseoutTimesheet[], nullable: [BETA] Timesheet data for closeout reconciliation. Only used when closeout_mode is 'standalone'.
      - `type` 'system' | 'worker' | 'client' | 'reconciled', required: Type of timesheet: system, worker, client, reconciled
      - `source` 'api' | 'sms' | 'email' | 'phone' | 'agent' | 'null', nullable: How this timesheet was obtained: api, sms, email, phone, agent. Defaults to 'api'.
      - `start_time` string, nullable: Start time (ISO 8601)
      - `end_time` string, nullable: End time (ISO 8601)
      - `total_duration_worked` integer, nullable: Total duration worked in seconds
      - `total_break_duration` integer, nullable: Total break duration in seconds
      - `total_payment_amount` number, nullable: Total payment amount
      - `approved_at` string, nullable: Timestamp when the timesheet was approved by the customer (ISO 8601)
      - `breaks` CloseoutTimesheetBreak[], nullable: Structured break records
        - `start_time` string, required: Break start time (ISO 8601)
        - `end_time` string, required: Break end time (ISO 8601)
        - `duration` integer, nullable: Break duration in seconds
        - `type` 'meal' | 'rest' | 'other' | 'null', nullable: Break category: meal, rest, other
      - `events` CloseoutTimesheetEvent[], nullable: List of timesheet events
        - `start` string, nullable: Start time of the event (ISO 8601)
        - `duration` integer, nullable: Duration of the event in seconds
        - `type` string, nullable: Type of event
        - `data` object, nullable: Additional event data
      - `raw` object, nullable: Raw timesheet data
    - `worker_locations` CloseoutWorkerLocation[], nullable: [BETA] Worker location data for closeout reconciliation. Only used when closeout_mode is 'standalone'.
      - `geometry` PointLocationGeometry, required
        - `type` 'Point', required: Point Geometry type
        - `coordinates` number[], required: Location coordinates represented as [longitude, latitude].
      - `reported_at` string, nullable: When the location was reported (ISO 8601)
      - `inserted_at` string, nullable: When the location was inserted (ISO 8601)
      - `duration_at_location` integer, nullable: Duration at this location in seconds
    - `messages` CloseoutMessage[], nullable: [BETA] Messages data for closeout reconciliation. Only used when closeout_mode is 'standalone'.
      - `timestamp` string, nullable: Message timestamp (ISO 8601)
      - `from` string, nullable: Sender of the message
      - `to` string, nullable: Recipient of the message
      - `type` string, nullable: Type of message
      - `phone_number` string, nullable: Phone number
      - `body` string, nullable: Message body
      - `duration` integer, nullable: Duration in seconds (for call-type messages)
    - `facility_name` string, nullable: [BETA] Facility name for closeout reconciliation. Only used when closeout_mode is 'standalone'.
    - `workflow_ids` string[], nullable: [BETA] Workflow IDs for closeout reconciliation. Only used when closeout_mode is 'standalone' or 'tracked'.
  - `track_mode` 'full_shift' | 'pre_shift' | 'on_shift', required: Tracking mode of the order. Note that `on_time` and `flex` are deprecated modes.
  - `route` union: Route that will be created to contain the orders to be tracked
    - TrackOrderRoute
      - `route_handle` string, nullable: route handle for the route to be created
      - `metadata` object, nullable: Metadata for the route
    - unknown
  - `version` integer, nullable: Route version.
  - `agent_mode` unknown
  - `closeout_mode` unknown
  - `worker_phone_number` string, nullable: [BETA] Worker phone number for closeout reconciliation. Only used when closeout_mode is 'standalone'.
  - `device_switch_mode` 'manual' | 'login' | 'closest_to_destination' | 'null', nullable: Mode to control the active device for tracking orders. The following options are available: - `login` : Order tracking is based on the device the worker last logged into. When the worker logs into a new device, the orders automatically transfer to the new device. This is the default setting. - `closest_to_destination` : Order tracking is based on the device closest to the order's destination. The system monitors all of the worker's recent devices and selects the one nearest to the destination for tracking the order. - `manual` : Order tracking remains on the device that was active when the order was created.

## Response `201`

Successful response

- TrackOrdersResponse
  - `route_handle` string, required: Unique identifier for the route
  - `status` 'planned' | 'assigned' | 'tracking' | 'completed' | 'summarizing', required: Current state of route
  - `version` integer, required: Value indicating the latest updated state of the route
  - `created_at` string, required: Timestamp at which the route was created
  - `embed_url` string, required: Embeddable link that renders the route profile view
  - `orders` TrackedOrder[], required: List of orders to be fulfilled in the route
    - `timezone` string, nullable: Time zone
    - `order_handle` string, required: Unique customer provided identifier for an order
    - `status` 'planned' | 'assigned' | 'dispatched' | 'ongoing' | 'disabled' | 'cancelled' | 'completed' | 'summarizing' | 'unplanned', required: Current state of the order - `unplanned`, `planned`, `assigned`, `ongoing`, `completed`, `cancelled`
    - `destination` OrderDestinationSpecialType, required
      - `geofence_id` string, nullable: Geofence ID to extract geometry from
      - `place_handle` string, nullable: Place Handle to extract geometry from
      - `address` string, nullable: Address for the order destination
      - `geometry` union, required: GeoJSON representation of point geometry for the order destination
        - PointGeometry
          - `coordinates` number[], required: Location coordinates represented as [longitude, latitude]
          - `type` 'Point': Geometry type
        - PolygonGeometry
          - `type` 'Polygon', required: Geometry type
          - `coordinates` array[], required: Location coordinates represented as [[[longitude, latitude], [lon, lat]...]]
            - array[]
              - …
      - `place_id` string, nullable: Place ID
      - `radius` integer, nullable: Radius of the circular geofence representing the order destination
    - `fulfillment_attempt` integer, nullable: Number identifying the attempt count for the order
    - `risk_status` boolean, nullable: Flag indicating whether the order is at risk
    - `ops_group_handle` string, nullable: Unique identifier for the ops group to which the orders in the route are associated
    - `plan_mode` unknown
    - `plan_id` string, nullable: Order plans identifier
    - `planning_failure_reason` string, nullable: Reason explaining why automated planning left the order unplanned. Present only when a planning attempt could not assign the order.
    - `device_id` string, nullable: Unique identifier for a device
    - `driver_handle` string, nullable: Unique customer provided identifier for the driver
    - `worker_handle` string, nullable: Unique customer provided identifier for the worker
    - `place_handle` string, nullable: Unique customer provided identifier of the place
    - `created_at` string, nullable: Timestamp at which the order was created
    - `started_at` string, nullable: Timestamp at which the order tracking started
    - `assigned_at` string, nullable: Timestamp at which the order was assigned to a driver
    - `driver_name` string, nullable: Customer provided name for the driver
    - `planned_at` string, nullable: Timestamp at which the order was planned into a route
    - `scheduled_at` string, nullable: Timestamp by which the order should be fulfilled to meet the customer promise
    - `scheduled_after` string, nullable: Timestamp after which the order should be fulfilled to meet the customer promise
    - `completed_at` string, nullable: Timestamp at which the order was completed
    - `cancelled_at` string, nullable: Timestamp at which the order was cancelled
    - `disabled_at` string, nullable: Timestamp at which the order was disabled so that it can be fulfillment later
    - `enabled_at` string, nullable: Timestamp at which the disabled order was enabled for fulfillment
    - `arrived_at` string, nullable: Timestamp at which the driver arrived at the order fulfillment location
    - `exited_at` string, nullable: Timestamp at which the driver exited from the order fulfillment location
    - `metadata` object, nullable: Additional customer provided information about the order
    - `risks` object, nullable: Object containing different risk statuses for the order
    - `expected_service_time` integer, nullable: Time in seconds that the driver is expected to spend at the location when fulfilling the order
    - `product_type` string[], nullable: List of customer provided product/service types used when matching orders to a driver
    - `type` unknown
    - `type_index` integer, nullable: Field to specify the index of type
    - `capacity_used` integer, nullable: Volumetric unit occupied by the order
    - `region` union: City, state, and country where the orders needs to be fulfilled
      - Region
        - `country` string, required: Country
        - `city` string, nullable: City
        - `state` string, nullable: State
      - unknown
    - `distance` integer, nullable: Total distance in meters travelled by the driver to reach the order location
    - `duration` integer, nullable: Total time in seconds spent on the order.
    - `estimate` union: Object containing the estimate information for the order that has not been completed
      - OrderListEstimate
        - `start_at` string, nullable: Deprecated: use `start_by`. Always returns the same value as `start_by`.
        - `start_by` string, nullable: Latest time the worker can leave their current (or planned start) location and still reach this order by its `scheduled_at`, following the route sequence and the remaining service time at earlier stops. Computed by planning and once at the first tracking ETA, which uses traffic for the planned arrival time. `null` when the order has no `scheduled_at`.
        - `arrive_at` string, nullable: Estimated timestamp by which a driver should arrive at order destination
        - `distance` integer, nullable: Estimated total distance that the driver should travel
        - `duration` integer, nullable: Estimated total time that the driver should spend to fulfill all orders in the route
        - `initial_arrive_at` string, nullable: Initial Estimated timestamp by which a driver should arrive at the destination
        - `current_worker_location` union: Current Worker location details
          - DriverLocation
            - `geometry` LocationGeometryResponse, required
              - …
            - `bearing` number, required: Bearing of the driver
            - `accuracy` number, required: Accuracy of location the driver
            - `speed` number, required: Speed of the driver
            - `recorded_at` string, required: Time when the location of the driver was recorded
          - unknown
      - unknown
    - `share_url` string, nullable: Shareable URL for the consumer to track the live movement of the drive after the order is dispatched
    - `route_handle` string, nullable: Unique identifier for the route
    - `track_mode` unknown
    - `actual_service_time` integer, nullable: Time in seconds that the driver is actually spent at the location when fulfilling the order
    - `tracked_service_time` integer, nullable: Time in seconds that the driver was tracked at the location when fulfilling the order
    - `tracking_rate` number, nullable: Indicates the ratio of time tracked to expected tracking time of order. Values lie between 0.0 and 1.0
    - `time_to_first_event` number, nullable: Time in seconds to receive first event from device after order start
    - `time_to_first_location` number, nullable: Time in seconds to receive first location from device after order start
    - `created_by` union: Source of the order creation. This can be a user, system, or any other entity responsible for creating the order.
      - Source
        - `source` string, nullable: Source of the request
        - `timestamp` string, nullable: Time when request was made
        - `ip-address` string, nullable: IP address of source
        - `device_id` string, nullable: Id of the device that made the request
        - `driver_handle` string, nullable: Id of the driver who made the request
        - `user_id` string, nullable: Id of the user who made the request
        - `email` string, nullable: Email of the user who made the request
      - unknown
    - `outage_summary` OrderOutageSummary[], nullable: List of outages experienced during the specified time range.
      - `duration` integer, required: Sum total duration of all outages experienced with this `code` in the specified time range.
      - `distance` integer: Sum total (estimated) distance covered during all outages experienced with this `code` in the specified time range.
      - `code` string, required: Code indicating the type of outage
      - `label` string, required: Text indicating the type of outage
      - `description` string, required: Text describing the outage.
      - `category` 'behavioural' | 'adversarial' | 'reachability' | 'os' | 'sporadic' | 'null', nullable: String indicating the category of outage
    - `embed_url` string, nullable: Embeddable URL for the ops team to view order timeline
    - `device_switch_mode` unknown
    - `tasks` OrderTask[], nullable: List of tasks associated with the order.
      - `label` string, required: Type of task to be created for the order.
      - `task_definition_id` string, nullable: Id of the tasks definition from which this task is picked
      - `description` string, nullable: Description of the task type.
      - `metadata` object, nullable: Additional metadata for the task.
      - `priority` 'none' | 'low' | 'medium' | 'high' | 'null', nullable: Priority of the task. Valid values are none, low, medium, high.
      - `task_id` string, required: Unique identifier for the created task.
      - `status` string, nullable: Status of the task. Valid values are pending, ongoing, completed, cancelled.
    - `priority` unknown
    - `worker_profile` object, nullable: Metadata associated with a driver
    - `rescheduled_marked_at` string, nullable: Timestamp at which the order was rescheduled
    - `cancellation_source` object, nullable: Detail about how order got cancelled
    - `cancellation_reason` string, nullable: Customer-reported reason why the shift did not occur as planned: `no_show`, `worker_cancelled`, `client_cancelled`, `other`. Consumers must accept new values.
    - `timesheets` union[], nullable: Timesheet entries for the order. Includes HyperTrack-computed (HypertrackLocationTimesheet) and customer-provided entries.
      - union
        - HypertrackLocationTimesheet
          - `source` string, required: Always hypertrack-location. Identifies this as a HyperTrack-computed entry.
          - `type` string, required: Always location. Distinguishes this computation type from future types.
          - `start_time` string, nullable: ISO 8601 timestamp when the worker arrived on site (first geofence entry). Null if the worker never entered the destination geofence.
          - `end_time` string, nullable: ISO 8601 timestamp when the worker left the site (last geofence exit). Null if the worker was still inside at order closure.
          - `total_duration_on_premises` integer, required: Total seconds the worker spent at the destination (sum of geofence visit durations).
          - `total_break_duration` integer, required: Residual seconds not at the destination. Equals (end_time - start_time) - total_duration_on_premises.
          - `breaks` BreakEntry[], nullable: Geofence exit→re-entry windows representing time away from the destination. Each entry has start_time, end_time, and duration (seconds). Null when there are no exit→re-entry gaps.
            - `type` string, required: Break type (e.g. "meal", "rest").
            - `start_time` string, required: ISO 8601 timestamp when the break started.
            - `end_time` string, required: ISO 8601 timestamp when the break ended.
            - `duration` integer, required: Break duration in seconds.
          - `finalized` boolean, required: Always true. Signals this entry was computed at order completion and will not change.
        - object
  - `created_by` union: Source of the route creation. This can be a user, system, or any other entity responsible for creating the route.
    - Source
      - `source` string, nullable: Source of the request
      - `timestamp` string, nullable: Time when request was made
      - `ip-address` string, nullable: IP address of source
      - `device_id` string, nullable: Id of the device that made the request
      - `driver_handle` string, nullable: Id of the driver who made the request
      - `user_id` string, nullable: Id of the user who made the request
      - `email` string, nullable: Email of the user who made the request
    - unknown
  - `ops_group_handle` string: URL safe unique identifier for the ops group to which the orders in the route are associated
  - `track_mode` 'full_shift' | 'on_shift' | 'pre_shift', required: Value representing whether the order is tracked in on_shift, pre_shift or full_shift mode. Modes such as `on_time` and `flex` are deprecated.
  - `plan_mode` 'on_demand' | 'scheduled' | 'manual' | 'null', nullable: Value indicating how the orders in the route were planned
  - `started_at` string, required: Timestamp at which the route tracking started
  - `assigned_at` string, required: Timestamp at which the route was assigned to a driver
  - `planned_at` string, nullable: Timestamp at which the orders were planned into this route
  - `completed_at` string, nullable: Timestamp at which the route was completed
  - `device_id` string, nullable: Unique identifier for a device
  - `driver_handle` string, nullable: Unique customer provided identifier for the driver
  - `worker_handle` string, nullable: Unique customer provided identifier for the worker
  - `metadata` object, nullable: Additional customer provided information about the route
  - `region` union: City, state, and country where the orders in the route are being fulfilled
    - Region
      - `country` string, required: Country
      - `city` string, nullable: City
      - `state` string, nullable: State
    - unknown
  - `distance` integer, nullable: Actual distance travelled by the driver to fulfill all orders in the route
  - `duration` integer, nullable: Actual time spent by the driver to fulfill all orders in the route
  - `estimate` union: Object containing the estimate information for routes that have not been completed
    - RouteDetailEstimate
      - `start_by` string, nullable: Latest time the worker can leave the planned start location and still reach every scheduled order in the route on time, following the route sequence and service times. Orders without `scheduled_at` use a placeholder deadline. Computed at planning.
      - `distance` integer, required: Estimated total distance that the driver should travel in the route
      - `duration` integer, required: Estimated total time that the driver should spend to fulfill all orders in the route
      - `polyline` EstimatePolyline, required
        - `type` string, required: Type of GeoJSON feature. It will always be `LineString` for polyline
        - `coordinates` array[], required: GeoJSON representation of LineString coordinates, inner list element is represented as [longitude, latitude]
          - unknown[]
            - unknown
      - `start_location` union: The starting point location from where the driver begins their journey for the route
        - LocationGeometryResponse
          - `type` string, required: Geometry type
          - `coordinates` unknown[], required: Location coordinates represented as list of [longitude, latitude].
            - unknown
        - unknown
      - `end_location` union: The final destination location where the route ends after completing all orders
        - LocationGeometryResponse
          - `type` string, required: Geometry type
          - `coordinates` unknown[], required: Location coordinates represented as list of [longitude, latitude].
            - unknown
        - unknown
    - unknown
  - `plan_id` string, nullable: Unique identifier for the plan to which the route belongs to
  - `device_switch_mode` unknown
  - `candidate_devices` string[], nullable: List of devices among which the route is expected to be tracked
  - `completion_source` string, nullable: Source of the route completion
  - `scheduled_start_at` string, nullable: Scheduled start time of the route
  - `polyline` union: LineString of actual coordinates traversed by the driver to fulfill the orders in the route
    - Polyline
      - `type` string, required: Type of GeoJSON feature. It will always be `LineString` for polyline
      - `coordinates` array[], required: GeoJSON representation of LineString coordinates, inner list element is represented as [longitude, latitude, altitude, recorded_at]
        - unknown[]
          - unknown
    - unknown
  - `start_location` union: Location where the driver started tracking to fulfill the orders in the route
    - LocationGeometryResponse
      - `type` string, required: Geometry type
      - `coordinates` unknown[], required: Location coordinates represented as list of [longitude, latitude].
        - unknown
    - unknown
  - `end_location` union: Location where the driver stopped tracking after completing all orders in the route
    - LocationGeometryResponse
      - `type` string, required: Geometry type
      - `coordinates` unknown[], required: Location coordinates represented as list of [longitude, latitude].
        - unknown
    - unknown
  - `tracking_rate` number, nullable: Indicates the ratio of time tracked to expected tracking time of route. Values lie between 0.0 and 1.0
  - `time_to_first_event` number, nullable: Time in seconds to receive first event from device after order start
  - `time_to_first_location` number, nullable: Time in seconds to receive first location from device after order start
  - `completion_type` 'end_at_last_order' | 'return_to_start_location' | 'manual' | 'null', nullable: Configuration to identify where routes are expected to end

## Other responses

- `400`: Bad Request
- `401`: Authentication error
- `404`: Not Found
- `409`: Conflict

---

[API](https://skmtc.dev/hypertrack/apis/hypertrack-api.md) - [All operations](https://skmtc.dev/hypertrack/apis/hypertrack-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hypertrack/apis/hypertrack-api/revisions/389326c4c9c8?raw)