DHL Express MyDHL API

DHL Express - MyDHL API Integration Requirements

Shipping Requirements

All shipments require both weight and dimensions.

Connection Requirements:

You must have an active account with DHL Express - MyDHL API.

The following properties are required to connect your account.

Property	Type	Description
`dhl_shipper_number`	string	Your DHL Shipper Account Number
`api_key`	string	Your DHL account API key
`api_secret`	string	Your DHL account API secret

Optional Connection Elements

The following properties are optional to add in the request when you connect your account.

Property	Type	Required?	Description
`dhl_duties_taxes_number`	string	Optional	Your DHL Duties Taxes Account Number
`dhl_location_finder_api_key`	string	Optional	Your DHL Location Finder API Key
`go_green_plus`	boolean	Optional	Select this option to default GoGreen Plus on all orders. Applies to International deliveries only.
`use_my_own_commercial_invoice`	boolean	Optional	Print my own commercial invoice rather than the DHL invoice (not eligible for paperless trade).
`provide_commercial_invoice_outside_of_auctane`	boolean	Optional	* Provide my own commercial invoice electronically to DHL outside of Auctane.
`shipper_business_party_role_type`	string	Optional	* * Business party type of the shipper.
`return_label_validity_period`	string	Optional	* * * Return Label/QR Code Validity Period

Property Descriptions

* use_my_own_commercial_invoice. Using this property, you agree, "I will ensure my commercial invoice is provided electronically to DHL to support paperless trade shipping. I understand that shipments cannot be transported without the commercial invoice being provided to DHL electronically, and where necessary, printed and affixed to the package for non-paperless trade shipments."
** shipper_business_party_role_type. This information is used for international shipping and placed on the commercial invoice for compliant customs clearance. Allowed values are: business, direct_consumer, government, other, private, reseller.
* * * return_label_validity_period. Defines the duration that return shipment data information is stored in the carrier’s systems and the return label or/and QR Code remains active and can be used. Allowed values are: 3 months, 6 months, 12 months, 24 months, PT, PU, PV, PW.

Connect a DHL Express MyDHL API Account to ShipStation

To connect your DHL Express MyDHL API account to ShipStation:

Go to Account Settings.
Select Shipping, then choose Carriers from the sidebar.
Click the Your Carrier Accounts tab.
Click the Add Carrier button.
Select DHL Express MyDHL API and click Connect.

You can type 'DHL Express MyDHL API' into the search bar also,
Enter your DHL Express MyDHL API

DHL Shipper Account Number,

API Key, and

API Secret into the corresponding required fields.

Optional: You may also enter your string values for

dhl_duties_taxes_number,

dhl_location_finder_api_key,

shipper_business_party_role_type,

return_label_validity_period

and the Boolean values for

go_green_plus,

use_my_own_commercial_invoice, and

provide_commercial_invoice_outside_of_auctane, although they are not required.
Click Connect.

Available Features for DHL Express - MyDHL API Integration

The ShipStation integration with DHL Express - MyDHL API supports the following standard features and services:

Common ShipStation Features

Feature	Supported?
Domestic Shipping
International Shipping
Electronic Customs Submission
Return Labels
Estimated Rates
Carrier Insurance
Tracking
Third-Party Billiing
End of Day (Electronic)
End of Day (PDF)
Label Branding
Label Messages
Multi-package Shipping
Multiple Accounts
Support for Unicode characters (Kanji, Cyrillic, etc.) on labels
Supports Pickup / Dropoff (PUDO)

DHL Express MyDHL API Domestic Services

Service Name	API Code
DHL Domestic Express	`dhl_express_mydhl_domestic_express`
DHL Domestic Express 09:00	`dhl_express_mydhl_domestic_express_09`
DHL Domestic Express 12:00	`dhl_express_mydhl_domestic_express_12`
DHL Domestic Express - Service Point	`dhl_express_mydhl_domestic_express_service_point`
DHL Domestic Express 09:00 - Service Point	`dhl_express_mydhl_domestic_express_09_service_point`
DHL Domestic Express 12:00 - Service Point	`dhl_express_mydhl_domestic_express_12_service_point`

DHL Express MyDHL API International Services

