Skip to main content
POST
/
tracks
cURL
curl https://api.goshippo.com/tracks/ \
-H "Authorization: ShippoToken <API_TOKEN>" \
-d carrier="usps" \
-d tracking_number="9205590164917312751089" \
-d metadata="Order 000123"
import shippo
from shippo.models import components

s = shippo.Shippo(
api_key_header='ShippoToken <API_TOKEN>',
shippo_api_version='2018-02-08',
)


res = s.tracking_status.create(request=components.TracksRequest(
carrier='usps',
metadata='Order 000123',
tracking_number='9205590164917312751089',
))

if res is not None:
# handle response
pass
import { Shippo } from "shippo";

const shippo = new Shippo({
apiKeyHeader: "ShippoToken <API_TOKEN>",
shippoApiVersion: "2018-02-08",
});

async function run() {
const result = await shippo.trackingStatus.create({
carrier: "usps",
metadata: "Order 000123",
trackingNumber: "9205590164917312751089",
});

// Handle the result
console.log(result);
}

run();
using Shippo;
using Shippo.Models.Components;

var sdk = new ShippoSDK(
apiKeyHeader: "ShippoToken <API_TOKEN>",
shippoApiVersion: "2018-02-08"
);

var res = await sdk.TrackingStatus.CreateAsync(
tracksRequest: new TracksRequest() {
Carrier = "usps",
Metadata = "Order 000123",
TrackingNumber = "9205590164917312751089",
},
shippoApiVersion: "2018-02-08"
);

// handle response
declare(strict_types=1);

require 'vendor/autoload.php';

use Shippo\API;
use Shippo\API\Models\Components;

$sdk = API\Shippo::builder()
->setSecurity(
'ShippoToken <API_TOKEN>'
)
->setShippoApiVersion('2018-02-08')
->build();

$tracksRequest = new Components\TracksRequest(
carrier: 'usps',
metadata: 'Order 000123',
trackingNumber: '9205590164917312751089',
);

$response = $sdk->trackingStatus->create(
tracksRequest: $tracksRequest,
shippoApiVersion: '2018-02-08'

);

if ($response->track !== null) {
// handle response
}
package hello.world;

import com.goshippo.shippo_sdk.Shippo;
import com.goshippo.shippo_sdk.models.components.TracksRequest;
import com.goshippo.shippo_sdk.models.operations.CreateTrackResponse;
import java.lang.Exception;

public class Application {

public static void main(String[] args) throws Exception {

Shippo sdk = Shippo.builder()
.apiKeyHeader("ShippoToken <API_TOKEN>")
.shippoApiVersion("2018-02-08")
.build();

CreateTrackResponse res = sdk.trackingStatus().create()
.shippoApiVersion("2018-02-08")
.tracksRequest(TracksRequest.builder()
.carrier("usps")
.trackingNumber("9205590164917312751089")
.metadata("Order 000123")
.build())
.call();

if (res.track().isPresent()) {
// handle response
}
}
}
const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
carrier: 'usps',
tracking_number: '9205590164917312751089',
metadata: 'Order 000123'
})
};

fetch('https://api.goshippo.com/tracks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
package main

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

func main() {

url := "https://api.goshippo.com/tracks"

payload := strings.NewReader("{\n \"carrier\": \"usps\",\n \"tracking_number\": \"9205590164917312751089\",\n \"metadata\": \"Order 000123\"\n}")

req, _ := http.NewRequest("POST", url, payload)

req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
require 'uri'
require 'net/http'

url = URI("https://api.goshippo.com/tracks")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"carrier\": \"usps\",\n \"tracking_number\": \"9205590164917312751089\",\n \"metadata\": \"Order 000123\"\n}"

response = http.request(request)
puts response.read_body
{
  "carrier": "usps",
  "messages": [
    "<string>"
  ],
  "tracking_history": [
    {
      "object_created": "2023-11-07T05:31:56Z",
      "object_id": "<string>",
      "object_updated": "2023-11-07T05:31:56Z",
      "status": "DELIVERED",
      "status_details": "Your shipment has been delivered at the destination mailbox.",
      "location": {
        "city": "Las Vegas",
        "country": "US",
        "state": "NV",
        "zip": "89101"
      },
      "substatus": {
        "code": "information_received",
        "text": "Information about the package received.",
        "action_required": true
      },
      "status_date": "2016-07-23T00:00:00Z"
    }
  ],
  "tracking_number": "9205590164917312751089",
  "address_from": {
    "city": "Las Vegas",
    "country": "US",
    "state": "NV",
    "zip": "89101"
  },
  "address_to": {
    "city": "Las Vegas",
    "country": "US",
    "state": "NV",
    "zip": "89101"
  },
  "eta": "2023-11-07T05:31:56Z",
  "metadata": "Order 000123",
  "original_eta": "2021-07-23T00:00:00Z",
  "servicelevel": {
    "name": "Priority Mail Express",
    "terms": "<string>",
    "token": "usps_priority_express",
    "extended_token": "<string>",
    "parent_servicelevel": {
      "name": "Priority Mail Express",
      "terms": "<string>",
      "token": "usps_priority_express",
      "extended_token": "<string>"
    }
  },
  "tracking_status": {
    "object_created": "2023-11-07T05:31:56Z",
    "object_id": "<string>",
    "object_updated": "2023-11-07T05:31:56Z",
    "status": "DELIVERED",
    "status_details": "Your shipment has been delivered at the destination mailbox.",
    "location": {
      "city": "Las Vegas",
      "country": "US",
      "state": "NV",
      "zip": "89101"
    },
    "substatus": {
      "code": "information_received",
      "text": "Information about the package received.",
      "action_required": true
    },
    "status_date": "2016-07-23T00:00:00Z"
  },
  "transaction": "<string>"
}
{}

Authorizations

Authorization
string
header
default:ShippoToken
required

API key authentication using the ShippoToken scheme. Format: Authorization: ShippoToken <API_TOKEN> Example: Authorization: ShippoToken shippo_live_abc123

Headers

SHIPPO-API-VERSION
string
default:2018-02-08

Optional string used to pick a non-default API version to use. See our API version guide.

Example:

"2018-02-08"

Body

application/json
carrier
string
required

Name of the carrier of the shipment to track.

Example:

"usps"

tracking_number
string
required

Tracking number to track.

Example:

"9205590164917312751089"

metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

Example:

"Order 000123"

Response

Tracking status

carrier
string
required

Name of the carrier of the shipment to track. See Carriers.

Example:

"usps"

messages
string[]
required
tracking_history
object[]
required

A list of tracking events, following the same structure as tracking_status. It contains a full history of all tracking statuses, starting with the earlier tracking event first.

tracking_number
string
required

Tracking number to track.

Example:

"9205590164917312751089"

address_from
object

The sender address with city, state, zip and country information.

address_to
object

The recipient address with city, state, zip and country information.

eta
string<date-time>

The estimated time of arrival according to the carrier, this might be updated by carriers during the life of the shipment.

metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

Example:

"Order 000123"

original_eta
string<date-time>

The estimated time of arrival according to the carrier at the time the shipment first entered the system.

Example:

"2021-07-23T00:00:00Z"

servicelevel
object

Contains details regarding the service level for the given rate.

tracking_status
object

The latest tracking information of this shipment.

transaction
string

The object_id of the transaction associated with this tracking object. This field is visible only to the object owner of the transaction.