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 is continuously updated based on carrier data and reflects both current and historical scan events.
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:
- Automatically when a shipment is purchased through the EasyPost API or Dashboard.
-
Manually by calling the
POST /trackersendpoint with atracking_codeand (optionally) acarrier.
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
| Status | Definition |
unknown
|
The carrier has no available tracking information. |
pre_transit
|
Shipment information submitted; carrier has not taken possession. |
in_transit
|
Package is in transit. |
out_for_delivery
|
Package is on final delivery route. |
available_for_pickup
|
Package is available for pickup at a carrier location. |
delivered
|
Package has been delivered. |
return_to_sender
|
Package is being returned to the sender. |
failure
|
Delivery failed and will not proceed. |
canceled
|
Shipment was canceled. |
error
|
Unknown error occured; contact the carrier for details. |
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 result from carrier formatting differences. For example, USPS may return timestamps without time zones, while FedEx includes full offsets. All timestamps are stored in UTC.
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.
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:
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.