Multi-Carrier Order Tracking Page — Complete Guide (dftracking)

dftracking adds a branded order tracking page to your PrestaShop store. The module queries carrier APIs directly (Colissimo, Mondial Relay, Chronopost, DHL), normalizes their heterogeneous statuses into a common vocabulary and renders them on a four-step timeline, together with the detailed event history of each package.

Installation

1. In your PrestaShop back office, open Modules > Module Manager.
2. Click Upload a module and drop the dftracking.zip file.
3. Click Configure once the installation is complete.

On installation, the module creates the cache table ps_dftracking_shipment, generates a random cron token and registers four hooks: moduleRoutes (friendly URL /order-tracking), displayOrderDetail (“Track my package” button on the order detail), displayCustomerAccount (link in the customer account) and actionFrontControllerSetMedia (page stylesheet).

Carrier API credentials

Each carrier has its own authentication scheme. Only fill in the ones you actually use: an unconfigured carrier is simply never queried, and the module falls back to the public tracking link.

Colissimo / La Poste

The connector uses the Suivi v2 API on the Okapi platform. Create a free account on developer.laposte.fr, subscribe to the “Suivi” API and paste the Okapi key into the Colissimo / La Poste — Okapi API key field.

Mondial Relay

The connector uses the WSI2_TracingColisDetaille service. Enter your Enseigne code (usually 8 characters, e.g. BDTEST13 in the test environment) and your private key, both provided in your Mondial Relay contract or from Connect Hub. The module computes the MD5 signature expected by the service automatically.

Chronopost

No credentials are required: the connector relies on the public TrackingServiceWS endpoint, which accepts tracking numbers without authentication. The account and password fields exist for specific setups but remain optional.

DHL

The connector uses the Shipment Tracking – Unified API. Create an account on developer.dhl.com, subscribe to that API and paste the key into the DHL — API key field. Mind the free plan quotas: the module’s cache and cron are designed precisely to preserve them.

Carrier mapping

The Carrier mapping section lists every carrier in your store and lets you assign a connector to each. Two mechanisms work together:

• Explicit mapping — you pick the connector from the dropdown. This is the recommended approach, especially if your carriers use custom commercial names (“24h Express Delivery”, “Pickup point collection”…).
• Auto-detection — for carriers left on “Not tracked”, the module looks for keywords in the carrier name (colissimo, la poste, mondial relay, point relais, chronopost, dhl…) and applies the matching connector.

Tracking page branding

The Branding & display section controls the front page appearance:

• Primary color — headings, current timeline step, carrier links. Defaults to #2c3e50.
• Accent color — completed steps and the “Delivered” status. Defaults to #27ae60.
• Custom headline — replaces the default “Track your order” title at the top of the page.
• Show order products — adds the list of items with thumbnails and quantities below the timeline.
• Cache TTL (minutes) — see the next section.

Colors are injected as CSS variables on the page container: the rest of the layout naturally inherits from your theme.

Cache and refresh

Each tracked package occupies one row in the ps_dftracking_shipment table, which stores the normalized status, the events as JSON, the carrier tracking URL and the last update timestamp.

Two mechanisms keep this data fresh:

1. The cron task — the primary mechanism. It selects non-final packages whose data has exceeded the cache TTL, refreshes them in batches, and registers new shipments from orders placed in the last 60 days along the way.
2. Refresh on page view — the safety net. If a customer opens their tracking page while the data is stale, the API is queried immediately.

In both cases, a package whose status is Delivered or Returned to sender is never queried again: those states are considered final.

Setting up the cron

The cron URL, token included, is displayed at the top of the module configuration page. Schedule it every 30 to 60 minutes:

*/30 * * * * curl -s "https://yourstore.com/index.php?fc=module&module=dftracking&controller=cron&token=YOUR_TOKEN" > /dev/null

The optional &limit=100 parameter caps the number of API calls per run (50 by default, 200 maximum). The endpoint replies in JSON: {"ok":true,"refreshed":12,"errors":0,"time":"…"}.

The tracking page for customers

The page is available at /order-tracking (URL editable in Shop Parameters > Traffic & SEO after installation).

• Logged-in customer — the “Track my package” button appears on every order detail, and an “Order tracking” link is added to the customer account. The module always verifies that the order belongs to the logged-in customer.
• Guest — a form asks for the order reference and the email address. Both must match for the order to be displayed; on failure, the error message stays deliberately generic and never reveals whether the reference exists.

The global timeline reflects the most advanced package of the order. Below it, each shipment gets its own card: carrier name, tracking number, colored status pill, detailed event history (date, label, location) and a link to the carrier’s official tracking page.

Normalized statuses

Carrier-specific labels are converted into seven common statuses, allowing a consistent display whatever the package:

• Awaiting carrier pickup — label created, package not scanned yet.
• In transit — the package is moving through the network.
• Out for delivery — final leg, today’s round.
• Available at pickup point — package waiting at a relay or office.
• Delivered — final status.
• Delivery incident — anomaly reported by the carrier.
• Returned to sender — final status.

Multi-package orders

The module reads the order_carrier table: every tracking number attached to the order is handled as an independent shipment, with its own connector, status and history. For older stores where the tracking number is only stored on the order itself (shipping_number), a fallback mechanism ensures compatibility.

Adding a carrier

The architecture is deliberately open. To integrate an additional carrier:

1. Create a class in src/Adapter/ extending DftrackingAbstractCarrierAdapter.
2. Implement getCode(), getLabel(), isConfigured(), getPublicUrl(), getNameKeywords() and fetch(). The latter returns a status / events / tracking_url array, reusing the httpRequest(), event() and result() helpers from the abstract class.
3. Add the class to the DftrackingAdapterRegistry::all() array and the matching require_once in dftracking.php.

The new connector automatically appears in the back-office mapping dropdowns.

Troubleshooting

• The page shows “Your order has not been shipped yet” — no tracking number is set on the order. Add it from the order page in the back office, Shipping tab.
• The status does not update — first check that the cron task runs by calling its URL manually in a browser: the JSON response reports the number of packages refreshed and errors. Then check Advanced Parameters > Logs: API call failures are recorded there with the message returned by the carrier.
• “tracking number not found” error — normal in the hours following label creation: the carrier has not registered the package yet. The module will retry on the next cycle.
• A carrier is not recognized — auto-detection found no keyword in its name. Map it explicitly in the Carrier mapping section.
• The guest form cannot find the order — the reference and email must match the order exactly. Watch out for orders placed with an email address different from the customer account one.
• The page does not use my colors — clear the PrestaShop cache (Advanced Parameters > Performance) after changing them, as the stylesheet is cached by the theme.

Uninstalling

Uninstalling drops the ps_dftracking_shipment table and all configuration keys, including your API credentials. Back those up if you plan to reinstall the module.