With proactive tracking notification, users of the DHL Shipment Tracking API can now receive push notifications on the status of their shipments, including delivery time and routing updates etc.

You can subscribe for updates in two ways

• based on TrackingID*
• based on Customer AccountID*

*see supported subscription scenarios

Advantages of Push Notifications

Push updates provide close to real time status updates ad continuously keeps consumers up-to-date. No need for actively requesting the latest shipment update in order to have the latest status. 

Improved Customer Experience

Push updates provide a versatile and straightforward solution, easily integrated into the customer's workflow with minimal setup required. The result is real-time notifications delivered at reduced costs.

Supported Products

• eCommerce
  • Europe:  Cross-border products (Parcel Connect, Return Connect, Parcel International, Connect PLUS, Return International) 
  • Parcel UK: Parcel Connect, Return Connect, Worldwide Air, Parcel International, International Road Economy  
  • Parcel NL, domestic shipments
  • PPL, domestic (CZ)  shipments
  • US: Domestic Ground, Expedited, Expedited Max, Parcel International, Packet International
     
• P&P (Post und Paket)
  • Brief
    • Einschreiben National, Einschreiben, Einschreiben Rückschein, Einschreiben Eigenhändig, Einschreiben Einwurf, Wert, Prio, Nachname, Einschreiben International, Einschreiben Rückschein International, Einschreiben Eigenhändig International, Wert National, Warenpost Tracked International, Ländernachweis, Postzustellungsauftäge (PZA)
       
• Global Forwarding 
  • SameDay: SameDay Jetline Unaccompanied shipment, SameDay Jetline accompanied shipment, Same Day Speedline, SameDay Sprintline 
  • eCommerce shipments
     
• DHL Freight
  • EuroConnect, Eurapid, EuroLine, EuroNet, Customs Services, Coldchain,Trade Fairs & Events, Standard Pallet Domestic, Premium Pallet Domestic, Lead Logistics Provider, Transport Related Warehousing, RailConnect, RailLine, Parcel, Home Delivery

Coming soon - not yet supported

• P&P, Paket, Post International (DPI), Internetmarke
• Global Forwarding, Airfreight, Ocean Freight
• Express

Notifications will have the same format as the traditional request & response UTAPI documented at: https://developer.dhl.com/api-reference/shipment-tracking

Retry mechanism

To ensure you do not loose any notifications in the case your system is not available this push API comes with a retry mechanism.

To successfully consume our notification, the receiving system must:

• use a valid SSL certificate and
• reply to the event POST request with a HTTP 200 response within 5 seconds.

If either of these requirements is not met, the system will retry delivery in 1 hour. If the second delivery fails, the system will retry delivery 6 hours after the second delivery attempt. If the third delivery fails, the system will not try to send the event again and the technical contact associated with the account will be notified of the deactivation via email. If event delivery fails 10,000 times consecutively for a specific webhook, that webhook will be automatically deactivated, and the technical contact associated with the corresponding pickup customer account will be notified of the deactivation via email.

Supported Subscription scenarios

Get Access

Access is free of charge for all customers. If you are a third party please contact our support team. 

You are required to request credentials for any and all applications you develop as described below.

To register your app and get your API subscription keys:

1. Click My Apps on the portal website.
2. Click the + Add App button.
   The “Add App” form appears.
3. Complete the Add App form. 
   You can select the APIs you want to access.
4. When you have completed the form, click the Add App button.

Authentication

Every call to the API requires a subscription key. This key needs to be passed through a request header (DHL-API-Key).

To view your API subscription keys:

1. From the My Apps screen, click on the name of your app.
   The Details screen appears. 
2. If you have access to more than one API, click the name of the relevant API. 
   Note: The APIs are listed under the “Credentials” section. 
3. Click the Show link below the asterisks that is hiding the Consumer Key. 
   The Consumer Key appears.

Environments

The addressable API base URL/URI environments are:  

Setup process

How to create and activate subscription please refer to the Reference Docs.

Two types of subscription are supported - 

• by Shipment (immediate activation)
• by Account,  (Business approval is required to fully activate account subscription)

1) Create subscription notification

Once a subscription has been created your webhook will receive a confirmation about the subscription creation. This confirmation will  contain a "secret"  in the header and the same value is also listed as a secret in the body. This "secret" is needed to confirm you are owner of the webhook and to active the subscription

Example:

