
Shopify DHL tracking can mean three different things: getting a tracking number onto an order, getting the customer a working link, and getting live delivery status back into Shopify. This guide is for store owners who ship with DHL and the developers or agencies who automate it. It covers the simple route, the app route, and how a custom build would use DHL’s tracking API and write events back to Shopify.
The three levels of DHL tracking
| Level | What the customer gets | Effort |
|---|---|---|
| 1. Tracking number on the fulfillment | A number and a link in the shipping email | Low, can be manual |
| 2. Automatic number from labels | The same, without anyone typing | Needs a label or carrier app |
| 3. Live status in Shopify | Order timeline moves to in transit, out for delivery, delivered | Needs an app or custom integration |
Most stores need level 1 or 2. Level 3 is where automation earns its keep, because it reduces “where is my parcel” messages, but it also adds moving parts that need maintenance.
Level 1: add DHL tracking in Shopify
When you fulfil an order you enter the carrier and the tracking number. Shopify documents that if the carrier name matches its supported list exactly (capitalisation counts), it builds the tracking link automatically. For anything else, send the URL yourself. The details are in the FulfillmentTrackingInput reference, which also notes that relying on number-format detection can produce wrong links, so it recommends sending both company and URL.
Two practical points for DHL specifically. DHL runs several different businesses (Express, Parcel, eCommerce and others), and a tracking number belongs to one of them. Pick the carrier name that matches what you actually used. And enter the notify-customer option on purpose; if your tracking number does not appear, our guide to Shopify tracking numbers not showing walks through the usual causes.
Level 2: apps that create DHL labels
Several Shopify apps connect to DHL accounts, create labels and write the tracking number back to the order. We are not going to rank them, because features and pricing change, and plenty of vendor pages are sales material with no stated limits. When you evaluate one, ask:
- Which DHL businesses and countries does it support (Express, Parcel, eCommerce)?
- Does it write the carrier name and URL, or only the number?
- Does it update status after fulfilment, or only create the label?
- What does it cost per label or per month, and who owns the DHL account?
- What happens when a label is voided or a parcel is split into several boxes?
Shopify’s own help centre also covers carrier setup. Read the current listing and reviews before installing, and test with a real shipment.
Level 3: live status with the DHL tracking API
If you want status updates without relying on an app, DHL offers a public tracking API through its developer portal. These facts come from the DHL Shipment Tracking API reference:
- You pass an API key in the
DHL-API-Keyheader. The key comes from an app you create in the portal; a demo key returns mocked data only. - The endpoint is
GET https://api-eu.dhl.com/track/shipments, and GET is the only method allowed. - Parameters include
trackingNumber, plus optionalservice(to point at the right DHL business, for exampleexpress),originCountryCode,requesterCountryCode,recipientPostalCodeandlanguage. - Services named in the documentation include
express,parcel-de,parcel-uk,ecommerceandsameday, among others. Check the page for the current list. - The response can include status, milestone timestamps, travel history, estimated delivery time and proof of delivery. Availability depends on the service and product.
- Errors come back as problem-details JSON. Exceeding your limit returns HTTP 429.
Rate limits, as documented
The documentation says initial access is 250 calls per day, and it describes that as a starting level for development, not production use. DHL’s page on getting a higher rate limit says new apps get default daily and per-second limits, and that you can request an upgrade from your app’s page; the extra allowance varies by API and is generally scaled to your shipping volume. The per-second figure is not shown in the app details view, so confirm it when you register.
Do the maths before you build. A store with 400 open parcels cannot poll each one every hour on 250 calls a day. That is why a serious build needs a higher limit, sensible polling (only active shipments, longer gaps for slow services) and caching.
DHL status codes differ by service. The documentation notes, for example, different status code styles for Parcel Germany and eCommerce. Build your mapping from the live responses for the services you use, not from a generic table, and watch the DHL changelog for format changes.
Mapping DHL events to Shopify
Shopify lets an app record shipment events on a fulfillment using the fulfillmentEventCreate mutation. It requires the write_fulfillments access scope and the fulfill_and_ship_orders permission, and takes a fulfillment ID, a status, timestamps, an optional message and location fields. The FulfillmentEventStatus enum has these values: LABEL_PURCHASED, LABEL_PRINTED, READY_FOR_PICKUP, CONFIRMED, CARRIER_PICKED_UP, IN_TRANSIT, OUT_FOR_DELIVERY, ATTEMPTED_DELIVERY, DELAYED, DELIVERED and FAILURE.
A sensible mapping, which you should confirm against DHL’s real responses for your services:
| What DHL reports (in plain words) | Shopify event status |
|---|---|
| Shipment information received / label created | LABEL_PURCHASED or CONFIRMED |
| Parcel collected from sender | CARRIER_PICKED_UP |
| Moving between hubs | IN_TRANSIT |
| With the courier for delivery | OUT_FOR_DELIVERY |
| Delivery tried, nobody home | ATTEMPTED_DELIVERY |
| Delay notice | DELAYED |
| Waiting at a service point | READY_FOR_PICKUP |
| Delivered | DELIVERED |
| Returned, damaged or failed | FAILURE |
Keep DHL’s original wording in the event message so staff see what the courier said.
An architecture that works
- A webhook such as
fulfillments/createtells your system a new DHL fulfillment exists. Shopify’s webhook documentation lists the fulfillment topics, and says each delivery carries an HMAC header you must verify and a unique webhook ID you should use to deduplicate. - Your service stores the fulfillment ID, tracking number and the DHL
servicevalue. - A scheduled job polls DHL for active shipments within the rate limit. Stop polling once delivered or failed.
- For each new event, create a fulfillment event in Shopify, once. Store the last event time to avoid duplicates.
- Notify the customer through your normal channel, such as Shopify notifications, email or WhatsApp.
- Log failures, alert on a drop in events, and retry after throttling. Shopify’s API uses a leaky bucket model: when the bucket fills you get a throttle error and need to back off.
Our general guide to automating order status updates covers the pattern for any courier, and Shopify Flow examples shows what you can do without code.
When this is not worth building
If you ship a few dozen parcels a week, a label app plus DHL’s own tracking page is enough. A custom integration makes sense with high volume, several DHL services, special rules (returns, service points, customs), or a need to combine several couriers into one customer experience. Compare against the cost of support messages and delivery disputes in your own store.
Frequently Asked Questions
Does Shopify support DHL tracking out of the box?
You can add a DHL number and carrier to any fulfillment, and Shopify builds links for carriers on its supported list. Live status updating depends on the carrier being on Shopify’s update list or on an app or integration adding events.
Is DHL’s tracking API free?
DHL’s portal gives developers access with an API key, and documents default limits. Pricing and upgrade terms for higher limits are decided with DHL, so check the portal.
What is the DHL tracking API rate limit?
The documentation states initial access of 250 calls per day, intended for development, with upgrades available on request. Exceeding the limit returns HTTP 429.
Can I write DHL status into the Shopify order timeline?
Yes, with the fulfillmentEventCreate mutation, which accepts statuses such as IN_TRANSIT and DELIVERED.
Why is my DHL link going to the wrong page?
Often the company name does not match Shopify’s list, or no URL was sent, so Shopify guessed from the number’s format. Send both.
Conclusion
For Shopify DHL tracking, start by getting the number, carrier and link right on every fulfillment. Add a label app if typing is the bottleneck, and consider a custom integration only when status updates justify the build and the rate limits are sorted. If you would like help with this, CYPHEX can plan and deliver it for you, with one project lead as your contact. See our courier tracking automation service and API integration development.
Stock photography provided by Pexels under the Pexels License.
