Tracking | Frequently Asked Questions

How do I track packages using the API?
What do your Tracking Statuses mean?
Do you have a Tracking page I can send my customers?
How do I get realtime tracking updates for my shipment with EasyPost?
How often are your tracking statuses updated?
Why are there time zone discrepancies on trackers?
How can I set up email or SMS tracking notifications for my shipments?
Will EasyPost send me delivery confirmation when a package is delivered?
How do you handle failed deliveries, second attempts, final details, etc.?
Can I set an expected delivery date with your API?
Is there a tracking status for a returned package that's delivered back to sender?
I have a Tracker with a status of 'failure' due to weather. If the weather clears up, will the status re-update itself to 'in_transit'?
How do you bill for your trackers?
If we submit the same tracking code more than once, will we be charged twice?

How do I track packages using the API?

There are two methods to track packages with the EasyPost API.

1. Provide your existing tracking number and carrier to generate tracking info
2. Purchase the shipping label with EasyPost, which includes a free Tracker to track packages

For example, let’s say you purchase an EasyPost USPS shipping label with a USPS tracking number; there’s no extra work needed to track the package. We will automatically provide a free tracker with each purchased postage label that you buy from us. This is all-inclusive for each carrier you purchase an EasyPost label for, whether it’s a UPS tracking number, FedEx tracking number, etc, it is free with your EasyPost label purchase. 

If you want to track a package with a USPS tracking number (or any other carrier) that was not processed via EasyPost, then you’ll still need the tracking number of that package to create what is called a stand-alone tracker to track packages with our API. Insert the USPS tracking number when creating your Tracker object, which we outline for you in our API Tracking Documentation.

A Tracker object contains all of the tracking information to track a package when the Tracker is created automatically; each Tracker is continually updated in the background as the package moves through its life cycle, regardless of whether or not the label was purchased through EasyPost.

After creation, a Tracker object will be updated periodically based on when the carrier provides the information to track packages within EasyPost with new tracking information. This information can be consumed by using our webhooks infrastructure. Every time a Tracker is updated a webhook Event will be sent.

Check out our Tracking Guide for more information on how to track packages with the EasyPost API.

What do your tracking Statuses mean?

When you track packages within EasyPost, we have some standard tracking information terms that are displayed as the tracking status detail of your shipment. The standardized tracking information statuses across our platform include the following:

Do you have a Tracking page I can send my customers?

Tracking packages is simple with the EasyPost API - all you need is the tracking number and the name of the carrier to generate an EasyPost Tracker. Whenever you purchase a Shipment or Tracker, we will generate a Tracking URL that you can send to your customers. To obtain the Tracking URL, please use the public_url from the Tracker object.

For example, let’s say you purchase a USPS Priority Mail package with the EasyPost API; EasyPost will automatically include a tracker object with your USPS tracking number. This USPS Priority Mail tracking number will be linked to an EasyPost Tracking URL, which allows you to track your EasyPost label attached to the tracking number as it moves toward its destination.

Here's an example of the Tracker object being generated from the USPS Priority Mail Tracking number and carrier specification with a Tracker.create API call in Node.js:

const Easypost = require('@easypost/api');
const api = new Easypost('<YOUR_TEST/PRODUCTION_API_KEY>');

const tracker = new api.Tracker({
  tracking_code: '9400110898825022579493',
  carrier: 'USPS',
});

tracker.save().then(console.log);

Returned object with URL for the tracking page for your customer:

{
  ...
  "id": "trk_a1b2c3d4",
  "tracking_code": "9400123456789012345123",
  "status": "in_transit",
  "created_at": "2016-06-20T21:52:28Z",
  "updated_at": "2016-06-20T21:52:32Z",
  "est_delivery_date": null,
  "carrier": "USPS",
  "tracking_details": [...],
  "public_url": "https://track.easypost.com/..."
}

You can see the Tracking URL listed at the bottom of the code block. Other language examples of setting up the Tracking URL by inputting your carrier’s Tracking number can be found in our Official Client Libraries.

How do I get realtime tracking updates for my shipment with EasyPost?

Set up webhook URLs either through our API or through our dashboard. For more information on webhooks, take a look at our webhook documentation.

Once your webhooks and trackers are set up, you’ll receive real-time tracking updates on the associated packages.

How often are your tracking statuses updated?

We poll the carriers during the early stages of transit every couple of hours.

Different carriers track at different speeds, but as a rule, we check for updates more often once the package nears delivery.

Why are there time zone discrepancies on trackers?

Simply put, these discrepancies are the result of different carriers presenting different data. For instance, USPS return timestamps with no time zones at all, while FedEx always returns properly zoned timestamps.

Our system works on the UTC time zone, so make assumptions that the timestamp reflects the UTC time zone.

How can I set up email or SMS tracking notifications for my shipments?

We have complete guides on how to use our tracking webhooks to set up either email or SMS based tracking notifications for your outbound shipments.

• Email Tracking Tutorial
• SMS Tracking Tutorial

Will EasyPost send me delivery confirmation when a package is delivered?

Yes, it will come in the form of a TrackingLocation object. If the TrackingLocation matches the destination address of your shipment, it’s essentially a confirmation of delivery.

How do you handle failed deliveries, second attempts, final details, etc.?

A single failed delivery with a retry will still be classified as in_transit. It will also have a message detailing the specific failed delivery attempt.

If the delivery fails to the point where the carrier decides to stop redelivery, the tracking detail will either be return_to_sender, available_for_pickup, or failure depending on the action the carrier takes.

Can I set an expected delivery date with your API?

No, you can't set up an expected delivery date with our API.

Sometimes our rate objects will contain the delivery_days and the delivery_dates attributes when the carrier returns them, but there's no guarantee that they will. We've also included a delivery_date_guaranteed attribute that can be used to determine if the above attributes are valid.

Is there a tracking status for a returned package that's delivered back to sender?

No. Once a package is returned to sender, it will be delivered.

If you need to differentiate between packages delivered to the recipient and packages returned to sender, you can use the "previous_attributes" hash on the webhook Event object to determine the status of the tracker before the package was delivered.

I have a Tracker with a status of 'failure' due to weather. If the weather clears up, will the status re-update itself to 'in_transit'?

Yes. If packages have the failure status on their trackers due to weather, they will automatically update themselves to in_transit if they’re able to continue shipping after the weather clears up.

How do you bill for your trackers?

EasyPost only charges for each new tracker that is created, and we deduplicate create requests for each user. Specifically, if a user submits two Tracker create requests with the same tracking_code/carrier combination, the second request will simply return the first tracker that was created so as to prevent you from getting charged twice.

We do not deduplicate trackers in test mode, but this behavior will occur in production mode as long as less than 3 months have passed since the original tracker was created; after 3 months, we will created a new tracker since at that point it could refer to a totally different shipment.

There is no charge to retrieve a tracker object using a retrieve request. Using webhooks is encouraged since it is a significantly more efficient workflow and reduces overhead (which in theory could also save money in the long run), but EasyPost will not charge you anything for using retrieve requests to poll for trackers. .

If we submit the same tracking code more than once, will we be charged twice?

No, if you submit the same tracking code/carrier combination twice, we will only charge you once. The duplicate request will just return the originally created tracker.

To clarify, it's possible to use the same tracking code on different carriers (which we do charge you separately for since it's actually two different trackers), but that rarely happens.