Service Name	API Code
DHL Economy Select (nondoc) - Service Point: H_TV	`dhl_express_mydhl_economy_select_nondoc_service_point`
DHL Economy Select (nondoc): H	`dhl_express_mydhl_economy_select_nondoc`
DHL Express 09:00 (doc) - Service Point: K_TV	`dhl_express_mydhl_express_09_doc_service_point`
DHL Express 09:00 (nondoc) - Service Point: E_TV	`dhl_express_mydhl_express_09_nondoc_service_point`
DHL Express 09:00 (doc): K	`dhl_express_mydhl_express_09_nondoc_service_point`
DHL Express 09:00 (nondoc): E	`dhl_express_mydhl_express_09_nondoc`
DHL Express 10:30 (doc) - Service Point: L_TV	`dhl_express_mydhl_express_1030_doc_service_point`
DHL Express 10:30 (doc): L	`dhl_express_mydhl_express_1030_doc`
DHL Express 10:30 (nondoc) - Service Point: M_TV	`dhl_express_mydhl_express_1030_nondoc_service_point`
DHL Express 10:30 (nondoc): M	`dhl_express_mydhl_express_1030_nondoc`
DHL Express 12:00 (doc) - Service Point: T_TV	`dhl_express_mydhl_express_12_doc_service_point`
DHL Express 12:00 (doc): T	`dhl_express_mydhl_express_12_doc`
DHL Express 12:00 (nondoc) - Service Point: Y_TV	`dhl_express_mydhl_express_12_nondoc_service_point`
DHL Express 12:00 (nondoc): Y	`dhl_express_mydhl_express_12_nondoc`
DHL Express Worldwide (doc) - Service Point: D_TV	`dhl_express_mydhl_express_worldwide_doc_service_point`
DHL Express Worldwide (doc) - Service Point: D_TV	`dhl_express_mydhl_express_worldwide_doc_service_point`
DHL Express Worldwide (doc): D	`dhl_express_mydhl_express_worldwide_doc`
DHL Express Worldwide (nondoc) - Service Point: P_TV	`dhl_express_mydhl_express_worldwide_nondoc_service_point`
DHL Express Worldwide (nondoc): P	`dhl_express_mydhl_express_worldwide_nondoc`
Economy Select EU - Service Point: W_TV	`dhl_express_mydhl_economy_select_eu_service_point`
Economy Select EU: W	`dhl_express_mydhl_economy_select_eu`
Express Worldwide EU - Service Point: U_TV	`dhl_express_mydhl_express_worldwide_eu_service_point`
Express Worldwide EU: U	`dhl_express_mydhl_express_worldwide_eu`

DHL Shipping Unavailable to US Territories

Services for DHL (Express and Ecommerce) and DHL Express by ShipStation no longer support shipments to US territories.

Package Types

Name	Abbreviation	API Code	Package Attributes
3BX	3BX	`dhl_express_mydhl_3bx`	Domestic, International
2BC	2BC	`dhl_express_mydhl_2bc`	Domestic, International
2BP	2BP	`dhl_express_mydhl_2bp`	Domestic, International
CE1	CE1	`dhl_express_mydhl_ce1`	Domestic, International
7BX	7BX	`dhl_express_mydhl_7bx`	Domestic, International
6BX	6BX	`dhl_express_mydhl_6bx`	Domestic, International
4BX	4BX	`dhl_express_mydhl_4bx`	Domestic, International
2BX	2BX	`dhl_express_mydhl_2bx`	Domestic, International
1CE	1CE	`dhl_express_mydhl_1ce`	Domestic, International
WB1	WB1	`dhl_express_mydhl_wb1`	Domestic, International
WB3	WB3	`dhl_express_mydhl_wb3`	Domestic, International
XPD	XPD	`dhl_express_mydhl_xpd`	Domestic, International
8BX	8BX	`dhl_express_mydhl_8bx`	Domestic, International
5BX	5BX	`dhl_express_mydhl_5bx`	Domestic, International
WB6	WB6	`dhl_express_mydhl_wb6`	Domestic, International
TBL	TBL	`dhl_express_mydhl_tbl`	Domestic, International
TBS	TBS	`dhl_express_mydhl_tbs`	Domestic, International
WB2	WB2	`dhl_express_mydhl_wb2`	Domestic, International
Your Own Package	YOP	`dhl_express_mydhl_yop`	Domestic, International

Delivery Confirmation

The following Delivery Confirmation types are available.

