This guide provides a comprehensive description about our products, features, keywords and rules.
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.
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 |
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 |
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
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 Endorsement | Value |
---|---|
1 | Address Service Requested |
2 | Forwarding Service Requested |
3 | Change Service Requested |
4 | Return Service Requested |
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 |
Sample Hazmat Labels
Content Category 2 - Lithium metal Batteries Packed with Equipment
Available for Domestic Ground only and International PLT Canada only. Requires an additional marking label UN3091 as seen below.
Content Category 3 - Lithium metal Batteries Stand-alone
Available for Domestic Ground only and International PLT Canada only. Requires an additional marking label UN3090 as seen below.
Content Category 5- Lithium-ion Batteries Packed with Equipment
Available for Domestic Ground only and International PLT Canada only. Requires an additional marking label UN3481 as seen below.
Content Category 6- Lithium-ion Batteries Stand-alone
Available for Domestic Ground only and International PLT Canada only. Requires an additional marking label UN3480 as seen below.
Content Category 8 (Domestic label shown below) and Content Category 40 (International)- Limited Quantity
Available for Domestic Ground only and International PLT Canada only. Requires an additional marking label seen below:
For International and Domestic Labels, please ensure to comply with marking requirements for various DG Categories.
Identification Type | Value |
---|---|
National ID Number | 1 |
Military Number | 2 |
Passport Number | 3 |
Other | 4 |
Tax ID Type | Description | Region / Country |
---|---|---|
0 | Other / Unknown | Any |
1 | GST / VAT | Any |
2 | EORI | EU |
3 | IOSS | EU |
5 | PAN | IN |
Package Type | Description |
1 | Box |
2 | Polybag |
3 | Tube |
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 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.
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. |
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.
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
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 |
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 |
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 |
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
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