Track a Package

With ShipEngine, you can subscribe to real-time tracking events for any package – regardless of whether you created the label via ShipEngine.

For labels that were created via ShipEngine, we recommend that you track by Label ID. For other packages, follow the instructions below to track via the tracking number instead.

Supported Carriers

Carrier	Carrier Code
U.S. Postal Service	`usps`
Stamps.com	`stamps_com`
FedEx	`fedex`
UPS	`ups`
DHL Express	`dhl_express`
DHL ECommerce	`dhl_global_mail`
Canada Post	`canada_post`
Australia Post	`australia_post`
First Mile	`firstmile`
Asendia	`asendia`
OnTrac	`ontrac`
APC	`apc`
Newgistics	`newgistics`
Globegistics	`globegistics`
RR Donnelley	`rr_donnelley`
IMEX	`imex`
Access Worldwide	`access_worldwide`
Purolator Canada	`purolator_ca`
Sendle	`sendle`

Info

Event Timestamps

carrier_occurred_at is the timestamp of the event received from the carrier, it is assumed to be the local time of where the event occurred.

occurred_at is the UTC based time of the event's occurrence.

Warning The carried_occurred_at event property is not yet fully supported across all carriers.

Example

The following example demonstrates how to get tracking information. You need to specify the carrier_code (see the table above) and the tracking_number of the package.

Example Request

GET /v1/tracking?carrier_code=stamps_com&tracking_number=9405511899223197428490 HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__

curl -iX GET 'https://api.shipengine.com/v1/tracking?carrier_code=stamps_com&tracking_number=9405511899223197428490' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Host", "api.shipengine.com")
$headers.Add("API-Key", "__YOUR_API_KEY_HERE__")

$response = Invoke-RestMethod 'https://api.shipengine.com/v1/tracking?carrier_code=stamps_com&tracking_number=9405511899223197428490' -Method 'GET' -Headers $headers -Body $body
$response | ConvertTo-Json

var myHeaders = new Headers();
myHeaders.append("Host", "api.shipengine.com");
myHeaders.append("API-Key", "__YOUR_API_KEY_HERE__");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://api.shipengine.com/v1/tracking?carrier_code=stamps_com&tracking_number=9405511899223197428490", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://api.shipengine.com/v1/tracking?carrier_code=stamps_com&tracking_number=9405511899223197428490',
  'headers': {
    'Host': 'api.shipengine.com',
    'API-Key': '__YOUR_API_KEY_HERE__'
  }
};
request(options, function (error, response) { 
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.shipengine.com/v1/tracking?carrier_code=stamps_com&tracking_number=9405511899223197428490",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Host: api.shipengine.com",
    "API-Key: __YOUR_API_KEY_HERE__"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests

url = "https://api.shipengine.com/v1/tracking?carrier_code=stamps_com&tracking_number=9405511899223197428490"

payload = {}
headers = {
  'Host': 'api.shipengine.com',
  'API-Key': '__YOUR_API_KEY_HERE__'
}

response = requests.request("GET", url, headers=headers, data = payload)

print(response.text.encode('utf8'))

require "uri"
require "net/http"

url = URI("https://api.shipengine.com/v1/tracking?carrier_code=stamps_com&tracking_number=9405511899223197428490")

https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Host"] = "api.shipengine.com"
request["API-Key"] = "__YOUR_API_KEY_HERE__"

response = https.request(request)
puts response.read_body

var client = new RestClient("https://api.shipengine.com/v1/tracking?carrier_code=stamps_com&tracking_number=9405511899223197428490");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Host", "api.shipengine.com");
request.AddHeader("API-Key", "__YOUR_API_KEY_HERE__");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://api.shipengine.com/v1/tracking?carrier_code=stamps_com&tracking_number=9405511899223197428490")
  .method("GET", null)
  .addHeader("Host", "api.shipengine.com")
  .addHeader("API-Key", "__YOUR_API_KEY_HERE__")
  .build();
Response response = client.newCall(request).execute();

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.shipengine.com/v1/tracking?carrier_code=stamps_com&tracking_number=9405511899223197428490"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
  }
  req.Header.Add("Host", "api.shipengine.com")
  req.Header.Add("API-Key", "__YOUR_API_KEY_HERE__")

  res, err := client.Do(req)
  defer res.Body.Close()
  body, err := ioutil.ReadAll(res.Body)

  fmt.Println(string(body))
}

