Track Shipments

You can track shipments with Shippo using just a tracking number and the name of the carrier. To get started tracking shipments in Shippo, follow these two easy steps:

  1. Setup a webhook.
  2. POST the below to https://api.goshippo.com/tracks/
    {
        "carrier": "usps",
        "tracking_number": "9102969010383081813033"
    }

Its important to know that you must have a webhook registered saved with us prior to POSTing to the tracks endpoint, because once POSTed, that tracking number will only register to your active webhook.

Also, certain carriers require an account to track shipments sent through them, please see Carrier Restrictions below for details.

Setup Webhooks for tracking updates

Get push-notified of any status updates for your shipments from the API setting of your Shippo Dashboard. Anytime the tracking status changes, Shippo will POST to all active webhooks of your Shippo account. The POST request's body contains a JSON of the Transaction object as above.

For more information about webhook behaviors, see our guide.

You can set up your webhooks on the API settings page of your Shippo Dashboard. This page also allows you to test webhooks with a sample payload.

Requesting webhook updates for a shipment

To let Shippo know that you want to receive webhook updates for a shipment, you will need to POST to the Tracking Status endpoint. You can also add custom metadata to this POST call, which is not available in the GET call.

The POST request's body needs to consist of your shipment's tracking_number and carrier:

curl https://api.goshippo.com/tracks/ \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -d carrier="usps" \
    -d tracking_number="9205590164917312751089" \
    -d metadata="Order 000123"

You will get the same response as in the GET request outlined above.

Shippo will now automatically track your package and send webhook notifications to all your registered webhooks whenever the package's tracking status changes.

Expected webhook behavior

Shippo expects your webhook to return a response with a 2XX HTTP status code, indicating that the webhook has been received successfully. If Shippo doesn't receive a 2XX response status code, the webhook POST request will be re-tried 1 time with a 3 second delay between each try. Thus each webhook will receive, at most, 2 messages within 3 seconds. It is recommended that the maximum response time for your webhook be of 5 seconds or less.

For more information, see our Webhooks tutorial.

You will get a response back that includes the latest tracking status via the corresponding tracking_status field, and the entire history via the tracking_history field. Possible values for the status field are the same.

{
  "carrier": "usps",
  "tracking_number": "9205590164917312751089",
  "address_from": {
    "city": "Las Vegas",
    "state": "NV",
    "zip": "89101",
    "country": "US"
  },
  "address_to": {
    "city": "Spotsylvania",
    "state": "VA",
    "zip": "22551",
    "country": "US"
  },
  "transaction": "1275c67d754f45bf9d6e4d7a3e205314",
  "eta": "2016-07-23T00:00:00Z",
  "servicelevel": {
    "token": "usps_priority",
    "name": "Priority Mail"
  },
  "metadata": null,
  "tracking_status": {
    "object_created": "2016-07-23T20:35:26.129Z",
    "object_updated": "2016-07-23T20:35:26.129Z",
    "object_id": "ce48ff3d52a34e91b77aa98370182624",
    "status": "DELIVERED",
    "status_details": "Your shipment has been delivered at the destination mailbox.",
    "status_date": "2016-07-23T13:03:00Z",
    "location": {
      "city": "Spotsylvania",
      "state": "VA",
      "zip": "22551",
      "country": "US"
    }
  },
  "tracking_history": [
    {
      "object_created": "2016-07-22T14:36:50.943Z",
      "object_id": "265c7a7c23354da5b87b2bf52656c625",
      "status": "TRANSIT",
      "status_details": "Your shipment has been accepted.",
      "status_date": "2016-07-21T15:33:00Z",
      "location": {
        "city": "Las Vegas",
        "state": "NV",
        "zip": "89101",
        "country": "US"
      }
    },
    ...

    {
      "object_created": "2016-07-23T20:35:26.129Z",
      "object_id": "aab1d7c0559d43ccbba4ff8603089e56",
      "status": "DELIVERED",
      "status_details": "Your shipment has been delivered at the destination mailbox.",
      "status_date": "2016-07-23T13:03:00Z",
      "location": {
        "city": "Spotsylvania",
        "state": "VA",
        "zip": "22551",
        "country": "US"
      }
    }
  ]
}

Possible values for the status field are:

  • UNKNOWN: The package has not been found via the carrier's tracking system, or it has been found but not yet scanned by the carrier.
  • TRANSIT: The package has been scanned by the carrier and is in transit.
  • DELIVERED: The package has been successfully delivered.
  • RETURNED: The package is en route to be returned to the sender, or has been returned successfully.
  • FAILURE: The carrier indicated that there has been an issue with the delivery. This can happen for various reasons and depends on the carrier. This status does not indicate a technical, but a delivery issue.

Adding metadata

