MyDHL is a web service from DHL, one of the major logistics providers globally.
In this article, you will learn how to connect MyDHL to ShippyPro and add additional options such as a return label in the box or paperless trade to your existing connection. ✨
Summary:
1. Before you start
Register on the DHL Developer Portal
To proceed with the connection, you need to have an API Key, an API Secret and an Account Number that you can retrieve by registering to the DHL Developer Portal if you don't have one yet.
Fill out the DHL onboarding form
Go to APIs > Browse all services
Click on DHL Express - MyDHL API
Then on Get Access
Fill in your company data.
At "How would you like to use the API?" inside the DHL registration page, you should select the option "I require credentials to DHL Express – MyDHL API for an existing plugin/ecommerce platform/third-party solution" and simply add ShippyPro.
Concerning the section called "Requested Services", please tick over all the services available. The field named "Transaction volume per month" is only useful to DHL for statistics purposes, therefore it won't influence you on the use of the API.
After some hours you can check your DHL Developer profile where you should be able to see your App Status as approved.
Then, click on DHL EXPRESS – MYDHL API under App Name where you will Request Production Access on a red button. Once you click it, you will receive confirmation that the request has been sent within minutes and the local DHL team will need to approve it according to their timeline.
In case the request remains pending please contact DHL directly in order to speed it up.
Please also refer to DHL guide step-by-step guide here in case of questions or doubts.
2. Connect MyDHL to ShippyPro
Now that everything is correctly set up in MyDHL portal, you're ready to connect it to ShippyPro.
Navigate to Carriers > Connection and click on MyDHL Logo (simply type "MyDHL" on the search bar to spot it in a sec).
If you do Cash on Delivery shipments, remember to flag the checkbox "I confirm that I am aware of the below message":
Enter your API key, API Secret and Account Number
❗❗ Be sure that you avoid inserting spaces when you copy and paste, otherwise you will see the error "Invalid Credentials"
Pick your label type and your product code. Remember to ask your DHL Account Manager which are your active product codes. If you'd like to add multiple services, you'll need to create a new connection for each one.
Label Format | PDF A6 PDF A4 ZPL |
Product Code | ALL SERVICES EXPRESS 9:00 DOC (TDK) EXPRESS 9:00 NONDOC (TDE) EXPRESS 10:30 DOC (TDL) EXPRESS 10:30 NONDOC (TDM) EXPRESS 12:00 DOC (TDT) EXPRESS 12:00 NONDOC (TDY) EXPRESS DOMESTIC (DOM) EXPRESS DOMESTIC 9:00 (DOK) EXPRESS DOMESTIC 10:30 (DOL) EXPRESS DOMESTIC 12:00 (DOT) ECONOMY SELECT DOMESTIC (DES) EXPRESS WORLDWIDE DOC (DOX) EXPRESS WORLDWIDE NONDOC (WPX) EXPRESS WORLDWIDE EU (ECX) FREIGHT WORLDWIDE (FRT) ECONOMY SELECT EU (ESU) EXPRESS ENVELOPE DOC (XPD) MEDICAL EXPRESS DOC (CMX) MEDICAL EXPRESS NONDOC (WMX) EXPRESS JUMBO (WPX) SAME DAY (SDX) |
Please note that the service EXPRESS WORLDWIDE NONDOC is for merchandise only and EXPRESS WORLDWIDE DOC service is meant for documents, not other kinds of physical goods.
📌If you'd like to include multiple services in the same carrier connection you'll need to select Product Code: ALL SERVICES.
3. Additional Options
🔁 Enable Return Label in the box
If you’d like to print shipping and return labels together while you ship your orders (return label in the box), add your DHL Return Account Number inside the DHL Account Number field and your Account Number in the DHL Return Account Number field. Then tick Enable Return Label in the box option at the bottom and confirm. Please note that the label format will be the one you chose for outbound shipments since it cannot be changed for return labels.
📌 If you’d like to make Returns separately from the main shipment, you need to create a new MyDHL connection. This time, insert your Return Account Number in the Account Number field and your Account Number in the DHL Return Account Number field. So basically, the exact opposite of the first set-up. Do NOT tick the Enable Return Label in the box option. Finally you can create your manual shipment for the Return: click here to learn how.
By selecting Fixed Return Receiver Address (Only for 'Enable Return Label in the box'), if Enable Return Label in the box option is checked and an address is selected from the dropdown menu, the labels in the box are redirected not to the sender address, but to the address set in the dropdown.
You can add and edit the available address at any moment from Admin > My Addresses and parcels > My addresses.
🌱 Paperless Trade
You can also decide to enable the Paperless documentation option by ticking "Paperless Trade" and uploading your ETD invoice from "Invoice Manager" section, or via UploadPaperlessDocumentation API call.
🧾 Print commercial invoice
This option will allow you to automatically generate your commercial invoices for international shipments. By selecting this option, you won't have to enable the paperless checkbox in the modal - the ETD will be generated together with the shipping label!
🗓 Extend label validity
This service is usually used for return labels, and it will add the extension RET on the label created by MyDHL.
By selecting the Extend label validity option, you can extend the duration of a label without knowing the actual date of handling to the Carrier
🚚 Add freight charges to commercial invoice
If you select this option, the shipment costs will be added to the commercial invoice.
🧪 Test Mode
Enable the Test Mode if you'd like to make some test shipments. Please keep in mind that this option should be flagged only if you have test credentials, not production credentials!
⚠️ Dangerous Goods
For each shipment containing Dangerous Goods you must insert the contentId of the shipped dangerous goods.
If the shipment contains Dry Ice UN1845 you must insert the weight of the transported dry ice.
If the goods are in Excepted quantities in accordance with IATA, you must insert also the UNCode of the dangerous goods, available here.
✍🏻 Custom Label
If you want, you can also enter a Custom Label to recognize the connection among all the others.
📆 Default amount of additional weekdays required to prepare the shipments
The default amount of days required is 1 day, you can change it as you please by selecting the number of required days. The system will automatically skip bank holidays and weekends in the required days count.
❗Make sure to do this on all your myDHL connections, even though you might use only one service.
4. Errors & troubleshooting
While trying to connect MyDHL or while using it to ship your orders, you might experience some errors. No panic: keep reading to discover how to fix them! 🧑🔧
For more info and tips on errors on MyDHL connection please consult our step-by-step guide here.
Requested product not available for pickup date
In case the next day is a Bank Holiday, you might receive this error, as the system picks up the next day for pick-up by default. Make sure to change the value "Select the default amount of additional weekdays required to prepare the shipments" to 2 or more days from Carriers > Connection > myDHL > Edit for all your myDHL connections (not only the one you are using for the specific shipment)
7008: The requested Special Service Code: #/valueAddedServices/0/serviceCode ‘WY’ is not available between this origin and destination. Please validate the products and services combination (via the /rates or /products service) or contact our customer service.
This error appears when:
You activate the Paperless option for a non-taxable shipment (such as a domestic or intra-EU shipment).
The Paperless option is not available for that extra EU destination. In this case, try to flag the Print Commercial Invoice option in the connection modal of the carrier and reprocess the shipment.
7120: Required either #/outputImageProperties/imageOptions where typeCode=invoice or provide #/documentImages
The error message indicates that you need to activate the flag "Print Commercial Invoice" in the carrier modal (from Carriers > Connections > Edit) OR to upload the ETD file.''100002: Null Validator: SHIPMENT_ID not found in request map., 100002: Null Validator: SHIPMENT_ID_CHECK_DIGIT not found in request map.''
This error message refers to an internal DHL problem that does not allow AWB and JJD number assignment. Usually this is a temporary failure.If the malfunction persists, please contact your DHL representative.
Error Da rielaborare: #/customerReferences/0: required key [value] not found, #/outputImageProperties/customerBarcodes/0: required key [content] not found
In this case, please make sure to have correctly added the order ID as it's considered as mandatory info for the Carrier.
Da rielaborare: 1001: The requested product(s) (P) not available based on your search criteria.(409224511)
The indicated destination city is invalid: eg. "cityName": "NA". You can check the postcodes and locations accepted by myDHL system at this link: https://dct.dhl.com/
Da rielaborare: 1001: The requested product(s) (W) not available based on your search criteria
The indicated service is not eligible to be used for the shipment in question. Please choose another service and try again to ship the order.
410138: Requested product(s) not available at payer, H/-
The Product Code (meaning the DHL service) is wrong. Please check it with your DHL representative and select the correct one.
Invalid Credentials
In this case, always check if you input the correct credentials, and pay extra attention if you added an extra space in the API Key or API Secret. You can check the settings from Carriers > Connection and, once the Carrier is selected, click on Edit.
Value is shorter than minimum length
Either sender's VAT number or recipient's IOSS number is missing from your profile
MyDHL - error 8009: Shipper Billing Country must either be same as Billing Country of Shipment Origin or the Shipper Account must be an Impex Account
In case you’re making return shipments with MyDHL, the problem could be related to the fact that you haven’t set a return acount number from your MyDHL connection modal.For more info on how to correctly configure your account for the return shipments, please check out the section 🔁 Enable Return Label in the box in this guide.
MyDHL - Unedfined Error. Status code: 400
This happens mostly when your API credentials have not been activated on DHL's side: if you encounter this error, please double check in your account on DHL's developer portal if your API credentials have been activated for production, or request assistance to your DHL representative.#/content: required key [description] not found.
Select in the profile preferences as the reference number our Shippypro number.
Also, check if there are no gaps in the call made (whether you ship through the platform or via API).
Unable to send this shipment with the selected rate. Please try again or use a different rate.
It is not possible to Fix the order. You should either push the order back on To Ship, create a manual shipment, or repeat the Ship call.
In case you're shipping via API and you selected ALL SERVICES in the connection module, it's necessary to obtain both the CarrierService and RateID via GetRates call, and then include those two fields in your Ship API request.In case you selected a specific service in the connection module, you don't need to include RateID in the Ship request.
7121: #/content/exportDeclaration is mandatory when provided product is dutiable, please update and try again.
Select Paperless Trade in the carrier configuration under Carriers > Connection. Also remember to include all the information relating to the CN22 so that the parcel is processed correctly at customs controls.
My live rates for DHL are not displayed at the checkout screen in Shopify! Why?
Don’t worry, the solution to this might be very easy! Please make sure that your return address is not longer than 45 characters, if necessary you can split it between the two dedicated address fields. If the issue persists you can contact our Support Team for further assistance.