Confirmation Type	API Code	Carrier Code	Description
No Signature Required	`request.confirmation=None`	N/A	No mapping to the carrier API. Signature is included in the services
Signature Required	`request.confirmation=Signature`	SX	Signature is required for the shipment to be delivered. This signature may be a neighbor, building manager, or the recipient can authorize the release of the package (without being present).
Adult Signature	`request.confirmation=AdultSignature`	SD	Requires a signature from someone 21+ with government-issued photo ID upon delivery. It is commonly used for alcohol, tobacco, firearms, or high-value items.
Direct Signature	`request.confirmation=DirectSignature`	SF	Commonly used for valuable or sensitive items that require guaranteed delivery to the specified, authorized recipient.

Additional Features for DHL Express MyDHL API

The ShipStation integration with DHL Express MyDHL API allows for the following additional features:

Feature	Description
Contains Dry Ice	You can send shipments that contain dry ice. `advanced_options.DryIce`
Saturday Delivery	Saturday Delivery available: `advanced_options.saturday_delivery`
Duties Taxes Paid	`advanced_options.duties_taxes_paid`
Bill Duties to Sender	`advanced_options.bill_duties_to_sender`
Paperless Invoice	`advanced_options.paperless_invoice`
Direct Signature	`advanced_options.DirectSignature`
Delivery to Neighbour	`advanced_options.delivery_to_neighbour`
Windsor Framework Details	`advanced_options.windsor_framework_details.movement_indicator`
300 DPI label	`advanced_options.label_300dpi`
Label Branding	ShipStation supports Label Branding for this integration. You can enable it by following these steps: Upload Logo: Go to Settings > Store Setup, select the specific store, and open the Branding tab. Under General Branding Settings, upload a file to the Store Logo section. Enable Printing: Go to Settings > Printing Setup. In the label layout settings, locate the Label Branding section and check the box that reads, Print my store logos on my shipping labels.

Customs Declarations

DHL commercial invoices are available to download from the forms_download object in the label response.

Shipments to the UK need to have Freight Costs on the Commercial Invoice.

When you connect the carrier account to ShipStation API, you can select the option Use my own commercial invoice. The default integration behaviour is to apply Paperless Trade/Automated Digital Imaging (PLT/ADI) on all orders. By selecting this option, you can turn it off and use your own commercial invoice or a fully non-PLT flow.

Paperless Trade (PLT)

Paperless Trade (PLT) is the regulatory term used when a customs regime will accept either data or electronic images to perform the customs clearance. For PLT shipments, the shipper only needs to print the transport label. No customs paperwork needs to be printed and handed over to DHL.

Non-PLT countries require a physical hardcopy of the paperwork to be provided by the shipper and affixed to the package to ensure it was not altered or manipulated during transit. Wherever accepted, usage of the Paperless trade service is mandatory. There are a few scenarios where the shipment won’t be eligible for PLT, typically one of the following:

a) one of the countries in the origin/destination pair doesn’t support PLT, or
b) the declared value exceeds the maximum value allowed for one of the countries.

Automated Digital Imaging (ADI)

Automated Digital Imaging (ADI) is a benefit for Non-PLT shipments to reduce physical paperwork printing. DHL automatically stores the commercial invoice and waybill doc images and makes them available to authorized DHL staff globally. Therefore, to be compliant for non-PLT shipments, the shipper simply needs to print a copy of the commercial invoice and affix it to the sleeve on the package.

Use my own commercial invoice is not selected (OFF)

Enter your Company Name. Use your Acumatica Tenant Name in this field.

When Use my own commercial invoice is not selected (off), ShipStation API sends to the myDHL API a special service code WY** with bypassPLTError** feature on. It works for the following services only:

DHL Express Worldwide (nondoc) - P,

DHL Express 09:00 (nondoc) - E,

DHL Express 12:00 (nondoc) - Y,

DHL Economy Select (nondoc) - H,

DHL Express 10:30 (nondoc) - M, and

DHL Medical Express (nondoc) - Q

The WY special service code denotes the shipment as PLT, and the availability of the invoice data and DHL-generated invoice meets the data and image validation criteria for PLT. No need to print anything other than the transport label for the package.

**bypassPLTError - The default behavior of the DHL API is to return an error if PLT is requested but not available. The bypassPLTError feature will process the shipment successfully, convert the shipment from PLT to ADI, and return a warning message to print the customs paperwork as opposed to returning an error.
Use my own commercial invoice is selected (ON)

