References
Division: DHL eCommerce

Best for:

General Reference

  • Detailed references about products, API fields and general glossary.
Region: United States
Used for: Reference Data DS
Domestic Products
Product IDProduct Name(s)Notes
EXPDHL SmartMail Parcel / Parcel Plus Expedited 
MAXDHL SmartMail Parcel Expedited Max 
GNDDHL SmartMail Parcel / Parcel Plus Ground 
BEXDHL SmartMail BPM ExpeditedNo rates from API
BGNDHL SmartMail BPM GroundNo 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 IDProduct NameNotes
PLTDHL Parcel International Direct 
PLYDHL Parcel International Standard 
PKYDHL Packet International 
PIYDHL Parcel International Direct PriorityCA to US only
PIDDHL Parcel International Direct StandardCA to US only
PIXDHL Parcel International Direct MaxCA to US only
Return Products
Product IDProduct Name(s)Notes
RGNDHL SmartMail Parcel Return GroundNo rates from API
RPLDHL SmartMail Parcel Return PlusNo rates from API
RLTDHL SmartMail Parcel Return LightNo rates from API
International Regulations
 
PLT
NON PLT
Consignee phone numberRequired for Hong Kong, Japan, Israel, South Korea, & Mexico; recommended for other countries in case contact is neededRecommended for all countries in case contact is needed
Consignee email addressRequired for Japan; recommended for other countries in case contact is neededRecommended for all countries in case contact is needed
Consignee stateRequired for Canada, Australia and IsraelRequired for Canada, Australia and Israel
Consignee ID/ID typeNot requiredNot required
Consignee taxID/taxID typeRecommended 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 collectedRecommended for Brazil, Mexico, and Indonesia. Failure to provide an ID number may result in a hold or rejection in customs
Shipper phone numberRecommended for all countries in case contact is neededRecommended for all countries in case contact is needed
Shipper email addressRecommended for all countries in case contact is neededRecommended for all countries in case contact is needed
Shipper taxID/taxID typeRecommended depending on annual revenue and order value to UK, European Union, Australia, Germany, Singapore & New ZealandRecommended depending on annual revenue and order value to UK, European Union, Australia, New Zealand, Germany, Switzerland, Singapore, Malaysia & Norway
HS codeNot requiredStrongly recommended for all EU countries. May result in delays or returns if not provided.
Duties paidMay 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 CodeLocation
USATL1Mableton, GA
USBOS1Westborough, MA
USBWI1Manassas, VA
USCAK1Stow, OH
USCVG1Hebron, KY
USDEN1Denver, CO
USDFW1Irving, TX
USEWR1Avenel, NJ
USIAH1Houston, TX
USLAX1Whittier, CA
USMCO1Orlando, FL
USMCI1Kansas City, MO
USORD1Melrose Park, IL
USPHX1Phoenix, AZ
USRDU1Concord, NC
USSEA1Sumner, WA
USSFO1Union City, CA
USSLC1West Jordan, UT
CNYYZ1Toronto, CA
Service Endorsements
Service EndorsementValue
1Address Service Requested
2Forwarding Service Requested
3Change Service Requested
4Return Service Requested
Content Categories

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

ProductsCategory CodeDescriptionMax. WeightRestrictions
PLY01Lithium Metal / Alloy Batteries Contained in Equipment4.4 lbsCanada Only
PLT01Lithium Metal / Alloy Batteries Contained in Equipment11 lbsCanada Only
PLT02Lithium Metal / Alloy Batteries Packed with Equipment11 lbsCanada Only
PLT03Lithium Metal / Alloy Batteries Stand Alone5 lbsCanada Only
PLY04Lithium-ion or Lithium Polymer Batteries Contained in Equipment4.4 lbsCanada Only
PLT04Lithium-ion or Lithium Polymer Batteries Contained in Equipment11 lbsCanada Only
PLT05Lithium-ion or Lithium Polymer Batteries Packed with Equipment11 lbsCanada Only
PLT06Lithium-ion or Lithium Polymer Batteries Stand Alone5 lbsCanada Only
PLT40Limited quantities25 lbsCanada Only
Label Samples

Sample Hazmat Labels

Content Category 02 - 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.

null

 Content Category 03 - Lithium metal Batteries Stand-alone

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

null

 Content Category 05- 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.

null

Content Category 06- Lithium-ion Batteries Stand-alone

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

