Track a shipment

Retrieve the real-time tracking data of a shipment.

When you track a shipment using the API, it is automatically saved to your Ordertracker dashboard and periodically updated in the background for free.

You are only billed 1 API credit per unique tracking number regardless of how many times you track it.

GET/v4/tracking/data

Real-time tracking data

This endpoint allows you to retrieve the real-time tracking data of a shipment.

Required attributes

Name
trackingNumber
Type
string
Description
Tracking number of the shipment you wish to track.
Example: "CA123456789US"

Optional attributes

Name
timezone
Type
string
Description
Timezone of the client to enhance the relevance of history event dates.
You can retrieve the list of supported timezones here.
Default: Europe/Paris
Name
lang
Type
string
Description
Language in which the history event descriptions will be translated.
Possible languages: en de fr pt it es tr nl pl zh-cn zh-hk ja ko ru
Default: en
Name
forceCarriers
Type
array
Description
By default, the system automatically detects the carriers handling your shipment. However, it's important to note that certain carriers might use the same tracking number for different shipments. To ensure that you retrieve the data you are looking for, you have the option to pass an array of carrier names, limiting the request to those specified carriers.
You can retrieve the list of supported carriers directly from the API.
Example: ["CANADA POST", "CHINA POST"]
Name
customerOrderNumber
Type
string
Description
To enhance tracking accuracy, you have the option to include additional data in your request, such as the order number provided to the customer during the purchase. The more data you provide, the more accurate the API response will be.
Example: "0591827364"
Name
customerPhoneNumber
Type
string
Description
To enhance tracking accuracy, you have the option to include additional data in your request, such as the customer's phone number. The more data you provide, the more accurate the API response will be.
Example: "+12015550123"
Name
customerCountryCode
Type
string ISO 3166-1 alpha-2
Description
To enhance tracking accuracy, you have the option to include additional data in your request, such as the customer's country code. The more data you provide, the more accurate the API response will be.
Example: "US"
Name
customerZipCode
Type
string
Description
To enhance tracking accuracy, you have the option to include additional data in your request, such as the customer's ZIP code. The more data you provide, the more accurate the API response will be.
Example: "75000"

Request

GET

/v4/tracking/data

curl -G https://api.ordertracker.com/v4/tracking/data \
  -d trackingNumber=CA123456789US \
  -H "X-Ordertracker-Key: YOUR_API_KEY"

Response

{
  "trackingNumber": "CA123456789US",
  "status": "transit",
  "incidents": [],
  "transit": {
    "shippingDate": "2023-07-31T06:28:00.000Z",
    "deliveryDate": null,
    "daysInTransit": 1
  },
  "forecast": {
    "estimatedDeliveryDateMin": "2023-08-16T22:36:53.333Z",
    "estimatedDeliveryDateMax": "2023-08-23T22:36:53.333Z",
    "confidenceScore": 0.7
  },
  "history": [
    {
      "time": "2023-07-30T15:56:00.000Z",
      "carrier": "CHINA POST",
      "status": "inBetweenFacilities",
      "descriptionTranslated": "Your shipment has arrived at a transit center, it is on its way.",
      "lines": [
        "Arrived at sorting facility"
      ]
    },
    {
      "time": "2023-07-30T14:53:00.000Z",
      "carrier": "CANADA POST",
      "status": "inTransit",
      "descriptionTranslated": "Your shipment is in transit with the carrier.",
      "lines": [
        "International item has left originating country and is en route to Canada",
        "China CNTAOD"
      ]
    },
    {
      "time": "2023-07-30T10:15:00.000Z",
      "carrier": "CHINA POST",
      "status": "inCustoms",
      "descriptionTranslated": "Your shipment is being cleared through customs.",
      "lines": [
        "Item Presented to Customs"
      ]
    },
    {
      "time": "2023-07-30T08:28:00.000Z",
      "carrier": "CHINA POST",
      "status": "inTransit",
      "descriptionTranslated": "Your shipment is in transit with the carrier.",
      "lines": [
        "Package Received"
      ]
    },
    {
      "time": "2023-07-30T08:28:00.000Z",
      "carrier": "CANADA POST",
      "status": "labelCreated",
      "descriptionTranslated": "The carrier has been informed and will soon collect your shipment.",
      "lines": [
        "Label created"
      ]
    }
  ],
  "carriers": [
    "CHINA POST",
    "CANADA POST"
  ]
}

The shipment model

Name
trackingNumber
Type
string
Description
Tracking number of the shipment.
Name
status
Type
string
Description
Status of the shipment delivery.
Possible statuses: unknown transit delivered
Get more information about the statuses meaning in our help center.
Name
incidents
Type
array
Description
Incidents that might have happened during the shipment delivery.
Possible incidents: exception delayed returned
Name
transit.shippingDate
Type
date
Description
Date on which the shipment was shipped.
Name
transit.deliveryDate
Type
date
Description
Date on which the shipment was delivered.
Name
transit.daysInTransit
Type
number
Description
Number of days that have passed since the shipping date until the present time or the delivery date.
Name
forecast.estimatedDeliveryDateMin
Type
date
Description
Minimum estimated delivery date.
Name
forecast.estimatedDeliveryDateMax
Type
date
Description
Maximum estimated delivery date.
Name
forecast.confidenceScore
Type
number
Description
Delivery forecast confidence score ranging between 0 and 1, with a score of 1 indicating that the forecast is directly provided by the carrier.
When the delivery forecast is not directly provided by the carrier, we leverage our data lake to automatically calculate the forecast. This dynamic calculation takes into account the tracking updates received, which can lead to adjustments in the forecast over time. As new tracking information becomes available, the delivery forecast may either extend or shorten accordingly to provide the most accurate estimation for the shipment's delivery timeline.
Get more information about the delivery forecast in our help center.
Name
history.N.time
Type
date
Description
Scan date of the tracking event.
Name
history.N.carrier
Type
string
Description
Carrier name of the tracking event.
Name
history.N.status
Type
string
Description
Status of the tracking event.
Possible event statuses: unknown labelCreated inTransit inBetweenFacilities inCustoms inDestinationDistrict outForDelivery availableForPickup delayed exception returned delivered
Get more information about the substatuses meaning in our help center.
Name
history.N.descriptionTranslated
Type
string
Description
Description of the tracking event translated according to your request parameters.
Name
history.N.lines
Type
array
Description
Original description lines retrieved from the carrier.