PS PrestaShop PrestaShop Intermediate

Automatic DHL & Multi-Carrier Tracking — Full guide

Install, configure and run real-time DHL tracking, automatic status sync and the 19-carrier tracking page for PrestaShop 8 and 9.

Updated Module version 1.2.0

The DataFirefly Tracking module queries the DHL API in real time to track your DHL eCommerce and DHL Express parcels, automatically advances your order statuses on delivery, and gives your customers a branded tracking page covering 19 carriers. This guide covers installation, obtaining the DHL API key, configuration, the cron, the tracking page, status sync, adding carriers and troubleshooting.

Requirements

  • PrestaShop 8.0 to 9.x.
  • PHP 8.1 to 8.3 with the cURL extension enabled.
  • For DHL tracking: a key for the DHL “Shipment Tracking — Unified” API (developer.dhl.com).
  • Cron access (a server scheduled task or a cron service) for automatic tracking.

Real-time tracking applies only to DHL eCommerce and DHL Express. The other 17 carriers are shown with a tracking link to their official page and require no API key.

Installation

  1. In the back office, open Modules > Module Manager, then Upload a module and drop the datafirefly_tracking.zip file.
  2. Once installed, open the configuration page via the Configure button.

On installation, the module creates its tables, registers its hooks and automatically generates a cron token.

Getting the DHL API key

  1. Create an account on developer.dhl.com.
  2. Subscribe to the Shipment Tracking — Unified API and create an application.
  3. Copy the API key (the API Key field).

This is the tracking API key (Shipment Tracking — Unified), not the DHL eCommerce shipping key used to generate labels. The two keys are different.

Configuration

The configuration page brings together the following settings:

  • DHL Tracking API Key: paste your DHL API key here.
  • Enable polling: allows automatic updates for DHL parcels.
  • E-mails (Shipped, In transit, Delivered, Incident): notification preferences per status transition.
  • Update PrestaShop status on delivery: enables automatic order-status sync.
  • Log retention (days): how long log rows are kept before automatic purge.

Save your settings. As long as the key is not filled in and polling is not enabled, no DHL parcel is queried.

Supported carriers

The module recognises 19 carriers, split into two categories.

Real-time API tracking (2)

DHL eCommerce and DHL Express: statuses are fetched through the DHL API, normalised (created, in transit, delivered, incident) and shown on a timeline.

Colissimo, Chronopost, Shop2Shop, Mondial Relay, Relais Colis, Colis Privé, DPD, GLS, UPS, FedEx, TNT, La Poste, Poste Italiane, Correos, DHL Paket, bpost and PostNL: the tracking page shows a link to the carrier’s official page, with no API call.

Detection runs first by carrier module (external_module_name), then by carrier name. This also covers carriers configured by hand, with no external module.

Automatic tracking creation

When an order moves to the “Shipped” status, the module detects the carrier, resolves the tracking number and creates the tracking record. The number is looked up, in order, in:

  1. the order’s carrier line (order_carrier);
  2. DHL Parcel labels (where applicable);
  3. the DHL Express AWB number (where applicable).

For DHL parcels, tracking is then queried automatically; for the other carriers, a tracking link is simply associated with the order.

Cron setup

The cron drives the regular polling of DHL parcels and picks up shipments the hook may have missed (number set after the order moved to “Shipped”, carrier with no module). Schedule the following URL every 15 to 30 minutes:

curl "https://your-shop.com/module/datafirefly_tracking/cron?token=YOUR_TOKEN"

The token is generated on installation and shown in the configuration. For a one-off historical catch-up of older orders, add the days parameter:

curl "https://your-shop.com/module/datafirefly_tracking/cron?token=YOUR_TOKEN&days=60"

The backfill is capped at 180 days: beyond that, DHL purges its tracking data and the query would only return “not found” errors.

The API quota and the rate limiter

The DHL API is limited to 250 requests per day. The module ships a rate limiter that:

  • counts the day’s calls and stops polling cleanly at the cap, then resumes the next day;
  • spaces out polling by parcel status (more frequent on an incident, rarer for a merely created parcel);
  • definitively stops querying delivered parcels;
  • gives up on a number after several “not found” errors (e.g. a non-DHL number entered on a DHL carrier).

The day’s counter is visible in the configuration and on the order page.

Customer-facing tracking page

A “Track my parcel” link appears in the order detail and the customer account. The branded tracking page shows a 4-step timeline (Shipped, In transit, Out for delivery, Delivered) and the event detail.

It is accessible:

  • to logged-in customers, for their own orders;
  • to guests, via the tracking number together with the order reference.

Some carriers (PostNL) require the recipient postcode in the tracking URL: the module fills it in automatically from the order’s delivery address.

Back-office tracking

On each order page, a tracking tab shows the timeline, the latest event, the normalised status and a Refresh button to query DHL manually (within the quota). The link to the carrier’s official tracking page and to the front tracking page is also provided.

Order-status sync

When the Update PrestaShop status on delivery option is enabled, the module advances the order status for DHL parcels:

  • parcel delivered → “Delivered” status;
  • delivery incident → “Error” status.

The status change triggers PrestaShop’s native e-mails. The module prevents any downgrade: an order already delivered cannot go back to “in transit”.

Adding a carrier

Every carrier is described in a central registry (the CarrierRegistry class). Adding a carrier means adding a single entry containing:

  • its internal identifier and its label;
  • the module names (external_module_name) and the name patterns for detection;
  • its tracking URL (with the {tracking} and, if needed, {postcode} tokens);
  • the API-tracking or link flag, and the number-validation rule.

No other part of the module needs to change: detection, URL, label and dashboard all follow automatically.

Updating from an earlier version

Updating is done by replacing the module files; PrestaShop applies the migration scripts automatically. Version 1.1.0 widens the carrier-type column to accept the new carriers: this script is idempotent and preserves existing data.

No reconfiguration is needed after an update: the API key, the cron token and the existing tracking records are kept.

Troubleshooting

  • No DHL parcel is tracked: check that the API key is filled in, that polling is enabled and that the cron runs.
  • “Invalid API key” error: make sure you are using the Shipment Tracking — Unified API key, not the DHL eCommerce shipping key.
  • Quota reached: with 250 requests/day, polling stops and resumes the next day. Space out the cron or reduce the number of active parcels if needed.
  • A parcel stays not found: after several “not found” errors, the module gives up on the number (often a non-DHL number entered on a DHL carrier).
  • The order status does not change: check that the status-update option is enabled and that the parcel is indeed tracked by the DHL API.
  • Incomplete PostNL tracking link: the postcode comes from the delivery address; check that it is filled in on the order.

Uninstallation

Uninstalling removes the module’s tracking, log and quota tables along with its configuration. For a simple update, replacing the files is enough: the schema and the tracking records are preserved.

Was this page helpful?

Still stuck? Contact support