Best for:
- Creation of return labels to be used by end customers
- Returns sender countries: bgr, dnk, deu, est, fin, fra, grc, gbr, irl, ita, hrv, lva, ltu, lux, mlt, nld, aut, pol, prt, rou, swe, che, svk, svn, esp, cze, hun, cyp
- Determination of receiver configuration for your account
You are on the documentation page of the DHL Parcel DE Returns API of Post & Parcel Germany. In the following chapters we offer you:
- An Overview of the business functions covered via the API
- The technical documentation of the API
- The User Guide contains topics of connection and authentication
- Postman Collection
- Open API Specification and code examples in Reference Docs
- Find further Use Cases, FAQ, and Support Contact in section Additional Information
- Latest Release Notes
Scope
The API Returns allows you to use the following products of DHL Paket:
- DHL Retoure Online
- DHL Retoure International
Exemptions
The following DHL Paket products and services can not be used via the API Returns:
- DHL Paket with enclosed return label:
- DHL Paket International
- DHL Paket Europaket
- DHL Connect
- DHL Retoure Selbstzahler
Prerequisites
To create return labels using the API Returns, the following prerequisites must be fulfilled:
- A valid business customer contract with DHL Paket GmbH for the products DHL Retoure Online and/or DHL Retoure International
- Access to the Post & DHL Business Customer Portal with the authorization for the function "Returns"
Using the API
The API Returns allows to order return labels for planned return shipments from your customers.
It thereby enables business customers of DHL to seamlessly implement the label creation process for return labels into their own workflows, for example integrated into their own website.
You receive individual return labels via the API Retoure, which you can make available to your customers.
The following provides an overview on how to get access to the API.
- Technical Details on the API calls can be found here: "API Specification".
- Further hints on API usage are given in the sections "Support" and "FAQ".
Get Access
How to register your DHL Parcel DE Returns API and get your API subscription keys:
Use the "GetAccess" button (this will pre-populate this API if you create an app) or add the API to an existing app.
Approval is manual for the API production environment. You will receive a notice, once your APP has been approved.
Here you can find more help on how to register an app.
Authentication
Access Token
To access the API resources of the Post & Parcel Germany APIs, you must first verify yourself against our Authentication API. In exchange, you will receive the Access Token required for further requests. Please follow the instructions of the Authentication API (Post & Paket Deutschland) to get an Access Token.
Please note: You've been already granted to use the Authentication API (Post & Parcel Germany) automatically, when you have access to this specific API. There is no further action required on your part.
Alternatively, you can use Basic Auth (Username: "2222222222_customer", Password: "uBQbZ62!ZiBiVVbhc") for authentication and additionally provide your api-key as request header information ("dhl-api-key"). Please note that we will no longer offer Basic Auth in future API versions. It is strongly recommended to use OAuth2.
Sandbox
To use the "DHL Parcel DE Returns API", you will first need an application created including the API in sandbox mode, like described in Get Access.
You have the possibility to use our sandbox environment with following business customer user data:
Username: "user-valid" Password: "SandboxPasswort2023!" Description: Valid Business Customer User
Username and password can be used in the Authentication API to obtain an Access Token.
The following curl command illustrates how to obtain a token and use the Parcel DE Returns API:
curl -k -i -X POST -H "accept: application/json" -H 'content-type: application/x-www-form-urlencoded' https://api-sandbox.dhl.com/parcel/de/account/auth/ropc/v1/token -d 'grant_type=password&username=user-valid&password=SandboxPasswort2023!&client_id=KH2iQ8YwGYtGs4XUBKaGaiyWBPEZnsRm&client_secret=V8yPDt8GlGlNMRCh'
Once you have valid Access Token you can request the Returns API:
Try out basic access by querying the API version (without Access Token):
curl -H "accept: application/json" https://api-sandbox.dhl.com/parcel/de/shipping/returns/v1/ Query information for your receivernames (with Access Token): curl -H "Authorization: Bearer ${TOKEN}" -H "accept: application/json" https://api-sandbox.dhl.com/parcel/de/shipping/returns/v1/locations
A detailed description of the Returns API can be found in the "Open API Specification".
You can download the "Open API Specification" here.
Please use the following receivernames (Retourenempfänger / "receiverId") for testrequests:
Absendeland | Retourenempfängername (receiverID) |
Belgien | bel |
Bulgarien | bgr |
Dänemark | dnk |
Deutschland | deu |
Estland | est |
Finnland | fin |
Frankreich | fra |
Griechenland | grc |
Großbritannien und Nordirland | gbr |
Irland | irl |
Italien | ita |
Kroatien | hrv |
Lettland | lva |
Litauen | ltu |
Luxemburg | lux |
Malta | mlt |
Niederlande | nld |
Österreich | aut |
Polen | pol |
Portugal | prt |
Rumänien | rou |
Schweden | swe |
Schweiz | che |
Slowakei | svk |
Slowenien | svn |
Spanien | esp |
Tschechien | cze |
Ungarn | hun |
Zypern | cyp |
Production
To use the "DHL Parcel DE Returns API", you will first need an application created including the API in production mode, like described in Get Access.
Your business customer username and password can be used in the Authentication API to obtain an Access Token.
When selecting the respective business customer user: For security reasons it is recommended to use a "system user", because it is not possible to log on to the Post & DHL Business Customer Portal with a "system user".
Important: DHL contract customers receive the access data for access to production from the Post & DHL Business Customer Portal via DHL Paket sales.
To determine the return recipients, please use the /locations function via API call. The response includes all "ReveiverIDs".
Important! Only “ReceiverIDs” with a billing number can be used to create a return label. “ReceiverIDs” without a billing number belong to DHL Retoure Selbstzahler which cannot be ordered via die DHL Parcel DE Returns API.
Alternativley: You will find the respective names of the return recipients (receiverID) listed in the
Post & DHL Business Customer Portal (https://geschaeftskunden.dhl.de/) under the menu item "Returns" > "Settings" under the entry "Receiver ID".
Environments
The addressable API base URL/URI environments are:
Environment | Description | Comment |
---|---|---|
https://api-eu.dhl.com/parcel/de/shipping/returns/v1/ | Production environment | Production usage will be approved after successful sandbox usage has been certified by DHL. |
https://api-sandbox.dhl.com/parcel/de/shipping/returns/v1/ | Sandbox environment | Sandbox usage is possible even if you are not yet an DHL Parcel Business Customer. |
Error codes
Error Code | Description | Troubleshooting/Action |
400 | Bad Request | Please check the syntax of the call. |
401 | Authentication failed | Please check the access data. |
403 | Authorization failed | Please check your authorizations. |
500 | Internal error | An unexpected internal error has occurred. |
We recommend using the Postman software to test our APIs. Postman is a collaboration platform for API development and testing. Post & DHL Germany provides you a comprehensive Postman collection for every single API. You can download the complete API collection, import it into your Postman work space and get started quickly on your integration with our APIs.
The following steps must be performed to test the API beforehand:
You must request access to the sandbox environment to obtain an API key and API Secret
You can find detailed instructions on how to do this under Get Access.
Setting up the Postman Test Collection
- Download the Postman test collection from the download section.
- Import the Postman Test Collection (see official documentation of the Postman learning platform)
- Replace the value of the variable client_id and client_secret with your personal API key & secret.
Please also see our step-by-step instructions on how to use the Postman Test Collection.
Use Case Overview
In order to further test our API you can download our test suite here
The test suite can be used as a collection on the software postman: Postman API Platform | Sign Up for Free
Following steps have to be taken in order to use it:
- request access to Sandbox environment and receive an API-key (see Get Access for further details)
- import collection into postman (see official documentation from postman learning platform)
- replace value of the variable "dhl-api-key" by your personal API-key
Example Requests
Note: These sample calls cover only the basic operations of the API. Detailed example calls for all products and services can be found in our Postman test suite, further explanation in chapter how to test the API.
Order returns
Simple request for German returns label (PDF label and QR code)
POST /parcel/de/shipping/returns/v1/orders?labelType=BOTH
Host: https://api-sandbox.dhl.com
Content-Type: application/json
{
"receiverId": "deu",
"shipper": {
"name1": "Max Mustermann",
"addressStreet": "Kurfürstendamm",
"addressHouse": "1",
"postalCode": "10719",
"city": "Berlin"
}
}
Simple request for German returns label (PDF label only)
POST /parcel/de/shipping/returns/v1/orders?labelType=SHIPMENT_LABEL
Host: https://api-sandbox.dhl.com
Content-Type: application/json
{
"receiverId": "deu",
"shipper": {
"name1": "Max Mustermann",
"addressStreet": "Kurfürstendamm",
"addressHouse": "1",
"postalCode": "10719",
"city": "Berlin"
}
}
Simple request for German returns label (QR code only)
POST /parcel/de/shipping/returns/v1/orders?labelType=QR_LABEL
Host: https://api-sandbox.dhl.com
Content-Type: application/json
{
"receiverId": "deu",
"shipper": {
"name1": "Max Mustermann",
"addressStreet": "Kurfürstendamm",
"addressHouse": "1",
"postalCode": "10719",
"city": "Berlin"
}
}
In addition to the QR code, please also send your customer the so-called returns ID in text form (RET number). This is required if code cannot be read or scanned and has to be entered manually, for this purpose it has to be transmitted in a format which allows copying (no JPEC, PNG etc.). The Returns ID comprises the item number and the prefix “RET” (e.g., RET129900013151).
Elaborate request for German returns label
POST /parcel/de/shipping/returns/v1/orders?labelType=BOTH
Host: https://api-sandbox.dhl.com
Content-Type: application/json
{
"receiverId": "deu",
"shipper": {
"name1": "Max Mustermann",
"name2": "Zentraler Einkauf",
"name3": "Beispiel Firma GmbH",
"addressStreet": "Kurfürstendamm",
"addressHouse": "1",
"postalCode": "10719",
"city": "Berlin",
"state": "Nordrhein-Westfalen",
"email": "max.mustermann@mail.com",
"phone": "+49 170 123456789"
},
"customerReference": "Order Nr. 1234/2022",
"shipmentReference": "Account AB34-88",
"itemWeight": {
"uom": "kg",
"value": 1.5
},
"itemValue": {
"currency": "EUR",
"value": 99.99
}
}
Request for international returns label without customs declaration (shipper country inside the EEC)
POST /parcel/de/shipping/returns/v1/orders?labelType=SHIPMENT_LABEL
Host: https://api-sandbox.dhl.com
Content-Type: application/json
{
"receiverId": "fra",
"shipper": {
"name1": "Jean Doe",
"addressStreet": "Rue de Thorigny",
"addressHouse": "5",
"city": "Paris",
"postalCode": "75003"
}
}
Request for international returns label with customs declaration (only required if shipper country is outside the EEC (e.g. Switzerland))
POST /parcel/de/shipping/returns/v1/orders?labelType=SHIPMENT_LABEL
Host: https://api-sandbox.dhl.com
Content-Type: application/json
{
"receiverId": "che",
"shipper": {
"name1": "Hans Meier",
"addressStreet": "Heimpl.",
"addressHouse": "1/5",
"postalCode": "8001",
"city": "Zürich"
},
"customsDetails": {
"items": [
{
"itemDescription": "T-Shirt (red, size S)",
"packagedQuantity": 2,
"itemWeight": {
"uom": "kg",
"value": 1
},
"itemValue": {
"currency": "EUR",
"value": 19.98
}
},
{
"itemDescription": "T-Shirt (blue, size M)",
"packagedQuantity": 1,
"itemWeight": {
"uom": "kg",
"value": 0.5
},
"itemValue": {
"currency": "EUR",
"value": 19.99
}
}
]
}
}
Get recipients
Retrieving all returns recipients
GET /parcel/de/shipping/returns/v1/locations
Host: https://api-sandbox.dhl.com
Retrieving a specific returns recipient by its receiver Id
GET /parcel/de/shipping/returns/v1/locations?receiverId=swe
Host: https://api-sandbox.dhl.com
Retrieving returns recipients for a specific shipper country
GET /parcel/de/shipping/returns/v1/locations?countryCode=deu
Host: https://api-sandbox.dhl.com
Retrieving returns recipients for a specific billing number
GET /parcel/de/shipping/returns/v1/locations?billingNumber=22222222225301
Host: https://api-sandbox.dhl.com
Retrieving returns recipients for a specific postal code
GET /parcel/de/shipping/returns/v1/locations?postalCode=53113&countryCode=deu
Host: https://api-sandbox.dhl.com
General Information
I used the old Parcel Returns API on Entwicklerportal, what changed to the new Returns API?
If you implemented the previous parcel returns API, please notice the changes under Release Notes.
Authentication
What can I do, if I forgot my password or user name?
Please use the password reset function to assign a new password or user name at https://geschaeftskunden.dhl.de/
What kind of authentication is required to use the API Returns?
Please refer to section "Authentication".
Returns Order
What is the difference between customer reference and shipment reference?
The customer reference is visibly printed on the returns label, the shipment reference is only displayed in the overview of created returns labels in the Post & DHL Business Customer Portal.
Which format does the returns label have?
The returns label is included as a base64 encoded string (PDF file) in the response body (property "label.b64").
Returns with a shipper address in Germany additionally allow for a mobile returns label that is provided as a QR code. The label can be printed at Deutsche Post DHL Group's acceptance points.
The QR code is provided as base64 encoded string (PNG file) in the response body (property "qrLabel.b64") if the query paramter "labelType" is set to either "QR_LABEL" or "BOTH".
In addition to the QR code, please also send your customer the so-called returns ID in text form (RET number). This is required if code cannot be read or scanned and has to be entered manually, for this purpose it has to be transmitted in a format which allows copying (no JPEC, PNG etc.). The Returns ID comprises the item number and the prefix “RET” (e.g., RET129900013151).
What do I need to consider if I want to provide my customers with a link to create returns labels?
When publishing on your own homepage, please note that this website with the link to the creation of returns labels must not be findable via search engines.
What parameters can I use to pre-fill the web form for returns orders for my customers?
The following parameters can be appended to the returns URL after the HASH value via "&[parameter]" and "=[specification]":
ShipmentReference | Shipment reference, will be displayed in the returns overview |
CustomerReference | Customer reference, will be displayed on the return label |
senderName1 | Name1 of the sender |
senderName2 | Name2 of the sender |
senderStreet | Street of the sender |
senderStreetNumber | House number of the sender |
senderCity | City of the sender |
senderZip | Zip code of the sender |
ADDR_SEND_EMAIL | E-mail address to which the return label should be sent |
Example:
https://www.dhl.de/retoure/gw/rpcustomerweb/OrderEntry.action?hash=xxxx
&ShipmentReference=1234&CustomerReference=5678&senderName1=Absender1&senderName2=Absender2&senderStreet=Straße1&senderStreetNumber=HNR1&senderCity=Ort1&senderZip=53113& ADDR_SEND_EMAIL=name@domain.de
How can I cancel an ordered return?
A cancellation of ordered returns labels is not necessary, as only returns packages that have been posted by the shipper will be charged. The creation of a returns label is free of charge.
Returns Recipients
How do I determine the names of the return recipients (property "receiverId")?
You can retrieve the list of all return recipients using the GET locations method. Please refer to our example request.
Alternatively, log in to the Post & DHL Business Customer Portal. All return recipient names (= "receiverId") are listed in the "Settings" section of the "Returns" function. You can download a CSV list of all return recipients by clicking on the link "URL & Receiver Ids".
How do I change the receiving address of the returns labels?
The receiving address is configured in the returns recipient. A separate returns recipient is required for each country of origin and receiving address.
Returns recipients can be edited by selecting "Settings" from the "Returns" menu in the Post & DHL Business Customer Portal.
How can I create an additional return recipient?
New returns recipients can only be created by the DHL Sales division. Please consult your Sales contact at Deutsche Post & DHL. You can find your Sales contact at the bottom of the start page at https://geschaeftskunden.dhl.de/ after login.
Technical Support Business Customer Portal
0228 - 76367679
(Mo-Fr from 8 am - 6 pm)
International Returns
Why do DHL international returns labels differ from country to country?
In order to be able to offer end customers outside Germany the best acceptance network for their returns, DHL cooperates with various partners.
How can I determine the shipper address format for a specific country of origin?
On the websites of the Universal Postal Union ("UPU") you can view the valid address models: http://www.upu.int
Not all countries of origin are available for my returns. What can I do?
DHL Returns International is only available for countries of origin in Europe. If you are missing a European country, please consult your Sales contact at Deutsche Post & DHL. You can find your Sales contact on the bottom of the start page at https://geschaeftskunden.dhl.de/ after login.
For which countries of origin is the weight mandatory?
For Denmark, Portugal, and Sweden the weight must be transmitted in the webservice request as a mandatory attribute. For United Kingdom and Switzerland the weight must be included in the customs section of the webservice request.
General Product Information
What does the creation of a returns label cost?
Only returns packages that have actually been posted by the shipper will be charged. The creation of a returns label is free of charge.
Why can't shipping labels be created using the API Returns?
Only returns labels can be created using the API Returns. Please use the Business Shipping API to create shipping labels.
What can I do, if I have questions regarding the Post & DHL Business Customer Portal or the "Returns" function?
Please click on the "Help & information" section of the Post & DHL Business Customer Portal at: https://geschaeftskunden.dhl.de/
Where can I find more details about the DHL Returns products for business customers?
Please visit https://www.dhl.de/de/geschaeftskunden.html for more information about the DHL returns product suite for business customers.
You can request support in our Help Center. You can raise a ticket that allows you to request direct support from DHL Support. Please describe your enquiry in as much detail as possible and also send us reproducible extracts from the web service communication. We will try to help you with your problem as soon as possible during following times:
IT Customer Support & Integration Parcel
Geschäftszeiten: Mo-Fr 8.00 bis 16.00 Uhr
Specific Terms for the use of and/or access to the "DHL Parcel DE Returns API"
To register for the use of DHL Parcel DE Returns API You and/or the legal entity you are authorized to represent (hereinafter "You"/"Your") need to have an active customer account with Post & DHL Business Customer Portal (hereinafter referred to as "DHL"). An API Productive Key and access details will be provided to You subject to a successful validation of Your credentials by DHL. If You engage an external developer, or other IT services provider to develop Your Application or any other third party to access and/or use the DHL Parcel DE Returns API on Your behalf, You remain fully liable for any acts or omissions of such Third Parties in connection with the access to and/or usage of the DHL Parcel DE Returns API.
These Legal Terms do not replace and/or modify the applicable "General Terms and Conditions of DHL Parcel for business customers", available at https://www.dhl.de/en/geschaeftskunden/paket/rund-um-den-versand/agb.html or any other shipment services agreement, which govern Your parcel shipments.
In case You act as a third party software, vendor, marketplace or otherwise as commercial agent on DHL's and/or its affiliates' behalf, i.e. with DHL's and/or its affiliates' consent, You are obliged to refer the customer (i.e. the sender of the shipments) to the applicable terms and conditions for shipment.
You shall use the services and/or data that You receive via the DHL Parcel DE Returns API only for the legitimate contractual purposes and only in connection with Your or the shipping customers DHL shipments.
The following prerequisites and/or restrictions apply for the usage of and/or access to the DHL Parcel DE Returns API:
To release the API by DHL, the following functionalities have to be implemented:
- receiverID is editable
- Username (Post & DHL Business Customer Portal user) is editable
- Password is editable
- Implementation of customs documents (for non-EU countries)
- The name of the return sender should be specified in the attribute "shipper.name1" in the format "<firstname> <lastname>".
- The return ID (RET number) must be displayed near the QR code in a format that is easy to read and that allows copying (no JPEG, PNG, etc.). The return ID is composed of the shipment number and the prefix "RET", which immediately precedes the shipment number (e.g. RET129900013151).
Please note the following additional guidance and recommendations:
Above conditions have to be configurable for each participating company (e.g. on a marketplace or within the framework of a shopsoftware) and an appropriate documentation has to be available for shipping customers.
1.0.6
• The optional attribute “qrLink” has been added to the response of the POST /orders endpoint. This attribute contains a link to load the QR code for mobile returns into the Post & DHL app. The attribute is only available for national returns.
• The GET /locations endpoint now only returns recipients via which a DHL Returns Online shipment can be ordered. Returns recipient for DHL Returns Selfpayer are not included anymore.
1.0.5
Introduction of the authentication method OAuth2 parallel to the current Basic Auth. Later API versions will no longer support Basic Auth.
1.0.4
1. Customer reference
Special characters are now allowed in the customer reference field with the exception of pipe (|) and backslash (/).
The permitted special characters in the text are also encoded in the barcode. This makes it easier for you to collect returns by scanning the customer reference on the label.
The number of characters allowed in the customer reference field has been adjusted to “Mobile Returns” and set to 30 characters. If a longer value is transferred in the request, it is shortened accordingly.
2. EORI number
The "Economic Operators Registration and Identification" (EORI) number has been added to return recipients with sender country Switzerland or the United Kingdom in April 2023. The EORI must be specified in the import process for returns.
The EORI number field will be expanded to 22 characters so that customers with headquarters abroad can now add the German branch number to the foreign EORI number.
You can enter the EORI number for your return recipients with the sender country Switzerland or the United Kingdom by navigating to "Returns -> Settings" in the Post & DHL Business Customer Portal and editing the corresponding return recipients there. To do this, click on the "Pen" symbol. You must have permission to access the settings. If necessary, contact your company's main user with administration rights in the Post & DHL Business Customer Portal.
1.0.3
Correction of currency list.
1.0.2
- Extension of the customs content declaration (Commodity) by the two fields:
- countryOfOrigin: Country where the returned item was produced.
- hsCode: Harmonized System Code aka Customs tariff number.
- Precise definition of error codes in responses based on the JSONStatus.
- Further examples of using the API
Note:
In April there will be a change in the import handling procedure for goods shipped from the United Kingdom using DHL Retoure International. With effect from April 1, 2023, DHL Retoure International (returns API) will be expanded to include the mandatory fields of the CN23 document for the United Kingdom, as is the case now with Switzerland. Transmission of the required customs information will therefore be mandatory for Switzerland and the United Kingdom in the future.
What this means for you specifically is that with requests for the sending country “United Kingdom” the information for the CN23 document must be included as an obligatory field via the object “customsDetails“. The array “items” in this object must contain at least one goods item. Here we would like to note that the two fields “countryOfOrigin“ and “hsCode“ are optional entries but should nonetheless also be transmitted in order to simplify imports to Germany and avoid possible transit time delays. These two values will also be printed on the CN23 document in future.
Please note that due to the Northern Ireland Protocol negotiated between the UK and the European Union, DHL Retoure International is not subject to customs processes or customs registrations for items being returned from Northern Ireland. Effective April 1, 2023, therefore, no data need be transmitted for returns from Northern Ireland, the postal codes for which always begin with “BT”.
1.0.1
Initial release of the redsigned DHL Parcel DE Retruns API including following changes in compare to the old API:
New Services and Functions:
- Get available return locations for your account by using /locations
- International returns response including international shipping number
Major changes compared to the initial Returns API on entwickler.dhl.de:
Due to an API modernization and harmonization programm, Post & Parcel APIs becoming more similar to each other.
If you implemented the previous parcel returns API, please notice the following changes in the new version here:
- Renaming of business objects
Previous Parcel Returns API | New Parcel Retruns API |
---|---|
senderAddress | shipper |
postCode | postalCode |
streetName | addressStreet |
houseNumber | addressHouse |
- Renaming of business objects for international shipment
Previous Parcel Returns API | New Parcel Retruns API |
---|---|
positionDescription | itemDescription |
count | packagedQuantity |
weightInGrams | object: "itemWeight": {"uom": "g","value": 1000} |
currency |
object: "itemValue": {"currency": "EUR","value": 100} Please notice, that each item has to have a currency object and all CN23 items should have the same currency |
Following parameter are no longer necessary:
originalShipmentNumber, originalOperator, acompanyingDocument, originalInvoiceNumber, originalInvoiceDate, comment, originCountry, articleReference, tarifNumber
- Changes in Requests
returnDocumentType is not longer in request body, use the URL-Parameter instead: ?labelType=SHIPMENT_LABEL
Previous Parcel Returns API | New Parcel Retruns API |
---|---|
Request-Body-Parameter:
"returnDocumentType": "BOTH"
|
URL-Parameter : ?labelType=BOTH |
- Changes in Responses
Previous Parcel Returns API | New Parcel Retruns API |
---|---|
shipmentNumber | shipmentNo |
Responses including internationalShipmentNo | |
New object for response shipment status "sstatus" . {"title": "Created", "status": 201, ... } | |
labelData | "label":{"b64": "..."} |
qrLabelData | "qrLabel":{"b64": "..."} |