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.

1. 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 .
2. POST the below to the tracks endpoint .
   Copy

   Copied

   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.

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	Action Required?
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	outfordelivery	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	returntosender	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.

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

{
    "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"

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
• CDL
• 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.

1. Log in to our Web app to upload assets to the Tracking page in your settings.
2. Publish content and retrieve your base URL from the View test link link.
3. 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>