Shipium Tracking API Details

Suggest Edits

Overview of TrackingInfo

The TrackingInfo API – /trackinginfo – is used to retrieve the package tracking results from shipping carriers so that you can use them on your site or in your own applications. There are two different ways to retrieve this data (though both return data in the same format), either with detailed historical results or just with the most recent status. The latter is often what is really needed and can be MUCH smaller from a data perspective.

We will cover some details below, as well as walk through some typical examples.

Detailed Results

There is a boolean parameter in the data you pass, includeDetails, which determines whether you retrieve just the current status or if you get the history as well. There are many cases in which you may just wish to show the current status and as the history can be a significant amount of data, you will want to set includeDetails=false for any call that doesn't need the full history. Passing includeDetails=true will return additional rows in the returned array of trackingInfos.

Transaction IDs (ADVANCED)

For some Partners, there is a desired to associate a unique identifier with the tracking call. In order to support this, as well as making it easier for you to find the details of a particular API response after the fact, the TrackingInfo API has a unique ID (called the transactionId) associated with each call. If you do not provide one, Shipium will generate one for each call. If you want to provide your own so that you can associate these calls with an internal ID, you can pass this optional value which will be returned with the response.

Response Overview

While the API Documentation covers field-by-field details, it is worth having a basic understanding of how the data is represented in the returned data structure. At the top level is the transactionId previously discussed as well as the carrier for which the request has been made.

Next is where you will find your shipment's tracking information, in an array of JSON objects, one per each trackingId that was passed to the API. Each object contains some basic information about the shipment, the latest carrier tracking event and (if specified in the call) an array of carrierTrackingEvents starting with the most recent one and going backward in time.

Each of the carrierTrackingEvents (whether the latestCarrierTrackingEvent or prior events in the carrierTrackingEventHistory), the most useful fields are these:

  • shippedDateTime – The timestamp (in ISO-8601 format) for when the shipment was shipped. Note that this can be null if the item has not yet been picked up by the carrier.
  • deliveredDateTime – The timestamp (in ISO-8601 format) for when the shipment was delivered. Not that this is null until it has been delivered, as you might expect.
  • deliveryStep – A high-level, generally easier-for-customers to understand status of the shipment, such as "InTransit". This is what we generally recommend be used for showing to customers (possibly with a mapping to your own desired phrasing).
  • status – A slightly more detailed status of the shipment, such as "ArrivedCarrierFacility". Note that this example would have a deliveryStep of "InTransit".
  • event – each of these tells you additional information (generally geographic) about the event.
  • shipiumLastUpdateDateTime – A timestamp (in ISO-8601 format) giving information about the last time that information was pulled from the carrier for this shipment.

📘

Valid Carriers

If you are looking for the current list of supported carriers, you can use the Carriers API to retrieve the live list.

TrackingInfo API

Basic TrackingInfo Request

This example contains only the most recent status and auto-generates a transactionId for the response.

curl --request POST \
  --url '<<api_url>>/api/v1/trackinginfo' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer SAMPLEBEARERTOKEN' \
  --header 'content-type: application/json' \
  --data '{"carrier": "fedex", "includeDetails":false, "trackingIds":["61299988861736643287"]}'

Basic TrackingInfo Response

{
  "transactionId": "0298f463-05e1-4bf9-923a-404d19f98f2e",
  "carrier": "fedex",
  "trackingInfos": [
    {
      "trackingId": "61299988861736643287",
      "carrierTrackingInfo": {
          "carrier": "fedex",
          "trackingId": "61299988861736643287",
          "shippedDateTime": "2020-04-15T09:13:00-07:00",
          "deliveredDateTime": "2020-04-17T08:52:00-07:00",
          "deliveryStep": "Delivered",
          "status": "Delivered",
          "statusMessage": "The package has been delivered.",
          "latestCarrierTrackingEvent": {
              "eventDateTime": "2020-04-17T08:52:00-07:00",
              "deliveryStep": "Delivered",
              "status": "Delivered",
              "statusMessage": "The package has been delivered.",
              "carrierStatusMessage": "Delivered",
              "eventCity": "BROOKFIELD",
              "eventRegion": "WI",
              "eventPostalCode": "53005",
              "eventCountry": "US",
              "shipiumLastUpdateDateTime": null
          },
          "carrierTrackingEventHistory": []
      }
    }
  ]
}

Full History TrackingInfo Request

This example contains the full status history and uses a provided transactionId for the response.

curl --request POST \
  --url '<<api_url>>/api/v1/trackinginfo' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer SAMPLEBEARERTOKEN' \
  --header 'content-type: application/json' \
  --data '{"carrier": "fedex", "includeDetails":true, "trackingIds":["61299988861736643287"]}'

Full History TrackingInfoRequest

