TripV2 to Order API

Why Migrate to Orders API?

As shift work evolves, it's crucial for our customers to adapt to these changes. That’s why we've developed the new Orders API.

Previously, our Trips v2 API enabled customers to support use cases involving workers on multiple shifts per day by introducing the concept of Orders. We've taken this functionality a step further with the Orders API, offering more granular control and supporting advanced shift-based workflows. This shift from mere tracking to comprehensive location intelligence represents a holistic approach to understanding and addressing proof of work.

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.
  • 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.
  • 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 the TripsV2 APIs, you used the following endpoints:

- POST /trips
- POST /trips/{trip_id}/complete
- GET /trips/{trip_id}
- GET /trips/{trip_id}/analytics
- GET /trips

Now we provide a larger set of APIs to support more granular workflows. To learn more about the available APIs check the Orders API Reference.

Here are some samples of the key API mappings:

a. Create Trip -> Orders

// POST /trips
{
  "device_id": "65893616-AC7E-4740-AFB0-C42242FF9661",
  "orders": [
  	{
  	  "order_id": "test_order",
  	  "metadata": {
		 "shift_id": "ccWZY7p",
		 "worker_id": "53332",
		 "business_name": "Eldon Roark Tennis Center",
		 "business_id": "Bsw2AJo",
		 "worker_name": "cyntresia d.",
		 "message": "cyntresia d. to Eldon Roark Tennis Center (ccWZY7p)"
  	  },
  	  "scheduled_at": "2024-02-26T01:30:00+00:00",
	  "destination": {
	    "radius": 500,
		    "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]
		        ]
		      ]
		    }
		}
  	}
  ]
}

With the new Orders API, you can use a previously created place via its place_handle value to create an order destination. See Places API guide on how to create a place required for this Orders API example below.

// POST /orders/track
{
   "driver_handle": "[email protected]",
   "track_mode": "on_time",
   "orders": [
       {
          "order_handle": "test_order",
           "destination": {
        		"place_handle": "eldon_roark_tennis_center"
      		},
          "scheduled_at":  "2024-02-26T01:30:00+00:00",
				  "metadata": {
				    "shift_id": "ccWZY7p",
				    "worker_id": "53332",
				    "business_name": "Eldon Roark Tennis Center",
				    "business_id": "Bsw2AJo",
				    "worker_name": "cyntresia d.",
				    "message": "cyntresia d. to Eldon Roark Tennis Center (ccWZY7p)"
				  }
       }
   ]
}

b. Get trips -> orders

// GET /trips/{trip_id} -- Fetch a particular trip
// GET /trips -- Fetch all trips 
// GET /trips/{trip_id}/analytics -- Fetches the analytics for the trip

// GET /orders/{order_handle} -- Fetch a particular order
// GET /orders -- Fetch all orders
// GET /orders/{order_handle} -- Fetches the analytics and timeline for the order

c. Complete trip -> order

// POST /trips/{trip_id}/complete

// POST /orders/{order_handle}/complete

📘

There's so much more to do with the new Orders API, so please check the Orders API references

3. Migrate your 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 ot 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 is what the new world look like!

📘

For trckat customer links, you don't need any change!

4. Webhook Trips -> Orders

While there are some common webhooks you'll continue to receive, webhooks of type trip will no longer be sent. We instead provide a set of order webhooks as listed below.

Common webhooks:

Order webhooks:

📘

You can find more information on Order webhooks here

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 15 days ago