# 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. Note To use live tracking, you must use your [live key](/docs/guides_general/authentication). If you want to test tracking with test mode, see the [testing tracking guide](#testing-tracking). 1. Create a [webhook](/docs/tracking/webhooks). * 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](/docs/tracking/webhookdebugging). - 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. 2. POST the below to the [tracks endpoint](https://api.goshippo.com/tracks/). ``` curl https://api.goshippo.com/tracks/ \ -H "Authorization: ShippoToken " \ -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.](/shippoapi/public-api/carriers) Also, certain carriers require an account to track shipments sent through them or only permit tracking shipments created through Shippo. Please see [Carrier Restrictions](/docs/tracking/tracking#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](/shippoapi/public-api/tracking-status). 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. | ![green check mark](/assets/check.8abef316f25609dbcf8daf5f8347790915290e92ec6f76205f4c704d29149163.6839417a.svg) | | `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. | ![green check mark](/assets/check.8abef316f25609dbcf8daf5f8347790915290e92ec6f76205f4c704d29149163.6839417a.svg) | | `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. | ![green check mark](/assets/check.8abef316f25609dbcf8daf5f8347790915290e92ec6f76205f4c704d29149163.6839417a.svg) | | `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. | ![green check mark](/assets/check.8abef316f25609dbcf8daf5f8347790915290e92ec6f76205f4c704d29149163.6839417a.svg) | | `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. | ![green check mark](/assets/check.8abef316f25609dbcf8daf5f8347790915290e92ec6f76205f4c704d29149163.6839417a.svg) | | `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. | ![green check mark](/assets/check.8abef316f25609dbcf8daf5f8347790915290e92ec6f76205f4c704d29149163.6839417a.svg) | | `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. | ![green check mark](/assets/check.8abef316f25609dbcf8daf5f8347790915290e92ec6f76205f4c704d29149163.6839417a.svg) | | `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. | ![green check mark](/assets/check.8abef316f25609dbcf8daf5f8347790915290e92ec6f76205f4c704d29149163.6839417a.svg) | | `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. | ![green check mark](/assets/check.8abef316f25609dbcf8daf5f8347790915290e92ec6f76205f4c704d29149163.6839417a.svg) | | `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. | ![green check mark](/assets/check.8abef316f25609dbcf8daf5f8347790915290e92ec6f76205f4c704d29149163.6839417a.svg) | | `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. | ![green check mark](/assets/check.8abef316f25609dbcf8daf5f8347790915290e92ec6f76205f4c704d29149163.6839417a.svg) | | `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 " \ -d carrier="shippo" \ -d tracking_number="SHIPPO_TRANSIT" \ -d metadata="Order 000123" ``` ```json { "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](/docs/tracking/tracking#event-definitions) 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](/shippoapi/public-api/tracking-status) with your shipment `carrier` and `tracking_number`. You can find a [list of all supported carrier tokens here](/shippoapi/public-api/carriers). Here's a sample request. ``` curl https://api.goshippo.com/tracks/usps/9205590164917312751089\ -H "Authorization: ShippoToken " ``` 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 "\ -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 "\ -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 - 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](/docs/carriers/carrieraccounts) 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](https://goshippo.com/blog/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 `//`. By default, your URL may take the following pattern. `https://track.goshippo.com/tracking///` ![shippo tracking page sample](/assets/tracking-page.711770a9ec276d9d568be716c29b06b7dfc16ef4fc5ef4414b7758039f33bcf6.6839417a.png)