Tracker

A Tracker object contains all of the tracking information for a package. A Tracker is created automatically whenever you buy a Shipment through EasyPost; if you don't use EasyPost to purchase your shipping labels, you can still track packages through our API by creating a Tracker object directly. Each Tracker is continually updated in the background as the package moves through its life cycle, regardless of whether or not the label was purchased through EasyPost.

After creation, a Tracker object will be updated periodically based on when the carrier provides EasyPost with new tracking information. This information can be consumed by using our webhooks infrastructure. Every time a Tracker is updated, a webhook Event will be sent.

The Tracker object contains both the current information about the package as well as previous updates. All of the previous updates are stored in the tracking_details array. Each TrackingDetail object contains the status, the message from the carrier, and a TrackingLocation.

The TrackingLocation contains city, state, country, and zip information about the location where the package was scanned. The information each carrier provides is different, so some carriers may not make use of all of these fields.

Some Tracker objects may also contain a CarrierDetail, which stores some 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 also 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. The 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 simply 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_3898303eff624097a516ab324bb133f3",
  "object": "Tracker",
  "mode": "test",
  "tracking_code": "9405500207552011812894",
  "status": "pre_transit",
  "status_detail": "status_update",
  "created_at": "2024-01-24T00:07:43Z",
  "updated_at": "2024-01-24T00:07:43Z",
  "signed_by": null,
  "weight": null,
  "est_delivery_date": "2024-01-24T00:07:43Z",
  "shipment_id": "shp_82d5637d74404d1595eacdc7e5ca9273",
  "carrier": "USPS",
  "tracking_details": [
    {
      "object": "TrackingDetail",
      "message": "Pre-Shipment Info Sent to USPS",
      "description": "",
      "status": "pre_transit",
      "status_detail": "status_update",
      "datetime": "2023-12-24T00:07:43Z",
      "source": "USPS",
      "carrier_code": "",
      "tracking_location": {
        "object": "TrackingLocation",
        "city": null,
        "state": null,
        "country": null,
        "zip": null
      }
    },
    {
      "object": "TrackingDetail",
      "message": "Shipping Label Created",
      "description": "",
      "status": "pre_transit",
      "status_detail": "status_update",
      "datetime": "2023-12-24T12:44:43Z",
      "source": "USPS",
      "carrier_code": "",
      "tracking_location": {
        "object": "TrackingLocation",
        "city": "HOUSTON",
        "state": "TX",
        "country": null,
        "zip": "77063"
      }
    }
  ],
  "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/djE6dHJrXzM4OTgzMDNlZmY2MjQwOTdhNTE2YWIzMjRiYjEzM2Yz"
}

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": "2023-12-24T00:07:43Z",
  "source": "USPS",
  "carrier_code": "",
  "tracking_location": {
    "object": "TrackingLocation",
    "city": null,
    "state": null,
    "country": null,
    "zip": 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

Sometimes you may want to simulate specific tracking statuses (e.g. "out_for_delivery") within your application to test how your application responds. EasyPost has a set of test tracking_codes that, when sent to the API, respond with specific tracking statuses and send a webhook Event to your 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 you 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

AmazonMws

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

Dai Post

DaiPost

DeliverIt

Deutsche Post

DeutschePost

Deutsche Post UK

DeutschePostUK

DHL eCommerce Asia

DHLEcommerceAsia

DHL eCommerce Solutions

DhlEcs

DHL Express

DHLExpress

DHL Paket

DHLPaket

DPD

DPD NL

DPDNL

DPD UK

DPDUK

ePost Global

ePostGlobal

Estafeta

Evri

Fastway

FedEx

FedEx Cross Border

FedExCrossBorder

FedEx Mailview

FedExMailview

FedEx SmartPost

FedexSmartPost

FirstMile

Flexport

GSO

Hailify

Interlink Express

InterlinkExpress

JP Post

JPPost

Kuroneko Yamato

KuronekoYamato

La Poste

LaPoste

LaserShip

LaserShipV2

Loomis Express

LoomisExpress

LSO

Maergo

Newgistics

OnTrac

Optima

Osm Worldwide

OsmWorldwide

Parcelforce

PARCLL

Parcll

Passport

PassportGlobal

PostNL

Purolator

Royal Mail

RoyalMail

SEKO OmniParcel

OmniParcel

Sendle

SF Express

SFExpress

SmartKargo

Sonic

Spee-Dee

SpeeDee

Swyft

TForce Logistics

TForce

Toll

UDS

UPS

UPS i-parcel

UPSIparcel

UPS Mail Innovations

UPSMailInnovations

USPS

Veho

Yanwen

Create a Tracker

A Tracker can be created with only a tracking_code. Optionally, you can provide the carrier parameter, which indicates the carrier the package was shipped with. If no carrier is provided, EasyPost will attempt to determine the carrier based on the tracking_code provided. Providing a carrier parameter is recommended, since some tracking codes are ambiguous and may match with more than one carrier. In addition, not having to auto-match the carrier will significantly speed up the response time.

In an effort to reduce wasted resources, EasyPost prevents the creation of duplicate Trackers. A Tracker is considered to be a duplicate if another Tracker with the same tracking_code and carrier was created by the same User in the last three months. In the case where a duplicate request is submitted, the original Tracker will be 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_a45db88bb5194557879246abd110606c",
3  "object": "Tracker",
4  "mode": "test",
5  "tracking_code": "EZ1000000001",
6  "status": "pre_transit",
7  "status_detail": "status_update",
8  "created_at": "2024-01-23T23:58:57Z",
9  "updated_at": "2024-01-23T23:58:57Z",
10  "signed_by": null,
11  "weight": null,
12  "est_delivery_date": "2024-01-23T23:58:57Z",
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": "2023-12-23T23:58:57Z",
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    },
33    {
34      "object": "TrackingDetail",
35      "message": "Shipping Label Created",
36      "description": "",
37      "status": "pre_transit",
38      "status_detail": "status_update",
39      "datetime": "2023-12-24T12:35:57Z",
40      "source": "USPS",
41      "carrier_code": "",
42      "tracking_location": {
43        "object": "TrackingLocation",
44        "city": "HOUSTON",
45        "state": "TX",
46        "country": null,
47        "zip": "77063"
48      }
49    }
50  ],
51  "carrier_detail": {
52    "object": "CarrierDetail",
53    "service": "First-Class Package Service",
54    "container_type": null,
55    "est_delivery_date_local": null,
56    "est_delivery_time_local": null,
57    "origin_location": "HOUSTON TX, 77001",
58    "origin_tracking_location": {
59      "object": "TrackingLocation",
60      "city": "HOUSTON",
61      "state": "TX",
62      "country": null,
63      "zip": "77063"
64    },
65    "destination_location": "CHARLESTON SC, 29401",
66    "destination_tracking_location": null,
67    "guaranteed_delivery_date": null,
68    "alternate_identifier": null,
69    "initial_delivery_attempt": null
70  },
71  "finalized": true,
72  "is_return": false,
73  "public_url": "https://track.easypost.com/djE6dHJrX2E0NWRiODhiYjUxOTQ1NTc4NzkyNDZhYmQxMTA2MDZj"
74}