You can add metadata to the tracking request through a POST request. This is a free form field where any user-specific information can be added. By making a POST request to add metadata, all your existing webhooks will also be connected to the tracking shipment. However, if you don't have any webhooks it will only add the metadata information.

You can see metadata as part of responses of the GET request, but you can only change it with POST requests.

You can track any shipments with Shippo as long as you have the tracking number. You can also set up webhook callbacks to get notified of any status updates.

  1. Track shipments created on Shippo, these shipping labels were created with the API and already exists as an object on Shippo.
  2. Track any shipment, with the tracking number and knowledge of which carriers it's shipped with, shipments created outside of Shippo can be tracked through our Tracking Status endpoint. Certain carriers require an account to track shipments sent through them, please see Carrier Restrictions below for details.

Track Shipments created on Shippo

For each production label you purchase, Shippo automatically tracks the package status through the corresponding carrier's tracking system.

The latest status is accessible via the corresponding Transaction's tracking_status field, and the entire history is available via the tracking_history field. Here's a sample Transaction object:

{
    "object_state":"VALID",
    "status":"SUCCESS",
    "object_created":"2014-11-29T16:31:19.512Z",
    "object_updated":"2014-11-29T16:31:19.512Z",
    "object_id":"5695ae3a5eda41ba9abdbf347fd545f3",
    "tracking_number":"9102969010383081813033",
    "tracking_status":{  
        "object_created":"2014-11-29T16:31:19.511Z",
        "status":"DELIVERED",
        "status_details":"Your shipment has been delivered.",
        "status_date":"2012-03-08T09:58:00Z",
        "location":{  
            "city":"Beverly Hills",
            "state":"CA",
            "zip":"90210",
            "country":"US"
        }
    },
    "eta":"2014-07-21T12:00:00.000Z"
}

Track Any Shipment

To track any shipment, including those created outside of Shippo, you can also send a GET request to the Tracking Status endpoint with your shipment's carrier and tracking_number.

You can find a list of all supported carrier tokens here.

Here's a sample request.

curl https://api.goshippo.com/tracks/usps/9205590164917312751089 \
    -H "Authorization: ShippoToken <API_TOKEN>"

You will get a response back that which includes:

  • The city, state, zip code and country of the address_from and address_to
  • Estimated time of arrival, and the service level of the package
  • Latest tracking_status
  • Entire history through the tracking_history attribute.
  • Possible values for the status field are the same as above.

Here's a sample Tracking response:

{
  "carrier": "usps",
  "tracking_number": "9205590164917312751089",
  "address_from": {
    "city": "Las Vegas",
    "state": "NV",
    "zip": "89101",
    "country": "US"
  },
  "address_to": {
    "city": "Spotsylvania",
    "state": "VA",
    "zip": "22551",
    "country": "US"
  },
  "transaction": "1275c67d754f45bf9d6e4d7a3e205314",
  "eta": "2016-07-23T00:00:00Z",
  "servicelevel": {
    "token": "usps_priority",
    "name": "Priority Mail"
  },
  "metadata": null,
  "tracking_status": {
    "object_created": "2016-07-23T20:35:26.129Z",
    "object_updated": "2016-07-23T20:35:26.129Z",
    "object_id": "ce48ff3d52a34e91b77aa98370182624",
    "status": "DELIVERED",
    "status_details": "Your shipment has been delivered at the destination mailbox.",
    "status_date": "2016-07-23T13:03:00Z",
    "location": {
      "city": "Spotsylvania",
      "state": "VA",
      "zip": "22551",
      "country": "US"
    }
  },
  "tracking_history": [
    {
      "object_created": "2016-07-22T14:36:50.943Z",
      "object_id": "265c7a7c23354da5b87b2bf52656c625",
      "status": "TRANSIT",
      "status_details": "Your shipment has been accepted.",
      "status_date": "2016-07-21T15:33:00Z",
      "location": {
        "city": "Las Vegas",
        "state": "NV",
        "zip": "89101",
        "country": "US"
      }
    },
    ...

    {
      "object_created": "2016-07-23T20:35:26.129Z",
      "object_id": "aab1d7c0559d43ccbba4ff8603089e56",
      "status": "DELIVERED",
      "status_details": "Your shipment has been delivered at the destination mailbox.",
      "status_date": "2016-07-23T13:03:00Z",
      "location": {
        "city": "Spotsylvania",
        "state": "VA",
        "zip": "22551",
        "country": "US"
      }
    }
  ]
}

Carrier Restrictions

Some carriers require that you have an account with them in order to track shipments being delivered through them. This is only relevant if you are sending your tracking numbers as a POST to get updates via our webhook (where it is required to have a Shippo account). Otherwise, you simply wouldn't be able to track shipments through the below carriers.

In order to track shipments with the below carriers, you need to add your respective carrier account into your Shippo account:

  • Australia Post
  • Purolator

See Carrier Accounts for details on adding carrier accounts to your Shippo account.