#import <Foundation/Foundation.h>

dispatch_semaphore_t sema = dispatch_semaphore_create(0);

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://api.shipengine.com/v1/tracking?carrier_code=stamps_com&tracking_number=9405511899223197428490"]
  cachePolicy:NSURLRequestUseProtocolCachePolicy
  timeoutInterval:10.0];
NSDictionary *headers = @{
  @"Host": @"api.shipengine.com",
  @"API-Key": @"__YOUR_API_KEY_HERE__"
};

[request setAllHTTPHeaderFields:headers];

[request setHTTPMethod:@"GET"];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
  if (error) {
    NSLog(@"%@", error);
  } else {
    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
    NSError *parseError = nil;
    NSDictionary *responseDictionary = [NSJSONSerialization JSONObjectWithData:data options:0 error:&parseError];
    NSLog(@"%@",responseDictionary);
    dispatch_semaphore_signal(sema);
  }
}];
[dataTask resume];
dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);

import Foundation

var semaphore = DispatchSemaphore (value: 0)

var request = URLRequest(url: URL(string: "https://api.shipengine.com/v1/tracking?carrier_code=stamps_com&tracking_number=9405511899223197428490")!,timeoutInterval: Double.infinity)
request.addValue("api.shipengine.com", forHTTPHeaderField: "Host")
request.addValue("__YOUR_API_KEY_HERE__", forHTTPHeaderField: "API-Key")

request.httpMethod = "GET"

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
  guard let data = data else {
    print(String(describing: error))
    return
  }
  print(String(data: data, encoding: .utf8)!)
  semaphore.signal()
}

task.resume()
semaphore.wait()

Example Response

{
  "tracking_number": "9405511899223197428490",
  "status_code": "DE",
  "status_description": "Delivered",
  "carrier_status_code": "01",
  "carrier_status_description": "Your item was delivered in or at the mailbox at 9:10 am on March 2, 2017 in AUSTIN, TX 78756.",
  "ship_date": "2019-07-26T22:10:50.286Z",
  "estimated_delivery_date": null,
  "actual_delivery_date": "2019-07-26T22:10:50.286Z",
  "exception_description": null,
  "events": [
    {
      "occurred_at": "2019-09-13T12:32:00Z",
      "carrier_occurred_at": "2019-09-13T05:32:00",
      "description": "Arrived at USPS Facility",
      "city_locality": "OCEANSIDE",
      "state_province": "CA",
      "postal_code": "92056",
      "country_code": "",
      "company_name": "",
      "signer": "",
      "event_code": "U1"
    }
  ]
}

{
  "tracking_number": "9405511899223197428490",
  "status_code": "DE",
  "status_description": "Delivered",
  "carrier_status_code": "01",
  "carrier_status_description": "Your item was delivered in or at the mailbox at 9:10 am on March 2, 2017 in AUSTIN, TX 78756.",
  "ship_date": "2019-07-26T22:10:50.286Z",
  "estimated_delivery_date": null,
  "actual_delivery_date": "2019-07-26T22:10:50.286Z",
  "exception_description": null,
  "events": [
    {
      "occurred_at": "2019-09-13T12:32:00Z",
      "carrier_occurred_at": "2019-09-13T05:32:00",
      "description": "Arrived at USPS Facility",
      "city_locality": "OCEANSIDE",
      "state_province": "CA",
      "postal_code": "92056",
      "country_code": "",
      "company_name": "",
      "signer": "",
      "event_code": "U1"
    }
  ]
}

Tracking Status Codes

Here's how the status_code and status_description fields correspond to each other, and how they correspond to the tracking_status field of a label:

status_code	status_description	tracking_status
`AC`	Accepted	N/A
`IT`	In Transit	`in_transit`
`DE`	Delivered	`delivered`
`EX`	Exception	`error`
`UN`	Unknown	`unknown`
`AT`	Delivery Attempt	N/A
`NY`	Not Yet In System	`in_transit`