References

Division: DHL eCommerce

This guide provides a comprehensive description about our products, features, keywords and rules.

Region: United States

Domestic Products

Product ID	Product Name(s)	Notes
EXP	DHL SmartMail Parcel / Parcel Plus Expedited
MAX	DHL SmartMail Parcel Expedited Max
GND	DHL SmartMail Parcel / Parcel Plus Ground
BEX	DHL SmartMail BPM Expedited	No rates from API
BGN	DHL SmartMail BPM Ground	No rates from API

*Product Name field is subject to change and should not be used to uniquely identify and select products. Please only use the Product ID.

International Products

Product ID	Product Name	Notes
PLT	DHL Parcel International Direct
PLY	DHL Parcel International Standard
PKY	DHL Packet International
PIY	DHL Parcel International Direct Priority	CA to US only
PID	DHL Parcel International Direct Standard	CA to US only
PIX	DHL Parcel International Direct Max	CA to US only

Return Products

Product ID	Product Name(s)	Notes
RGN	DHL SmartMail Parcel Return Ground	No rates from API
RPL	DHL SmartMail Parcel Return Plus	No rates from API
RLT	DHL SmartMail Parcel Return Light	No rates from API

International Regulations

	PLT	NON PLT
Consignee phone number	Required for Hong Kong, Japan, Israel, South Korea, & Mexico; recommended for other countries in case contact is needed	Recommended for all countries in case contact is needed
Consignee email address	Required for Japan; recommended for other countries in case contact is needed	Recommended for all countries in case contact is needed
Consignee state	Required for Canada, Australia and Israel	Required for Canada, Australia and Israel
Consignee ID/ID type	Not required	Not required
Consignee taxID/taxID type	Recommended for Israel, Mexico, & South Korea. If not provided, it will cause delays at customs as our delivery partner will attempt to contact the consignee via phone/email and hold the package until Tax ID is collected	Recommended for Brazil, Mexico, and Indonesia. Failure to provide an ID number may result in a hold or rejection in customs
Shipper phone number	Recommended for all countries in case contact is needed	Recommended for all countries in case contact is needed
Shipper email address	Recommended for all countries in case contact is needed	Recommended for all countries in case contact is needed
Shipper taxID/taxID type	Recommended depending on annual revenue and order value to UK, European Union, Australia, Germany, Singapore & New Zealand	Recommended depending on annual revenue and order value to UK, European Union, Australia, New Zealand, Germany, Switzerland, Singapore, Malaysia & Norway
HS code	Not required	Strongly recommended for all EU countries. May result in delays or returns if not provided.
Duties paid	May be true (DDP) or may be false (DDU)	Must be false (DDU)

Updated March 25, 2024

Distribution Centers

distributionCenter is a mandatory field in both the Label API and the Rating API.

In the Rating API,

For an International Rate request

distributionCenter provided in the request is not used in rate calculation.

For a Domestic Rate request

if the distributionCenter is used to determine the origin zone for rate calculation.

If pickup account is not designated as a dropoff, then the distributionCenter is not used in rate calculation.

Facility Code	Location
USATL1	Mableton, GA
USBOS1	Westborough, MA
USBWI1	Manassas, VA
USCAK1	Stow, OH
USCVG1	Hebron, KY
USDEN1	Denver, CO
USDFW1	Irving, TX
USEWR1	Avenel, NJ
USIAH1	Houston, TX
USLAX1	Whittier, CA
USMCO1	Orlando, FL
USMCI1	Kansas City, MO
USORD1	Melrose Park, IL
USPHX1	Phoenix, AZ
USRDU1	Concord, NC
USSEA1	Sumner, WA
USSFO1	Union City, CA
USSLC1	West Jordan, UT
CNYYZ1	Toronto, CA

Service Endorsements

Service Endorsement	Value
1	Address Service Requested
2	Forwarding Service Requested
3	Change Service Requested
4	Return Service Requested

Content Categories

The following represents the supported DG codes for use with our domestic products.