null

 Content Category 08 (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:

null

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

Consignee ID Types
Identification TypeValue
National ID Number1
Military Number2
Passport Number3
Other4
Tax ID Types
Tax ID TypeDescriptionRegion / Country
0Other / UnknownAny
1GST / VATAny
2EORIEU
3IOSSEU
4TBDAny
5PANIN
Package Types
  
Package TypeDescription
1Box
2Polybag
3Tube
Weight Units
Weight Unit Of MeasureDescription
LBpounds
OZounces
KGkilograms
Ggrams

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

Dimension Units
Dimension Unit Of MeasureDescription
INinches
CMcentimeters

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

Services
  
ServiceDescription
omittedIf the service attribute is omitted, a default value is used. The default value for domestic shipments is usually DELCON.
DELCONMost shipments originating and destined to the United States will default to DELCON. Delivery confirmation is free for domestic shipments.
SIGCONSignature 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
ProvinceProvince Code
ALBERTAAB
BRITISH COLUMBIABC
MANITOBAMB
NEW BRUNSWICKNB
NEWFOUNDLAND AND LABRADORNL
NORTHWEST TERRITORIESNT
NOVA SCOTIANS
NUNAVUTNU
ONTARIOON
PRINCE EDWARD ISLANDPE
QUEBECQC
SASKATCHEWANSK
YUKONYT
Brazilian States
StateState Code
ACREAC
ALAGOASAL
AMAZONASAM
AMAPÁAP
BAHIABA
CEARÁCE
DISTRITO FEDERALDF
ESPÍRITO SANTOES
GOIÁSGO
MARANHÃOMA
MINAS GERAISMG
MATO GROSSO DO SULMS
MATO GROSSOMT
PARÁPA
PARAÍBAPB
PERNAMBUCOPE
PIAUÍPI
PARANÁPR
RIO DE JANEIRORJ
RIO GRANDE DO NORTERN
RONDÔNIARO
RORAIMARR
RIO GRANDE DO SULRS
SANTA CATARINASC
SERGIPESE
SÃO PAULOSP
TOCANTINSTO
Duty & Tax Supported Countries & Currencies
Country CodeWorld Atlas Country NameCurrency Code
ADAndorraEUR
AEUnited Arab EmiratesAED
AFAfghanistanAFN
AGAntigua and BarbudaXCD
AIAnguillaXCD
ALAlbaniaALL
AMArmeniaAMD
AOAngolaAOA
ARArgentinaARS
ASAmerican SamoaUSD
ATAustriaEUR
AUAustraliaAUD
AWArubaAWG
AXAland IslandsEUR
AZAzerbaijanAZN
BABosnia and HerzegovinaBAM
BBBarbadosBBD
BDBangladeshBDT
BEBelgiumEUR
BFBurkina FasoXOF
BGBulgariaBGN
BHBahrainBHD
BIBurundiBIF
BJBeninXOF
BLSaint BarthélemyEUR
BMBermudaBMD
BNBrunei DarussalamBND
BOBoliviaBOB
BQCaribbean NetherlandsUSD
BRBrazilBRL
BSBahamasBSD
BTBhutanBTN
BWBotswanaBWP
BZBelizeBZD
CACanadaCAD
CDDemocratic Republic of the CongoCDF
CFCentral African RepublicXAF
CGCongoXAF
CHSwitzerlandCHF
CICote d'IvoireXOF
CKCook IslandsNZD
CLChileCLF
CMCameroonXAF
CNChinaCNY
COColombiaCOP
CRCosta RicaCRC
CVCape VerdeCVE
CWCuracaoANG
CYCyprusEUR
CZCzech RepublicCZK
DEGermanyEUR
DJDjiboutiDJF
DKDenmarkDKK
DMDominicaXCD
DODominican RepublicDOP
DZAlgeriaDZD
ECEcuadorUSD
EEEstoniaEUR
EGEgyptEGP
EREritreaERN
ESSpainEUR
ETEthiopiaETB
FIFinlandEUR
FJFijiFJD
FOFaroe IslandsDKK
FRFranceEUR
GAGabonXAF
GBUnited KingdomGBP
GDGrenadaXCD
GEGeorgiaGEL
GFFrench GuianaEUR
GGGuernseyGBP
GHGhanaGHS
GIGibraltarGIP
GLGreenlandDKK
GMGambiaGMD
GNGuineaGNF
GPGuadeloupeEUR
GQEquatorial GuineaXAF
GRGreeceEUR
GTGuatemalaGTQ
GUGuamUSD
GWGuinea-BissauXOF
GYGuyanaGYD
HKHong KongHKD
HNHondurasHNL
HRCroatiaHRK
HTHaitiHTG
HUHungaryHUF
ICCanary IslandsEUR
IDIndonesiaIDR
IEIrelandEUR
ILIsraelILS
IMIsle of ManGBP
INIndiaINR
IQIraqIQD
ISIcelandISK
ITItalyEUR
JEJerseyGBP
JMJamaicaJMD
JOJordanJOD
JPJapanJPY
KEKenyaKES
KGKyrgyzstanKGS
KHCambodiaKHR
KIKiribatiAUD
KMComorosKMF
KNSaint Kitts and NevisXCD
KRKorea, Republic ofKRW
KWKuwaitKWD
KYCayman IslandsKYD
KZKazakhstanKZT
LALao People's Democratic RepublicLAK
LBLebanonLBP
LCSaint LuciaXCD
LILiechtensteinCHF
LKSri LankaLKR
LRLiberiaLRD
LSLesothoLSL
LTLithuaniaEUR
LULuxembourgEUR
LVLatviaEUR
LYLibyan Arab JamahiriyaLYD
MAMoroccoMAD
MCMonacoEUR
MDMoldovaMDL
MEMontenegroEUR
MFSaint Martin (French part)EUR
MGMadagascarMGA
MKMacedonia, the Former Yugoslav Republic ofMKD
MLMaliXOF
MMMyanmarMMK
MNMongoliaMNT
MOMacaoMOP
MQMartiniqueEUR
MSMontserratXCD
MTMaltaEUR
MRMauritaniaMRU
MUMauritiusMUR
MVMaldivesMVR
MWMalawiMWK
MXMexicoMXN
MYMalaysiaMYR
MZMozambiqueMZN
NANamibiaNAD
NCNew CaledoniaXPF
NENigerXOF
NGNigeriaNGN
NINicaraguaNIO
NLNetherlandsEUR
NONorwayNOK
NPNepalNPR
NRNauruAUD
NZNew ZealandNZD
OMOmanOMR
PAPanamaPAB
PEPeruPEN
PFFrench PolynesiaXPF
PGPapua New GuineaPGK
PHPhilippinesPHP
PKPakistanPKR
PLPolandPLN
PMSaint Pierre and MiquelonEUR
PRPuerto RicoUSD
PSPalestineILS
PTPortugalEUR
PWPalauUSD
PYParaguayPYG
QAQatarQAR
REReunionEUR
RORomaniaRON
RSSerbiaRSD
RWRwandaRWF
SASaudi ArabiaSAR
SBSolomon IslandsSBD
SCSeychellesSCR
SESwedenSEK
SGSingaporeSGD
SHSaint HelenaSHP
SISloveniaEUR
SKSlovakiaEUR
SLSierra LeoneSLE
SMSan MarinoEUR
SNSenegalXOF
SRSurinameSRD
SSSouth SudanSSP
STSao Tome and PrincipeSTN
SVEl SalvadorUSD
SZSwazilandSZL
TCTurks and Caicos IslandsUSD
TDChadXAF
TFThe French Southern and Antarctic LandsEUR
TGTogoXOF
THThailandTHB
TJTajikistanTJS
TLTimor-LesteUSD
TMTurkmenistanTMT
TNTunisiaTND
TOTongaTOP
TRTurkeyTRY
TTTrinidad and TobagoTTD
TWTaiwanTWD
TZUnited Republic of TanzaniaTZS
UGUgandaUGX
USUnited StatesUSD
UYUruguayUYU
UZUzbekistanUZS
VCSaint Vincent and the GrenadinesXCD
VEVenezuelaVES
VGBritish Virgin IslandsUSD
VIUS Virgin IslandsUSD
VNViet NamVND
VUVanuatuVUV
WFWallis and FutunaXPF
WSSamoaWST
XINorthern IrelandGBP
XKKosovoEUR
YTMayotteEUR
ZASouth AfricaZAR
ZMZambiaZMW
ZWZimbabweZWL
International Destinations Not Serviced
ProductCountryPostal CodeComments
AllAmerican Samoa, Guam, Marshall Islands, Micronesia, Northern Mariana Islands, Palau, Puerto Rico, U.S. Minor Outlying Islands, U.S. Virgin IslandsAllThese 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.
AllCrimea Region, Somalia, Yemen, Haiti, Belarus, Russia and UkraineAllTemporary 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.
AllCuba, Iran, North Korea, Sudan, SyriaAllDue 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, PKTEstonia96001-96245, 96300-96327 
PLTFrance971XX-976XX, 984XX-988XX 
PLTSpain07XXX, 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