DHL Parcel DE Returns (Post & Parcel Germany)
v 1.0.3
Division: Post & Parcel Germany, Parcel

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
Region: Germany
Used for: Shipping
Overview

You are on the documentation page of the DHL Parcel DE Returns API of Post & Parcel Germany. In the following chapters we offer you:

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

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.

User Guide

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".

If you implemented the previous parcel returns API, please notice the changes under Release Notes.

Get Access

How to register your DHL Parcel DE Returns API and get your API subscription keys:

  1. Click Get Access Button on top of this page and the create App form will open with the sandbox environment of the API being pre-selected.
  2. If required, change selection to "DHL Parcel DE Returns API"
  3. When you have completed the form, click the Create App button.
  4. You will now find your App under My Apps.
  5. From the My Apps screen, click on the name of your app.
    The Details screen appears.
  6. 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.
  7. Click the Show link below the asterisks that are hiding the Consumer Key.
    The Consumer Key appears.

Every call to the API requires a consumer key. This key needs to be specified in the request header (DHL-API-Key).

Please note that different keys are required for sandbox respectively production environment. Both can be requested via above procedure and copied from API credentials section.

Alternatively to "get access" you can go to My Apps on the portal website and click the + Create App button:

  • The "Create App" form appears.
  • Complete the Create App form and select the "DHL Parcel DE Returns API".
    • You will find two entries of the API in the list: one for Sandbox, one for Production use.

Authentication

Sandbox

To create return labels in the sandbox, you have the option of using our testsuite with the following user data:

  • Username: "2222222222_customer"
  • Password: "uBQbZ62!ZiBiVVbhc"
  • Above given username and password must be provided via basic authentication (Basic Auth).

A detailed description of the Retoure 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.

In addition, the following access data for the webservice (API) must be specified:

  • User: "User from Post & DHL Business Customer Portal".
    (User must be authorized for returns!)
  • Password: "Password of above user".
  • Your active business customers user and password values must be provided via basic authentication (Basic Auth).

When selecting the respective user, please also consider the duration of the validity of passwords:

  • the password validity of a "user" is" 90 days
  • the password validity of a "system user" is" 365 days

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" that you can use to create a return label.

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 Paket 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.
Postman Collection

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 (dhl-api-key).
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 "dhl-api-key" with your personal API key.

Please also see our step-by-step instructions on how to use the Postman Test Collection.

Use Cases

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"
    }
}

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
FAQ

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/

Forgot Password

What kind of authentication is required to use the API Returns?

Please refer to section "Authentication".

Returns Order

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

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".

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".

ReceiverId

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.

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.

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/

Help and Information

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.

Support

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

Legal Terms
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.2
22.Feb.2023
  • 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
07.Sep.2022

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": "..."}