Products	Category Code	Description	Max. Weight	Restrictions
PLY	01	Lithium Metal / Alloy Batteries Contained in Equipment	4.4 lbs	Canada Only
PLT	01	Lithium Metal / Alloy Batteries Contained in Equipment	11 lbs	Canada Only
PLT	02	Lithium Metal / Alloy Batteries Packed with Equipment	11 lbs	Canada Only
PLT	03	Lithium Metal / Alloy Batteries Stand Alone	5 lbs	Canada Only
PLY	04	Lithium-ion or Lithium Polymer Batteries Contained in Equipment	4.4 lbs	Canada Only
PLT	04	Lithium-ion or Lithium Polymer Batteries Contained in Equipment	11 lbs	Canada Only
PLT	05	Lithium-ion or Lithium Polymer Batteries Packed with Equipment	11 lbs	Canada Only
PLT	06	Lithium-ion or Lithium Polymer Batteries Stand Alone	5 lbs	Canada Only
PLT	40	Limited quantities	25 lbs	Canada Only

Label Samples

Sample Hazmat Labels

Content Category 2 - Lithium metal Batteries Packed with Equipment

null

Available for Domestic Ground only and International PLT Canada only. Requires an additional marking label UN3091 as seen below.

null

Content Category 3 - Lithium metal Batteries Stand-alone

null

Available for Domestic Ground only and International PLT Canada only. Requires an additional marking label UN3090 as seen below.

null

Content Category 5- Lithium-ion Batteries Packed with Equipment

null

Available for Domestic Ground only and International PLT Canada only. Requires an additional marking label UN3481 as seen below.

null

Content Category 6- Lithium-ion Batteries Stand-alone

null

Available for Domestic Ground only and International PLT Canada only. Requires an additional marking label UN3480 as seen below.

null

Content Category 8 (Domestic label shown below) and Content Category 40 (International)- Limited Quantity

null

Available for Domestic Ground only and International PLT Canada only. Requires an additional marking label seen below:

null

For International and Domestic Labels, please ensure to comply with marking requirements for various DG Categories.

Consignee ID Types

Identification Type	Value
National ID Number	1
Military Number	2
Passport Number	3
Other	4

Tax ID Types

Tax ID Type	Description	Region / Country
0	Other / Unknown	Any
1	GST / VAT	Any
2	EORI	EU
3	IOSS	EU
5	PAN	IN

Package Types


Package Type	Description
1	Box
2	Polybag
3	Tube

Weight Units

Weight Unit Of Measure	Description
LB	pounds
OZ	ounces
KG	kilograms
G	grams

DTC API supports unit of measures different from this list. Please refer to the specifications for details.

Dimension Units

Dimension Unit Of Measure	Description
IN	inches
CM	centimeters

DTC API supports unit of measures different from this list. Please refer to the specifications for details.

Services


Service	Description
omitted	If the service attribute is omitted, a default value is used. The default value for domestic shipments is usually DELCON except in the case of Marketing Parcel where the default value is no service.
DELCON	Most shipments originating and destined to the United States will default to DELCON. Delivery confirmation is free for domestic shipments except for Marketing Parcels which will incur additional surcharges.
SIGCON	Signature confirmation is also available for certain domestic products at an additional cost. SIGCON is not supported for International Products. Please contact your Sales representative for more details.

User-Agent

Technology partners who provide API integration services to multiple merchants are required to send their partner registration ID and software name in the User-Agent HTTP request header of all API requests.

Merchants who integrate directly with DHLeC are not assigned a registration ID and do not need to send a custom User-Agent HTTP request header.

The registration ID is a 6-character alphanumeric value assigned by DHL eCommerce. The software name is chosen by the technology partner and can be any value, up to a length of 50 characters.

Within the User-Agent HTTP request header, the two elements should be separated by a single space character:

User-Agent:[REGISTRATION_ID] [SOFTWARE_NAME]

Example:

User-Agent: ABC123 ShipMaster Pro

If you have any questions about the technology partner identification scheme, please reach out to your solutions partner manager.

