Shipment Tracking API

Track shipments consistently with Shipium's Shipment Tracking API.

Get started

The Shipment Tracking API enables you to retrieve tracking data for shipments that were rate shopped using Shipium's Carrier and Method Selection service to provide package transit updates to your customers.

You can use this API to search for single or bulk registered tracking events. By default, only the most recent tracking event is included for single and bulk searches. To include all tracking events, you'll need to update your search parameters. On this page, you'll find information on how to do this.

🚧

Bulk search limitation

You're limited to no more than 100 tracking numbers within a single request.

With a bulk search, in the trackingSearchRequests and shipiumTrackingId arrays, you can provide up to 100 tracking requests at a time, but no more than 100.

This document provides guidance for using the Shipment Tracking API. The Track and Trace document provides information about all of Shipium's Track and Trace services. You can refer to the Track Shipments document for specifics about tracking Shipium shipments and to the Use Webhooks for Tracking document for additional details about using webhooks.

Track shipments using the API

This guide provides support for conducting single and bulk searches using two methods:

  • search via carrier, using both the carrier ID and carrier tracking ID; and
  • search via Shipium, using the Shipium tracking ID.

You can filter the search in two ways:

  • request only the most recent tracking status, excluding historical tracking events (default); or
  • request full tracking event history.

If your desired search doesn't seem to fit the parameters defined for these two search types, see the Edge Cases section of this guide for additional support.

Shipment status

The API response returns a normalized shipmentStatus value for each request. The following table describes the types of shipment statuses.

Shipment statusDescription
RegisteredThe package has been registered for tracking.
Label PrintedThe shipment label has been printed.
In TransitThe package has been picked up by the carrier, arrived at a carrier facility, left a carrier facility, or is in transit to the customer.
Out For DeliveryThe package is out for delivery.
DeliveredThe package has been delivered.
ExceptionThere has been a carrier exception for this package.
Return to Sender: In TransitThe package is being returned and has been picked up by the carrier, arrived at a carrier facility, left a carrier facility, or is in transit to the returns facility.
Return to Sender: ExceptionThe package is being returned, and there has been a carrier exception for this package.
Return to Sender: Out for DeliveryThe package is being returned and is out for delivery.
Return to Sender: DeliveredThe package is being returned and has been delivered.

Search by carrier (carrierId and carrierTrackingId)

You can conduct a single or bulk search by carrier for your organization using a combination of carrier ID and carrier tracking ID. This is described in the table below, which includes each applicable API call. You can find carrier ID and carrier service method ID values in Supported Carriers.

Search TypeCarrier FieldsAPI Call
SinglecarrierId and carrierTrackingIdGET: api/v1/tracking/carrier/{carrierId}/{carrierTrackingId}
BulkcarrierId and carrierTrackingIdPOST: api/v1/tracking/bulkCarrierTrackingSearch

👉

Shipments using multiple carriers

For shipments tracked via multiple carriers, Shipium retrieves all tracking events as if they were associated with the initial carrier regardless of how many carriers were involved in delivering the shipment.

Example cURL requests for search by carrier (carrierId and carrierTrackingId)

This section includes example cURL requests and JSON responses for both single and bulk searches by carrier.

Single search by carrier (carrierId and carrierTrackingId) - default

This example shows the cURL request for single searching by carrier. By default, the excludeEvents parameter value is set to "true" and only the most recent tracking event will be included.

curl --location --request GET 'https://api.shipium.com/api/v1/tracking/carrier/{carrierId}/{carrierTrackingId}?excludeEvents=true' \
--header $AUTHSTRING  

Example JSON response:

{
    "shipiumTrackingId": "b3d5f0f7-a49b-475f-b70e-727c0cc5b530",
    "carrierId": "ups",
    "carrierTrackingId": "1Z074E600396493771",
    "carrierServiceMethodId": "ups-ground-service-method",
    "shipmentStatus": "Delivered",
    "shippedDateTime": "2022-11-08T18:45:45Z",
    "deliveredAtDateTime": "2022-11-10T11:35:54-05:00",
    "carrierEstimatedDeliveryDate": "2022-11-10T11:35:54-05:00",
    "trackingEvents": []
}

