The DHL Parcel EU (BE - LU - NL) API gives you access to all of our comprehensive services, such as label printing, pick-ups, and track and trace.

Authentication and Authorization	Capabilities	Print Labels	Delivery Times	Pick-ups	Track and Trace
Your API key and User ID give you access to all of our services	Checks available products based on destination	Create shipping and return labels for all your shipments	Let your customers choose the day and time they want to receive their parcel	Book pick-ups for your shipments and have them picked up at your convenience	Always know the status of your shipments

The API covers:

• Creating labels for domestic and international shipments
• Users with a DHL Parcel customer account in either:
  • Belgium,
  • Luxembourg or
  • Netherlands

Scope

Capabilities

The Capability Service API checks whether the selected options, services, and type of shipment are available for each service or country. Use this service to create any shipping label, so you can rest assured that we’ll deliver all of your shipments. 

Print Labels

Create shipping and return labels for all your shipments with the Label Service API. A shipment can consist of several parcels, or you can designate each parcel as a separate shipment. Before creating the label, check whether the selected products are available by using the Capability Service API.

Delivery Times

Let your customers choose the day and time they want to receive their parcel. Put delivery times in your online store’s check-out to give your customers more options. In order to deliver shipments within the selected time windows, please present them to the DHL driver on the correct day. 

Pick-ups

Book pick-ups for your shipments and have them picked up at your convenience. We pick up parcels and pallets in one pick-up. Our standard option is to book pick-up as of the next pick-up day – you can only schedule a pick-up appointment for the same day in Spain and Portugal. If a pick-up is scheduled for the same day, please check availability with an ISO country code and the postal code of the pick-up address.

Track and Trace

The Track and Trace API displays the current status of the delivery. Linking with this API offers you a whole range of options. You can integrate the track and trace component into your own online store, so that your customers return to your website to check the status of their delivery. Based on the delivery status, you can also send useful notifications to your customers, such as when the delivery time has been scheduled.  

Using the API

The DHL Parcel EU (BE  - LU - NL) has been developed for and by developers. You need knowledge of REST APIs, JSON, and HTTPS and a business account in the My DHL Parcel online shipping service.

Log in to My DHL Parcel in Belgium, Luxembourg or Netherlands and go to the “Settings” menu. This is where you can create your API user ID and key and start linking the API right away. Click on the button ‘CREATE API KEY’ in the tab ‘API KEYS’, the user-id and key are generated.

Hold on to this information, since it will only be given out once. When pressing the button again, a new user-id and key will be generated, overwriting and invalidating the previous one.

Example Use Cases

Automatically more convenience

Linking to the Label API means labels will automatically roll out of your systems when orders come in. This will save a lot of time in your shipping process and prevent errors due to retyping or data import and export.

Attract more customers with track and trace

If you’ve linked our API to your online store, you can utilize even more opportunities during the customer journey – all the way from purchase through to delivery. By offering track and trace in your own online store, your customers will receive automatic notifications and you’ll increase the chance of repeat sales.

ServicePoint: a plus point for you

Your customers will be thrilled to know they can collect their parcel at a DHL ServicePoint, as they won’t have to worry about waiting for the delivery at home. If you’ve added the delivery option to your online store with our API, your customers can arrange everything immediately. Once the parcel has arrived, they’ll be sent a notification.

Improve your customer service with the track and trace API

The track and trace API helps your customer service employees by placing up-to-date track and trace details directly in view in your own system. Your agents can inspect the signature for receipt, if available. As they’ll no longer need to consult a separate track-and-trace system, you can considerably reduce the length of calls to Customer Service.

Get Access

To use the DHL Parcel EU (BE - LU - NL) API, your organization requires to have an active customer account with one of the DHL Parcel countries.

I already have an account number with one of the DHL Parcel EU countries:

If you do not have a customer account with one of the Parcel EU countries, please proceed with the steps below to create a new customer account:

Authentication

The user-id and key are used to make the initial call to the Authenticate API key endpoint. As a response, the endpoint returns both an access token and a refresh token.

The access token is valid for a limited time, indicated by the expiration time in the response attribute ‘accessTokenExpiration’. When this time (expressed as a unix time stamp) has expired, the secure access can again be established by obtaining a new access token using the refresh token and the Authenticate refresh token endpoint. Please keep in mind that this refresh token also has an expiration date time, but it is significantly longer than that of the access token.

The response of the refresh endpoint is the same as the initial call to the Authenticate API key endpoint; it also results in an access and a refresh token with expiration date times.

The resulting access tokens contain some encoded information about your access rights, including a list of account numbers. By default, access tokens give access to all account numbers assigned to your API key user. To limit this list, you may provide the optional accountNumbers field in your authentication request.

Example of response body (200) of the /api-key:

