Tracking

Use the Shippo Tracking API to track shipments from all carriers with normalized data, complete tracking history, and real-time updates. When used with webhooks, you’ll receive instant notifications whenever there’s a tracking update. This setup ensures you always have the latest tracking information for all your shipments and can alert recipients if they need to take action.

Track live shipments

If you have already created a webhook, labels purchased through Shippo will send tracking events to that webhook. If you did not purchase a label through Shippo and would like to receive tracking updates on your webhook you can register the tracking number with the following example using a tracking number and the name of the carrier.

NoteTo use live tracking, you must use your live key. If you want to test tracking with test mode, see the testing tracking guide.

Create a webhook.
- Set the webhook Event Type to Track Updated.
- Set the webhook Environment to Production.
- Set the webhook URL to an address that can listen to your webhook.

Important

Tracking webhooks are not idempotent.
Clients should register a webhook only once per tracking event.
Duplicate registrations can result in multiple notifications for the same event.

POST the below to the tracks endpoint.

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

You must register a webhook prior to POSTing to the tracking endpoint. Once POSTed, all updates to that tracking number will only be sent to your active tracking webhooks. You can find a list of all supported carrier tokens here. Also, certain carriers require an account to track shipments sent through them or only permit tracking shipments created through Shippo. Please see Carrier Restrictions below for details. 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, see a sample response below. Tracking is included for shipments created on Shippo but incurs a cost per tracking number for all other shipments.