Single search by carrier (carrierId and carrierTrackingId) - all events included

You have the option to include all tracking events for single searching. This example shows the cURL request for single searching by carrier, including the option to include all tracking events. To include tracking events, set the optional excludeEvents parameter to "false".

curl --request GET \
  --url 'https://api.shipium.com/api/v1/tracking/carrier/{carrierId}/{carrierTrackingId}?excludeEvents=false' \  
  --header 'accept: application/json'  \ 
  --header $AUTHSTRING    \
  --header 'content-type: application/json' 

Example JSON response:

{

   "shipiumTrackingId": "7df8264e-6b4a-4af0-8d3f-f5246f3075e2",
   "carrierId": "fedex",
   "carrierTrackingId": "274204633522",
   "carrierServiceMethodId": "fedex-2day-service-method",
   "shipmentStatus": "Delivered",
   "shippedDateTime": "2022-06-13T16:30:00Z",
   "deliveredAtDateTime": "2022-06-15T11:00:00-04:00",
   "trackingEvents": [
       {
           "carrierDescription": "Delivered",
           "shipmentStatus": "Delivered",
           "eventDate": "2022-06-15T15:00:00Z",
           "postalCode": "44102",
           "country": "US",
           "city": "CLEVELAND",
           "region": "OH"
       },
       {
           "carrierDescription": "On FedEx vehicle for delivery",
           "shipmentStatus": "Out For Delivery",
           "eventDate": "2022-06-15T11:20:00Z",
           "postalCode": "44130",
           "country": "US",
           "city": "MIDDLEBURG HEIGHTS",
           "region": "OH"
       },
       {
           "carrierDescription": "At local FedEx facility",
           "shipmentStatus": "In Transit",
           "eventDate": "2022-06-15T11:17:00Z",
           "postalCode": "44130",
           "country": "US",
           "city": "MIDDLEBURG HEIGHTS",
           "region": "OH"
       },
       {
           "carrierDescription": "At destination sort facility",
           "shipmentStatus": "In Transit",
           "eventDate": "2022-06-15T08:56:00Z",
           "postalCode": "44135",
           "country": "US",
           "city": "CLEVELAND",
           "region": "OH"
       },
       {
           "carrierDescription": "Departed FedEx hub",
           "shipmentStatus": "In Transit",
           "eventDate": "2022-06-15T00:17:00Z",
           "postalCode": "27410",
           "country": "US",
           "city": "GREENSBORO",
           "region": "NC"
       },
       {
           "carrierDescription": "Left FedEx origin facility",
           "shipmentStatus": "In Transit",
           "eventDate": "2022-06-14T01:50:00Z",
           "postalCode": "75038",
           "country": "US",
           "city": "IRVING",
           "region": "TX"
       },
       {
           "carrierDescription": "Shipment arriving On-Time",
           "shipmentStatus": "Label Printed",
           "eventDate": "2022-06-13T18:08:00Z",
           "postalCode": "75038",
           "country": "US",
           "city": "IRVING",
           "region": "TX"
       },
       {
           "carrierDescription": "Picked up",
           "shipmentStatus": "In Transit",
           "eventDate": "2022-06-13T16:30:00Z",
           "postalCode": "75038",
           "country": "US",
           "city": "IRVING",
           "region": "TX"
       },
       {
           "carrierDescription": "Shipment information sent to FedEx",
           "shipmentStatus": "Label Printed",
           "eventDate": "2022-06-10T23:46:35Z"
       }
   ]
}

Bulk search by carrier (carrierId and carrierTrackingId) - default

This example shows the cURL request for bulk searching by carrier. By default, the excludeEvents parameter value is set to "true" and only the most recent tracking event will be included.

curl --location --request POST 'https://api.shipium.com/api/v1/tracking/bulkCarrierTrackingSearch' \
--header 'Content-Type: application/json' \
--header $AUTHSTRING  \
--data-raw '{
    "trackingSearchRequests": [
    {
      "carrierId": "OnTrac",
      "carrierTrackingId": "d10013441676680"
    }
  ],
  "excludeEvents": true
}'

Example JSON response:

