Shipment Tracking
The DHL Parcel DE Connector provides fully automatic shipment tracking via the DHL Track & Trace API v2. Once a shipping label has been created, you can follow the current delivery status directly in Business Central — without needing to visit the DHL portal.
Opening the Page
Tracking events for a shipment are displayed as a timeline on the Shipment Label Card:
- Open the Shipment Labels list (via the DHL Dashboard or the Shipping page).
- Click on a label with a tracking number.
- In the lower section of the card, you will see the Tracking Timeline.
How It Works
Automatic Status Polling (Job Queue)
Shipment tracking works as a recurring background task:
| Property | Description |
|---|---|
| Job Queue Entry | ALN MCDHL Job Queue Handler with parameter TRACKING |
| Interval | Configurable (default: every 4 hours) |
| Rate Limit | Maximum 250 API calls per day (DHL requirement) |
| Maximum Age | Shipments older than X days are no longer tracked (default: 30 days) |
Automatic Setup
When you enable tracking in the DHL Setup, the Job Queue Entry is automatically created. You can adjust the polling interval in the setup.
Which Shipments Are Tracked?
Not all shipments are queried. Automatic tracking applies only to:
- Shipments with provider DHL Parcel DE
- Status: Created or Manifested (i.e., not cancelled or already delivered)
- Delivery status: not already "Delivered" or "Returned"
- With tracking number (shipments without a number are skipped)
- Younger than the configured maximum age
Deduplication
Already known events are not stored again. On each API call, only new events are added, ensuring the timeline remains accurate and duplicate-free.
Tracking Timeline
The timeline shows all DHL events in chronological order (newest first) with color coding:
| Color | Event Code | Meaning |
|---|---|---|
| 🟢 Green | delivery |
Shipment delivered |
| 🔴 Red | failure |
Delivery attempt failed / problem |
| ⚪ Default | transit |
Shipment in transit |
| ⚪ Default | pre-transit |
Shipment announced / in system |
| ⚪ Default | customs |
Customs processing |
| ⚪ Default | notification |
Notification sent |
| ⚪ Default | pickup |
Shipment picked up |
| ⚪ Default | other |
Other status change |
Information Displayed per Event
| Field | Description |
|---|---|
| Date/Time | Timestamp of the event |
| Event Code | Category (transit, delivery, failure, ...) |
| Status Text | DHL short description (e.g., "Shipment delivered") |
| Description | Detailed description of the event |
| Location | Location of the event (e.g., "DHL Delivery Base Frankfurt") |
| Country | Country code (e.g., "DE") |
| Signed By | Name of recipient for personal delivery |
Status Mapping
DHL events are automatically mapped to the hub delivery status:
| DHL Event Code | Hub Delivery Status | Description |
|---|---|---|
delivery |
Delivered | Shipment successfully delivered |
pickup |
Picked Up | Shipment picked up |
failure |
Exception | Delivery problem |
transit |
In Transit | Shipment in transit |
pre-transit |
In Transit | Shipment announced in system |
customs |
In Transit | Shipment at customs |
notification |
(unchanged) | Notification only, no status change |
other |
(unchanged) | No automatic status change |
The hub delivery status is visible on the Shipment Label List and the Shipment Label Card.
Write-Back to the Posted Sales Shipment
Each tracking update also writes the current shipment status directly back to the posted sales shipment that the label belongs to. This lets the clerk see the delivery status right on the posted shipment — without having to open the shipping label.
The information appears on a new FastTab Delivery Tracking on the "Posted Sales Shipment" card:
| Field | Description |
|---|---|
| Delivery Status | The mapped hub delivery status (e.g., In Transit, Delivered, Exception) |
| Tracking Number | The carrier's tracking/shipment number |
| Tracking URL | Direct link to the carrier's shipment tracking |
| Last Updated | Timestamp of the last tracking poll |
| Delivery Date | Date of successful delivery (once reported) |
The write-back happens automatically on every polling cycle.
Platform-Wide Feature
The status write-back to the posted sales shipment is a feature of the merchantCENTRAL hub and applies platform-wide to all shipment connectors (DHL, DHL Express, DPD, GLS, UPS, Hermes, Rhenus) — not just DHL.
Estimated Delivery Date
When DHL provides an estimated delivery date (estimatedTimeOfDelivery) in the API response, it is automatically stored on the Shipment Label and displayed. This helps with planning and customer inquiries.
Setup
Enabling Tracking
- Open the DHL Setup (Setup Card) or the DHL Dashboard.
- Navigate to the Tracking group.
- Enable Tracking Enabled.
- Enter the Tracking API Key (via the drill-down dialog).
Separate API Key
The DHL Track & Trace API v2 uses its own API key, which is different from the Shipping API key. You can obtain this key from the DHL Developer Portal under the app "DHL Tracking (Unified)".
Configuration Fields
| Field | Description | Default |
|---|---|---|
| Tracking Enabled | Enables/disables automatic tracking | Off |
| Tracking API Key | API key for the Track & Trace API (separate key!) | — |
| Tracking Poll Interval (Min.) | Polling interval in minutes | 240 (4 hours) |
| Tracking Max Age Days | Shipments older than X days are no longer tracked | 30 |
Managing the Job Queue
After activation, a Job Queue Entry is automatically created:
- Object: Codeunit
ALN MCDHL Job Queue Handler - Parameter:
TRACKING - Recurrence: Every X minutes (as configured)
You can manage the Job Queue Entry via the standard BC page "Job Queue Entries" — e.g., pause, manually run, or adjust the interval.
Rate Limit and Best Practices
| Aspect | Recommendation |
|---|---|
| Rate Limit | 250 calls/day — one call per shipment per polling cycle |
| Recommended Interval | 4 hours (= 6 cycles/day) — with 40 active shipments = 240 calls/day |
| High Volume | With >200 active shipments, increase interval to 6–8 hours |
| Max Age | Reduce to 14 days if many shipments are active |
Practical Tip
For most businesses, a 4-hour interval is perfectly sufficient. DHL shipments within Germany are typically delivered within 1–2 business days. A shorter interval (e.g., 1 hour) rarely provides an information advantage but consumes the daily rate limit faster.
Frequently Asked Questions
Why don't I see any tracking events?
- Tracking not enabled: Check "Tracking Enabled" in the DHL Setup.
- No Tracking API Key: The Tracking key is a separate key — not identical to the Shipping API Key.
- Shipment too new: DHL typically needs 30–60 minutes after label creation before the first events appear.
- Shipment too old: Shipments older than "Max Age Days" are no longer queried.
- Job Queue paused: Check the status of the TRACKING Job Queue Entry.
Why does the status still show "In Transit" even though the shipment was delivered?
The status updates at the next polling cycle. If you want to see the status immediately, you can manually run the Job Queue Entry (page "Job Queue Entries" → Select → Action "Run").
What happens with API errors?
If the DHL API is temporarily unavailable, the shipment will be queried again at the next polling cycle. Persistent errors (e.g., invalid API key) are shown on the Setup Card as the last error message.