DHL Parcel Poland Integration

The DHL module connects WooCommerce to the DHL Parcel Poland REST API for shipment tracking. You enter the tracking number on the order, and the module fetches the current status and event history from DHL.

Requirements

Polski PRO requires: Polski (free) v1.6.0+, WordPress 6.4+, WooCommerce 8.0+, PHP 8.1+. A DHL API key and DHL account number are also required for live tracking lookups.

Configuration

The DHL settings belong to the shipping group of the PRO settings (the polski_pro_shipping option). They are read and written through the PRO settings REST route, /wp-json/polski-pro/v1/settings, which requires the manage_woocommerce capability. A dedicated shipping settings screen is planned but has not shipped yet.

API authentication

Setting	Key	Description
DHL enabled	dhl_enabled	Switches the DHL provider on
DHL API key	dhl_api_key	Bearer token from the DHL WebAPI portal
DHL account number	dhl_account_number	DHL Parcel Poland customer account number

You can obtain the API key by registering at developer.dhl.com and creating an application with access to the DHL Parcel Poland API.

Enabling the module

1. Send dhl_enabled as true in the shipping group of a PUT to /wp-json/polski-pro/v1/settings
2. Send dhl_api_key and dhl_account_number in the same request, because the payload replaces the whole option
3. The tracking box on the order belongs to the Fulfillment module, so that module has to be enabled in Polski > Modules

DHL is only queried when dhl_enabled is on and both fields are filled in. With any of the three missing, the order still keeps the tracking number and the tracking link, but no live status is fetched.

Recording a tracking number

Labels are created in your own DHL tools. Once you have the number, save it on the order:

1. Open an order in WooCommerce > Orders
2. In the Shipment Tracking section, select the DHL carrier
3. Paste the number into Tracking number
4. Leave Tracking URL empty to have it built for you, or paste your own link
5. Update the order

The DHL tracking link is generated in the following format:

https://www.dhl.com/pl-pl/home/sledzenie-przesylek.html?tracking-id={number}

Refresh live tracking

When an order has a tracking number, the Shipment Tracking section shows a Live preview with a Refresh live tracking button. It calls the DHL tracking API with your Bearer token and displays the current status plus the event list (description, date, location).

A lookup is cached for 10 minutes. The button clears the cache for that shipment and fetches the data again, so use it when you expect a fresh scan.

Where tracking appears

• Tracking column in the orders list: carrier, number, live status and a Track link
• Order details in the customer account, plus a Track shipment action next to the order
• WooCommerce order emails, with the tracking block appended after the order table
• Status emails for Packed, Shipped and Delivered, containing the carrier, the tracking number and the tracking link

The three statuses are also available as bulk actions in the orders list: Change status to Packed, Shipped and Delivered.

Labels and ServicePoint search

Label generation and ServicePoint search are written but not connected. DHLProvider holds a label call and a pickup point lookup, but nothing in wp-admin or the checkout reaches them, so there is no Generate label button, no label PDF and no pickup point lookup on screen, and parcels have to be created in DHL’s own tools for now.

Troubleshooting

Symptom	Cause	Solution
Live preview shows no status	Module off, or API key / account number empty	Save dhl_enabled, the API key and the account number through the settings route
Refresh returns nothing	Invalid Bearer token (HTTP 401) or unknown tracking number	Check the token in the settings and the number on the order
Status looks stale	The 10 minute lookup cache	Click Refresh live tracking
Repeated empty responses	DHL request limit (HTTP 429)	Wait a moment and refresh again

Filters and actions

The DHL module ships no public filters yet. Tracking data lives in order meta, so you can set it from your own code:

// Save a DHL tracking number on an order.
$order = wc_get_order($orderId);
$order->update_meta_data('_polski_shipping_carrier', 'dhl');
$order->update_meta_data('_polski_tracking_number', '6230000123456789');
$order->save();

Leave _polski_tracking_url unset and the DHL link is derived from the number when tracking is displayed.