{
  "transactionId": "f41c72b4-c9a4-4d1e-a3f4-44a232621a47",
  "carrier": "fedex",
  "trackingInfos": [
    {
      "trackingId": "61299988861736643287",
      "carrierTrackingInfo": {
          "carrier": "fedex",
          "trackingId": "61299988861736643287",
          "shippedDateTime": "2020-04-15T09:13:00-07:00",
          "deliveredDateTime": "2020-04-17T08:52:00-07:00",
          "deliveryStep": "Delivered",
          "status": "Delivered",
          "statusMessage": "The package has been delivered.",
          "latestCarrierTrackingEvent": {
              "eventDateTime": "2020-04-17T08:52:00-07:00",
              "deliveryStep": "Delivered",
              "status": "Delivered",
              "statusMessage": "The package has been delivered.",
              "carrierStatusMessage": "Delivered",
              "eventCity": "BROOKFIELD",
              "eventRegion": "WI",
              "eventPostalCode": "53005",
              "eventCountry": "US",
              "shipiumLastUpdateDateTime": null
        },
        "carrierTrackingEventHistory": [
          {
            "eventDateTime": "2020-04-17T08:52:00-07:00",
            "deliveryStep": "Delivered",
            "status": "Delivered",
            "statusMessage": "The package has been delivered.",
            "carrierStatusMessage": "Delivered",
            "eventCity": "BROOKFIELD",
            "eventRegion": "WI",
            "eventPostalCode": "53005",
            "eventCountry": "US",
            "shipiumLastUpdateDateTime": null
          },
          {
            "eventDateTime": "2020-04-17T05:25:00-07:00",
            "deliveryStep": "InTransit",
            "status": "OutForDelivery",
            "statusMessage": "The package is out for delivery.",
            "carrierStatusMessage": "Out for delivery",
            "eventCity": "BROOKFIELD",
            "eventRegion": "WI",
            "eventPostalCode": "53005",
            "eventCountry": "US",
            "shipiumLastUpdateDateTime": null
          },
          {
            "eventDateTime": "2020-04-17T05:14:00-07:00",
            "deliveryStep": "InTransit",
            "status": "ArrivedCarrierFacility",
            "statusMessage": "The package has arrived at a carrier facility.",
            "carrierStatusMessage": "At U.S. Postal Service facility",
            "eventCity": "BROOKFIELD",
            "eventRegion": "WI",
            "eventPostalCode": "53045",
            "eventCountry": "US",
            "shipiumLastUpdateDateTime": null
          },
          {
            "eventDateTime": "2020-04-17T03:51:00-07:00",
            "deliveryStep": "InTransit",
            "status": "InTransit",
            "statusMessage": "The package is in transit to the customer.",
            "carrierStatusMessage": "In transit",
            "eventCity": "BROOKFIELD",
            "eventRegion": "WI",
            "eventPostalCode": "53045",
            "eventCountry": "US",
            "shipiumLastUpdateDateTime": null
          },
          {
            "eventDateTime": "2020-04-17T01:42:00-07:00",
            "deliveryStep": "InfoReceived",
            "status": "InfoReceived",
            "statusMessage": "Information about this package has been received by the carrier.",
            "carrierStatusMessage": "Shipment information sent to U.S. Postal Service",
            "eventCity": null,
            "eventRegion": null,
            "eventPostalCode": "53045",
            "eventCountry": "US",
            "shipiumLastUpdateDateTime": null
          },
          {
            "eventDateTime": "2020-04-17T01:17:53-07:00",
            "deliveryStep": "InTransit",
            "status": "DepartedCarrierFacility",
            "statusMessage": "The package has left a carrier facility.",
            "carrierStatusMessage": "Departed FedEx location",
            "eventCity": "FEDEX SMARTPOST NEW BERLIN",
            "eventRegion": "WI",
            "eventPostalCode": "53151",
            "eventCountry": "US",
            "shipiumLastUpdateDateTime": null
          },
          {
            "eventDateTime": "2020-04-16T20:48:31-07:00",
            "deliveryStep": "InTransit",
            "status": "ArrivedCarrierFacility",
            "statusMessage": "The package has arrived at a carrier facility.",
            "carrierStatusMessage": "Arrived at FedEx location",
            "eventCity": "FEDEX SMARTPOST NEW BERLIN",
            "eventRegion": "WI",
            "eventPostalCode": "53151",
            "eventCountry": "US",
            "shipiumLastUpdateDateTime": null
          },
          {
            "eventDateTime": "2020-04-16T04:20:55-07:00",
            "deliveryStep": "InTransit",
            "status": "DepartedCarrierFacility",
            "statusMessage": "The package has left a carrier facility.",
            "carrierStatusMessage": "Departed FedEx location",
            "eventCity": "INDIANAPOLIS",
            "eventRegion": "IN",
            "eventPostalCode": "46241",
            "eventCountry": "US",
            "shipiumLastUpdateDateTime": null
          },
          {
            "eventDateTime": "2020-04-15T09:13:00-07:00",
            "deliveryStep": "InTransit",
            "status": "ArrivedCarrierFacility",
            "statusMessage": "The package has arrived at a carrier facility.",
            "carrierStatusMessage": "Arrived at FedEx location",
            "eventCity": "INDIANAPOLIS",
            "eventRegion": "IN",
            "eventPostalCode": "46241",
            "eventCountry": "US",
            "shipiumLastUpdateDateTime": null
          },
          {
            "eventDateTime": "2020-04-13T21:07:16-07:00",
            "deliveryStep": "InfoReceived",
            "status": "InfoReceived",
            "statusMessage": "Tracking ID for the package is unknown to the carrier.",
            "carrierStatusMessage": "Shipment information sent to FedEx",
            "eventCity": null,
            "eventRegion": null,
            "eventPostalCode": "46143",
            "eventCountry": "US",
            "shipiumLastUpdateDateTime": null
          }
        ]
      }
    }
  ]
}