{
  "self": "https://api-eu.dhl.com/tracking/push/v1/subscription/94d0131a-66b1-450d-82ac-4566b29c3dc1",
  "scope": "subscription.validate",
  "expires": "2022-11-08T15:27:09.021945677Z",
  "secret": "rZxQ2L1FDlbuaQObrAhtgq",
  "note": "Subscription validation token provided."
}

2) Activate subscription notification

Once the subscription has been activated the webhook will receive a confirmation about the subscription activation. Upon activation the subscription is ready to provide tracking updates.

Example:

{
  "self": "https://api-test.dhl.com/tracking/push/v1/subscription/94d0131a-66b1-450d-82ac-4566b29c3dc1",
  "scope": "subscription.ready",
  "expires": "2023-05-02T15:32:15.33751504Z",
  "note": "Subscription ready for notifications."
}

3) Receive Shipment notifications

The webhook will receive notifications about status and e.g. delivery time of a shipment. For shipments data schema, please refer to the "specification of a consumer web-hook endpoint" file in the download section

Example:

{
    "self": "https://api-eu.dhl.com/push/subscription/94d0131a-66b1-450d-82ac-4566b29c3dc1",
    "scope": "subscription.push",
    "expires": "2025-04-08T12:26:31.919Z",
    "note": "Event push message",
    "shipments": [
        {
            "id": "7777777770",
            "service": "ecommerce-europe",
            "status": {
                "timestamp": "2023-03-02T07:53:47Z",
                "location": {
                    "address": {
                        "countryCode": "NL",
                        "postalCode": "1043 AG",
                        "addressLocality": "Oderweg 2, AMSTERDAM"
                    }
                },
                "statusCode": "transit",
                "status": "in customs",
                "description": "The shipment is pending completion of customs inspection.",
                "pieceIds": [
                    "JD014600006281230701",
                    "JD014600006281230702",
                    "JD014600006281230703"
                ],
                "remark": "The shipment is pending completion of customs inspection.",
                "nextSteps": "The status will be updated following customs inspection."
            }
        }
    ]
}

specifics for the use of Tracking Data

• Tracking data is provided to You and/or the entity you are authorized to represent (hereinafter “You”/”Your”)  via this SHIPMENT TRACKING API under the prerequisite, that You retrieved the according tracking number in compliance with the applicable law, especially in the field of data protection and competition law and that You use the tracking number and/or tracking data solely for Your own legitimate tracking purposes.
• You may only submit tracking data to the recipient of DHL Group shipment and no other person; such submission shall always been in compliance with applicable laws in the field of data protection and competition law, which includes that the data shall not be combined with advertisement or presented in a way that it could be regarded as advertisement.
• If you are acting on behalf of a (mutual) shipping customer or the consignee, i.e. you are neither the sender nor the consignee of the DHL Group-shipment the Tracking Data refers to, the following applies:
  
  •    You are required to obtain all necessary consent(s) under the applicable laws, especially Data Protection Laws and postal secrecy protection laws. This shall include the obligation to obtain valid consent from the sender, and - if the Tracking Data contains consignee data, such as name or address - to ensure that valid consent has been obtained from the consignee, in each case prior to requesting the Tracking Data.
  
  •    You shall make the sender aware of the necessity of transparently informing the consignee about the processing of their personal data in accordance with applicable Data Protection Laws.
  
  •    You shall transparently inform the sender and/or consignee that the use of Your Application may lead to the disclosure of protected data (e.g., protected by postal secrecy and Data Protection Laws) to third parties, including yourself.
  
  •    You are required to inform the sender and/or consignee of the restrictions outlined in this User Guide and the General Developer Portal Terms of Use.

You shall, upon our written request, provide proof of compliance with the above requirements. We may conduct an audit to verify your compliance with the above requirements in accordance with the audit provisions (see section “MONITORING AND AUDIT”) in our General Developer Portal Terms of Use.
 

• In no case shall you reveal and/or provide third parties with the tracking number and/or tracking data and/or analyze, modify such data in any form and/or derive data/information especially for competitive reasons from it without our prior written consent.
• Tracking data shall be used in accordance with the following specification:
  • Display “Delivered by Deutsche Post DHL Group“ in text (minimum font size) as soon as it is presented/submitted to recipient
• You shall delete the tracking number and tracking data which You received via the SHIPMENT TRACKING API 30 days after the delivery (of the shipment) to the recipient is completed.