IP Addresses

It is possible that your security team may need to whitelist DHL eCommerce IP addresses, so that your systems are able to communicate with the DHL eCommerce API. If this is the case, you can reference the list of DHL eCommerce IP addresses below.

IP Addresses for Inbound Traffic

The following IP addresses are used by the DHL eCommerce API to accept inbound traffic (e.g. for servicing traditional API requests):

35.229.17.35

34.89.220.138

35.198.247.238

IP Addresses for Outbound Traffic

The following IP addresses are used by the DHL eCommerce API to send outbound traffic (e.g. for webhook callbacks):

35.227.114.100

35.231.61.159

Canadian Provinces

Province	Province Code
ALBERTA	AB
BRITISH COLUMBIA	BC
MANITOBA	MB
NEW BRUNSWICK	NB
NEWFOUNDLAND AND LABRADOR	NL
NORTHWEST TERRITORIES	NT
NOVA SCOTIA	NS
NUNAVUT	NU
ONTARIO	ON
PRINCE EDWARD ISLAND	PE
QUEBEC	QC
SASKATCHEWAN	SK
YUKON	YT

Brazilian States

State	State Code
ACRE	AC
ALAGOAS	AL
AMAZONAS	AM
AMAPÁ	AP
BAHIA	BA
CEARÁ	CE
DISTRITO FEDERAL	DF
ESPÍRITO SANTO	ES
GOIÁS	GO
MARANHÃO	MA
MINAS GERAIS	MG
MATO GROSSO DO SUL	MS
MATO GROSSO	MT
PARÁ	PA
PARAÍBA	PB
PERNAMBUCO	PE
PIAUÍ	PI
PARANÁ	PR
RIO DE JANEIRO	RJ
RIO GRANDE DO NORTE	RN
RONDÔNIA	RO
RORAIMA	RR
RIO GRANDE DO SUL	RS
SANTA CATARINA	SC
SERGIPE	SE
SÃO PAULO	SP
TOCANTINS	TO

Duty & Tax Supported Countries & Currencies

