Tracker
The Tracker
object contains tracking information for a package.
A Tracker
is created automatically when a Shipment
is purchased through EasyPost.
For labels not purchases via EasyPost, a Tracker
can still be created directly through the API.
Each Tracker
is continually updated in the background as packages progress through the delivery lifecycle. Updates are based on
information provided by the carrier and are delivered via webhook Event
if enabled.
Each Tracker
includes both current and historical tracking data. Historical updates are stored in the tracking_details
array. Each
TrackingDetail
contains the status, a message from the carrier, and
a TrackingLocation
.
The TrackingLocation
includes city, state, country, and zip information for the scan event location.
Data availability varies by carrier.
Some Tracker
objects include a CarrierDetail
, which stores additional information about the Tracker
that the carrier has made available to EasyPost.
The CarrierDetail
object contains the service
and container_type
of the package.
Additionally, it stores the est_delivery_date_local
and est_delivery_time_local
, which provide information about the local delivery time.
It's worth noting that tracking_codes
are not globally unique. Each carrier promises uniqueness for a given tracking_code
for a certain period of time, but the length of time varies greatly based on the specific carrier and service level.
Carriers do eventually recycle tracking codes, and for this reason enforcing uniqueness on the tracking_code
field is not recommended.
EasyPost does, however, prevent the creation of duplicate Trackers
based on tracking_code
and carrier
;
duplicate requests by the same User
will return the original Tracker
.
The current status of the package. Possible values:
- "unknown"
- "pre_transit"
- "in_transit"
- "out_for_delivery"
- "delivered"
- "available_for_pickup"
- "return_to_sender"
- "failure"
- "cancelled"
- "error"
Additional details about the current status. Possible values:
- "address_correction"
- "arrived_at_destination"
- "arrived_at_facility"
- "arrived_at_pickup_location"
- "awaiting_information"
- "cancelled"
- "damaged"
- "delayed"
- "delivery_exception"
- "departed_facility"
- "departed_origin_facility"
- "expired"
- "failure"
- "held"
- "in_transit"
- "label_created"
- "lost"
- "missorted"
- "out_for_delivery"
- "received_at_destination_facility"
- "received_at_origin_facility"
- "refused"
- "return"
- "status_update"
- "transferred_to_destination_carrier"
- "transit_exception"
- "unknown"
- "weather_delay"
TrackingDetail
objectsCarrierDetail
object (if available)Tracker
was createdTracker
was last updated{
"id": "trk_9135862729734d96ad2f9ed0f0565a27",
"object": "Tracker",
"mode": "test",
"tracking_code": "EZ1000000001",
"status": "pre_transit",
"status_detail": "status_update",
"created_at": "2025-05-09T20:40:17Z",
"updated_at": "2025-05-09T20:40:17Z",
"signed_by": null,
"weight": null,
"est_delivery_date": "2025-05-09T20:40:17Z",
"shipment_id": null,
"carrier": "USPS",
"tracking_details": [
{
"object": "TrackingDetail",
"message": "Pre-Shipment Info Sent to USPS",
"description": "",
"status": "pre_transit",
"status_detail": "status_update",
"datetime": "2025-04-09T20:40:17Z",
"source": "USPS",
"carrier_code": "",
"tracking_location": {
"object": "TrackingLocation",
"city": null,
"state": null,
"country": null,
"zip": null
},
"est_delivery_date": null
},
{
"object": "TrackingDetail",
"message": "Shipping Label Created",
"description": "",
"status": "pre_transit",
"status_detail": "status_update",
"datetime": "2025-04-10T09:17:17Z",
"source": "USPS",
"carrier_code": "",
"tracking_location": {
"object": "TrackingLocation",
"city": "HOUSTON",
"state": "TX",
"country": null,
"zip": "77063"
},
"est_delivery_date": null
}
],
"fees": [],
"carrier_detail": {
"object": "CarrierDetail",
"service": "First-Class Package Service",
"container_type": null,
"est_delivery_date_local": null,
"est_delivery_time_local": null,
"origin_location": "HOUSTON TX, 77001",
"origin_tracking_location": {
"object": "TrackingLocation",
"city": "HOUSTON",
"state": "TX",
"country": null,
"zip": "77063"
},
"destination_location": "CHARLESTON SC, 29401",
"destination_tracking_location": null,
"guaranteed_delivery_date": null,
"alternate_identifier": null,
"initial_delivery_attempt": null
},
"public_url": "https://track.easypost.com/djE6dHJrXzkxMzU4NjI3Mjk3MzRkOTZhZDJmOWVkMGYwNTY1YTI3"
}
Status of the package at the time of the scan event. Possible values:
- "unknown"
- "pre_transit"
- "in_transit"
- "out_for_delivery"
- "delivered"
- "available_for_pickup"
- "return_to_sender"
- "failure"
- "cancelled"
- "error"
Additional details about the current status. Possible values:
- "address_correction"
- "arrived_at_destination"
- "arrived_at_facility"
- "arrived_at_pickup_location"
- "awaiting_information"
- "cancelled"
- "damaged"
- "delayed"
- "delivery_exception"
- "departed_facility"
- "departed_origin_facility"
- "expired"
- "failure"
- "held"
- "in_transit"
- "label_created"
- "lost"
- "missorted"
- "out_for_delivery"
- "received_at_destination_facility"
- "received_at_origin_facility"
- "refused"
- "return"
- "status_update"
- "transferred_to_destination_carrier"
- "transit_exception"
- "unknown"
- "weather_delay"
{
"object": "TrackingDetail",
"message": "Pre-Shipment Info Sent to USPS",
"description": "",
"status": "pre_transit",
"status_detail": "status_update",
"datetime": "2025-04-09T20:40:17Z",
"source": "USPS",
"carrier_code": "",
"tracking_location": {
"object": "TrackingLocation",
"city": null,
"state": null,
"country": null,
"zip": null
},
"est_delivery_date": null
}
{
"object": "TrackingLocation",
"city": null,
"state": null,
"country": null,
"zip": null
}
{
"object": "CarrierDetail",
"service": "First-Class Package Service",
"container_type": null,
"est_delivery_date_local": null,
"est_delivery_time_local": null,
"origin_location": "HOUSTON TX, 77001",
"origin_tracking_location": {
"object": "TrackingLocation",
"city": "HOUSTON",
"state": "TX",
"country": null,
"zip": "77063"
},
"destination_location": "CHARLESTON SC, 29401",
"destination_tracking_location": null,
"guaranteed_delivery_date": null,
"alternate_identifier": null,
"initial_delivery_attempt": null
}
Specific tracking statuses (e.g. "out_for_delivery") can be simulated to test application behavior.
EasyPost provides a set of test tracking_codes
that, when sent to the API, responds with specific tracking statuses and sends a webhook Event
to a test mode URL.
The tracking updates that are sent by these tracking_codes
will contain canned information, but it will be similar in form to the information normally provided by the carrier selected.
A Tracker
can be created using only a tracking_code
.
Optionally, the carrier
parameter can be included to specify the shipping carrier.
If no carrier
is provided, EasyPost attempts to determine the carrier based on the tracking_code
.
Providing a carrier
parameter is recommended, as some tracking codes are ambiguous and may match multiple carriers.
Explicitly setting the carrier also improves response time by avoiding auto-matching the carrier.
To minimize unnecessary resource usage, EasyPost prevents the creation of duplicate Trackers
.
A Tracker
is considered a duplicate if another Tracker
with the same tracking_code
and carrier
was created by the same User
within the past three months.
In such cases, the original Tracker
is returned.
A Tracker object is immutable once created. All information must be provided during creation; it cannot be modified later.
Request Parameters
1curl -X POST https://api.easypost.com/v2/trackers \
2 -u "EASYPOST_API_KEY": \
3 -H 'Content-Type: application/json' \
4 -d '{
5 "tracker": {
6 "tracking_code": "EZ1000000001",
7 "carrier": "USPS"
8 }
9 }'
1{
2 "id": "trk_9135862729734d96ad2f9ed0f0565a27",
3 "object": "Tracker",
4 "mode": "test",
5 "tracking_code": "EZ1000000001",
6 "status": "pre_transit",
7 "status_detail": "status_update",
8 "created_at": "2025-05-09T20:40:17Z",
9 "updated_at": "2025-05-09T20:40:17Z",
10 "signed_by": null,
11 "weight": null,
12 "est_delivery_date": "2025-05-09T20:40:17Z",
13 "shipment_id": null,
14 "carrier": "USPS",
15 "tracking_details": [
16 {
17 "object": "TrackingDetail",
18 "message": "Pre-Shipment Info Sent to USPS",
19 "description": null,
20 "status": "pre_transit",
21 "status_detail": "status_update",
22 "datetime": "2025-04-09T20:40:17Z",
23 "source": "USPS",
24 "carrier_code": null,
25 "tracking_location": {
26 "object": "TrackingLocation",
27 "city": null,
28 "state": null,
29 "country": null,
30 "zip": null
31 },
32 "est_delivery_date": null
33 },
34 {
35 "object": "TrackingDetail",
36 "message": "Shipping Label Created",
37 "description": null,
38 "status": "pre_transit",
39 "status_detail": "status_update",
40 "datetime": "2025-04-10T09:17:17Z",
41 "source": "USPS",
42 "carrier_code": null,
43 "tracking_location": {
44 "object": "TrackingLocation",
45 "city": "HOUSTON",
46 "state": "TX",
47 "country": null,
48 "zip": "77063"
49 },
50 "est_delivery_date": null
51 }
52 ],
53 "carrier_detail": {
54 "object": "CarrierDetail",
55 "service": "First-Class Package Service",
56 "container_type": null,
57 "est_delivery_date_local": null,
58 "est_delivery_time_local": null,
59 "origin_location": "HOUSTON TX, 77001",
60 "origin_tracking_location": {
61 "object": "TrackingLocation",
62 "city": "HOUSTON",
63 "state": "TX",
64 "country": null,
65 "zip": "77063"
66 },
67 "destination_location": "CHARLESTON SC, 29401",
68 "destination_tracking_location": null,
69 "guaranteed_delivery_date": null,
70 "alternate_identifier": null,
71 "initial_delivery_attempt": null
72 },
73 "finalized": true,
74 "is_return": false,
75 "public_url": "https://track.easypost.com/djE6dHJrXzkxMzU4NjI3Mjk3MzRkOTZhZDJmOWVkMGYwNTY1YTI3"
76}
Retrieves a list of all Tracker
objects associated with the given API Key
.
See the Pagination section for more details on retrieving all records when multiple pages are available.
The Tracker
List endpoint is the recommended method of retrieving a Tracker
by tracking_code
or carrier
.
Unlike retrieving a Tracker
using the retrieve endpoint, which accepts an id
, this endpoint accepts the tracking_code
as the search parameter.
Typically, only one Tracker
exists for a given tracking_code
, but results can be further filtered by including the carrier
parameter in the request.
Request Parameters
after_id
.before_id
.end_datetime
.start_datetime
.Trackers
with the given tracking codes. Useful for retrieving Trackers
by tracking_code
rather than by their ids.Trackers
with the given carrier.1curl -X GET "https://api.easypost.com/v2/trackers?page_size=5" \
2 -u "EASYPOST_API_KEY":
1{
2 "trackers": [
3 {
4 "id": "trk_9135862729734d96ad2f9ed0f0565a27",
5 "object": "Tracker",
6 "mode": "test",
7 "tracking_code": "EZ1000000001",
8 "status": "pre_transit",
9 "status_detail": "status_update",
10 "created_at": "2025-05-09T20:40:17Z",
11 "updated_at": "2025-05-09T20:40:17Z",
12 "signed_by": null,
13 "weight": null,
14 "est_delivery_date": "2025-05-09T20:40:17Z",
15 "shipment_id": null,
16 "carrier": "USPS",
17 "tracking_details": [
18 {
19 "object": "TrackingDetail",
20 "message": "Pre-Shipment Info Sent to USPS",
21 "description": "",
22 "status": "pre_transit",
23 "status_detail": "status_update",
24 "datetime": "2025-04-09T20:40:17Z",
25 "source": "USPS",
26 "carrier_code": "",
27 "tracking_location": {
28 "object": "TrackingLocation",
29 "city": null,
30 "state": null,
31 "country": null,
32 "zip": null
33 },
34 "est_delivery_date": null
35 },
36 {
37 "object": "TrackingDetail",
38 "message": "Shipping Label Created",
39 "description": "",
40 "status": "pre_transit",
41 "status_detail": "status_update",
42 "datetime": "2025-04-10T09:17:17Z",
43 "source": "USPS",
44 "carrier_code": "",
45 "tracking_location": {
46 "object": "TrackingLocation",
47 "city": "HOUSTON",
48 "state": "TX",
49 "country": null,
50 "zip": "77063"
51 },
52 "est_delivery_date": null
53 }
54 ],
55 "fees": [],
56 "carrier_detail": {
57 "object": "CarrierDetail",
58 "service": "First-Class Package Service",
59 "container_type": null,
60 "est_delivery_date_local": null,
61 "est_delivery_time_local": null,
62 "origin_location": "HOUSTON TX, 77001",
63 "origin_tracking_location": {
64 "object": "TrackingLocation",
65 "city": "HOUSTON",
66 "state": "TX",
67 "country": null,
68 "zip": "77063"
69 },
70 "destination_location": "CHARLESTON SC, 29401",
71 "destination_tracking_location": null,
72 "guaranteed_delivery_date": null,
73 "alternate_identifier": null,
74 "initial_delivery_attempt": null
75 },
76 "public_url": "https://track.easypost.com/djE6dHJrXzkxMzU4NjI3Mjk3MzRkOTZhZDJmOWVkMGYwNTY1YTI3"
77 }
78 ],
79 "has_more": true
80}
Retrieve a Tracker
by its id
.
1curl -X GET https://api.easypost.com/v2/trackers/trk_... \
2 -u "EASYPOST_API_KEY":
1{
2 "id": "trk_9135862729734d96ad2f9ed0f0565a27",
3 "object": "Tracker",
4 "mode": "test",
5 "tracking_code": "EZ1000000001",
6 "status": "pre_transit",
7 "status_detail": "status_update",
8 "created_at": "2025-05-09T20:40:17Z",
9 "updated_at": "2025-05-09T20:40:17Z",
10 "signed_by": null,
11 "weight": null,
12 "est_delivery_date": "2025-05-09T20:40:17Z",
13 "shipment_id": null,
14 "carrier": "USPS",
15 "tracking_details": [
16 {
17 "object": "TrackingDetail",
18 "message": "Pre-Shipment Info Sent to USPS",
19 "description": "",
20 "status": "pre_transit",
21 "status_detail": "status_update",
22 "datetime": "2025-04-09T20:40:17Z",
23 "source": "USPS",
24 "carrier_code": "",
25 "tracking_location": {
26 "object": "TrackingLocation",
27 "city": null,
28 "state": null,
29 "country": null,
30 "zip": null
31 },
32 "est_delivery_date": null
33 },
34 {
35 "object": "TrackingDetail",
36 "message": "Shipping Label Created",
37 "description": "",
38 "status": "pre_transit",
39 "status_detail": "status_update",
40 "datetime": "2025-04-10T09:17:17Z",
41 "source": "USPS",
42 "carrier_code": "",
43 "tracking_location": {
44 "object": "TrackingLocation",
45 "city": "HOUSTON",
46 "state": "TX",
47 "country": null,
48 "zip": "77063"
49 },
50 "est_delivery_date": null
51 }
52 ],
53 "fees": [],
54 "carrier_detail": {
55 "object": "CarrierDetail",
56 "service": "First-Class Package Service",
57 "container_type": null,
58 "est_delivery_date_local": null,
59 "est_delivery_time_local": null,
60 "origin_location": "HOUSTON TX, 77001",
61 "origin_tracking_location": {
62 "object": "TrackingLocation",
63 "city": "HOUSTON",
64 "state": "TX",
65 "country": null,
66 "zip": "77063"
67 },
68 "destination_location": "CHARLESTON SC, 29401",
69 "destination_tracking_location": null,
70 "guaranteed_delivery_date": null,
71 "alternate_identifier": null,
72 "initial_delivery_attempt": null
73 },
74 "public_url": "https://track.easypost.com/djE6dHJrXzkxMzU4NjI3Mjk3MzRkOTZhZDJmOWVkMGYwNTY1YTI3"
75}
Delete a tracker object using its id
.
This action is permanent and stops all future webhook Event
deliveries associated with the Tracker
. Once a tracker is deleted,
any attempt to retrieve it using the GET /trackers/:id
endpoint will return a 404 Not Found
response.
1curl -X DELETE https://api.easypost.com/v2/trackers/trk_... \
2 -u "EASYPOST_API_KEY":
1{
2 "success": true
3}