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.


Tracker object

id
string
Unique identifier, begins with "trk_"
object
string
"Tracker"
mode
string
"test" or "production"
tracking_code
string
The tracking code provided by the carrier
status
string

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"
status_detail
string

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"
signed_by
string
The name of the person who signed for the package (if available)
weight
float
The weight of the package as measured by the carrier in ounces (if available)
est_delivery_date
datetime
The estimated delivery date provided by the carrier (if available)
shipment_id
string
The ID of the EasyPost Shipment object associated with the Tracker (if any)
carrier
string
The name of the carrier handling the shipment
tracking_details
Array of the associated TrackingDetail objects
carrier_detail
The associated CarrierDetail object (if available)
public_url
string
URL to a publicly-accessible webpage that shows tracking details for this tracker
fees
Fee array
Array of the associated Fee objects
created_at
datetime
When the Tracker was created
updated_at
datetime
When the Tracker was last updated
Tracker Object
{
  "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"
}

TrackingDetail object

object
string
"TrackingDetail"
message
string
Summary of the scan event
status
string

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"
status_detail
string

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"
datetime
datetime
The timestamp when the tracking scan occurred
source
string
The original source of the information for this scan event, usually the carrier
tracking_location
The location associated with the scan event
TrackingDetail Object
{
  "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
}

TrackingLocation object

object
string
"TrackingLocation"
city
string
The city where the scan event occurred (if available)
state
string
The state where the scan event occurred (if available)
country
string
The country where the scan event occurred (if available)
zip
string
The postal code where the scan event occurred (if available)
TrackingLocation Object
{
  "object": "TrackingLocation",
  "city": null,
  "state": null,
  "country": null,
  "zip": null
}

CarrierDetail object

object
string
"CarrierDetail"
service
string
The service level the associated shipment was shipped with (if available)
container_type
string
The type of container the associated shipment was shipped in (if available)
est_delivery_date_local
date
The estimated delivery date as provided by the carrier, in the local time zone (if available)
est_delivery_time_local
time
The estimated delivery time as provided by the carrier, in the local time zone (if available)
origin_location
string
The location from which the package originated, stringified for presentation (if available)
origin_tracking_location
TrackingLocation
The location from which the package originated, broken down by city/state/country/zip (if available)
destination_location
string
The location to which the package is being sent, stringified for presentation (if available)
destination_tracking_location
TrackingLocation
The location to which the package is being sent, broken down by city/state/country/zip (if available)
guaranteed_delivery_date
datetime
The date and time the carrier guarantees the package to be delivered by (if available)
alternate_identifier
string
The alternate identifier for this package as provided by the carrier (if available)
initial_delivery_attempt
datetime
The date and time of the first attempt by the carrier to deliver the package (if available)
CarrierDetail Object
{
  "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
}

Testing Specific Tracking States

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.


Test Tracking Codes

EZ1000000001
pre_transit
EZ2000000002
in_transit
EZ3000000003
out_for_delivery
EZ4000000004
delivered
EZ5000000005
return_to_sender
EZ6000000006
failure
EZ7000000007
unknown

Carrier Tracking Strings

Accurate
Accurate
AmazonMws
AmazonMws
AmazonShipping
AmazonShipping
APC
APC
Asendia USA
AsendiaUsa
Australia Post
AustraliaPost
AxlehireV3
AxlehireV3
Better Trucks
BetterTrucks
Canada Post
CanadaPost
Canpar
Canpar
CDL Last Mile Solutions
ColumbusLastMile
Chronopost
Chronopost
CloudSort
CloudSort
Courier Express
CourierExpress
CouriersPlease
CouriersPlease
CSLogistics
CSLogistics
Dai Post
DaiPost
DeliverIt
DeliverIt
Deutsche Post UK
DeutschePostUK
Deutsche Post
DeutschePost
DHL eCommerce Asia
DHLEcommerceAsia
DHL eCommerce Solutions
DhlEcs
DHL Express
DHLExpress
DHL Paket
DHLPaket
DoorDash
DoorDash
DPD NL
DPDNL
DPD UK
DPDUK
DPD
DPD
ePost Global
ePostGlobal
Estafeta
Estafeta
Evri
Evri
Fastway
Fastway
FedEx Cross Border
FedExCrossBorder
FedEx Default
FedExDefault
FedEx Mailview
FedExMailview
FedEx SmartPost
FedexSmartPost
FedEx
FedEx
First Choice
FirstChoice
FirstMile
FirstMile
Flexport
Flexport
Gio
Gio
GIOExpress
GIOExpress
GSO
GSO
Hailify
Hailify
Henry
Henry
Interlink Express
InterlinkExpress
Jet
Jet
Kuroneko Yamato
KuronekoYamato
La Poste
LaPoste
LaserShip
LaserShipV2
Loomis Express
LoomisExpress
LSO
LSO
OnTrac
OnTrac
Optima
Optima
Osm Worldwide
OsmWorldwide
Parcelforce
Parcelforce
PARCLL
Parcll
Passport
PassportGlobal
PostNL
PostNL
Purolator
Purolator
Quick
Quick
Royal Mail
RoyalMail
SEKO OmniParcel
OmniParcel
Sendle
Sendle
SF Express
SFExpress
SmartKargo
SmartKargo
Sonic
Sonic
Spee-Dee
SpeeDee
Swyft
Swyft
TForce Logistics
TForce
UDS
UDS
UPS i-parcel
UPSIparcel
UPS Mail Innovations
UPSMailInnovations
UPS
UPS
USPS
USPS
Veho
Veho
Yanwen
Yanwen

Create a Tracker

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

tracking_code
i.e. 9400110898825022579493
The tracking code associated with the package you would like to track
carrier
i.e. USPS
The carrier associated with the tracking_code you provided. The carrier will get auto-detected if none is provided.
POST /trackers
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  }'
Response
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}

Retrieve all Trackers

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

before_id
i.e. trk_...
Optional pagination parameter. Only records created before the given ID will be included. May not be used with after_id.
after_id
i.e. trk_...
Optional pagination parameter. Only records created after the given ID will be included. May not be used with before_id.
start_datetime
i.e. 2016-01-02T00:00:00Z
Only return records created after this timestamp. Defaults to 1 month ago, or 1 month before a passed end_datetime.
end_datetime
i.e. 2016-01-02T00:00:00Z
Only return records created before this timestamp. Defaults to end of the current day, or 1 month after a passed start_datetime.
page_size
i.e. 30
The number of records to return on each page. The maximum value is 100, and default is 20.
tracking_codes
i.e. ["9400110898825022579493"]
Only return Trackers with the given tracking codes. Useful for retrieving Trackers by tracking_code rather than by their ids.
carrier
i.e. USPS
Only return Trackers with the given carrier.
GET /trackers
1curl -X GET "https://api.easypost.com/v2/trackers?page_size=5" \
2  -u "EASYPOST_API_KEY":
Response
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

Retrieve a Tracker by its id.

GET /trackers/:id
1curl -X GET https://api.easypost.com/v2/trackers/trk_... \
2  -u "EASYPOST_API_KEY":
Response
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

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.

DELETE /trackers/:id
1curl -X DELETE https://api.easypost.com/v2/trackers/trk_... \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "success": true
3}