Country Code	World Atlas Country Name	Currency Code
AD	Andorra	EUR
AE	United Arab Emirates	AED
AF	Afghanistan	AFN
AG	Antigua and Barbuda	XCD
AI	Anguilla	XCD
AL	Albania	ALL
AM	Armenia	AMD
AO	Angola	AOA
AR	Argentina	ARS
AS	American Samoa	USD
AT	Austria	EUR
AU	Australia	AUD
AW	Aruba	AWG
AX	Aland Islands	EUR
AZ	Azerbaijan	AZN
BA	Bosnia and Herzegovina	BAM
BB	Barbados	BBD
BD	Bangladesh	BDT
BE	Belgium	EUR
BF	Burkina Faso	XOF
BG	Bulgaria	BGN
BH	Bahrain	BHD
BI	Burundi	BIF
BJ	Benin	XOF
BL	Saint Barthélemy	EUR
BM	Bermuda	BMD
BN	Brunei Darussalam	BND
BO	Bolivia	BOB
BQ	Caribbean Netherlands	USD
BR	Brazil	BRL
BS	Bahamas	BSD
BT	Bhutan	BTN
BW	Botswana	BWP
BZ	Belize	BZD
CA	Canada	CAD
CD	Democratic Republic of the Congo	CDF
CF	Central African Republic	XAF
CG	Congo	XAF
CH	Switzerland	CHF
CI	Cote d'Ivoire	XOF
CK	Cook Islands	NZD
CL	Chile	CLF
CM	Cameroon	XAF
CN	China	CNY
CO	Colombia	COP
CR	Costa Rica	CRC
CV	Cape Verde	CVE
CW	Curacao	ANG
CY	Cyprus	EUR
CZ	Czech Republic	CZK
DE	Germany	EUR
DJ	Djibouti	DJF
DK	Denmark	DKK
DM	Dominica	XCD
DO	Dominican Republic	DOP
DZ	Algeria	DZD
EC	Ecuador	USD
EE	Estonia	EUR
EG	Egypt	EGP
ER	Eritrea	ERN
ES	Spain	EUR
ET	Ethiopia	ETB
FI	Finland	EUR
FJ	Fiji	FJD
FO	Faroe Islands	DKK
FR	France	EUR
GA	Gabon	XAF
GB	United Kingdom	GBP
GD	Grenada	XCD
GE	Georgia	GEL
GF	French Guiana	EUR
GG	Guernsey	GBP
GH	Ghana	GHS
GI	Gibraltar	GIP
GL	Greenland	DKK
GM	Gambia	GMD
GN	Guinea	GNF
GP	Guadeloupe	EUR
GQ	Equatorial Guinea	XAF
GR	Greece	EUR
GT	Guatemala	GTQ
GU	Guam	USD
GW	Guinea-Bissau	XOF
GY	Guyana	GYD
HK	Hong Kong	HKD
HN	Honduras	HNL
HR	Croatia	HRK
HT	Haiti	HTG
HU	Hungary	HUF
IC	Canary Islands	EUR
ID	Indonesia	IDR
IE	Ireland	EUR
IL	Israel	ILS
IM	Isle of Man	GBP
IN	India	INR
IQ	Iraq	IQD
IS	Iceland	ISK
IT	Italy	EUR
JE	Jersey	GBP
JM	Jamaica	JMD
JO	Jordan	JOD
JP	Japan	JPY
KE	Kenya	KES
KG	Kyrgyzstan	KGS
KH	Cambodia	KHR
KI	Kiribati	AUD
KM	Comoros	KMF
KN	Saint Kitts and Nevis	XCD
KR	Korea, Republic of	KRW
KW	Kuwait	KWD
KY	Cayman Islands	KYD
KZ	Kazakhstan	KZT
LA	Lao People's Democratic Republic	LAK
LB	Lebanon	LBP
LC	Saint Lucia	XCD
LI	Liechtenstein	CHF
LK	Sri Lanka	LKR
LR	Liberia	LRD
LS	Lesotho	LSL
LT	Lithuania	EUR
LU	Luxembourg	EUR
LV	Latvia	EUR
LY	Libyan Arab Jamahiriya	LYD
MA	Morocco	MAD
MC	Monaco	EUR
MD	Moldova	MDL
ME	Montenegro	EUR
MF	Saint Martin (French part)	EUR
MG	Madagascar	MGA
MK	Macedonia, the Former Yugoslav Republic of	MKD
ML	Mali	XOF
MM	Myanmar	MMK
MN	Mongolia	MNT
MO	Macao	MOP
MQ	Martinique	EUR
MS	Montserrat	XCD
MT	Malta	EUR
MR	Mauritania	MRU
MU	Mauritius	MUR
MV	Maldives	MVR
MW	Malawi	MWK
MX	Mexico	MXN
MY	Malaysia	MYR
MZ	Mozambique	MZN
NA	Namibia	NAD
NC	New Caledonia	XPF
NE	Niger	XOF
NG	Nigeria	NGN
NI	Nicaragua	NIO
NL	Netherlands	EUR
NO	Norway	NOK
NP	Nepal	NPR
NR	Nauru	AUD
NZ	New Zealand	NZD
OM	Oman	OMR
PA	Panama	PAB
PE	Peru	PEN
PF	French Polynesia	XPF
PG	Papua New Guinea	PGK
PH	Philippines	PHP
PK	Pakistan	PKR
PL	Poland	PLN
PM	Saint Pierre and Miquelon	EUR
PR	Puerto Rico	USD
PS	Palestine	ILS
PT	Portugal	EUR
PW	Palau	USD
PY	Paraguay	PYG
QA	Qatar	QAR
RE	Reunion	EUR
RO	Romania	RON
RS	Serbia	RSD
RW	Rwanda	RWF
SA	Saudi Arabia	SAR
SB	Solomon Islands	SBD
SC	Seychelles	SCR
SE	Sweden	SEK
SG	Singapore	SGD
SH	Saint Helena	SHP
SI	Slovenia	EUR
SK	Slovakia	EUR
SL	Sierra Leone	SLE
SM	San Marino	EUR
SN	Senegal	XOF
SR	Suriname	SRD
SS	South Sudan	SSP
ST	Sao Tome and Principe	STN
SV	El Salvador	USD
SZ	Swaziland	SZL
TC	Turks and Caicos Islands	USD
TD	Chad	XAF
TF	The French Southern and Antarctic Lands	EUR
TG	Togo	XOF
TH	Thailand	THB
TJ	Tajikistan	TJS
TL	Timor-Leste	USD
TM	Turkmenistan	TMT
TN	Tunisia	TND
TO	Tonga	TOP
TR	Turkey	TRY
TT	Trinidad and Tobago	TTD
TW	Taiwan	TWD
TZ	United Republic of Tanzania	TZS
UG	Uganda	UGX
US	United States	USD
UY	Uruguay	UYU
UZ	Uzbekistan	UZS
VC	Saint Vincent and the Grenadines	XCD
VE	Venezuela	VES
VG	British Virgin Islands	USD
VI	US Virgin Islands	USD
VN	Viet Nam	VND
VU	Vanuatu	VUV
WF	Wallis and Futuna	XPF
WS	Samoa	WST
XI	Northern Ireland	GBP
XK	Kosovo	EUR
YT	Mayotte	EUR
ZA	South Africa	ZAR
ZM	Zambia	ZMW
ZW	Zimbabwe	ZWL