When Use my own commercial invoice is selected (ON), then neither the WY special service code nor the bypassPLTError feature is used. The shipper will be on fully manual/non-PLT, and will need to physically print the commercial invoice and give the paperwork to the carrier. For this scenario, ShipEngine will request the waybill document on all shipments from myDHL API as well as the commercial invoice doc. Waybill Docs are required to print and give to the carrier, along with a hard copy of the commercial invoice for shipments that aren’t processed as PLT or ADI.

For merchants who want to control which particular international shipments they apply a PLT solution to, use another configuration. Select the Use my own commercial invoice option and set the shipment parameter advanced_options.paperless_invoice to true. With this setup, only the shipment with this advanced option selected will be sent with the WY special service code. The bypassPLTError feature would not be applied. If the PLT is not available for a particular shipment, then you will receive an error from the carrier's API.

To avoid violating the arrangements with the carrier, it is important to remember that the configuration of the ShipEngine/ShipStation/DM/MPM or any other internal generic commercial invoice document is not allowed for this integration.
Find more information on pages 20-24 of the carrier’s Solution Provider Companion Guide.

Shipping from Great Britain to Northern Ireland

DHL Express MyDHL API will support the B2B movement types for shipping from Great Britain to Northern Ireland, in accordance with the Windsor Framework.

To comply with the Windsor Framework, the following changes are required for the Non-Document shipment creation process.

Change the DHL product code in the request from N to 3.
Flag the shipment as being dutiable in the request.
Provide Invoice Line-Item data.
For B2B shipments sent on the Green lane, a UKIMS number with registration type code IMS is required in the registrationNumbers section of the API request.
For B2B shipments sent on the Red lane (and preferred for the Green lane), you are required to use paperless trade (PLT) to provide a copy of the invoice.
No changes are required for Document shipments.

For more information, see Implementing a DHL Integrated Solution: Windsor Framework Requirements with My DHL API.

Scheduling Pickups

DHL Express MyDHL API supports scheduling pickups, as well as Pickup canceling, with no cancellation fees.

When scheduling pickups:

The date should not be a past date or a date more than 10 days in the future.
The time is the local time of the shipment based on the shipper's time zone.

Return Services

During carrier account setup, merchants can select the Return Label/QR Code Validity Period. This setting determines how long return shipment data is stored and how long labels or QR codes remain active for use.

The allowed validity periods are:

3 months
6 months
12 months
24 months

The carrier offers a Label-free shipping feature where the driver prints the label upon pickup via a QR code. However, the carrier advises against this for high-volume shipments, as they will not print labels for large quantities.

Returns are only available with the following services:

DHL Express Domestic - N
DHL Economy Select (nondoc) - H
DHL Express Worldwide (nondoc) - P
DHL Economy Select EU - W
DHL Express Worldwide EU - U

Dangerous Goods - DHL Express MyDHL API

To send Dangerous Goods (DG) shipments with DHL Express MyDHL API, customers must have approval on their DHL Account Numbers. Approval is given for specific ServiceCodes/ContentIds (Contract sign off).

If merchants send DG shipments without having approval/contract, then those shipments will be stopped in the DHL facility.

See the ShipStation API Dangerous Goods page to learn which dangerous goods objects and properties you should use, about properties required by various carriers to indicate you are shipping dangerous goods (DG), and how to remain in compliance with the carrier's dangerous goods shipping requirements.

Create a Dangerous Goods Shipment

To create a DG shipment, the following DHL-specific values are required in the request: [DangerousGoods.ServiceCode] and [DangerousGoods.ContentId].

DHL customers will likely need to have logic to 'calculate' ContentId/ServiceCode - similar to the one available in ShipStation API.
Some specific use cases will also require a UN Number, Special Provision (CustomDescription), or DryIceNetWeight (DryIce).

For specific Request elements, see the DHL Express Dangerous Goods.pdf.

Notes about Dangerous Goods Shipments

The customer is responsible for the correct packaging of the shipment, including additional labels, stickers, and documents (as required by the Dangerous Goods regulations).

ShipStation API-implemented logic to calculate ContentID/ServiceCode is based on the DangerousGoods data provided in the request. Logic covers the vast majority of potential use cases. However, we are not able to calculate some ContentIds.

Any regulation changes (ADR/IATA) might trigger changes on the DHL side and consequently. ShipStation API logic to find/calculate ContentId/ServiceCode. In that case, additional Analyst/DEV work might be required to accommodate the new regulations.

Please see the DHL Shipping dangerous goods: Guidelines and best practices page for more details.
See also the MyDHL API Reference data guide - 2.8.0.pdf page.