Basic TrackingInfo Request (with custom transactionId)

This example contains only the most recent status and auto-generates a transactionId for the response.

curl --request POST \
  --url '<<api_url>>/api/v1/trackinginfo' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer SAMPLEBEARERTOKEN' \
  --header 'content-type: application/json' \
  --data '{"carrier": "fedex", "includeDetails":false, "trackingIds":["61299988861736643287"],"transactionId":"CUSTOM_PARTNER_TXNID"}'

Basic TrackingInfo Response (with custom transactionId)

{
  "transactionId": "CUSTOM_PARTNER_TXNID",
  "carrier": "fedex",
  "trackingInfos": [
    {
      "trackingId": "61299988861736643287",
      "carrierTrackingInfo": {
          "carrier": "fedex",
          "trackingId": "61299988861736643287",
          "shippedDateTime": "2020-04-15T09:13:00-07:00",
          "deliveredDateTime": "2020-04-17T08:52:00-07:00",
          "deliveryStep": "Delivered",
          "status": "Delivered",
          "statusMessage": "The package has been delivered.",
          "latestCarrierTrackingEvent": {
              "eventDateTime": "2020-04-17T08:52:00-07:00",
              "deliveryStep": "Delivered",
              "status": "Delivered",
              "statusMessage": "The package has been delivered.",
              "carrierStatusMessage": "Delivered",
              "eventCity": "BROOKFIELD",
              "eventRegion": "WI",
              "eventPostalCode": "53005",
              "eventCountry": "US",
              "shipiumLastUpdateDateTime": null
          },
          "carrierTrackingEventHistory": []
      }
    }
  ]
}

Full History TrackingInfo Request (with custom transactionId)

This example contains the full status history and uses a provided transactionId for the response.

curl --request POST \
  --url '<<api_url>>/api/v1/trackinginfo' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer SAMPLEBEARERTOKEN' \
  --header 'content-type: application/json' \
  --data '{"carrier": "fedex", "includeDetails":true, "trackingIds":["61299988861736643287"],"transactionId":"CUSTOM_PARTNER_TXNID"}'

Full History TrackingInfoRequest (with custom transactionId)