International Destinations Not Serviced

Product	Country	Postal Code	Comments
All	American Samoa, Guam, Marshall Islands, Micronesia, Northern Mariana Islands, Palau, Puerto Rico, U.S. Minor Outlying Islands, U.S. Virgin Islands	All	These destinations are an overseas territory of the United States. As such, shipments are designated as a Domestic shipment rather than International. Please use DHL eCommerce Domestic services for these locations. Goods received by DHL eCommerce International services will be returned to the customer.
All	Crimea Region, Somalia, Yemen	All	Temporary blocks are currently in place. DHL eCommerce cannot organize safe transportation due to ongoing conflicts within the region. Goods received by DHL eCommerce International services will be returned to the customer.
All	Cuba, Iran, North Korea, Sudan, Syria	All	Due to U.S. Government trade embargos, DHL eCommerce does not currently provide service to these countries. Goods received by DHL eCommerce International services will be returned to the customer.
PLT, PKY, PKT	Estonia	96001-96245, 96300-96327
PLT	France	971XX-976XX, 984XX-988XX
PLT	Spain	07XXX, 35XXX, 38XXX, 51XXX, 52XXX

Updated October 8, 2021

Glossary

Identifiers

packageId

Customer-provided package ID, also known as the CCN (customer confirmation number) or the GM number.

Example: GM60511234500000001

dhlPackageId

DHL-generated package ID. This value is generated differently for domestic and international packages (domestic: mail identifier; international: TMUID).

Example: 3387191106122423

trackingId

Last-mile carrier package ID. For international shipments, this ID is only available after the package has been shipped. For domestic shipments, this ID contains the full USPS IMpb number and is always available. If the package is overlabeled for any reason, this field contains the latest carrier package ID.

Example: 420071149361269903500011492028

deliveryConfirmationNumber

For domestic shipments, this is the USPS tracking number, which is part of the IMpb number and is also sometimes referred to as the PIC (package identification code). If the package is overlabeled for any reason, this field contains the latest USPS tracking number. For international shipments, this field contains the last-mile carrier package ID (same value as the trackingId field) and is only available after the package has been shipped.

Example: 9361269903500011492028

overlabeledDspNumber

For domestic shipments which have been overlabeled, this is the original USPS tracking number. The USPS tracking number is part of the IMpb number and is also sometimes referred to as the PIC (package identification code). For international shipments and non-overlabeled domestic shipments, this field is unused.

Example: 9261269903500013618305

intelligentMailBarcode