{
  "accessToken":"yJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiIwOGZkMTRhMC05YWYzLTRkZDMtODU3YS1hNzUyYWY3ZjUyYTciLCJzdWIiOiI2YmZjNzU2MS00YjQxLTRjYjctYTFjMy1kYzMxZmFmODYwZGIiLCJvcmdhbml6YXRpb25JZCI6ImE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMDMyNDMxNSwiZXhwIjoxNTEwMzI1MjE2LCJyb2xlcyI6WyJsYWJlbC1zZXJ2aWNlLkIyWCIsInBpY2t1cC1zZXJ2aWNlLkIyWCJdLCJhY2NvdW50cyI6WyIwODUwMDAwMSJdfQ.D9Zf0hnDXhPXoWar42wzSiZHRKLBYriyKQyj1zERrBw",
  "accessTokenExpiration": 1510325216 ,
  "refreshToken":
  "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJhMWQ5MDMyMi04YmRiLTQ1NjQtOTMxMy04OTg5N
ThmMzgwNDQiLCJzdWIiOiI2YmZjNzU2MS00YjQxLTRjYjctYTFjMy1kYzMxZmFmODYwZGIiLCJvcmdhbml6YXRp
b25JZCI6ImE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMDMyNDMxNSwiZXh
wIjoxNTEwOTI5MTE2LCJyb2xlcyI6WyJhdXRoLXNlcnZpY2UuUkVGUkVTSCJdLCJhY2NvdW50cyI6WyIwODUwMD
AwMSJdfQ.fi7hn6u3mFwcJ4AG8cYEh8OJFm2NDwOt407aP7sENSo",
  "refreshTokenExpiration": 1510929116,
  "accountNumbers": ["1234567"]
}

The accessToken to be used in the HTTP header for authentication. The accessTokenExpiration is the unix time stamp for the expiration of the token (in this case, 2017-11-10 14:46:56Z).

The refreshToken may be used to obtain a new accessToken without having to re-supply credentials. It has a longer expiration (refreshTokenExpiration) than the access token. This makes it possible to set up a longer-running session without the need to store original credentials.

The accountNumbers field lists all account numbers that the access token grants permission to use.

Request examples

Get Access Token

Curl

curl -X POST "https://api-gw.dhlparcel.nl/authenticate/api-key" -H "Accept:application/json" -H "Content-Type: application/json" -d "{\"userId\": \"f36abdfa- 9894-4d1f-bb6e-e471a953c04d\", \"key\": \"1c8545e1-767f-4531-9c6b-5f5f80737562\"}"

Responses

Success (code 200)

{
  "accessToken": "_Your token_",
  "accessTokenExpiration": 1510138597,
  "refreshToken": "_Your refresh token _",
  "refreshTokenExpiration": 1510742497,
  "accountNumbers": ["1234567"]
}

Refresh token

Request examples

Curl

curl -X POST "https://api-gw.dhlparcel.nl/authenticate/refresh-token" -H "Accept:application/json" -H "Content-Type: application/json" -d "{\"refreshToken\":\"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiIwMWVlYjBkMy1hZmM0LTRiYjEtYTgzZS0wZDkxYzE4ZjVhZDUiLCJzdWIiOiI2YmZjNzU2MS00YjQxLTRjYjctYTFjMy1kYzMxZmFmODYwZGIiLCJvcmdhbml6YXRpb25JZCI6ImE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMDIxMDcxNSwiZXhwIjoxNTEwODE1NTE2LCJyb2xlcyI6WyJhdXRoLXNlcnZpY2UuUkVGUkVTSCJdLCJhY2NvdW50cyI6WyIwODUwMDAwMSJdfQ.y-Hm3T6_moUWXF_v2uyOXcX7tu1uddyhG6fsDQliPXw\"}"

Responses

Success (code 200)

{
  "accessToken": "_Your token_",
  "accessTokenExpiration": 1510138597,
  "refreshToken": "_Your refresh token _",
  "refreshTokenExpiration": 1510742497,
  "accountNumbers": ["1234567"]
}

Environments

The addressable API base URL/URI environments are:  

Note: For testing collect your api sandbox key at My DHL Parcel

Rate limits

Rate limits protect the DHL infrastructure from suspicious requests that exceed defined thresholds.

When the limit is reached, you will receive an HTTP Status code: 

429: Too many requests.  

Additional Information

Shipment options

This is the current (at time of writing) list of shipment options. 

Specifics for the use of DHL Parcel EU (BE LU - NL) API