{
  "transactionId": "CUSTOM_PARTNER_TXNID",
  "carrier": "fedex",
  "trackingInfos": [
    {
      "trackingId": "61299988861736643287",
      "carrierTrackingInfo": {
          "carrier": "fedex",
          "trackingId": "61299988861736643287",
          "shippedDateTime": "2020-04-15T09:13:00-07:00",
          "deliveredDateTime": "2020-04-17T08:52:00-07:00",
          "deliveryStep": "Delivered",
          "status": "Delivered",
          "statusMessage": "The package has been delivered.",
          "latestCarrierTrackingEvent": {
              "eventDateTime": "2020-04-17T08:52:00-07:00",
              "deliveryStep": "Delivered",
              "status": "Delivered",
              "statusMessage": "The package has been delivered.",
              "carrierStatusMessage": "Delivered",
              "eventCity": "BROOKFIELD",
              "eventRegion": "WI",
              "eventPostalCode": "53005",
              "eventCountry": "US",
              "shipiumLastUpdateDateTime": null
          },
          "carrierTrackingEventHistory": [
          {
            "eventDateTime": "2020-04-17T08:52:00-07:00",
            "deliveryStep": "Delivered",
            "status": "Delivered",
            "statusMessage": "The package has been delivered.",
            "carrierStatusMessage": "Delivered",
            "eventCity": "BROOKFIELD",
            "eventRegion": "WI",
            "eventPostalCode": "53005",
            "eventCountry": "US",
            "shipiumLastUpdateDateTime": null
          },
          {
            "eventDateTime": "2020-04-17T05:25:00-07:00",
            "deliveryStep": "InTransit",
            "status": "OutForDelivery",
            "statusMessage": "The package is out for delivery.",
            "carrierStatusMessage": "Out for delivery",
            "eventCity": "BROOKFIELD",
            "eventRegion": "WI",
            "eventPostalCode": "53005",
            "eventCountry": "US",
            "shipiumLastUpdateDateTime": null
          },
          {
            "eventDateTime": "2020-04-17T05:14:00-07:00",
            "deliveryStep": "InTransit",
            "status": "ArrivedCarrierFacility",
            "statusMessage": "The package has arrived at a carrier facility.",
            "carrierStatusMessage": "At U.S. Postal Service facility",
            "eventCity": "BROOKFIELD",
            "eventRegion": "WI",
            "eventPostalCode": "53045",
            "eventCountry": "US",
            "shipiumLastUpdateDateTime": null
          },
          {
            "eventDateTime": "2020-04-17T03:51:00-07:00",
            "deliveryStep": "InTransit",
            "status": "InTransit",
            "statusMessage": "The package is in transit to the customer.",
            "carrierStatusMessage": "In transit",
            "eventCity": "BROOKFIELD",
            "eventRegion": "WI",
            "eventPostalCode": "53045",
            "eventCountry": "US",
            "shipiumLastUpdateDateTime": null
          },
          {
            "eventDateTime": "2020-04-17T01:42:00-07:00",
            "deliveryStep": "InfoReceived",
            "status": "InfoReceived",
            "statusMessage": "Information about this package has been received by the carrier.",
            "carrierStatusMessage": "Shipment information sent to U.S. Postal Service",
            "eventCity": null,
            "eventRegion": null,
            "eventPostalCode": "53045",
            "eventCountry": "US",
            "shipiumLastUpdateDateTime": null
          },
          {
            "eventDateTime": "2020-04-17T01:17:53-07:00",
            "deliveryStep": "InTransit",
            "status": "DepartedCarrierFacility",
            "statusMessage": "The package has left a carrier facility.",
            "carrierStatusMessage": "Departed FedEx location",
            "eventCity": "FEDEX SMARTPOST NEW BERLIN",
            "eventRegion": "WI",
            "eventPostalCode": "53151",
            "eventCountry": "US",
            "shipiumLastUpdateDateTime": null
          },
          {
            "eventDateTime": "2020-04-16T20:48:31-07:00",
            "deliveryStep": "InTransit",
            "status": "ArrivedCarrierFacility",
            "statusMessage": "The package has arrived at a carrier facility.",
            "carrierStatusMessage": "Arrived at FedEx location",
            "eventCity": "FEDEX SMARTPOST NEW BERLIN",
            "eventRegion": "WI",
            "eventPostalCode": "53151",
            "eventCountry": "US",
            "shipiumLastUpdateDateTime": null
          },
          {
            "eventDateTime": "2020-04-16T04:20:55-07:00",
            "deliveryStep": "InTransit",
            "status": "DepartedCarrierFacility",
            "statusMessage": "The package has left a carrier facility.",
            "carrierStatusMessage": "Departed FedEx location",
            "eventCity": "INDIANAPOLIS",
            "eventRegion": "IN",
            "eventPostalCode": "46241",
            "eventCountry": "US",
            "shipiumLastUpdateDateTime": null
          },
          {
            "eventDateTime": "2020-04-15T09:13:00-07:00",
            "deliveryStep": "InTransit",
            "status": "ArrivedCarrierFacility",
            "statusMessage": "The package has arrived at a carrier facility.",
            "carrierStatusMessage": "Arrived at FedEx location",
            "eventCity": "INDIANAPOLIS",
            "eventRegion": "IN",
            "eventPostalCode": "46241",
            "eventCountry": "US",
            "shipiumLastUpdateDateTime": null
          },
          {
            "eventDateTime": "2020-04-13T21:07:16-07:00",
            "deliveryStep": "InfoReceived",
            "status": "InfoReceived",
            "statusMessage": "Tracking ID for the package is unknown to the carrier.",
            "carrierStatusMessage": "Shipment information sent to FedEx",
            "eventCity": null,
            "eventRegion": null,
            "eventPostalCode": "46143",
            "eventCountry": "US",
            "shipiumLastUpdateDateTime": null
          }
        ]
      }
    }
  ]
}

Carrier Listing API Call

curl --request GET \
  --url '<<api_url>>/api/v1/carriers' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer SAMPLEBEARERTOKEN' \
  --header 'content-type: application/json'

Carrier Listing API Response

[
  "fedex",
  "usps"
]

Updated 6 months ago