For domestic flats shipments, this is the USPS IMb number. If the package is overlabeled for any reason, this field contains the latest IMb number. For international shipments and non-flats domestic shipments, this field is unused.

Example: 0031043534391627906195625053434

overlabeledIntelligentMailBarcode

For domestic flats shipments which have been overlabeled, this is the original USPS IMb number. For international shipments and non-overlabeled / non-flats domestic shipments, this field is unused.

Example: 0031043534391640211895625057522

manifestId

Unique identifier for each manifest created in the DHL system. This is returned in the Get Manifest API where each manifest will have the manifestId as the unique reference. This will also be barcoded and printed on the Driver Summary Manifest (DSM).

Example: 532903701308165834461

requestId

Unique identifier for each manifest request that was submitted to the DHL system. This is used to download and print the manifests later using the Get Manifest API. A single requestId can result in multiple manifestId when there's more than one manifest being generated for the request.

Example: bae87627-3566-4670-b8d2-fe90bfed75a9

Conventions

Package

The smallest unit in shipping is an Article / Piece / Item / Package / Parcel. These words are often used interchangeably. For the purposes of this API documentation, we use the term Package everywhere.

Shipment

The next higher unit is called a Shipment. This means one or more Packages going to the same destination (end consumer). A group of Packages is called a Shipment.

All of our shipping products support only 1 package per shipment hence we use the term Package and Shipment sometimes interchangeably.

Manifest

Also called a BOL / Bill of Lading / Consignment note / handover document / DSM / closeout document / DMF, a Manifest is a set of packages grouped by some common characteristic, such as those bound to the same distribution center after pickup, same shipping product, shipping class (domestic or international) etc. For example, all Domestic packages bound to a single distribution center will go into a first manifest, X-border packages bound to a single distribution center will go into a second manifest, Domestic packages bound to another distribution center will go into a third manifest etc. Sometimes, a new manifest can be created also because of technical limitations on maximum number of packages that can be successfully processed in a single manifest request.

Order

When one or more Manifests are picked up from the same origin (pickup location), it's called an Order. An Order can contain Domestic and X-border packages and can go to one or more Distribution facilities. It is simply a pickup load.

Container

A Container is a physical unit to carry a group of Packages, Manifests or Orders. A Container should contain at least one Package. A Container can contain less than 1 manifest, 1 manifest or more than 1 manifest. A Container can contain less than 1 Order or 1 order.

De minimis

A customs duty de minimis value (or VAT de minimis value) is the minimum threshold which an imported good's value must exceed in order to incur customs (or VAT) charges.

Weights

Weights are subject to applicable corrections when package(s) are weighed/measured at DHL eCommerce facilities.

Billable Weight

Weight that will be used for calculating fees and charges. This will be the Actual Weight, rounded up to the nearest oz for Parcel products and nearest lb for Parcel Plus products, unless the following three criteria are met:

Actual weight greater than or equal to 1 lb
Volume (L*W*H) is greater than 1 cubic foot
Volumetric (Dimensional) weight (L*W*H*(DiscountFactor, if applicable)/166) is greater than Actual weight

Then the Dimensional Weight will be used.

Actual Weight

Weight provided by the client in Label API and/or Product Finder API request.

Dimensional Weight (a.k.a.: Volumetric weight)

Weight calculated using dimensions provided in the dimensions object of the Label API and Product Finder API request. It is calculated by multiplying Length x Width x Height x (Discount Factor based on package Type, if applicable) / Dim Factor.

Other

AMP - Advanced Mail Processing
ESM - Electronic Shipment Manifest
DSM - Driver Summary Manifest
DMF - Domestic Manifest File
RSF - Return Shipment File
STC - Service Type Code
API - Application Programming Interface
EOD - End Of Day
Connect - X-border shipment processing system
NewOps - Domestic Shipment processing system
IMpb - Intelligent Mail package barcode
SSF - USPS Shipping Services File
BOL - Bill Of Lading
DELCON - Delivery Confirmation Number
FTP / SFTP - Secure File Transfer Protocol