Understanding Trackers

Trackers are created automatically when a shipment is purchased through EasyPost. For shipments not purchased via EasyPost, a tracker can be created manually using the API. Each tracker reflects both current and historical scan events. When enough location information is available, EasyPost assigns a local time zone to each tracking event. If not, timestamps default to UTC. 

Webhooks can be used to receive real-time updates when the carrier provides new information. 

Creating a Tracker

Trackers can be created in two ways:

• Shipment-Based Tracking: When a shipment is purchased through the EasyPost API or Dashboard.
• Standalone Tracking: Created by calling the POST /trackers endpoint with a tracking_code and (optionally) a carrier. 

When no carrier is provided, EasyPost attempts to detect the best-fit carrier based on the tracking code. For the most accurate results, both the carrier and tracking_code values should be provided. 

Duplicate tracker requests are deduplicated for up to three months in production mode. A second request with the same carrier and tracking_code combination will return the original tracker to avoid duplicate billing. 

See the Tracker section of the API Docs for more information. 

Deleting a Tracker

Trackers can be deleted via the EasyPost API using the DELETE /trackers/:id endpoint. This action is permanent and stops all future webhook event deliveries associated with the tracker. 

curl -X DELETE https://api.easypost.com/v2/trackers/trk_... \
  -u "EASYPOST_API_KEY":

Once a tracker is deleted, any attempt to retrieve it using the GET /trackers/:id endpoint will return a 404 Not Found response. 

See the Tracker section of the API Docs for more information. 

Tracker Status Definitions

Tracking Finalization

There are a few circumstances in which an EasyPost tracker will be marked "finalized," after which we will stop polling for tracking updates.

1. Status-Based Finalization

Tracking automatically and immediately concludes when a tracker enters one of the following terminal statuses:

• delivered

• cancelled

• error

2. Inactivity 

If a tracker remains stuck in an initial, unresolved state without any carrier updates, it will eventually expire and finalize:

• Outbound Shipments: Finalized after 7 weeks of sitting in a pre_transit or unknown status.

• Return Shipments: Finalized after 6 months of sitting in a pre_transit or unknown status.

3. Stale Trackers 

For trackers in any other status (such as in_transit or out_for_delivery) that suddenly stop receiving updates from the carrier:

• Outbound Shipments: Finalized after 3 months of no updates.

• Return Shipments: Finalized after 9 months of no updates.

4. Delivery Failures

If a tracker’s status is updated to failure and remains unchanged for 2 weeks, the tracker will be finalized.

FAQs

General Tracker Behavior

Q: How often are tracking statuses updated? 

A: EasyPost polls carriers every few hours during the early stages of transit. Polling frequency increases as packages approach delivery. Update frequency may vary by carrier. 

Q: Why are there time zone discrepancies on trackers?

A: Time zone discrepancies occur because carriers provide timestamps in different formats. Some carriers include full time-zone offsets, while others return only "local time."

When enough location information is available for an event, EasyPost assigns the appropriate local time zone. When the location cannot be resolved, the timestamp defaults to UTC. This may result in a mix of localized and UTC timestamps on the same tracker.

Q: How do I get real-time tracking updates?

A: Webhook URLs can be configured through the API or Dashboard. Once webhooks are set, updates are delivered automatically when carrier data changes.

Q: Can tracking information be shared with customers?

A: Yes. Each tracker includes a public_url field, which links to a public tracking page that can be shared with recipients. 

Q. Why am I seeing a "Carrier Credentials were not available" error on my standalone tracker?

A. When it comes to standalone tracking via the Trackers endpoint, certain carriers require credentials to be present in order for them to provide us tracking updates via API. When you add a carrier account into EasyPost, we use the associated credentials to make those tracking requests.

It is generally recommended to add credentials for any carrier you will be creating standalone trackers for. However, as not all carriers explicitly require this, we've included a list of carriers that do require customer credentials below:

• Hermes / Evri
• FedEx
• DHL eCommerce Solutions
• OSM Worldwide
• Australia Post
• OnTracV3
• LaserShip
• Amazon Shipping
• Veho

Sharing and Notifications

Q: Is there a tracking page that can be shared with customers?

A: Yes. The public_url field in the Tracker object contains a shareable tracking page. This URL is generated automatically when a tracker is created through the API or Dashboard. 

For example, the following EasyPost API call creates a USPS tracker:

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); 

A public_url is returned in the Tracker object and can be sent to recipients:

 {
  ...
  "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/..."
}

Q: How can email or SMS tracking notifications be set up? 

A: Webhooks can be used to trigger tracking notifications via email or SMS. For setup instructions, refer to the following resources: 

• Email Tracking Tutorial
• SMS Tracking Tutorial

Delivery and Status Handling

Q: Will EasyPost send delivery confirmation when a package is delivered?

A: Yes. A TrackingLocation object is returned when a delivery scan occurs. If the location matches the destination address, this serves as confirmation of delivery. 

Q: How are failed deliveries, second attempts, or final delivery outcomes handled?

A: A failed delivery attempt with a pending retry will retain the status in_transit and include a message describing the issue. 

If a delivery is not retried, the status will update to return_to_sender, available_for_pickup, or failure, depending on the carrier.

Q: Is there a status for returned packages delivered back to the sender?

A: No. Returned packages are marked as delivered once scanned at the return destination. Use the previous_attributes field in the webhook Event object to verify whether the shipment was previously marked returned_to_sender.

Q: If a tracker has a failure status due to weather, will it update if delivery resumes?

A: Yes. The tracker will be updated to in_transit automatically if the carrier resumes delivery after a weather delay. 

Q: Can an expected delivery date be set using the API?

A: No. Expected delivery dates cannot be set manually. Some rate objects may include delivery_days, delivery_date, or delivery_date_guaranteed if returned by the carrier.

Billing and Deduplication

Q: How are trackers billed?

A: Trackers are billed only when created. If a second request is made using the same carrier and tracking_code within three months, the original tracker is returned, and no additional charge is applied. Deduplication is not enforced in test mode. 

Q: Will submitting the same tracking code more than once result in duplicate charges?

A: No. In production mode, repeated submissions of the same carrier and tracking_code combination will return the original tracker. Submitting the same tracking code with a different carrier will result in separate charges.

Additional Resources

EasyPost API Docs - Trackers

Webhooks Guide

Generating a Tracker Report