{
    "trackings": [
        {
            "shipiumTrackingId": "cbecd7cf-6f5e-4bf4-a3ce-75f08ba34579",
            "carrierId": "ontrac",
            "carrierTrackingId": "D10013441676680",
            "carrierServiceMethodId": "ontrac-ground-service-method",
            "shipmentStatus": "Delivered",
            "shippedDateTime": "2022-11-01T21:23:00Z",
            "deliveredAtDateTime": "2022-11-02T12:30:00-07:00",
            "carrierEstimatedDeliveryDate": "2022-11-01T17:00:00-07:00",
            "trackingEvents": []
        }
    ]
}

Bulk search by carrier (carrierId and carrierTrackingId) - all events included

This example shows the cURL request for bulk searching by carrier, including the option to include all tracking event details. To include, the optional excludeEvents field value should be "false".

curl --location --request POST 'https://api.shipium.com/api/v1/tracking/bulkCarrierTrackingSearch' \
--header 'Content-Type: application/json' \
--header $AUTHSTRING  \
--data-raw '{
    "trackingSearchRequests": [
    {
      "carrierId": "OnTrac",
      "carrierTrackingId": "d10013441676680"
    }
  ]
  "excludeEvents": false
}'

Example JSON response:

{
    "trackings": [
        {
            "shipiumTrackingId": "cbecd7cf-6f5e-4bf4-a3ce-75f08ba34579",
            "carrierId": "ontrac",
            "carrierTrackingId": "D10013441676680",
            "carrierServiceMethodId": "ontrac-ground-service-method",
            "shipmentStatus": "Delivered",
            "shippedDateTime": "2022-11-01T21:23:00Z",
            "deliveredAtDateTime": "2022-11-02T12:30:00-07:00",
            "carrierEstimatedDeliveryDate": "2022-11-01T17:00:00-07:00",
            "trackingEvents": [
                {
                    "carrierDescription": "Delivered - Consignment left",
                    "shipmentStatus": "Delivered",
                    "eventDate": "2022-11-02T19:30:00Z",
                    "postalCode": "94901",
                    "country": "US",
                    "city": "SAN RAFAEL",
                    "region": "CA"
                },
                {
                    "carrierDescription": "Out for delivery",
                    "shipmentStatus": "Out For Delivery",
                    "eventDate": "2022-11-02T15:14:00Z",
                    "postalCode": "94901",
                    "country": "US",
                    "city": "SAN RAFAEL",
                    "region": "CA"
                },
                {
                    "carrierDescription": "Package arrived at destination facility",
                    "shipmentStatus": "In Transit",
                    "eventDate": "2022-11-02T12:44:00Z",
                    "postalCode": "94954",
                    "country": "US",
                    "city": "PETALUMA",
                    "region": "CA"
                },
                {
                    "carrierDescription": "Origination scan - Package scanned at facility",
                    "shipmentStatus": "In Transit",
                    "eventDate": "2022-11-01T21:23:00Z",
                    "postalCode": "89506",
                    "country": "US",
                    "city": "Reno",
                    "region": "NV"
                },
                {
                    "carrierDescription": "Shipping label created; data received",
                    "shipmentStatus": "Label Printed",
                    "eventDate": "2022-11-01T17:16:00Z",
                    "postalCode": "89506",
                    "country": "US",
                    "city": "Reno",
                    "region": "NV"
                }
            ]
        }
    ]
}

Search by Shipium (shipiumTrackingId)

You can conduct a single or bulk search by Shipium using the Shipium tracking ID, as noted in the following table, which includes each applicable API call.

Search TypeShipium FieldAPI Call
SingleshipiumTrackingIdGET: api/v1/tracking/{shipiumTrackingId}
BulkshipiumTrackingIdPOST: api/v1/tracking/bulkTrackingSearch

Example cURL requests for search by Shipium (shipiumTrackingId)

This section includes example cURL requests and JSON responses for both single and bulk searches by Shipium.

Single search by Shipium (shipiumTrackingId) - default

This example shows the cURL request for single searching by Shipium tracking ID. By default, the excludeEvents parameter value is set to "true" and only the most recent tracking event will be included.

curl --location --request GET 'https://api.shipium.com/api/v1/tracking/b3d5f0f7-a49b-475f-b70e-727c0cc5b530?excludeEvents=true' \
--header $AUTHSTRING

