TripsV1 to Orders API
Why migrate to Orders API?
Orders API represents the next generation of our product, introducing new capabilities made possible by its improved architecture and implementation.
It offers more granular control and supports advanced shift-based workflows. This shift from mere tracking to comprehensive location intelligence represents a holistic approach to understanding and addressing proof of work. For TripsV1 customers, this is a major leap from being able to track a single shift to having the ability to create multi-shift use cases which are the need of the hour.
Here are some key features of the Orders API:
- A new range of APIs that provide more granular control for advanced workflows.
- Seamless integration with other HyperTrack features, such as Places, Geotags, and Visits.
- Native NCNS (No-call No-show) and Order risk detection capabilities
- The introduction of the Places API, which leverages places of interest created through the Orders API to refine geofence definitions and provide insights based on historical visits. This enhancement ensures a more reliable proof of work and leads to better route optimizations. You can use the same Place API handle in Orders API calls while benefiting from ongoing updates and enhancements as HyperTrack refines geofence definitions for these places.
- The Orders suite now includes Clock-in/Clock-out signals to clearly define shift boundaries, aiding in better payout accuracy and dispute resolution. Combined with the new SDK, you can ensure that workers Clock-in/Clock-out only inside the destination boundary.
- API supports automatic worker device management where Orders are moved between devices when the workers login to different devices
- API supports the use of Places that automatically handles geofence creations based on the defined Place. This integration provides customers with improved geofence shapes based on ground truth that helps improve fraud detection, provides better ETAs, and worker left early detections
- Enhanced UI experiences with point in time ETAs and replay features
- The performance of the API has been improved.
- Enhanced performance and geofence detection accuracy through the integration of the Orders/Places Suite with our new SDK, which delivers a more accurate location stream.
- Addition of more detailed information to our Webhooks.
These enhancements make the Orders API a robust tool for managing workforce logistics with precision and insight.
Migration Steps
1. Migrate from Devices to Workers
For the Orders API, we've introduced the concept of a Worker. This is the person that is assigned a gig and goes to your customer location to complete the perform the service. A worker is associated with only one device at any given instance, but we now provide the ability for the worker to change their device seamlessly between shifts while ensuring their work is correctly attributed to them.
To learn more on how to set up your workers check out our Worker Setup guide.
In this step, you can create a worker for each device you currently have in the HyperTrack system and map them.
2. Migrate your API from Trips to Orders
With TripsV1, you used the following endpoints:
- POST /trips
- POST /trips/{trip_id}/complete
- GET /trips/{trip_id}
- GET /trips/{trip_id}/analytics
- GET /trips
Create Order with Orders API
To track and Order, update the endpoint from POST /trips to POST /order/track. Here are comparable samples of the payloads:
| TripsV1 Payload | Orders Payload |
|---|---|
| { "device_id": "4432225-AC7E-4740-AFB0-D42142FF9255", "destination": { "radius": 500, "generate_estimate": true, "scheduled_at": "2024-02-26T01:30:00+00:00", "geometry": { "type": "Polygon", "coordinates": [ [ [-90.013951, 35.031187], [-90.013919, 35.030037], [-90.012792, 35.030037], [-90.012878, 35.031187], [-90.013951, 35.031187], [-90.013951, 35.031187], [-90.013951, 35.031187], [-90.013951, 35.031187], [-90.013951, 35.031187] ] ] } }, "metadata": { "shift_id": "42222", "worker_id": "15522" } } | { "worker_handle": "[email protected]", "track_mode": "on_time", "ops_group_handle": "default", "orders": [ { "order_handle": "order-1", "scheduled_at": "2024-02-26T01:30:00Z", "destination": { "address": "1709 Automation Pkwy, San Jose, CA 95101", "geometry": { "type": "Polygon", "coordinates": [ [ [-90.013951, 35.031187], [-90.013919, 35.030037], [-90.012792, 35.030037], [-90.012878, 35.031187], [-90.013951, 35.031187], [-90.013951, 35.031187], [-90.013951, 35.031187], [-90.013951, 35.031187], [-90.013951, 35.031187] ] ] }, } , "metadata": { "shift_id": "42222", "worker_id": "15522" } }, ] } |
Note the new order_handle field that allows you to label the order using your business term for the shift
Complete the Order
To complete an order being tracked, update the endpoint from POST /trips/{trip_id}/complete to POST orders/<order_handle>/complete.
Get Order data
To get the details of a single Order, update the endpoint from GET /trips/<trip_id> to GET /orders/<order_handle>
To get the list of all Orders with your choice of filtering, update the endpoint from GET /trips to GET /orders
To get analytics data for an Order, update the endpoint from GET /trips/<trip_id>/analytics to GET /orders/<order_handle>. This endpoint provides the active duration at destination, tracking rate, active duration and total duration of tracking during the lifetime of the Order.
Orders API
There's so much more to do with the new Orders API, so please check the Orders API references
3. Enhance your workflows with Order webhooks
The only impact of this migration are the deprecation of trips webhooks for orders webhooks. The following list of webhooks are unchanged:
- location
- device_status
- battery
- trip
- reinstall
- registration_update
The mapping of the Trips API to Orders API are listed below:
| Trips Webhook | Orders Webhook | New Type |
|---|---|---|
| Trip Created | Route Created | route |
| Trip Destination Arrival | Order Arrived | order |
| Trip Destination Exit | Order Exited | order |
| Trip Delayed | Order Delayed | order |
| Trip First ETA | Order First ETA | order |
| Trip ETA Change | Order ETA Change | order |
| Trip Completed | Order Completed | order |
Additionally you will also receive webhooks around Risks and Place boundary corrections.
Webhooks
You can find more information on Order webhooks here
4. Migrate to the new UI
We've been chipping away at creating a much better UI experience for your Ops teams. If you are users of our embed and trckat views, you can make the changes below to get the latest experience with your Orders.
https://embed.hypertrack.com/trips/{trip_id}?publishable_key={your_key}
https://embed.hypertrack.com/views/orders/{order_handle}?publishable_key={your_key}
Here's what the new world looks like!
New UI Experience
There are a lot more improved UI experiences for you Ops teams to adopt. Please take a look here for more information.
Voila! Following these steps will move you to the new HyperTrack world!
Migrations are hard and the HyperTrack team is with you every step of the way, so feel free to reach out to us and we'll ensure that your experience is as seamless as possible.
Updated 13 days ago