{
  "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",
  "original_eta": "2023-07-23T00:00:00Z",
  "eta": "2023-07-23T00:00:00Z",
  "servicelevel": {
    "token": "usps_priority",
    "name": "Priority Mail"
  },
  "metadata": null,
  "tracking_status": {
    "object_created": "2023-07-23T20:35:26.129Z",
    "object_updated": "2023-07-23T20:35:26.129Z",
    "object_id": "ce48ff3d52a34e91b77aa98370182624",
    "status": "DELIVERED",
    "status_details": "Your shipment has been delivered at the destination mailbox.",
    "status_date": "2023-07-23T13:03:00Z",
    "location": {
      "city": "Spotsylvania",
      "state": "VA",
      "zip": "22551",
      "country": "US"
    }
  },
  "tracking_history": [
    {
      "object_created": "2023-07-22T14:36:50.943Z",
      "object_id": "265c7a7c23354da5b87b2bf52656c625",
      "status": "TRANSIT",
      "status_details": "Your shipment has been accepted.",
      "status_date": "2023-07-21T15:33:00Z",
      "location": {
        "city": "Las Vegas",
        "state": "NV",
        "zip": "89101",
        "country": "US"
      }
    },
    ...

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

Event definitions

The returned response from a tracking request includes a status. The status is a high-level indication of where in the delivery process your package is. Below is a list of possible status values with a description of each.

Status	Description
`PRE_TRANSIT`	The label is created but before the package is dropped off or picked up 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.
`UNKNOWN`	The package has not been found via the carrier’s tracking system.

Each status may also have a substatus. A substatus can give finer details about the current status of your package. Each field’s definition is also available in our API Reference documentation. The action_required indicates the substatus requires action from the shipper or recipient to complete delivery.

Status	Substatus	Definition	Meaning
`PRE_TRANSIT`	information_received	Information about the package received.	The carrier has received the necessary details about your package. This is normally the first step in the shipping process, indicating that the shipment information is in the carrier’s system.
`TRANSIT`	address_issue	Address information is incorrect. Contact carrier to ensure delivery.	There is a problem with the address provided for the delivery. The address may be incorrect or incomplete. You must contact the carrier to correct the address and ensure the package can be delivered.
`TRANSIT`	contact_carrier	Contact the carrier for more information.	The carrier needs more additional information or action from you. You should contact the carrier to resolve any issues or get more details about the package status.
`TRANSIT`	delayed	Delivery of package is delayed.	The delivery of the package is experiencing a delay. This could be due to various reasons such as weather conditions, high shipment volumes, or logistical issues.
`TRANSIT`	delivery_attempted	Delivery of package has been attempted. Contact carrier to ensure delivery.	The carrier tried to deliver the package but was unsuccessful. This may be due to no one being available to receive it or other access issues. You should contact the carrier to arrange for another delivery attempt.
`TRANSIT`	delivery_rescheduled	Delivery of package has been rescheduled.	The scheduled delivery date for the package has been changed. This could be due to the recipient’s request or other logistical reasons.
`TRANSIT`	delivery_scheduled	Package is scheduled for delivery.	Your package is planned for delivery on a specific date. The carrier has set a delivery date for your package.
`TRANSIT`	location_inaccessible	Delivery location inaccessible to carrier. Contact carrier to ensure delivery.	The delivery location cannot be reached by the carrier. This could be due to physical barriers, restricted access, or other obstacles. You should contact the carrier to resolve the issue and ensure delivery.
`TRANSIT`	notice_left	Carrier left notice during attempted delivery. Follow carrier instructions on notice.	The carrier left a notice at your address during an attempted delivery. This notice will have instructions on how to receive your package, such as scheduling a redelivery or picking it up from a carrier location.
`TRANSIT`	out_for_delivery	Package is out for delivery.	Your package is currently on its way to the delivery address. This can also mean your package was scanned by a package handler and placed on a pallet to be loaded on a vehicle for delivery. It is with the carrier’s delivery personnel and should be delivered soon.
`TRANSIT`	package_accepted	Package has been accepted into the carrier network for delivery.	The carrier has received your package into their network and it is ready to be processed for delivery
`TRANSIT`	package_arrived	Package has arrived at an intermediate location in the carrier network.	Your package has reached a transit point in the carrier’s network. This is typically an intermediate facility where packages are sorted and sent to their next destination.
`TRANSIT`	package_damaged	Package has been damaged. Contact carrier for more details.	Your package has been damaged during the shipping process. You should contact the carrier to get more information and possibly file a claim.
`TRANSIT`	package_departed	Package has departed from an intermediate location in the carrier network.	Your package has left a transit point in the carrier’s network and is on its way to the next destination.
`TRANSIT`	package_forwarded	Package has been forwarded.	Your package has been redirected to a different address. This could be due to a forwarding request by the recipient or an address correction.
`TRANSIT`	package_held	Package held at carrier location. Contact carrier for more details.	The carrier is holding your package at a specific location. You should contact the carrier to find out why it is being held and how to retrieve it.
`TRANSIT`	package_processed	Package has been processed at an intermediate location.	Your package has been processed at a transit point and is ready for the next step in the delivery process.
`TRANSIT`	package_processing	Package is processing at an intermediate location in the carrier network.	Your package is currently being processed at a transit point. This involves sorting and preparing it for the next leg of its journey.
`TRANSIT`	pickup_available	Package is available for pickup at carrier location.	Your package is available for pickup at a carrier location. You can go to the specified location to collect your package.
`TRANSIT`	reschedule_delivery	Contact carrier to reschedule delivery.	You need to contact the carrier to arrange a new delivery date for your package. This might be due to an issue with the initial delivery attempt.
`DELIVERED`	delivered	Package has been delivered.	Your package has been successfully delivered to the recipient’s address.
`RETURNED`	return_to_sender	Package is to be returned to sender.	Your package is being sent back to the sender. This could be due to an undeliverable address, refusal by the recipient, or other reasons.
`RETURNED`	package_unclaimed	Package is unclaimed.	Your package has not been claimed by the recipient. You may need to contact the carrier to arrange for collection or redelivery.
`FAILURE`	package_undeliverable	Package is not able to be delivered.	The carrier is unable to deliver your package. This could be due to address issues, recipient unavailability, or other reasons. You should contact the carrier to resolve the issue.
`FAILURE`	package_disposed	Package has been disposed.	The carrier has disposed of your package. This usually happens when a package is undeliverable and unclaimed for an extended period.
`FAILURE`	package_lost	Package has been lost. Contact carrier for more details.	Your package has been lost in the shipping process. You should contact the carrier for more details and to possibly file a claim for the lost item.
`UNKNOWN`	other	Unrecognized carrier status.

Testing tracking

In our Test environment you are able to review our responses with mock tracking numbers. Using your Shippo Test Token, use shippo as your carrier and the tracking number be one of the following, depending on which tracking event you’re testing: SHIPPO_PRE_TRANSIT, SHIPPO_TRANSIT, SHIPPO_DELIVERED, SHIPPO_RETURNED, SHIPPO_FAILURE, SHIPPO_UNKNOWN. Follow this example.

Test tracking request

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

Test tracking response

{
    "messages": [],
    "carrier": "shippo",
    "tracking_number": "SHIPPO_TRANSIT",
    "address_from": {
        "city": "San Francisco",
        "state": "CA",
        "zip": "94103",
        "country": "US"
    },
    "address_to": {
        "city": "Chicago",
        "state": "IL",
        "zip": "60611",
        "country": "US"
    },
    "eta": "2018-08-02T18:49:42.566",
    "original_eta": "2018-08-02T18:49:42.566",
    "servicelevel": {
        "token": "shippo_priority",
        "name": "Priority Mail"
    },
    "metadata": "Shippo test tracking",
    "tracking_status": {
        "object_created": "2018-07-30T18:49:42.586",
        "object_updated": null,
        "object_id": "560f1b9cfe8341a2899e0388f1b9081c",
        "status": "TRANSIT",
        "status_details": "Your shipment has departed from the origin.",
        "status_date": "2018-07-29T16:44:42.586",
        "substatus": null,
        "location": {
            "city": "San Francisco",
            "state": "CA",
            "zip": "94103",
            "country": "US"
        }
    },
    "tracking_history": [
        {
            "object_created": "2018-07-30T18:49:42.589",
            "object_updated": null,
            "object_id": "9a056563ad874a0b9bf79dee321f25f5",
            "status": "UNKNOWN",
            "status_details": "The carrier has received the electronic shipment information.",
            "status_date": "2018-07-28T14:39:42.589",
            "substatus": null,
            "location": {
                "city": "San Francisco",
                "state": "CA",
                "zip": "94103",
                "country": "US"
            }
        },
        {
            "object_created": "2018-07-30T18:49:42.589",
            "object_updated": null,
            "object_id": "82ef073b04ef48368e79b835af788fce",
            "status": "TRANSIT",
            "status_details": "Your shipment has departed from the origin.",
            "status_date": "2018-07-29T16:44:42.589",
            "substatus": null,
            "location": {
                "city": "San Francisco",
                "state": "CA",
                "zip": "94103",
                "country": "US"
            }
        }
    ],
    "transaction": null,
    "test": true
}

To see all possible status, substatus and corresponding action_required values, review our full list above.

Track Shippo shipments

For each production label you purchase, Shippo automatically tracks the shipment status through the corresponding carrier’s tracking system. The latest status is accessible via the corresponding Transaction’s tracking_status field. Here’s a sample Transaction object:

{
    "object_state": "VALID",
    "status": "SUCCESS",
    "object_created": "2023-11-29T16:31:19.512Z",
    "object_updated": "2023-11-29T16:31:19.512Z",
    "object_id": "5695ae3a5eda41ba9abdbf347fd545f3",
    "object_owner": "test@shippo.com",
    "test": false,
    "rate": "693ea14a541f44e090291b929c171d5a",
    "tracking_number": "9102969010383081813033",
    "tracking_status": "DELIVERED",
    "eta": "2023-11-24T00:00:00Z",
    "tracking_url_provider": "https:\/\/tools.usps.com\/go\/TrackConfirmAction_input?origTrackNum=9102969010383081813033",
    "label_url": "https:\/\/shippo-delivery-east.s3.amazonaws.com\/5695ae3a5eda41ba9abdbf347fd545f3.pdf?Signature=AyiitLq2g%2F2R9fjboCTVxi5z7JQ%3D&Expires=1534873886&AWSAccessKeyId=AKIAJGLCC5MYLLWIG42A",
    "commercial_invoice_url": null,
    "messages": [],
    "order": "ca760ef0099040b4a2b7feec827bca88",
    "metadata": "",
    "parcel": "e0de043b2f7f4b6d8e6f23ad69641cc1",
    "billing": {"payments": []}
}

Track individual shipments

To submit an individual tracking request for a single shipment, including those created outside of Shippo, you can send a GET request to the Tracking Status endpoint with your shipment 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>"

The response is similar to the example above.

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 tracked shipment. 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"

Including package details

You can include an optional boolean parameter, include_package_details, in the tracking POST request. This parameter is currently supported only for UPS and FedEx. If omitted, it defaults to false. If set to true, Shippo may include weight and dimensions in the tracking API response when those details are available from the carrier’s tracking API. Package details are returned only in the tracking API response; track_updated webhook payloads do not include weight or dimensions. Weight and dimensions may be partial and may be updated over time as the carrier provides additional data. Shippo includes only fields provided by the carrier and does not add default or null values for missing dimension fields. Dimensions are omitted only when the unit is missing and cannot be safely inferred, or when the carrier-provided data is invalid. Here’s a sample request:

curl https://api.goshippo.com/tracks/\
    -H "Authorization: ShippoToken <API_TOKEN>"\
    -d carrier="ups"\
    -d tracking_number="1Z999AA10123456784"\
    -d include_package_details=true

For example, when include_package_details=true and the carrier returns package details, the response can include:

"weight": [
    {
        "value": "2.2",
        "unit": "LB"
    },
    {
        "value": "1.0",
        "unit": "KG"
    }
],
"dimensions": [
    {
        "length": "1",
        "width": "2",
        "height": "3",
        "unit": "in"
    },
    {
        "length": "3",
        "width": "5",
        "height": "8",
        "unit": "cm"
    }
],

Carrier restrictions

Some carriers require that you have an account with them 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. To track shipments with the below carriers, add your respective carrier account into your Shippo account:

Australia Post
BetterTrucks
Correos España
GLS US
Gophr
GSO
Hongkong Post
Jitsu
LSO
Mondial Relay
PCF
Poste Italiane
Purolator
Swyft

Additionally, the following carriers only permit tracking shipments that were created though Shippo:

Canada Post
Colissimo
Deutsche Post
DHL eCommerce
DHL Germany
DPD UK
Evri UK
Lasership
New Zealand Post
Ontrac
Passport

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

Tracking pages

Tracking pages let retailers share detailed order tracking information through the native look and feel of their own brand. You can brand your own tracking pages within the Shippo web app.

Log in to our Web app to upload assets to the Tracking page in your settings.
Publish content and retrieve your base URL from the View test link link.
Send customers to your pages (include this link in your own emails, for example) with the <baseurl>/<carrier>/<trackingnumber>.

By default, your URL may take the following pattern. https://track.goshippo.com/tracking/<UserID>/<carrier>/<trackingnumber>

Overview

Get started

AI & agents

Guides

Concepts

Track live shipments

Event definitions

Testing tracking

Track Shippo shipments

Track individual shipments

Adding metadata

Including package details

Carrier restrictions

Tracking pages

​Track live shipments

​Event definitions

​Testing tracking

​Track Shippo shipments

​Track individual shipments

​Adding metadata

​Including package details

​Carrier restrictions

​Tracking pages

Track live shipments

Event definitions

Testing tracking

Track Shippo shipments

Track individual shipments

Adding metadata

Including package details

Carrier restrictions

Tracking pages