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.

Endpoints

Tracker object

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

TrackingDetail array

Array of the associated TrackingDetail objects

carrier_detail

CarrierDetail

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

The timestamp when the tracking scan occurred

source

string

The original source of the information for this scan event, usually the carrier

tracking_location

TrackingLocation

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

AmazonMws

AmazonShipping

APC

Asendia USA

AsendiaUsa

Australia Post

AustraliaPost

AxlehireV3

Better Trucks

BetterTrucks

Canada Post

CanadaPost

Canpar

CDL Last Mile Solutions

ColumbusLastMile

Chronopost

CloudSort

Courier Express

CourierExpress

CouriersPlease

CSLogistics

Dai Post

DaiPost

Deutsche Post UK

DeutschePostUK

Deutsche Post

DeutschePost

DHL eCommerce Asia

DHLEcommerceAsia

DHL eCommerce Solutions

DhlEcs

DHL Express

DHLExpress

DHL Paket

DHLPaket

DoorDash

DPD NL

DPDNL

DPD UK

DPDUK

DPD

ePost Global

ePostGlobal

Estafeta

Evri

Fastway

FedEx Cross Border

FedExCrossBorder

FedEx Default

FedExDefault

FedEx Mailview

FedExMailview

FedEx SmartPost

FedexSmartPost

FedEx

First Choice

FirstChoice

FirstMile

Flexport

Gio

GIOExpress

GSO

Hailify

Henry

Interlink Express

InterlinkExpress

Jet

Kuroneko Yamato

KuronekoYamato

La Poste

LaPoste

LaserShip

LaserShipV2

Loomis Express

LoomisExpress

LSO

OnTrac

Optima

Osm Worldwide

OsmWorldwide

Parcelforce

PARCLL

Parcll

Passport

PassportGlobal

PostNL

Purolator

Quick

Royal Mail

RoyalMail

SEKO OmniParcel

OmniParcel

Sendle

SF Express

SFExpress

SmartKargo

Sonic

Spee-Dee

SpeeDee

Swyft

TForce Logistics

TForce

UDS

UPS i-parcel

UPSIparcel

UPS Mail Innovations

UPSMailInnovations

UPS

USPS

Veho

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}