There's two methods of tracking packages with EasyPost:
Our tracking service uses webhooks to give you updates about your shipments. Refer to our webhooks guide to learn how we use webhooks to send you tracking updates.
If you haven't run through our Getting Started Guide, definitely do that before moving on to this one.
To track a shipment not created with EasyPost, you simply need to create a Tracker Object. You need to pass the “tracking_code" and “carrier” to the API. The “carrier” attribute is optional, though it is best to pass it if you have it available. When the “carrier” attribute is not passed, we will auto-detect the carrier for you. If we are unable to match the tracking code to a specific carrier, we will return an error.
Here is an example of how to make a tracker object:
After a Tracker is created, we will periodically check the status of your package and notify you when its status changes. Jump to Step 2 to learn how we'll give you updates via webhooks.
To start tracking a package, there is nothing extra you need to do. Whenever you purchase a shipping label with EasyPost, we’ll start automatically tracking its progress and notifying you of any updates via webhooks (more on that in step 2).
When you purchase a shipping label, we will also respond back with the tracking number for the label. You don’t need to store the tracking number to get tracking updates but it is generally good practice to store it. Here’s an example of purchasing a shipping label and getting a tracking number. To see all the steps for shipping a package, take a look at our Getting Started Guide.
After you purchase a shipping label or create a tracker, we will automatically start sending tracking update Events. Event Objects are sent to the webhook URLs you’ve configured. Updates will only be sent when there is a status change for the package (e.g. a package changes from "Out for Delivery" to "Delivered"). We check the status of each package more frequently once it is Out for Delivery.
The Tracker Object statuses are listed in our API Documentation.
When you purchase a label in either Test or Production mode, you will immediately get a tracking event after purchase. Test and Production mode behave slightly differently:
You’ll know it is a tracking update event because the object "type" is "Event" and the "description" is "tracker.updated". The "result" value of Event will also contain a Tracker object that has the information about the current progress of the package. When building application logic, the “status” of Tracker object is most useful and reliable to use.
The Tracker object also contains additional information from the carrier in “tracking_details” attribute. For example, along with “in_transit” updates you may receive information that it reached a particular location (eg “Processed through Sort Facility June 01 2013 4:53 pm BELL GARDENS CA 9020”). The “tracking_details” will be an array containing both details about the current status and all previous statuses. The oldest status is the first element of the array and we append newer statuses as they come in. Order is not perfectly reliable as carrier data is occasionally incorrect. We recommend using the “status” on the Tracker object for any key business logic.
Here’s an example of a tracking event webhook:
Once you're receiving webhooks, there's a lot of ways for you to re-engage with your customers. Here's a few ideas that some of our customers use:
public_urlfield of a Tracker Object.
Congratulations! You’ve just tracked your first package with EasyPost! Check out our Full Reference API Documentation.