Example JSON response:

{
    "shipiumTrackingId": "b3d5f0f7-a49b-475f-b70e-727c0cc5b530",
    "carrierId": "ups",
    "carrierTrackingId": "1Z074E600396493771",
    "carrierServiceMethodId": "ups-ground-service-method",
    "shipmentStatus": "Delivered",
    "shippedDateTime": "2022-11-08T18:45:45Z",
    "deliveredAtDateTime": "2022-11-10T11:35:54-05:00",
    "carrierEstimatedDeliveryDate": "2022-11-10T11:35:54-05:00",
    "trackingEvents": []
}

Single search by Shipium (shipiumTrackingId) - all events included

This example shows the cURL request for single searching by Shipium, including the option to include all tracking events. To include tracking events, set the optional excludeEvents parameter to "false".

curl --location --request GET 'https://api.shipium.com/api/v1/tracking/b3d5f0f7-a49b-475f-b70e-727c0cc5b530?excludeEvents=false' \
--header $AUTHSTRING   

Example JSON response:

{
    "shipiumTrackingId": "b3d5f0f7-a49b-475f-b70e-727c0cc5b530",
    "carrierId": "ups",
    "carrierTrackingId": "1Z074E600396493771",
    "carrierServiceMethodId": "ups-ground-service-method",
    "shipmentStatus": "Delivered",
    "shippedDateTime": "2022-11-08T18:45:45Z",
    "deliveredAtDateTime": "2022-11-10T11:35:54-05:00",
    "carrierEstimatedDeliveryDate": "2022-11-10T11:35:54-05:00",
    "trackingEvents": [
        {
            "carrierDescription": "DELIVERED ",
            "shipmentStatus": "Delivered",
            "eventDate": "2022-11-10T16:35:54Z",
            "country": "US",
            "city": "SNELLVILLE",
            "region": "GA"
        },
        {
            "carrierDescription": "Out For Delivery Today",
            "shipmentStatus": "In Transit",
            "eventDate": "2022-11-10T14:25:08Z",
            "country": "US",
            "city": "Doraville",
            "region": "GA"
        },
        {
            "carrierDescription": "Processing at UPS Facility",
            "shipmentStatus": "In Transit",
            "eventDate": "2022-11-10T12:53:55Z",
            "country": "US",
            "city": "Doraville",
            "region": "GA"
        },
        {
            "carrierDescription": "Arrived at Facility",
            "shipmentStatus": "In Transit",
            "eventDate": "2022-11-10T05:46:00Z",
            "country": "US",
            "city": "Doraville",
            "region": "GA"
        },
        {
            "carrierDescription": "Departed from Facility",
            "shipmentStatus": "In Transit",
            "eventDate": "2022-11-10T04:54:00Z",
            "country": "US",
            "city": "Atlanta",
            "region": "GA"
        },
        {
            "carrierDescription": "Arrived at Facility",
            "shipmentStatus": "In Transit",
            "eventDate": "2022-11-09T20:20:00Z",
            "country": "US",
            "city": "Atlanta",
            "region": "GA"
        },
        {
            "carrierDescription": "Departed from Facility",
            "shipmentStatus": "In Transit",
            "eventDate": "2022-11-09T20:09:00Z",
            "country": "US",
            "city": "Atlanta",
            "region": "GA"
        },
        {
            "carrierDescription": "Arrived at Facility",
            "shipmentStatus": "In Transit",
            "eventDate": "2022-11-09T17:23:00Z",
            "country": "US",
            "city": "Atlanta",
            "region": "GA"
        },
        {
            "carrierDescription": "Departed from Facility",
            "shipmentStatus": "In Transit",
            "eventDate": "2022-11-09T13:49:00Z",
            "country": "US",
            "city": "Knoxville",
            "region": "TN"
        },
        {
            "carrierDescription": "Arrived at Facility",
            "shipmentStatus": "In Transit",
            "eventDate": "2022-11-09T11:18:00Z",
            "country": "US",
            "city": "Knoxville",
            "region": "TN"
        },
        {
            "carrierDescription": "Departed from Facility",
            "shipmentStatus": "In Transit",
            "eventDate": "2022-11-09T06:39:00Z",
            "country": "US",
            "city": "Roanoke",
            "region": "VA"
        },
        {
            "carrierDescription": "Arrived at Facility",
            "shipmentStatus": "In Transit",
            "eventDate": "2022-11-09T05:10:00Z",
            "country": "US",
            "city": "Roanoke",
            "region": "VA"
        },
        {
            "carrierDescription": "Departed from Facility",
            "shipmentStatus": "In Transit",
            "eventDate": "2022-11-08T23:59:00Z",
            "country": "US",
            "city": "Middletown",
            "region": "PA"
        },
        {
            "carrierDescription": "Origin Scan",
            "shipmentStatus": "In Transit",
            "eventDate": "2022-11-08T18:45:45Z",
            "country": "US",
            "city": "Middletown",
            "region": "PA"
        },
        {
            "carrierDescription": "Shipper created a label, UPS has not received the package yet. ",
            "shipmentStatus": "Label Printed",
            "eventDate": "2022-11-01T00:00:08Z",
            "country": "US"
        }
    ]
}