To register for the use of and/or access to DHL Parcel EU (BE - LU - NL) API and the underlying API Services (capabilities check, pickup request, label creation, time windows, tracking) – hereinafter collectively referred to as DHL Parcel EU (BE -  LU - NL) API – you and/or the entity you are authorized to represent (hereinafter “You”/”Your”) need to have an account with and/or have entered into a shipping contract with a DHL entity in the Benelux, Spain, Portugal or Sweden (hereinafter referred to as “DHL”). If You engage an external developer or other IT services provider to represent You and to develop Your Application according to the General Developer Portal Terms of Use and these special API terms & conditions (also referred to as “Legal Terms”), You are liable for the acts or omissions of such third party in connection with the access to and/or usage of the DHL Parcel EU (BE - LU - NL) API.

These Legal Terms and the General Developer Portal Terms of Use govern your usage of and/or access to the DHL Parcel EU (BE - LU - NL) API and, unless otherwise stated herein, do not replace and/or modify any applicable shipping terms and conditions (e.g. General Transport Conditions – AVC; Convention on the contract for the international carriage of goods by road – CMR)  and/or any other agreements, (shipping) contracts or SOWs with DHL or any of its affiliates, which govern services or products provided to you (separately, each an “Agreement”). Notwithstanding the foregoing, you expressly acknowledge and agree that solely with respect to your use of and access to the DHL Parcel Europe API these Legal Terms and the General Developer Portal Terms of Use shall have preference over the terms and conditions in an Agreement, unless any terms and conditions in an Agreement specifically address the use of/access to the DHL Parcel Europe API by You, in which case the specific terms and conditions of the Agreement shall prevail with respect to Your use of/access to the DHL Parcel Europe API.

You shall use the services and/or data that You receive via the DHL Parcel EU (BE - LU - NL) API only for the legitimate contractual purposes and only in connection with DHL’s shipping services, and in compliance with all applicable laws and regulations, including but not limited to, laws regarding the use of personal data. 

For the purposes of the use of the DHL Parcel EU (BE - LU - NL) API, these Legal Terms and the General Developer Portal Terms of Use are governed by the law and jurisdiction defined in the applicable Agreement. Should no law or jurisdiction be defined in the Agreement or otherwise, these Legal Terms shall be governed according to the law and jurisdiction of the principal place of business of the according DHL entity/division providing the shipping services. 
The following prerequisites and/or restrictions apply for the usage of data or information received via the DHL Parcel EU (BE - LU - NL) API:

• Capabilities:
  • The API Service “capabilities” provides You with the possibility to check which shipping services and additional services are offered by DHL for Your shipments to a specific destination and recipient (business or consumer), e.g. parcel type XS, S, M, L, XL, weight of the shipment, delivery to a DHL ServicePoint, home delivery, evening delivery, signature at delivery, age check, insurance etc..

• Pickup Request:
  • The API Service “pickup request” provides You with the possibility to request pickup of Your shipment (i.e. your packages, parcels and/or pallets). 

• Label:
  • The API Service “label” provides You with the possibility to create and download labels for shipments. Please note that the creating and/or downloading of a label does not constitute the shipping contract. Such contract will be concluded once the labeled shipment is picked up and accordingly accepted by DHL. 

• Time Windows:
  • The API Service “time windows” provides You with the possibility to choose time windows for delivery of shipments and publish them, e.g. in the check-out of Your or Your customer’s online store. To be able to deliver the shipments within the chosen time windows to the consignees/recipients, according (daily) pick-up times are arranged, which need to be observed by You. Notwithstanding that DHL will make every reasonable effort to deliver the shipments within the chosen time windows, these are not guaranteed and do not form part of the shipping contract. 

• Tracking:
  • Data requested and received via the DHL Parcel EU (BE - LU - NL) API, such as transport status, estimated delivery time, is hereinafter referred to as “Tracking Data”.
  • Tracking Data is Confidential Information in the meaning of section “Communication” of the General Developer Portal Terms of Use. Other than set forth below You must not reveal and/or provide third parties with the Tracking Data and/or analyze, modify such data in any form and/or derive data/information especially for competitive purposes from it without DHL’s prior written consent.
  • You shall not combine the Tracking Data with an advertisement or present it in a way that it could be regarded as advertisement. 
  • Unless otherwise agreed, You shall delete the Tracking Data (including the transport history) 30 days after the delivery is completed. DHL shall not be required to provide Tracking Data to You that is older than 30 days from the delivery date.
  • The use and submission of Tracking Data – including to any of Your subcontractors – shall always be in compliance with applicable laws and regulations, including – without limitation – data protection laws and competition/antitrust law. 
  • If You are neither the shipper nor the recipient of shipments the Tracking Data refers to, the following applies additionally:
    • You shall ensure, that you are duly authorized to act on behalf of the shipper;
    • You shall make the shipper aware of the restrictions set out in these Legal Terms and the General Developer Portal Terms of Use;
    • You shall make the shipper aware of the necessity to inform the recipient transparently about the processing of his/her personal data according to applicable data protection laws.