Track Using a Label ID

If you generate your labels through ShipEngine, then you can easily subscribe to real-time tracking events using the label ID.

You can also track packages for which you did not use ShipEngine to generate the label, as long as you have the tracking number. See Track a Package for details.

tip

Requirements

You will need a label_id from another Label Request, if you don't have one you can learn how to Create a Label.

Example

GET /v1/labels/:label_id/track

This endpoint allows you to track a specific label that was generated with ShipEngine. You just need the label_id, which you got back when you created the label.

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 Request

GET /v1/labels/se-324658/track HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Cache-Control: no-cache

curl -iX GET https://api.shipengine.com/v1/labels/se-324658/track \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-H 'Cache-Control: no-cache' \

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

$response = Invoke-RestMethod 'https://api.shipengine.com/v1/labels/se-324658/track' -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__");
myHeaders.append("Cache-Control", "no-cache");

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

fetch("https://api.shipengine.com/v1/labels/se-324658/track", 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/labels/se-324658/track',
  'headers': {
    'Host': 'api.shipengine.com',
    'API-Key': '__YOUR_API_KEY_HERE__',
    'Cache-Control': 'no-cache'
  }
};
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/labels/se-324658/track",
  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__",
    "Cache-Control: no-cache"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests

url = "https://api.shipengine.com/v1/labels/se-324658/track"

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

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/labels/se-324658/track")

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__"
request["Cache-Control"] = "no-cache"

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

var client = new RestClient("https://api.shipengine.com/v1/labels/se-324658/track");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Host", "api.shipengine.com");
request.AddHeader("API-Key", "__YOUR_API_KEY_HERE__");
request.AddHeader("Cache-Control", "no-cache");
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/labels/se-324658/track")
  .method("GET", null)
  .addHeader("Host", "api.shipengine.com")
  .addHeader("API-Key", "__YOUR_API_KEY_HERE__")
  .addHeader("Cache-Control", "no-cache")
  .build();
Response response = client.newCall(request).execute();

package main

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

func main() {

  url := "https://api.shipengine.com/v1/labels/se-324658/track"
  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__")
  req.Header.Add("Cache-Control", "no-cache")

  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/labels/se-324658/track"]
  cachePolicy:NSURLRequestUseProtocolCachePolicy
  timeoutInterval:10.0];
NSDictionary *headers = @{
  @"Host": @"api.shipengine.com",
  @"API-Key": @"__YOUR_API_KEY_HERE__",
  @"Cache-Control": @"no-cache"
};

[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/labels/se-324658/track")!,timeoutInterval: Double.infinity)
request.addValue("api.shipengine.com", forHTTPHeaderField: "Host")
request.addValue("__YOUR_API_KEY_HERE__", forHTTPHeaderField: "API-Key")
request.addValue("no-cache", forHTTPHeaderField: "Cache-Control")

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": "1Z932R800390810600",
  "status_code": "DE",
  "status_description": "Delivered",
  "carrier_status_code": "D",
  "carrier_status_description": "DELIVERED",
  "shipped_date": "2019-07-27T11:59:03.289Z",
  "estimated_delivery_date": "2019-07-27T11:59:03.289Z",
  "actual_delivery_date": "2019-07-27T11:59:03.289Z",
  "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": "1Z932R800390810600",
  "status_code": "DE",
  "status_description": "Delivered",
  "carrier_status_code": "D",
  "carrier_status_description": "DELIVERED",
  "shipped_date": "2019-07-27T11:59:03.289Z",
  "estimated_delivery_date": "2019-07-27T11:59:03.289Z",
  "actual_delivery_date": "2019-07-27T11:59:03.289Z",
  "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

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