Retrieve all Trackers

A list of all Tracker objects associated with the given API Key can also be retrieved. See the Pagination section of our docs for more details on retrieving all records when multiple pages are available.

Using the Tracker List endpoint is the recommended way of retrieving a Tracker by tracking_code or carrier. Unlike the retrieving a Tracker using the retrieve endpoint, which accepts an id, this endpoint accepts the tracking_code as the search parameter. Normally, you'll only have one Tracker with a given tracking_code, but it is also possible to further filter those results by including the carrier parameter in your 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_code

i.e. 9400110898825022579493

Only return Trackers with the given tracking code. Useful for retrieving an individual Tracker by tracking_code rather than by id.

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_3898303eff624097a516ab324bb133f3",
5      "object": "Tracker",
6      "mode": "test",
7      "tracking_code": "9405500207552011812894",
8      "status": "pre_transit",
9      "status_detail": "status_update",
10      "created_at": "2024-01-24T00:07:43Z",
11      "updated_at": "2024-01-24T00:07:43Z",
12      "signed_by": null,
13      "weight": null,
14      "est_delivery_date": "2024-01-24T00:07:43Z",
15      "shipment_id": "shp_82d5637d74404d1595eacdc7e5ca9273",
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": "2023-12-24T00:07:43Z",
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        },
35        {
36          "object": "TrackingDetail",
37          "message": "Shipping Label Created",
38          "description": "",
39          "status": "pre_transit",
40          "status_detail": "status_update",
41          "datetime": "2023-12-24T12:44:43Z",
42          "source": "USPS",
43          "carrier_code": "",
44          "tracking_location": {
45            "object": "TrackingLocation",
46            "city": "HOUSTON",
47            "state": "TX",
48            "country": null,
49            "zip": "77063"
50          }
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/djE6dHJrXzM4OTgzMDNlZmY2MjQwOTdhNTE2YWIzMjRiYjEzM2Yz"
75    }
76  ],
77  "has_more": true
78}

Retrieve a Tracker

Retrieve a Tracker by its id.

Request Parameters

i.e. trk_...

Unique, starts with "trk_"

GET /trackers/:id

1curl -X GET https://api.easypost.com/v2/trackers/trk_... \
2  -u "EASYPOST_API_KEY":

Response

1{
2  "id": "trk_3898303eff624097a516ab324bb133f3",
3  "object": "Tracker",
4  "mode": "test",
5  "tracking_code": "9405500207552011812894",
6  "status": "pre_transit",
7  "status_detail": "status_update",
8  "created_at": "2024-01-24T00:07:43Z",
9  "updated_at": "2024-01-24T00:07:43Z",
10  "signed_by": null,
11  "weight": null,
12  "est_delivery_date": "2024-01-24T00:07:43Z",
13  "shipment_id": "shp_82d5637d74404d1595eacdc7e5ca9273",
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": "2023-12-24T00:07:43Z",
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    },
33    {
34      "object": "TrackingDetail",
35      "message": "Shipping Label Created",
36      "description": "",
37      "status": "pre_transit",
38      "status_detail": "status_update",
39      "datetime": "2023-12-24T12:44:43Z",
40      "source": "USPS",
41      "carrier_code": "",
42      "tracking_location": {
43        "object": "TrackingLocation",
44        "city": "HOUSTON",
45        "state": "TX",
46        "country": null,
47        "zip": "77063"
48      }
49    }
50  ],
51  "fees": [],
52  "carrier_detail": {
53    "object": "CarrierDetail",
54    "service": "First-Class Package Service",
55    "container_type": null,
56    "est_delivery_date_local": null,
57    "est_delivery_time_local": null,
58    "origin_location": "HOUSTON TX, 77001",
59    "origin_tracking_location": {
60      "object": "TrackingLocation",
61      "city": "HOUSTON",
62      "state": "TX",
63      "country": null,
64      "zip": "77063"
65    },
66    "destination_location": "CHARLESTON SC, 29401",
67    "destination_tracking_location": null,
68    "guaranteed_delivery_date": null,
69    "alternate_identifier": null,
70    "initial_delivery_attempt": null
71  },
72  "public_url": "https://track.easypost.com/djE6dHJrXzM4OTgzMDNlZmY2MjQwOTdhNTE2YWIzMjRiYjEzM2Yz"
73}