Bulk search by Shipium (shipiumTrackingId) - default

This example shows the cURL request for bulk searching by Shipium tracking ID. By default, the excludeEvents parameter value is set to "true" and only the most recent tracking event will be included.

curl --location --request POST 'https://api.shipium.com/api/v1/tracking/bulkTrackingSearch' \
--header 'Content-Type: application/json' \
--header $AUTHSTRING   \
--data-raw '{ 
    "shipiumTrackingIds": [
        "e528f7fa-c046-4689-b514-a13ed6da5e87"
    ],
    "excludeEvents": true
}'

Example JSON response:

{
    "trackings": [
        {
            "shipiumTrackingId": "e528f7fa-c046-4689-b514-a13ed6da5e87",
            "carrierId": "ups",
            "carrierTrackingId": "1Z074E600395261166",
            "carrierServiceMethodId": "ups-ground-service-method",
            "shipmentStatus": "Delivered",
            "shippedDateTime": "2022-11-08T18:43:51Z",
            "deliveredAtDateTime": "2022-11-10T11:35:54-05:00",
            "carrierEstimatedDeliveryDate": "2022-11-10T11:35:54-05:00",
            "trackingEvents": []
        }
    ]

Bulk search by Shipium (shipiumTrackingId) - all events included

This example shows the cURL request for bulk searching by Shipium, including the option to include all tracking events. To include, the optional excludeEvents field value should be "false".

curl --location --request POST 'https://api.shipium.com/api/v1/tracking/bulkTrackingSearch' \
--header 'Content-Type: application/json' \
--header $AUTHSTRING   \
--data-raw '{ 
    "shipiumTrackingIds": [
        "e528f7fa-c046-4689-b514-a13ed6da5e87"
    ],
    "excludeEvents": false
}'

Example JSON response:

{
    "trackings": [
        {
            "shipiumTrackingId": "e528f7fa-c046-4689-b514-a13ed6da5e87",
            "carrierId": "ups",
            "carrierTrackingId": "1Z074E600395261166",
            "carrierServiceMethodId": "ups-ground-service-method",
            "shipmentStatus": "Delivered",
            "shippedDateTime": "2022-11-08T18:43:51Z",
            "deliveredAtDateTime": "2022-11-10T11:35:54-05:00",
            "carrierEstimatedDeliveryDate": "2022-11-10T11:35:54-05:00",
            "trackingEvents": [
                {
                    "carrierDescription": "DELIVERED ",
                    "shipmentStatus": "Delivered",
                    "eventDate": "2022-11-10T16:35:54Z",
                    "country": "US",
                    "city": "SNELLVILLE",
                    "region": "GA"
                },
                {
                    "carrierDescription": "Out For Delivery Today",
                    "shipmentStatus": "In Transit",
                    "eventDate": "2022-11-10T14:25:08Z",
                    "country": "US",
                    "city": "Doraville",
                    "region": "GA"
                },
                {
                    "carrierDescription": "Processing at UPS Facility",
                    "shipmentStatus": "In Transit",
                    "eventDate": "2022-11-10T12:54:03Z",
                    "country": "US",
                    "city": "Doraville",
                    "region": "GA"
                },
                {
                    "carrierDescription": "Arrived at Facility",
                    "shipmentStatus": "In Transit",
                    "eventDate": "2022-11-10T05:46:00Z",
                    "country": "US",
                    "city": "Doraville",
                    "region": "GA"
                },
                {
                    "carrierDescription": "Departed from Facility",
                    "shipmentStatus": "In Transit",
                    "eventDate": "2022-11-10T04:54:00Z",
                    "country": "US",
                    "city": "Atlanta",
                    "region": "GA"
                },
                {
                    "carrierDescription": "Arrived at Facility",
                    "shipmentStatus": "In Transit",
                    "eventDate": "2022-11-09T20:20:00Z",
                    "country": "US",
                    "city": "Atlanta",
                    "region": "GA"
                },
                {
                    "carrierDescription": "Departed from Facility",
                    "shipmentStatus": "In Transit",
                    "eventDate": "2022-11-09T20:09:00Z",
                    "country": "US",
                    "city": "Atlanta",
                    "region": "GA"
                },
                {
                    "carrierDescription": "Arrived at Facility",
                    "shipmentStatus": "In Transit",
                    "eventDate": "2022-11-09T17:23:00Z",
                    "country": "US",
                    "city": "Atlanta",
                    "region": "GA"
                },
                {
                    "carrierDescription": "Departed from Facility",
                    "shipmentStatus": "In Transit",
                    "eventDate": "2022-11-09T13:49:00Z",
                    "country": "US",
                    "city": "Knoxville",
                    "region": "TN"
                },
                {
                    "carrierDescription": "Arrived at Facility",
                    "shipmentStatus": "In Transit",
                    "eventDate": "2022-11-09T11:18:00Z",
                    "country": "US",
                    "city": "Knoxville",
                    "region": "TN"
                },
                {
                    "carrierDescription": "Departed from Facility",
                    "shipmentStatus": "In Transit",
                    "eventDate": "2022-11-09T06:39:00Z",
                    "country": "US",
                    "city": "Roanoke",
                    "region": "VA"
                },
                {
                    "carrierDescription": "Arrived at Facility",
                    "shipmentStatus": "In Transit",
                    "eventDate": "2022-11-09T05:10:00Z",
                    "country": "US",
                    "city": "Roanoke",
                    "region": "VA"
                },
                {
                    "carrierDescription": "Departed from Facility",
                    "shipmentStatus": "In Transit",
                    "eventDate": "2022-11-08T23:59:00Z",
                    "country": "US",
                    "city": "Middletown",
                    "region": "PA"
                },
                {
                    "carrierDescription": "Origin Scan",
                    "shipmentStatus": "In Transit",
                    "eventDate": "2022-11-08T18:43:51Z",
                    "country": "US",
                    "city": "Middletown",
                    "region": "PA"
                },
                {
                    "carrierDescription": "Shipper created a label, UPS has not received the package yet. ",
                    "shipmentStatus": "Label Printed",
                    "eventDate": "2022-11-01T00:00:07Z",
                    "country": "US"
                }
            ]
        }
    ]
}

Timezone specifications

  • carrierEstimatedDeliveryDate will be local to the destination address timezone.
  • deliveredAtDateTime will be local to the destination address timezone.
  • eventDate will be Coordinated Universal Time (UTC) time.

Edge cases

If we're unable to find the destination address or timezone of the destination address

If we're unable to find the destination address or destination timezone, the date-time returned is still implied at the destination address timezone.

The API defaults to UTC time ('Z') as the timezone offset.

If you search for an unregistered tracking ID

If you search for a tracking ID not registered with Shipium (when calling the single GET endpoints), the API returns a 404 not found error message.

Example cURL request:

curl --request GET \
  --url '<<api_url>>/api/v1/tracking/carrier/ups/abc123' \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' 

Example JSON response for Status 404:

{
   "timestamp": "2022-07-14T19:36:09.096+00:00",
   "status": 404,
   "error": "Not Found",
   "message": "404 NOT_FOUND",
   "path": "/api/v1/tracking/carrier/ups/abc123"
}

📘

More Information on the API responses

As with all Shipium API responses, this API follows the API Response Codes standards unless otherwise specified.

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful: