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=33333333335301
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]":

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 the shipper country Denmark, it is mandatory to specify the weight in the web service request. For Great Britain, Switzerland and Norway, the weight must be specified in the customs information section.

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.