Skip to main content

📦 Trackers

Introduction to Tracker​

In order to have Ship24 track your shipments, you need to create a Tracker for each shipment on which you wish to receive tracking results. A Tracker is basically an instruction for Ship24 to track a shipment and is composed of a tracking number and a few shipment-related information such as courier information, origin country, destination country, etc.

Did you know?

Tracking numbers are not unique, you could have a shipment handled by FedEx in the US shipped in March and a shipment handled by GLS in Europe in March as well, with both of which sharing the same tracking number.

That's why we recommend providing as much information as possible on top of the tracking number when creating a Tracker. Based on that, a unique trackerId is systematically generated by Ship24 for each Tracker created and shared in the API response. We recommend storing and using Ship24's trackerId on top of the tracking number to identify and match information to a specific shipment. This Ship24's trackerId is also present in our webhook messages.

Alternatively, you can provide a unique clientTrackerId when creating a Tracker. The clientTrackerId is a field that allows you to assign a fully unique identifier to your shipments. It is validated for uniqueness on our side to ensure that each shipment is uniquely identifiable within our system. This makes it a reliable way to track and manage shipments, as you can use it as an identifier for the shipment in most of our endpoints (using the searchBy param). Please note that its uniqueness is validated across subscribed trackers only, which means if you unsubscribe to a tracker (PATCH with isSubscribed at false), you will be allowed to re-create a new tracker with the same clientTrackerId.

The shipmentReference is another optional field that you may use for your internal reference purposes. Unlike the clientTrackerId, the shipmentReference is not validated for uniqueness. Therefore, it is not recommended to use this field as a unique identifier unless you can guarantee its uniqueness on your side.

Both the clientTrackerId and shipmentReference will be included in our API response and webhook messages. While the clientTrackerId provides a validated unique identifier, the shipmentReference is meant for possibly non-unique identifier or reference. We recommend carefully choosing the field that best suits your operational needs.

Trackings endpoints overview​

A Tracker can be created using one of the following endpoints:

Create a new tracker, which means you are asking Ship24 to start tracking this shipment based on its tracking number and other information if provided.

Create new trackers, which means you are asking Ship24 to start tracking those shipments based on their tracking numbers and other information if provided.

Create a new tracker and get tracking results synchronously. As tracking results are fetched synchronously from couriers, the initial response time of the API may be up to one minute.

Once created, a Tracker will track the corresponding shipment by automatically and continuously gathering the tracking results from the different couriers and sources of data.

Tracker can be viewed and modified using the following endpoints:

Update an existing tracker by id. Data related to the shipment (i.e. destination country, shipping date) can't be modified if the Tracker already gathered shipment tracking information. Updating a Tracker is recommended in case you wish to provide additional courierCode afterward, however, it's best to provide all recommended information at the creation of a Tracker.

Get an existing tracker by id. Please note that this endpoint will only return the Tracker information and not the tracking result. See Get tracker results by id or Get tracker results by tracking number to get the tracking result.

Get the list of existing trackers, using page-based pagination.

Tracking results from a Tracker can be retrieved in different ways:

1- Automatically receive webhook notifications for new tracking results. See webhooks.

This is the most efficient way to receive tracking results as you don't need to call our system at regular intervals, and you get informed as soon as we discover new events.

2- Fetch instantly the latest tracking results from our system using one of the following endpoints:

If you store Ship24's trackerId in your system, this is the best way to fetch tracking results from an existing Tracker.

If you don't wish to store Ship24's trackerId in your system, you can use this endpoint to search a Tracker by tracking number. However, if you create two different Tracker for two different shipments going to two different destination countries with different couriers, that have the same tracking number, you will get an array of Tracker as a response. As tracking numbers are not unique, we always recommend using Get results for an existing tracker with Ship24's trackerId instead.

As this endpoint is idempotent, it can be used initially to create the Tracker and get tracking results, and later on to get subsequent results by calling it again. This is the simplest way if you wish to have just one unified endpoint that can be called again and again to get tracking results. However, make sure the payload sent is always the same, as a new Tracker will be created if any information in the payload changes, and keep in mind that the initial call will be long, as explained in the endpoint definition.