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) |
| Calls per run | Configurable via Tracking Calls Per Run (default: 250) |
| 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 per carton
When a shipment travels in several cartons, each carton has its own DHL shipment number and therefore its own journey. In that case the delivery status of the shipment as a whole says nothing about which goods are already with the recipient. merchantCENTRAL therefore follows such shipments carton by carton.
When does this apply?
Automatically, as soon as a shipment label has at least two packages with a tracking number of their own. A shipment in a single carton is tracked at shipment level as before — one call for one parcel, no detour.
What you see
Per carton — on the Packages FastTab of the shipment label card and in the central package list (search: Shipment Packages):
| Field | Description |
|---|---|
| Delivery Status | How far this individual carton has travelled. Delivered shows green, a problem or a return shows red |
| Delivered Date/Time | When this carton was delivered |
| Last Tracking Update | When the status was last retrieved from DHL (hidden by default) |
On the order line and the shipment line:
| Field | Description |
|---|---|
| Delivered Quantity | How many units of this line have arrived at the recipient |
| Fully Delivered On | When the last outstanding unit of this line arrived. Stays empty while any part is still in transit (hidden by default) |
The basis for this is the carton distribution captured when the labels are created — see Distribute contents. An item counts as delivered exactly when the carton it travels in is delivered. Several lines in the same carton change together; cartons still in transit leave their lines untouched.
Why a quantity and not a tick box
The delivered quantity is recalculated on every poll rather than accumulated. If a carton comes back as a return, the quantity drops accordingly. And should a line ever be split across several cartons, the same display handles it correctly without any change.
The delivery note keeps the history
The same figures are written to the lines of the posted sales shipment. Business Central deletes a sales order once it is fully shipped and invoiced — were the delivery status only on the order, it would disappear with it.
The columns are hidden at first
Delivered Quantity only appears on the order lines once there is at least one shipment label in the company. Fully Delivered On is hidden by default and can be shown via Personalise.
Status of the shipment
The overall status of the shipment label is derived from its cartons: Delivered only once every carton has arrived — as long as one is stuck, the shipment shows that carton's status. The delivery note therefore carries the same honest state.
One call per carton
A shipment of three cartons costs three calls instead of one. Cartons already delivered are no longer queried. Plan your quota accordingly — see Call quota.
Platform-wide function
Tracking per carton is a merchantCENTRAL Hub function and applies to all shipment connectors that support multi-colli — not only DHL.
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 delivery status becomes visible on the posted sales shipment (FastTab Shipment Tracking, see below) and — per carton — on the Packages FastTab of the shipment label card as well as in the package list.
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.
Normally there is nothing else to do.
No second API key needed
One key in the DHL Developer Portal covers every API approved in the same application — including the Track & Trace API. The connector therefore uses the key from the shipping credentials.
You only need the Tracking API Key (optional) field when tracking is to run through an application of its own, for instance to keep the call quotas apart.
No sandbox
The Track & Trace API exists in production only (api-eu.dhl.com). Test shipments created in sandbox mode do not exist there and therefore return no events.
Configuration Fields
| Field | Description | Default |
|---|---|---|
| Tracking Enabled | Enables/disables automatic tracking | Off |
| 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 |
| Tracking Calls Per Run | How many calls a single background run may send to DHL | 250 |
| Tracking API Base URL | Base URL of the Track & Trace API | https://api-eu.dhl.com |
| Tracking API Key (optional) | A key of its own for the Track & Trace API. Leave empty to use the key from the shipping credentials | — |
| Job Queue Status | State of the TRACKING job (Active, On Hold, Error, Not configured) | — |
The detail fields only appear once Tracking Enabled is switched on.
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.
Call quota and best practices
The quota at DHL
DHL grants the quota per application in the Developer Portal, not per connector:
| Starting quota | 250 calls per day, at most one call every five seconds. DHL explicitly calls this a development quota |
| Production | For live operation DHL provides for an increase, which you request through your application in the Developer Portal |
| DHL's rule of thumb | Daily shipment volume ÷ 30 × 3 transit days × 10 queries per shipment and day |
| Batch queries | Not possible — the DHL API answers one shipment number per request |
Request it before going live
The starting quota is enough for testing, not for day-to-day shipping. At 30 orders a day with three cartons each, the requirement is already in the order of 2,500 to 3,000 calls per day. Request the increase before you go into production.
The limit in the connector
Tracking Calls Per Run caps how many calls a single background run sends out. The preset of 250 matches DHL's starting quota.
- Once the limit is reached the run stops; the remaining shipments follow in the next run. The oldest shipments come first.
- Raise the value once DHL has increased your quota — otherwise this setting, not the quota, keeps deciding how many shipments a run gets through.
- What is counted is calls, not shipments: a shipment in three cartons costs three calls.
Interval and age
| Aspect | Recommendation |
|---|---|
| Recommended Interval | 4 hours (= 6 runs/day) |
| High Volume | Increase the interval to 6–8 hours instead of hitting the call limit again and again |
| Max Age | Reduce to 14 days if many shipments are active at the same time |
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 quota considerably faster.
Frequently Asked Questions
Why don't I see any tracking events?
- Tracking not enabled: Check Tracking Enabled in the DHL Setup.
- Sandbox shipment: There is no sandbox for the Track & Trace API. Shipments created in sandbox mode do not exist there.
- Track & Trace not approved: In the DHL Developer Portal, check that your application includes the Shipment Tracking (Unified) API alongside the Shipping API.
- 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").
Why is there no delivered quantity on an order line?
- The column is missing: Delivered Quantity only appears once there is at least one shipment label in the company. Fully Delivered On is hidden by default — show it via Personalise.
- No carton content captured: The quantity is derived from the item → carton assignment. If no content was distributed when the labels were created, there is nothing a delivery status could refer to.
- Carton still in transit: Its content only counts once the carton reaches Delivered. The Packages FastTab on the shipment label card shows which carton is still outstanding.
- Line does not ship via DHL: Items travelling by freight forwarder or another route are in no DHL carton and therefore have no delivery status.
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.