# 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. --- ## Tracker object | Property | Type | Description | |----------|------|-------------| | 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 | 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 | Example Object: ```json { "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 | Property | Type | Description | |----------|------|-------------| | 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 | TrackingLocation | The location associated with the scan event | Example Object: ```json { "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" } ``` --- ## TrackingLocation object | Property | Type | Description | |----------|------|-------------| | 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) | Example Object: ```json { "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" } ``` --- ## CarrierDetail object | Property | Type | Description | |----------|------|-------------| | 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 | An additional tracking identifier provided by the carrier for certain hybrid services (e.g., last-mile tracking number). May be returned at label purchase or populated asynchronously after label purchase. | | initial_delivery_attempt | datetime | The date and time of the first attempt by the carrier to deliver the package (if available) | Example Object: ```json { "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" } ``` --- ## 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 [Content omitted: parameter list rendered dynamically. Review the rendered documentation for complete parameter details.] --- ### Carrier Tracking Strings [Content omitted: parameter list rendered dynamically. Review the rendered documentation for complete parameter details.] --- ## Create a Tracker ### Example: POST /trackers #### cURL ```shell curl -X POST https://api.easypost.com/v2/trackers \ -u "EASYPOST_API_KEY": \ -H 'Content-Type: application/json' \ -d '{ "tracker": { "tracking_code": "EZ1000000001", "carrier": "USPS" } }' ``` #### Go ```go package example import ( "fmt" "github.com/EasyPost/easypost-go/v5" ) func create() { client := easypost.New("EASYPOST_API_KEY") tracker, _ := client.CreateTracker( &easypost.CreateTrackerOptions{ TrackingCode: "EZ1000000001", Carrier: "USPS", }, ) fmt.Println(tracker) } ``` #### Java ```java package trackers; import com.easypost.exception.EasyPostException; import com.easypost.model.Tracker; import com.easypost.service.EasyPostClient; import java.util.HashMap; public class Create { public static void main(String[] args) throws EasyPostException { EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY"); HashMap params = new HashMap(); params.put("tracking_code", "EZ1000000001"); params.put("carrier", "USPS"); Tracker tracker = client.tracker.create(params); System.out.println(tracker); } } ``` #### C# ```csharp using System; using System.Collections.Generic; using System.Threading.Tasks; using EasyPost; using Newtonsoft.Json; namespace EasyPostExamples { public class Examples { public static async Task Main() { var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY")); EasyPost.Parameters.Tracker.Create parameters = new() { TrackingCode = "EZ1000000001", Carrier = "USPS" }; EasyPost.Models.API.Tracker tracker = await client.Tracker.Create(parameters); Console.WriteLine(JsonConvert.SerializeObject(tracker, Formatting.Indented)); } } } ``` #### Node.js ```javascript const EasyPostClient = require('@easypost/api'); const client = new EasyPostClient('EASYPOST_API_KEY'); (async () => { const tracker = await client.Tracker.create({ tracking_code: 'EZ1000000001', carrier: 'USPS', }); console.log(tracker); })(); ``` #### PHP ```php tracker->create([ 'tracking_code' => 'EZ1000000001', 'carrier' => 'USPS' ]); echo $tracker; ``` #### Python ```python import easypost client = easypost.EasyPostClient("EASYPOST_API_KEY") tracker = client.tracker.create( tracking_code="EZ1000000001", carrier="USPS", ) print(tracker) ``` #### Ruby ```ruby require 'easypost' client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY') tracker = client.tracker.create( tracking_code: 'EZ1000000001', carrier: 'USPS', ) puts tracker ``` EasyPost supports two tracking workflows: **Shipment-Based Tracking** and **Standalone Tracking**. ### Shipment-Based Tracking Trackers are automatically created when a `Shipment` is purchased through the EasyPost API. Tracking information is tied to the `Shipment` and updates as the carrier provides new events. This is the most common tracking workflow and requires no separate `Tracker` creation. ### Standalone Tracking A `Tracker` can be created using only a `tracking_code`, without creating a `Shipment`. This is referred to as Standalone Tracking and is commonly used when shipping labels are purchased ouside of EasyPost and EasyPost is used solely for parcel tracking. 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` is recommended, as some tracking codes are ambiguous and may match multiple carriers. Explicitly setting the `carrier` also improves response time by avoiding carrier auto-detection. Some carriers restrict access to tracking data when requests originate from third-party platforms. In these cases, carrier-specific credentials may be required to retrieve tracking updates. Tracking availability and authentication requirements vary by carrier and may change over time. 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 previous three months. In such cases, the original `Tracker` is returned. [Note: This object is immutable after creation. Review the rendered documentation for details.] --- ## Retrieve all Trackers ### Example: GET /trackers #### cURL ```shell curl -X GET "https://api.easypost.com/v2/trackers?page_size=5" \ -u "EASYPOST_API_KEY": ``` #### Go ```go package example import ( "fmt" "github.com/EasyPost/easypost-go/v5" ) func list() { client := easypost.New("EASYPOST_API_KEY") trackers, _ := client.ListTrackers( &easypost.ListTrackersOptions{ PageSize: 5, }, ) fmt.Println(trackers) } ``` #### Java ```java package trackers; import com.easypost.exception.EasyPostException; import com.easypost.model.TrackerCollection; import com.easypost.service.EasyPostClient; import java.util.HashMap; public class All { public static void main(String[] args) throws EasyPostException { EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY"); HashMap params = new HashMap<>(); params.put("page_size", 5); TrackerCollection trackers = client.tracker.all(params); System.out.println(trackers); } } ``` #### C# ```csharp using System; using System.Collections.Generic; using System.Threading.Tasks; using EasyPost; using Newtonsoft.Json; namespace EasyPostExamples { public class Examples { public static async Task Main() { var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY")); EasyPost.Parameters.Tracker.All parameters = new() { PageSize = 5 }; EasyPost.Models.API.TrackerCollection trackerCollection = await client.Tracker.All(parameters); Console.WriteLine(JsonConvert.SerializeObject(trackerCollection, Formatting.Indented)); } } } ``` #### Node.js ```javascript const EasyPostClient = require('@easypost/api'); const client = new EasyPostClient('EASYPOST_API_KEY'); (async () => { const trackers = await client.Tracker.all({ page_size: 5, }); console.log(trackers); })(); ``` #### PHP ```php tracker->all([ 'page_size' => 5, ]); echo $trackers; ``` #### Python ```python import easypost client = easypost.EasyPostClient("EASYPOST_API_KEY") trackers = client.tracker.all( page_size=5, ) print(trackers) ``` #### Ruby ```ruby require 'easypost' client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY') trackers = client.tracker.all( page_size: 5, ) puts 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. --- ## Retrieve a Tracker ### Example: GET /trackers/:id #### cURL ```shell curl -X GET https://api.easypost.com/v2/trackers/trk_... \ -u "EASYPOST_API_KEY": ``` #### Go ```go package example import ( "fmt" "github.com/EasyPost/easypost-go/v5" ) func retrieve() { client := easypost.New("EASYPOST_API_KEY") tracker, _ := client.GetTracker("trk_...") fmt.Println(tracker) } ``` #### Java ```java package trackers; import com.easypost.exception.EasyPostException; import com.easypost.model.Tracker; import com.easypost.service.EasyPostClient; public class Retrieve { public static void main(String[] args) throws EasyPostException { EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY"); Tracker tracker = client.tracker.retrieve("trk_..."); System.out.println(tracker); } } ``` #### C# ```csharp using System; using System.Collections.Generic; using System.Threading.Tasks; using EasyPost; using Newtonsoft.Json; namespace EasyPostExamples { public class Examples { public static async Task Main() { var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY")); EasyPost.Models.API.Tracker tracker = await client.Tracker.Retrieve("trk_..."); Console.WriteLine(JsonConvert.SerializeObject(tracker, Formatting.Indented)); } } } ``` #### Node.js ```javascript const EasyPostClient = require('@easypost/api'); const client = new EasyPostClient('EASYPOST_API_KEY'); (async () => { const tracker = await client.Tracker.retrieve('trk_...'); console.log(tracker); })(); ``` #### PHP ```php tracker->retrieve('trk_...'); echo $tracker; ``` #### Python ```python import easypost client = easypost.EasyPostClient("EASYPOST_API_KEY") tracker = client.tracker.retrieve("trk_...") print(tracker) ``` #### Ruby ```ruby require 'easypost' client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY') tracker = client.tracker.retrieve('trk_...') puts tracker ``` Retrieve a `Tracker` by its `id`. --- ## Delete a Tracker ### Example: DELETE /trackers/:id #### cURL ```shell curl -X DELETE https://api.easypost.com/v2/trackers/trk_... \ -u "EASYPOST_API_KEY": ``` 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.