Best for:
- Business customers of Post & Parcel Germany
- Create and manage shipment labes for domestic and international Parcels
Current note: The access data for the sandbox environment of all Shipping SOAP and REST API versions has changed. All necessary information can be found here.
Current note: Version 2 of the SOAP API Business Customer Shipping will be completely switched off on May 31, 2025.
Further information on the upcoming shutdown can be found here.
You are on the documentation page of the DHL Parcel DE Shipping 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 DHL Parcel DE Shipping API permits the management of shipments and the online purchase of postage and is typically aimed at senders with a volume of more than 200 shipments per year. For DHL business customers who do not have a DHL business customer account (EKP) and who have a shipping volume of less than 200 shipments per year, shipping documents are created via the DHL private customer shipping API.
Using the API
The DHL Parcel DE Shipping API takes care of:
- The preparation of shipping documents for national and international shipping
- Creation of export documents
- Retrieval of labels
General basics
To connect the DHL Parcel DE Shipping API to your systems, we would like to give you an overview on shipping of goods with Deutsche Post DHL for business customers.
To create business customer shipments, you (or your customer) need(s) a business customer contract and access to the Post & DHL Business Customer Portal (GKP). The DHL Parcel DE Shipping API must be set up precisely for these contractually agreed products and services. In addition, the user access data to the GKP, all used billing numbers, sender and return addresses and bank account data must be implemented as configurable attributes.
There are two types of users: system users and personal users. System users can be used for system connections or webservices only. Logging in to the GKP interface is not possible with them. Personal users, on the other hand, are created for the usage in the GKP GUI.
The access data to the GKP consists of a username and a password. The username can, for example, consist of first and last names and may only contain lowercase letters and certain special characters.
The password must comply with the Post & DHL Business Customer Portal guidelines in order to meet certain security criteria: It must be at least 8 characters and no more than 20 characters long, contain at least one special character (!,$,/,(,),=,#,*,+), at least one letter and at least one number. Be sure to use the correct upper- and lower-case spelling when entering the password.
Password validity is 365 days for system users and 90 days for personal users. Users will be informed by e-mail before a password expires and will also receive a link to assign a new password in this e-mail. If the link in the e-mail has expired or if a user has not received an e-mail, they can use the "Forgot Password?" function on the GKP login page (https://geschaeftskunden.dhl.de/) to assign a new password.
EKP: The EKP is a "uniform customer and product number" and thus the key to using Deutsche Post DHL products. It consists of ten digits and is created and assigned by the DHL sales team. Each customer can be uniquely identified via this EKP. It is required for all system connections and must always be transferred.
Contract Procedure: The products used for shipping are referred to as contract procedure. You can find more information about the products here.
Contract Participation: The so-called contract participation is a two-digit numeric (00 to 99) or alphanumeric (AA to ZZ) character string. It is assigned by the DHL sales team. For each product (so-called contract procedure) a customer can use one or more contract participations. It is therefore recommended to keep the number of contract participations variable when configuring the interface. The contract participations enable a subdivision, for example, according to locations, seasonal business or different conditions. In addition, certain services, such as environmentally friendly shipping with GoGreen, are also stored as separate contract participations.
Bank account data: Bank data is only required if the cash on delivery service is enabled. Details of IBAN, BIC, payee, bank name and reason for payment must be entered here.
Contract Billing Number: The billing number is a 14-character string. It consists of the EKP, the contract procedure (=product) and the contract participation. The correct spelling is without spaces or special characters (all 14 characters directly one after the other).
Example:
| 1234567890 | 53 | 01 |
| EKP | Contract Procedure | Contract Participation |
Label format and printing
The DHL Parcel DE Shipping API offers all label formats, which are also available in the Post & DHL Business Customer Portal. We would like to point out that scaling of the label is not permitted, as this no longer guarantees the legibility of the label. Shipments for which machine readability is not possible will be invoiced to the sender with an additional charge for the required manual post-processing.
The following label formats are currently available (printFormat):
- "A4" Common Label laser printing A4 plain paper
- "910-300-700" Common Label laser printing (sheet A5) 105x208mm (910-300-700)
- "910-300-700-oz" Common Label laser printing (sheet A5) 105x208mm, without additional labels (910-300-700)
- "910-300-710" Common Label laser printing105x209mm (910-300-710)
- "910-300-600" Common Label thermal print (folding tape labels) 103x199mm (910-300-600)
- "910-300-610" Common Label thermal print (roll) 103x199mm (910-300-610)
- "910-300-400" Common Label thermal print (folding tape labels) 103x150mm (910-300-400)
- "910-300-410" Common Label thermal print (roll) 103x150mm (910-300-410)
- "910-300-300" Common Label laser printing (sheet A5) 105x148mm (910-300-300)
- "910-300-300-oz" Common Label laser printing (sheet A5) 105x148mm, without additional labels (910-300-300)
Additionally, the label format 100 x 70 mm can be used, but exclusively for the products Warenpost and Warenpost International. Please note that some information cannot be printed on this label due to its smaller size. The following rules therefore apply to address data on this label format:
- Sender: Name 2 and Name 3 are not printed
- For German consignee addresses, Name 3 is is not printed
- For international addresses, 6 lines are printed, with the last line always being the consignee country.
Label printing with a thermal printer corresponds to a resolution of 203dpi. We ask you to take this into account accordingly so that a smooth production run is possible.
Note on the Returning the label as a pure data structure: Returning the label information as a pure data structure (e.g. in XML format) without returning the actual label is not possible via the DHL Parcel DE Shipping API. However, the web service response contains all data attributes generated by DHL that are printed on the label (e.g. shipment number, routing code).
Products and services via the web service interface
Products
Shipments can be created using the API function POST "/orders". All products are handed over in the web service attribute "product" and validated by the "contract procedure" in the contract billing number. The contract procedures and product codes to be used can be found in the following overview:
Services
Details and combinatoric
The following table contains an overview of the minimum and maximum dimensions and weights per product. The parameters for creating shipments must be within these limits. The listed parameters are standard values.
Available services per product
In the following table you will find all available services per product. They are divided into three service groups for the sake of clarity only. These groups are not part of the webservice requests.
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 Shipping 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: "user-valid", Password: "SandboxPasswort2023!") for authentication and additionally provide your API key (take it from the firstly generated APP) 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 Shipping 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 an Access Token:
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=${YOUR_API_KEY}&client_secret=${YOUR_API_SECRET}'
Once you have valid Access Token you can request the Shipping API.
A detailed description of the DHL Parcel DE Shipping API can be found in the "Open API Specification".
You can download the "Open API Specification" here. Use the shipping examples there, to make your first label:
curl -k -i -X POST -H "Authorization: Bearer ${TOKEN}" -H "accept: application/json" -d ${YOURREQUEST} https://api-sandbox.dhl.com/parcel/de/shipping/v2/orders?validate=True
Following billing numbers and services are available in the sandbox:
Production
To use the "DHL Parcel DE Shipping 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 department.
Environments
The addressable API base URL/URI environments are:
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.
The following table creates transparency about the deprecation dates of previous API versions. To clarify the terms, please see the explanations below.
| API Version | Status | Deprecation Date | Sunset Date |
|---|---|---|---|
| GKV 1.x (SOAP) | Retired | 01.11.2023 | 31.05.2024 |
| GKV 2.x (SOAP) | Superseded | 01.11.2024 | 31.05.2025 |
| GKV 3.x (SOAP) | Superseded | 01.07.2025 | 31.05.2026 |
| Parcel DE Shipping V1 (Pilot) | Retired | 01.01.2024 | 30.09.2024 |
| Parcel DE Shipping V2 | Active |
Terms and conditions:
Status "Active": Using this API Version is recommended.
Status "Superseded": The API has been replaced by a new API Version. The API is still supported without limitation. It is recommended to switch to the "Active" API Version.
Status: "Deprecated": The service has been ended (with or without a replacement becoming available). Support for this service is limited to bug fixes only.
Status: "Retired": The API is no longer available since sunset date.
"Deprecation Date": From this date on, the API will be in status "Deprecated". Further development will be only based on security updates and bug fixing.
"Sunset Date": The API is no longer available from this date on.
Known Issues
A list of known issues in the current version of Parcel DE Shipping API. We will endeavor to rectify this in the coming releases:
- Identification number for customs purposes is not printed on customs declaration
- Shipper's contact person is not printed on the shipping label when a sender reference is used
- Recipient email address is not displayed in shipping details
- For some attributes, a warning is given regarding the field length, even though the field length is within the given limits, the attribute is processed correctly and the shipping label is successfully created.
- For some technical errors, the structure of the error message deviates from the structure described in the YAML.
- The attribute shipmentRefNo is not returned in the response for multiple shipments within one request and the option validate=true
Notes
- If the request contains a multi element array (e.g. multiple shipments), then the order of the items in the response corresponds to the order of the items in the request. For consistency, if the request contains only one item then the response contains a single element array.
- You can save shipper addresses and assign them with a shipper reference in the DHL Business Customer Portal. Additionally, you have the option to upload a logo for a shipper address. In the web service request, you can then provide the shipper reference and do not need to separately provide the shipper address data. Please note that when providing a shipper reference, the address data stored for that reference will always be printed on the label. This applies even if you additionally provide explicit shipper address data in the request.
Access, Authentication, and Autorisation
Where can I find the documentation of the old Business Customer Shipping API (SOAP)?
The documentation of the old Business Customer Shipping API (SOAP) is available in the download area of the Group API Developer Portal.
Please raise a support ticket to get access. It is recommended to switch to the latest DHL Parcel Shipping API.
How to find the Download Area in the Group API Developer Portal: Navigate to your private settings via the person symbol at the top right and then activate the "Downloads" tab. You will then find the "Documentation Developer Portal" area after approval.
Where can I find samples for authentication?
Please refer to the section on authentication at the User Guide .This also has a curl example.
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() (GET call on API URI) 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 Help Center.. Approval is not automatic as long as we are in Early Access or Beta.
Encoding
What encoding should I use for API calls?
You should use UTF-8 encoding for all API calls. Using UTF-8 ensures that all characters are correctly interpreted and processed, especially if your data contains non-ASCII characters. Using a different encoding might result in errors or unexpected results.
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).”
Can I retrieve only the relevant data attributes instead of the label?
Returning the label information as a pure data structure (e.g. in XML format) without returning the actual label is not possible via the DHL Parcel DE Shipping API. However, the web service response contains all data attributes generated by DHL that are printed on the label (e.g. shipment number, routing code).
Request Document
Do you support multi-piece shipments?
No, multi-parcel shipments are not supported. To make it clear to your customers on the shipping label that several parcels belong to one order, you can use the “costCenter” attribute and enter “1/2”, “2/2”, for example.
ShipperRef attribute -- how to use
You need to set the reference to a shipper (address details) in the business customer portal under “Parcel & goods -> Ship -> Address book -> Sender” 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. A hard validation error with HTTP 400 occurs if the shipper reference is unknown.
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 API specification. A packstation destination is identified by providing the lockerID attribute.
additionalAddressInformation1 and additionalAddressInformation2 elements of the consignee address
Please check the API specification. 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?
Via the GET /orders call, labels can be retrieved again up to three days after manifesting. A specific shipment number must be added to the call.
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 AccountReference attribute in the API.
Retoure international
This is NOT supported on this API. Please check the Parcel DE Returns API. You can create return labels for standard domestic parcels.
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).
Northern Ireland is part of the European customs union. Therefore, shipments to UK containing postal codes starting with “BT” do not require customs information.
Manifest
Get / manifest appears slow on the sandbox
The sandbox accounts are heavily shared. All customers with a sandbox account can create shipments on the sandbox environment. The manifest-all call may apply to a large number of shipments and therefore, the call might take longer.
Please note: The production behavior is different since your manifests are exclusively related to your shipments.
Can I get a manifest for each billing number?
Yes, you can create a manifest for each billing number. To do this, use the “billingNumber” attribute in the “POST /manifest” call.Yes, you can create a manifest for each billing number. To do this, use the “billingNumber” attribute in the “POST /manifest” call.
When is Manifest done? Do I have to do it?
It is done automatically at a pre-agreed time, usually the end of your working day. Afterwards shipments cannot be changed and labels (unless cached) cannot be downloaded. You can trigger manifesting explicitly via API as well (POST /manifest).
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": "v2.0.2" - 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 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
"property": "customs",
"validationMessage" : "Specifiying this line is not possible."
"validationState": "Error"
Likely you are getting the error message when sending an Europaket V54EPAK with more than one goods categories per packet. This product allows only a single goods category (defined by the attribute “hsCode”).
I get an error message complaining
"property": "customs.exportType",
"validationMessage" : "Please enter the type of shipment."
"validationState": "Error"
Likely you are getting the error message when sending a Parcel International and you are missing required customs data.
I get an error message complaining
"property": "billingNumber",
"validationMessage" : "The selected billing number is invalid."
"validationState": "Error"
Likely you are getting the 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 expired. 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 response plus many other options.
Warnings
I get an warning message complaining
"property": "consignee",
"validationMessage" : "The street entered could not be found."
"validationState": "Warning"
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 six or more zeroes. To avoid this, please set the query parameter mustEncode=true..
Other
I see there is also a dedicated Retoure API. What's the difference?
The DHL Parcel DE Shipping API allows you as business customer to already provide a return label as part of the original outbound shipment. The Parcel DE Returns API scope is different. Please refer do the documentation of the DHL Parcel DE Returns API.
I see German error messages, is English also available?
Yes, English error messages are available. You can define the accept language in the header parameter of the request.
Currencies can be specified in the request, what can I use?
Please use EUR as currency for cash on delivery (COD). The customs form allows for any other currency as defined in ISO-4217.
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 the activation take to use the production environment?
You should have received the activation of the production API within 1-3 working days.
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 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.
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
Business hours: Mo-Fr 8 a.m. to 16 p.m.
Specific Terms for the use of and/or access to the "DHL 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 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 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 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 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. Creating shipping documents from abroad to Germany 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 Post & 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 Post & 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 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.
- TThe delivery of shipments to a "Packstation" or "Postfiliale Direkt" 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" and "Postfiliale".
- 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.
2.1.11 update
Introduction of the new GoGreen logos on the shipping labels.
2.1.11
Introduction of the authentication method OAuth2 parallel to the current Basic Auth. Later API versions will no longer support Basic Auth.
2.1.10
- The "status" attribute is added to the web service response. It contains the same value as the existing "statusCode" attribute. This backwards-compatible extension ensures conformity with RFC 7807.
- The attributes "name2" and "name3" are now printed on the label when a returns label is ordered.
- If a sender phone number is transmitted when ordering a dutiable international shipment, it will be printed on the CN23 form.
- Bug fix for GET /orders call for international shipments with service cash on delivery.
- When using Packstations, the shipment number to be scanned could often not be identified on the package label because the naming of the barcodes was not clear. Therefore, the barcodes are now labeled "Sendungsnummer" or "Shipment Identifier / numéro de l'envoi" instead of the old designation "Identcode/License Plate".
- On all domestic shipments within Germany and on all DHL Paket International shipments, weights over 10kg or over 20kg are now indicated. The new weight symbols are printed above the weight information on the labels.
2.1.9
The routing code of the consignee’s address is added to the webservice response.
Bug fix for retrieving labels of international shipments via GET /orders.
Bug fix for GET /manifests call with return type URL.
2.1.8
The Movement Reference Number (MRN) can now be transferred as an optional parameter in the request when ordering an international shipment.
In the customs declaration, up to 99 goods items can now be transferred in the request.
Correction of enum values of attribute “printFormat” of the objects “Document” and “GetManifestData”.
2.1.7
The service „shipping confirmation” has been removed from the section “value added services” (VAS). Please use DHL Parcel Notification instead.
The documentation of the “BadRequest” response object has been corrected.
2.1.6
The service shipping confirmation is deprecated and no longer supported. Please use DHL Parcel Notification instead.
2.1.5
In the new fields "shipperCustomsRef" and "consigneeCustomsRef" the identification numbers of the shipper and consignee can now be transferred for customs purposes.
The fields "permitNo" and "attestionNo" are now printed correctly on the customs documents.
2.1.4
- Correction of "Shipper" model for successful JSON schema validation when using a shipper reference
2.1.3
- Correction of the documentation for the schema objects: ServiceInformation, POBox, shipDate, dateOfBirth, preferredDay
- Correction of the status code for the endpoint /manifests: If there are no shipments for the daily closing, error code 200 is returned.
- Correction for service DHL return shipment: The shipment number of the return shipment is now included in the response attribute “returnShipmentNo”.
2.1.2
- The successful delivery of a DHL parcel to your front door is generally documented through the signature of our DHL courier. If you additionally need the signature of the recipient, you can order the service “Signed for by recipient” for individual shipments as of July 1, 2023. The service is already available in the sandbox.
2.1.1
- Documentation fixes for schema objects: servers, b64 property of object document and property hsCode minlength
- Ordering of shipping labels via a sender reference now possible again
2.1.0
- A daily manifest can now be performed for all shipments of a certain billing number (operation POST /manifest).
- When a daily manifest list is retrieved, the sheet numbers associated with the billing numbers and shipment numbers are now returned in the response (operation GET /manifest).
2.0.2
- Initial Release
Coming from the original Parcel Business Customer Shipping API (SOAP) including the following operations (SOAP API calls):
- getVersion: With this operation the latest version available on the web can be queried.
- validateShipment: With this operation the data for a shipment can be validated before a shipment label and tracking number will be created.
- createShipmentOrder: This operation creates shipments for DHL Paket including the relevant shipping documents.
- updateShipmentOrder: With this operation shipping documents are updated for previously created shipments. The update automatically performs a cancellation and creating of a shipment.
- deleteShipmentOrder: This operation cancels earlier created shipments.
- getLabel: This operation hands back the shipping label for previously created shipments.
- getExportDoc: This operation hands back export documents for previously created shipments.
- doManifest: With this operation a end-of-day closing for up to 30 previously created shipments can be carried out.
- getManifest: With this operation end-of-day reports are available for a specific day or period.
This API provides equivalent REST endpoints, and attempts to closely replicate the original functionality.
Naming of API resources
The API is following URL naming conventions based on this scheme: https://api${environment}.dhl.com/${business_unit}/${domain_name}/${version_id}/${resource}/
For this API, this means:
https://api-eu.dhl.com/parcel/de/shipping/v2/orders/ andhttps://api-eu.dhl.com/parcel/de/shipping/v2/manifests/
Endpoints
The new API endpoints for the above mentioned old SOAP API calls are:
//orders/manifests/labels
Please have a detailed look at the mapping:
| Resource | Operation | Maps to | comments |
|---|---|---|---|
| / | GET | getVersion | API version and health check |
| /orders | GET | getLabel and getExportDoc | retrieve documents (label, returnlabel and customs documentation) |
| - | POST | createShipmentOrder | Validation or creation of new shipments. This is the primary function of the shipping API. |
| - | DELETE | deleteShipmentOrder | Delete an existing shipment. |
| /manifests | POST | doManifest | Close out the daily processing for selected shipments. |
| - | GET | getManifest | Download the manifesting document. |
| /labels | GET | downloadLabel | Abrufen der PDF-Etiketten von einer öffentlichen URL. Die URL ist Teil der Antwort auf den Aufruf von POST /orders |