last updated Feb 02 2022

The DHL business customer shipping API permits the management of shipments and purchase of shipping labels.

It is available for Business Customers of DHL Parcel Germany who send more than 200 shipments per year. DHL business customers, who do not have a DHL business customer account (EKP) and who send less than 200 shipments per year, may use the private customer shipping API (via https://entwickler.dhl.de).

The business customer shipping API offers the following features:

• Preparation of shipping documents for national and international shipping Including the creation of export documents and retrieval of labels
• Support of the following products: DHL Paket, DHL Paket International, DHL Europaket, DHL Paket Connect, Warenpost, Warenpost International (from Feb 1 2022 onwards)
• Support of additional services per product (e.g. CashOnDelivery, Ident-Check, Bulk, Returns, and more)
• Different document types (Shipping Labels, Return Labels, Customs Documentation, and more)
• Different option to format and deliver labels
• Close-out (end of day processing)
• restful, json-based API

This provides an easy-to-use API as an alternative to the existing flagship API "Versenden" of DHL Parcel Germany. The API is new, friendly, and feature-complete alternative to the legacy SOAP-based API. For information on the REST-API, please keep reading here.

Note: This API has completed closed beta and does not generally accept new users. More details about that can be found here.

Making your first call

Refer to the technical description (OAS / Swagger) for details on endpoints, operations, parameters, formats.

Refer to the information in the user guide on how to conduct calls, samples, postman collection, json schema, and more.

updated July 07 2021

The API has completed a closed beta phase on Feb 28 2021. In general, no new users will be accepted. The API documentation will now be restricted to existing users.

REQUEST ACCESS

Generally, participation in this program is not anymore possible. Please contact existing sales/account management contacts for more information**.** Generally, no new access credentials will be handed out via Get Access!. If you have questions, please use the contact form in the Help Center or do speak to your DHL contacts for possible steps.

SANDBOX USAGE (existing users)

Sandbox usage and go-live process for existing users will be supported. DHL reserves the right to revoke access for sandbox users which were inactive for more than 60 days.

Make sure to check the additional resources (User Guide section) such as the postman collection and json schema.

PRODUCTION USAGE

For eventual production use it is required to be a registered business customer of DHL Parcel Germany (see https://www.dhl.de/en/geschaeftskunden/paket/kunde-werden/angebot-dhl-geschaeftskunden-online.html). Please contact us when you feel ready. Please also refer to the FAQ entries discussing the go-live process.

Get Access

You must request credentials to interact with the Parcel DE Shipping API.

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.

It is possible to use the same app (and same key) for both Sandbox and Production environment.

Access will be manually approved separately for both Sandbox and Production while the API is in closed beta. You will be notified after approval.

Authentication Keys

Every call to the API requires a subscription key. For this API, the key needs to be passed in the 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.

Note that for Parcel Shipping DE you WILL NEED an existing Geschaeftskundenportal account (GKP credentials) for production usage.

Environments

The addressable API base URL/URI environments are:

Authentication Details

This section summarizes preconditions for access and provides background.

curl -H "accept: application/json" 

curl -u ${gkpuser}:${gkppass} -H "dhl-api-key: ${KEY}" https://api-sandbox.dhl.com/parcel/de/shipping/v1/

Next Steps

Once you have obtained API key for at least the sandbox:

1. Try out basic access by querying the API version:

   curl --H "accept: application/json" -H "dhl-api-key: ${KEY}" https://api-sandbox.dhl.com/parcel/de/shipping/v1/

2. Try out to validate a shipment against the sandbox (which you have stored in my_request.json)

   curl -X POST -H "dhl-api-key: ${KEY}" --H "accept: application/json" -H "Content-Type: application/json" -u 2222222222_01:pass -d @my_request.json https://api-sandbox.dhl.com/parcel/de/shipping/v1/orders/?validate=True

Note that you can use your credentials to try out several calls directly in the API description under "Reference Information". You will also see more complete curl examples and request documents there. Next, you can actually create a shipping label, retrieve it, and more.

Other Information

Tools

A number of additional tools are available, including:

• JSON schema allowing off-line validation of shipment validation and creation requests https://storage.googleapis.com/pp-shipping-de-artefacts/ShipmentOrderRequest.json
• Postman testing suites for experimentation and development tests https://storage.googleapis.com/pp-shipping-de-artefacts/pp-parcel-shipping_onboarding_collection.json.To use this, you must first replace the collection variable apikey with the approved sandbox key you have obtained.
• Public clients to showcase API interaction (python3, for download here soon, Golang sample client)

Rate limits

The API enforces limits on the number of requests and the maximum rate. These limits are specific to environment and API key. They will not usually impose a limitation for your regular use.

However, should the limit be reached, you will receive an HTTP Status code:

``` javascript
"status" : 429
"title": "Too Many Requests",
"detail": "pp-parcel-shipping-sandbox: 10000 requests allowed within 1 day(s) with maximum rate 100ps"
```

This means that you have either sent more than 10000 requests per day or more than one request within a 10ms window (!).

Specific Terms for the use of and/or access to the "Parcel DE Shipping API"

To register for the use of DHL Parcel DE Shipping API You and/or the legal entity you are authorized to represent (hereinafter "You"/"Your") need to have an active customer account with DHL Paket GmbH (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 Shipping 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 Shipping 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 Shipping API only for the legitimate contractual purposes and only in connection with Your DHL shipments.

The following prerequisites and/or restrictions apply for the usage of and/or access to the DHL Parcel DE Shipping API:

• The DHL Parcel DE Shipping API provides the possibility to create and print shipping labels and to book shipments. Please be aware that the booking of the shipment within DHL Parcel DE Shipping API does not constitute the contract of carriage. The contract of carriage will only be concluded when the shipment is handed over or picked up and accepted by DHL.
• Please note that the DHL Parcel DE Shipping API only facilitates shipments from Germany to Germany and from Germany to other countries as well as from Austria to Austria or from Austria to other countries. Creating shipping documents from abroad to Germany or Austria and from abroad to abroad is not possible via the DHL Parcel DE Shipping API .
• Please note, that the standard implementation of the functionality "Print Label and Export Documents" (createShipmentOrder) is as PDF label; an implementation according to the" Common Label specification" requires a separate approval by DHL.
• You need to configure your DHL business customer portal (account number or "EKP", procedures, products, services etc.) according to the necessities of the DHL Parcel DE Shipping API. If you act as a third party vendor or marketplace, these configurations need to be implemented for each shipping customer (merchant) individually.
• Credentials (user / password) for the DHL business customer portal need to be delivered/shared within the XML Request.
• When using the service "cash-on-delivery" ("Nachnahme") bank details (incl. BIC and IBAN data for national and international transfers) need to be delivered/shared within the XML Request.
• You shall implement the functionality "Cancel Shipment" (deleteShipmentOrder) within your Application.
• For all products value for the weight must necessarily be delivered. This value may have a predefined default value (only for contractually agreed fixed prices in procedure 01 ("Verfahren 01")) or consist of the specific weight of the shipment. Accordingly, the detection / default must be displayed in the e-shop or marketplace.
• You need to implement the functionality to cancel incorrect labels and have them generated correctly again.
• Non-codable shipments will result in extra charges of €0.30 per shipment (according to procedure 01 ("Verfahren 01")). Accordingly, the procedure must be clarified internally (Accept label without encodable address or cancellation and reprint after correction) and , if applicable, your customer/merchant needs to be informed.
• The delivery of shipments to a "Packstation", "Postfiliale Direkt"" and or a "Parcelshop" needs to be be implemented. For these services a 6-10 digit postal number ("PostNummer") is provided. Specific types of addresses have been defined for the recipient: "Packstation", "Postfiliale" and "ParcelShop".
• If you act as a third party vendor or marketplace a documentation of the interface is mandatory.

Please note the following additional guidance and recommendations:

• For one DHL product multiple billing numbers or participations ("Teilnahmen") can exist e.g. to distinguish locations, clients or promotions or to use on "GoGreen". If you act as a third party vendor or marketplace we recommend to provide multiple fields for the entry of billing numbers or participations ("Teilnahmen").
• If you act as a third party vendor or marketplace and do not wish to integrate all DHL products and services via the DHL Parcel DE Shipping API, we recommend that you additionally integrate a shortcut link to DHL's business customer portal. Your customers / merchants can then create shipping documents for non-integrated products directly or edit shipping documents created in your Application.
• Each package is exactly one (1) shipment. Please consider this shipping multiple items in multiple packages to one (1) recipient.

Access, Authentication, and Autorisation

Where can I find samples for authentication?

Please refer to the section on authentication at the [user guide] (https://developer.dhl.com/api-reference/parcel-de-shipping-post-parcel-germany#get-started-section/user-guide). This also has a curl example.

What authentication is needed for the "Try now!" function?

Two factors are needed. You need a valid api key (it looks like 7eelE1paJtbWvAKw0ROgVNLZak6rvEoD). For the basic auth part, you need GKP user and password. For try-out, use the known sandbox credentials (2222222222_01/pass).

My setup works for getVersion() but I get HTTP 401 for all other calls.

Please check the GKP credentials (they are provided via basic auth header). getVersion does not require those, but all other calls do.

I requested access and did not hear back for 48 hours or more.

Please reach out via contact form. Approval is not automatic as long as we are in beta.

Label Formatting and Printing

Can I modify the side margin when printing ZPL label?

A client reported successfully using the following: Before sending the received ZPL file to the printer, I add on the fly a ZPL command (^LS-30) just after the beginning of ZPL Data (^XA command).

Request Document

Do you support multi-piece shipments?

Not fully. There is limited support for that via the "costCenter" attribute if you need to group shipments.

ShipperRef attribute -- how to use

You need to set the reference to a shipper (address details) in the business customer portal and may then refer to this shipper via the shipperRef attribute. In that case, no shipper details are needed. If both are provided, the explicit information will be applied. Error message "CIG:Exception in extension function java.lang.IllegalArgumentException: is not known" is related to ShipperRef setting.

Weight

Shipment weight is important for billing. This is a mandatory attribute. You can provide shipment weight in either kg or g unit. If shipping internationally and needing customs data: Similar rules apply for individual item weights.

Dimensions

Providing dimensions (length, width, height) are optional. Adherance to product limitations will be checked by DHL. If you choose to provide that data, all attributs (unit of measure, length, height, width) are required.

Packstation Addresses

Please refer to sample included in the spec. A packstation destination is identified by providing the lockerID attribute.

address2 and address3 elements of the recipient address

Please check the API spec. Those elements are not printed for most labels. Exceptions include Parcel International labels for selected countries.

Label Download

How long are the labels available for download via /labels URL?

The labels are available for download until they have been manifested. After an initial download (and only then), the labels are being cached for currently 48 h. This means that labels can be downloaded for up to 48 h after manifesting. Note that after this time expired you receive HTTP 500.

Services

I set premium=false but PREMIUM is still printed on the label?

This is country-specific. Most EU countries do not offer economy products, so premium=true is applied. Other countries (CH) offer both.

COD (cash on delivery) - cannot provide the full bank account data

Depending on the GKP account privileges you may be required to create the account in the business customer portal and refer to it via accountRef attribute in the API.

Retoure international

This is NOT supported on this API. Please check the "online retoure API". You can create return labels for standard domestic parcels.

Retoure Services

This is a popular service, please refer to the samples included in the technical API spec and/or postman collection.

Notification

You can provide an email address and an optional (existing) email template reference here to notify about delivery progress. This functionality has been enhanced (template functionality) in June 2021 but the "old style" will work (but will fail JSON validation). Use validation if in doubt.

Customs Information

When providing customs information, do I need to provide it for each item I plan to ship?

Yes.

Will I need to provide customs information?

Depends on origin and destination address. Whenever shipping internationally and not covered differently. (E.g., You don't need it when shipping within the european customs union). Incomplete information may result in a backend errors 1101.

Manifest

GetManifest appears slow on the sandbox

The sandbox accounts are heavily shared. Therefore, the manifests can be extensive and slow to download. The production behavior is different since your manifests are exclusive.

Can I get a manifest for each billing number?

GET /manifests/{account}/ currently only supports one big combined manifest per EKP (customer number). The only parameter available is the manifesting date (if not provided, today's date is used). The manifest contains multiple sections and is sorted by billing number. For example, today's manifest (March 1 2021) currently has: Total of 73 pages. All relate to 2222222222 EKP. There are 8 sections, e.g. for 22222222220101, 22222222220104 billing numbers.

It is planned to enhance the functionality of manifesting to allow more flexible retrieval.

When is Manifest done? Do I have to do it?

It is done automatically at a preagreed time, usually the end of your work day. Afterwards shipments cannot be changed and labels (unless cached) cannot be downloaded. You can trigger manifesting explicitly via API as well.

Version

Do I need to call this?

This helps you as a quick connectivity check and also tells you the current version number. Part of the response is like "version": "v1.1.13" - the version of the API. Updates in the last component -- patch level -- will not be announced, they are guaranteed to be compatible.

Errors

General Hints

PLEASE use the validation switch available for POST /orders. It will tell you if you are missing an required elements, mistyped an attribute name and more. Please also use the postman collection (it does have samples for common requests). Please also note that the Swagger (OAS) descriptions contains working samples for most products (available via choice box when trying out a post).

I get an error message complaining "detail": "1101(Die Angabe der Zeile ist nicht möglich.)"

Likely you are getting the german error message when sending an Europaket V54EPAK with more than one goods categories per packet. This product allows only a single goods category.

I get an error message complaining "detail": "1101(Bitte geben Sie die Art der Sendung an)"

Likely you are getting the german error message when sending a Parcel International and you are missing required customs data. Please use validation, it will provide information on where the data is missing.

I get an error message complaining "detail": "1101(Der angegebene Service ist nicht bekannt)"

Likely you are getting the german error message when requesting a service which is either not known (check with validate=true please) or your account number + billing number information is not enabled for the service (e.g., Retoure). In that case please reach out to your DHL contact to check that.

I got an HTTP 500 error downloading a label from the URL returned by the POST call

Likely you are attempting to download a label after it has expiration. Please check the API spec on it. Before manifesting has been done there is also an alternative obtaining a label through the authenticated GET /orders call. This will also allow to obtain the label directly in the reponse plus many other options.

Warnings

I get an warning message complaining "detail": "0(Die angegebene Strasse kann nicht gefunden werden.)" or "detail": "0(Die angegebene Hausnummer kann nicht gefunden werden.)"

The address data could not be validated. You can use that label but DHL may incur extra charges (please check with your sales representative) to correct the address during processing. This also is indicated by a routing code on the label ending with 6 or more zeroes. To avoid this, please the query parameter mustEncode=true.

Other

I see there is also a dedicated Retoure API. What's the difference?

The Parcel Shipping API allows you as business customer to already provide a return label as part of the original outbound shipment. The Retoure API scope is different.

I see German error messages, is English also available?

Part of underlying systems in DHL may currently provide error details only in German. At the API layer this is mitigated where possible.

Currencies can be specified in the request, what can I use?

Please use EUR as currency, this is supported in all currency attributes.

For create, I am using the validate=true switch as recommended but I like the error messages better if I don't use it.

It is highly recommended to use validation initially. Validation will do two things:

• check the message syntax against JSON schema. This will tell you if the structure (and more) of your message looks good. Note that you can do this also offline by downloading the JSON schema [here] (https://developer.dhl.com/api-reference/parcel-de-shipping-post-parcel-germany#get-started-section/user-guide%other-information)
• do a dry-run against the backend. This will never create a shipment. However, you will get the same errors or success codes you would get with an actual shipment creation. As of v1.2.1, validate provides potentially additional error detail compared to create.

User-agent header

Please ensure that you are setting the user agent header to something unique. E.g., mydhlinterface/1.0.

Go-Live

I am an Easylog customer and want to migrate to REST. What do I need to know?

You should speak with your DHL sales representative. Likely you will need new billing numbers to avoid clashing number ranges between your Easylog shipments and shipments generated via API.

How long does it take to get certified to use the production environment? Is there a special procedure to follow?

This depends on the specifics. In general, you should plan for anything between 3 days and 1 month. There is no formal certification (we're in pilot mode) but suggest to cover:

• know how to retrieve the current version information
• be comfortable with the type of requests you will be creating in production, ensure that the products and services are covered
• use validation=true dry-run during testing prior to sending the actual request
• test other endpoints like delete /orders/${EKP} and the manifesting calls if you plan to use those
• ask DHL if things are unclear, we're happy to help and enhance
• set user-agent header

This can be all covered at your pace or you can ask DHL to observe a test scheduled at a convenient time for you. In both cases, please contact us, we'll double-check that your testing looks fine; your PROD credentials (EKP and billing numbers, other operational setup) appear correctly set up and will enable/approve your API key generally within 24 hours.

Will I use the same key for PROD and SANDBOX?

If you have requested access to both sandbox and production products in the same app, the same key will be typically be enabled for both PROD and SANDBOX. We can set you up based on your preferences. We can also add PROD access if you had originally only requested sandbox access.