API Docs

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 includes:

  • The status of the package at the time of the scan
  • A message from the carrier
  • A TrackingLocation containing available location information.

The TrackingLocation may include:

  • city
  • state
  • country
  • zip

Data availability varies by carrier. When enough location information is present, EasyPost assigns the appropriate local time zone to the event’s datetime. When location information is incomplete, timestamps default to UTC.

Some Tracker objects include a CarrierDetail, which stores additional carrier-provided information such as:

  • service
  • container_type
  • Localized delivery estimates (est_delivery_date_local, est_delivery_time_local)
  • Origin and destination locations, if available

Tracking codes are not globally unique. Carriers recycle codes over time, and the reuse period varies by carrier and service level. EasyPost prevents the creation of duplicate Trackers by returning the original Tracker when the same User submits a request with the same tracking_code and carrier within the previous three months.

Endpoints
POST
/trackers
GET
/trackers
GET
/trackers/:id
DELETE
/trackers/:id

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. When possible, EasyPost assigns a time zone to the timestamp based on the associated tracking_location.
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
Blue Streak
Bluestreak
Canada Post
CanadaPost
Canpar
Canpar
CDL Last Mile Solutions
ColumbusLastMile
Courier Express
CourierExpress
CouriersPlease
CouriersPlease
CSLogistics
CSLogistics
Dai Post
DaiPost
Deutsche Post UK
DeutschePostUK
Deutsche Post
DeutschePost
DHL eCommerce Asia
DHLEcommerceAsia
DHL eCommerce Solutions
DhlEcs
DHL Express
DHLExpress
DHL Express Default
DHLExpressDefault
DHL Paket
DHLPaket
DoorDash
DoorDash
Douglas
Douglas
DPD
DPD
DPD NL
DPDNL
DPD UK
DPDUK
ePost Global v2
EPostGlobalV2
Estafeta
Estafeta
Evri
Evri
FedEx
FedEx
FedEx Cross Border
FedExCrossBorder
FedEx Default
FedExDefault
FedEx SmartPost
FedexSmartPost
First Choice
FirstChoice
First Mile Concise
FirstMileConcise
Flexport
Flexport
Gio
Gio
Gori
Gori
GSO
GSO
Hailify
Hailify
Henry
Henry
Interlink Express
InterlinkExpress
Jet
Jet
Jitsu
Jitsu
Kuroneko Yamato
KuronekoYamato
LaserShip
LaserShipV2
Loomis Express
LoomisExpress
LSO
LSO
Maersk
Maersk
Omni Parcel
OmniParcel
OnTrac
OnTrac
OnTrac v3
OntracV3
Optima
Optima
Osm Worldwide
OsmWorldwide
Osm Worldwide v2
OsmWorldwideV2
Parcelforce
Parcelforce
PARCLL
Parcll
Passport
PassportGlobal
PostNL
PostNL
Purolator
Purolator
Quick
Quick
Roadie
Roadie
Rover
Rover
Royal Mail
RoyalMail
Royal Mail v3
RoyalMailV3
SEKO OmniParcel
OmniParcel
Sendle
Sendle
SF Express
SFExpress
SmartKargo
SmartKargo
Sonic
Sonic
SpeedX
SpeedX
Spee-Dee
SpeeDee
Sway
Sway
Swyft
Swyft
TCC
Tcc
TForce Logistics
TforceConcise
UDS
UDS
UniUni
UniUni
UPS DAP
UPSDAP
UPS i-parcel
UPSIparcel
UPS Mail Innovations
UPSMailInnovations
UPS
UPS
USA Export PBA
UsaExportPba
USPS
USPS
USPS Ship
UspsShip
Veho
Veho

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}