MYDHL API – DEVELOPER GUIDE

INTEGRATION MADE SIMPLE

PAGE 1 OF 280
MYDHL API – DEVELOPER GUIDE

DOCUMENT CONTROL
REVISION HISTORY:
Version Release Date Comments
1.7.2 19/06/2020 Updated ShipmentRequest with Advanced PLT processing
1.7.3 23/07/2020 Baselined for Loose BBX functionality
1.7.4 02/09/2020 Updated AWB Numbers in TrackingRequest
1.7.5 22/09/2020 Updated for VAT22 functionality
1.7.6 17/11/2020 Updated for Label-Free functionality
Update DocumentImage maximum size and Customer Logo
1.7.15 25/02/2021
maximum size
2.2 02/03/2021 Finalize and embed new WSDL
2.3 15/03/2021 Added SOAP Example with ExportDeclaration
2.4 22/03/2021 Updated Description max length in ShipmentRequest
Marked InvoiceDate as Mandatory in ShipmentRequest
2.5 08/04/2021
Added AddressValidate Error Appendix section
2.6 18/05/2021 Updated ItemNumber description in ShipmentRequest
Added Upload Invoice Data service details, Updated CI Mask v1.24.2 data
2.7 23/06/2021 in ShipmentRequest, PlaceOfIncoterm cardinality updates from
Mandatory to Optional.
Update reference data for:
a) <NumberTypeCode> added with DLI, NID, PAS and MID
b) <InvoiceReferenceType> added with
AAM,ABT,ACL,ADA,AES,AFD,ANT,BKN,BOL,CDN,COD,DSC,FF,FN,FTR,
HWB,IBC,IPP,LLR,MAB,MWB,NLR,OBC,PD,PRN,RMA,RTL,SID,SS,SWN
2.8 07/07/2021
c) <ItemReferenceType>
- added with AAM,CFR,DOM,FOR,USG,MAT
- removed ECN as no longer supported
d) <CustomsDocumentType> added with ELP
e) <CustomsPaperworkType> added with ELP
2.9 14/07/2021 Updated Appendix section for Registration Number Type Codes
Updated Create Shipment and Upload Invoice service on Export Line Item
2.10 06/08/2021
– QuantityUnitOfMeasurement list of enumeration (page 134, 352)
a) Updated Section 9.1 UPDATESHIPMENT - DESCRIPTION
b) Added LandedCost updates:
1. Updated Request Section with new optional elements
“EstimatedTariffRateType”, “GetTariffFormula”, “GetQuotationID” and
2.11 03/09/2021
“GetDetailedLineItemLevelStatus”.
2. Updated Response Section with new optional elements “QuotationID”,
“TariffRateFormula” and introduced “MessageDetail” for Notification.
3. Updated Appendix: Introduced RateRequest LandedCost Warnings

PAGE 2 OF 417
MYDHL API – DEVELOPER GUIDE

4. Updated Appendix: Introduced RateRequest LandedCost Category

Codes
5. Updated Appendix: Updated RateRequest LandedCost Errors
6. Updated SOAP RateRequest LandedCost: Samples
Removed element <DocumentFunction> from Section 5
2.12 06/12/2021
SHIPMENTREQUEST
a) Appendix: Added RequestPickup and UpdatePickup Error list
b) Introduced new Section 15 DOCUMENTIMAGEREQUEST
c) Introduced new Section DOCUMENTIMAGEREQUEST ERRORS
d) Introduced new Section 25 SERVICE INPUT/OUTPUT EXAMPLES FOR
DOCUMENTIMAGEREQUEST
e) Updated error code and message at Section 16 APPENDIX
f) Updated field lengths and numeric field formats for Create Shipment,
Update Shipment, Upload Invoice Data, Rate Request, Address
Validate, Request Pickp and Update Pickup service
g) Introduced element Warning and its children elements at Section 9.4
UPDATESHIPMENT – OUTPUT and Section 9.5 UPDATE SHIPMENT
2.13 09/01/2022 RESPONSE – OUTPUT FIELD LIST
h) Introduced new Section UPDATESHIPMENT WARNINGS at Section 16
APPENDIX
i) Introduced new Section SOAP UPDATESHIPMENT: SAMPLE WARNING
MESSAGE at Section 22.
j) Updated element <DeclarationText> maximum length.
k) Update reference data for:
1) <InvoiceReferenceType>:
removed NLR as no longer supported
2) <ItemReferenceType>:
added with NLR

a) Updated UploadInvoiceData service element <DocumentFunction>

2.14 03/03/2022
with additional note
a) Renamed from Label-less to Label-Free.
b) Updates in Section 5. SHIPMENTREQUEST
1. Removed element <PaperlessTradeEnabled>:
• Section 5.2.21 Updated details of
<RequestWayBillDocument>
2. Updated Section 5.2.8 with details on “WY” service type
3. Introduced value “RET_COM_INVOICE_A4_01” for existing
element <CustomsInvoiceTemplate>
2.15 07/06/2022 4. Introduced value “RETURNS_INVOICE” for existing element
<DHLCustomsInvoiceType>
5. Updated Section 5.3 Rephrase the statement for element
<ParentShipmentPackagesCount>
c) Updated Section 7.5 TRACKINGRESPONSE – OUTPUT FIELD LIST:
Removed maxlength for element <StateOrProvinceCode>
d) Updated Section 9.1 UPDATESHIPMENT – DESCRIPTION
e) Updated Section 16. APPENDIX – CREATESHIPMENT ERRORS
f) Updated Section 18. SHIPMENTREQUEST INPUT/OUTPUT EXAMPLES

PAGE 3 OF 417
MYDHL API – DEVELOPER GUIDE

g) QuantityUnitOfMeasurement list of enumeration

PAGE 4 OF 417
MYDHL API – DEVELOPER GUIDE

CONFIDENTIALITY (CONTENT IS COMMERCIALLY CONFIDENTIAL)

The information contained in this document is the property Deutsche Post DHL.
No part of its contents may be divulged to third parties without the express written approval of DHL
Express.
All rights reserved; no part of this document may be reproduced, stored in a retrieval system, or
transmitted in any form or by any other means, electronic, mechanical, photocopying, recording
otherwise without the prior written permission of DHL Express.
This document may not be lent, resold, hired out or otherwise disposed of by way of trade in any
form, binding or cover other than that in which it is published, without the prior written permission
of DHL Express.

DISCLAIMER (RIGHT TO MODIFY)

This document contains (as detailed) the latest information received in time to be incorporated
for publication. However, DHL Express reserves the right to modify the information contained
herein without published notification.
Deutsche Post World Net offers no warranty, express or implied, regarding its accuracy, sufficiency,
merchantability or fitness for any purpose of the information contained herein. Any use made
thereof is made entirely at the risk and for the account of the user.

TERMS AND CONDITIONS

The requirements and specifications outlined in this manual are governed by DHL’s Terms and
Conditions of Carriage, found on DHL’s website, www.DHL.com.

AUDIENCE

This document is intended to serve as a guide to assist DHL customers and third party developers
during the integration development process. The primary audience of this document is intended to
be a trading partner’s technical resources and internal MyDHL API support staff.

© 2005 - 2022 DHL Express, Inc. All rights reserved.

PAGE 5 OF 417
MYDHL API – DEVELOPER GUIDE

CONTENT

CONTENT ..................................................................................................................................................................6
1. INTRODUCTION........................................................................................................................................... 10
1.1 MYDHL API OVERVIEW ........................................................................................................................... 10
1.2 REQUIREMENTS – TECHNICAL SKILLS .............................................................................................. 10
1.3 REQUIREMENTS – BUSINESS UNDERSTANDING ........................................................................... 10
2. MYDHL API OVERVIEW OVERVIEW ........................................................................................................ 11
2.1 WEB SERVICE DEFINITION LANGUAGE AND REFERENCE DOCUMENTS ................................. 11
2.2 SECURITY AND AUTHENTICATION...................................................................................................... 13
3. WHAT WEB SERVICES OPERATIONS ARE AVAILABLE?.................................................................... 14
4. RATEREQUEST ............................................................................................................................................ 16
4.1 RATEREQUEST - DESCRIPTION ............................................................................................................ 16
4.2 RATEREQUEST - INPUT .......................................................................................................................... 16
4.3 RATEREQUEST – INPUT FIELD LIST .................................................................................................... 30
4.4 RATEREQUEST - OUTPUT ...................................................................................................................... 43
4.5 RATE RESPONSE – OUTPUT FIELD LIST ............................................................................................ 52
5. SHIPMENTREQUEST.................................................................................................................................. 58
5.1 SHIPMENTREQUEST - DESCRIPTION ................................................................................................. 58
5.2 SHIPMENTREQUEST - INPUT ............................................................................................................... 58
5.3 SHIPMENT REQUEST – INPUT FIELD LIST......................................................................................... 98
5.4 SHIPMENTREQUEST - OUTPUT ........................................................................................................ 160
5.5 SHIPMENT RESPONSE – OUTPUT FIELD LIST ............................................................................... 168
6. SHIPMENTDELETEREQUEST................................................................................................................ 174
6.1 SHIPMENTDELETEREQUEST - DESCRIPTION ............................................................................... 174
6.2 SHIPMENTDELETEREQUEST - INPUT ............................................................................................. 174
6.3 SHIPMENTDELETEREQUEST – INPUT FIELD LIST ....................................................................... 176
6.4 SHIPMENTDELETEREQUEST – OUTPUT ......................................................................................... 177
6.5 SHIPMENTDELETEREQUEST – OUTPUT FIELD LIST ................................................................... 178
7. TRACKINGREQUEST ............................................................................................................................... 180
7.1 TRACKINGREQUEST - DESCRIPTION .............................................................................................. 180
7.2 TRACKINGREQUEST - INPUT ............................................................................................................. 181
7.3 TRACKINGREQUEST – INPUT FIELD LIST ....................................................................................... 184
7.4 TRACKINGRESPONSE - OUTPUT ...................................................................................................... 189
7.5 TRACKINGRESPONSE – OUTPUT FIELD LIST ................................................................................ 195
8. DOCUMENTRETRIEVE - EPOD ............................................................................................................. 200

PAGE 6 OF 417
MYDHL API – DEVELOPER GUIDE

8.1 DOCUMENTRETRIEVE-EPOD - DESCRIPTION .............................................................................. 200

8.2 DOCUMENTRETRIEVE-EPOD - INPUT ............................................................................................. 200
8.3 SHIPMENTDOCUMENTRETRIEVE-EPOD – INPUT FILED LIST .................................................. 210
8.4 SHIPMENTDOCUMENTRETRIEVE-EPOD – OUTPUT ................................................................... 212
8.5 DOCUMENTRETRIEVE-EPOD – OUTPUT FIELD LIST ................................................................... 226
9. UPDATESHIPMENT ................................................................................................................................. 228
9.1 UPDATESHIPMENT - DESCRIPTION................................................................................................. 228
9.2 UPDATESHIPMENT - INPUT ............................................................................................................... 230
9.3 UPDATE SHIPMENT REQUEST – INPUT FIELD LIST .................................................................... 234
9.4 UPDATESHIPMENT - OUTPUT .......................................................................................................... 239
9.5 UPDATE SHIPMENT RESPONSE – OUTPUT FIELD LIST ............................................................. 241
10. REQUESTPICKUP ..................................................................................................................................... 242
10.1 REQUESTPICKUP - DESCRIPTION ................................................................................................. 242
10.2 REQUESTPICKUP - INPUT ............................................................................................................... 242
10.3 REQUESTPICKUP REQUEST – INPUT FIELD LIST ...................................................................... 251
10.4 REQUESTPICKUP - OUTPUT ........................................................................................................... 257
10.5 REQUEST PICKUP RESPONSE – OUTPUT FIELD LIST.............................................................. 259
11. UPDATEPICKUP ....................................................................................................................................... 259
11.1 UPDATEPICKUP - DESCRIPTION ................................................................................................... 259
11.2 UPDATEPICKUP - INPUT.................................................................................................................. 260
11.3 UPDATEPICKUP REQUEST – INPUT FIELD LIST ........................................................................ 268
11.4 UPDATEPICKUP - OUTPUT ............................................................................................................. 275
11.5 UPDATEPICKUP RESPONSE – OUTPUT FIELD LIST ................................................................. 277
12. ADDRESSVALIDATE ................................................................................................................................ 277
12.1 ADDRESSVALIDATE - DESCRIPTION ............................................................................................. 277
12.2 ADDRESSVALIDATE - INPUT ........................................................................................................... 278
12.3 ADDRESSVALIDATE REQUEST – INPUT FIELD LIST .............................................................. 280
12.4 ADDRESSVALIDATE - OUTPUT ....................................................................................................... 281
12.5 ADDRESSVALIDATE RESPONSE – OUTPUT FIELD LIST........................................................ 284
13. REQUESTIDENTIFIER .............................................................................................................................. 285
13.1 REQUESTIDENTIFIER - DESCRIPTION .......................................................................................... 285
13.2 REQUESTIDENTIFIER - INPUT......................................................................................................... 286
13.3 REQUESTIDENTIFIER REQUEST – INPUT FIELD LIST ............................................................ 288
13.4 REQUESTIDENTIFIER - OUTPUT ................................................................................................. 290
13.5 REQUESTIDENTIFIER RESPONSE – OUTPUT FIELD LIST ..................................................... 291
14. UPLOADINVOICEDATA ........................................................................................................................... 294

PAGE 7 OF 417
MYDHL API – DEVELOPER GUIDE

14.1 UPLOADINVOICEDATA - DESCRIPTION........................................................................................ 294

14.2 UPLOADINVOICEDATA - INPUT ...................................................................................................... 296
14.3 UPLOADINVOICEDATA REQUEST – INPUT FIELD LIST ......................................................... 314
14.4 UPLOADINVOICEDATA - OUTPUT .................................................................................................. 336
14.5 UPLOADINVOICEDATA RESPONSE – OUTPUT FIELD LIST..................................................... 338
15. DOCUMENTIMAGEREQUEST................................................................................................................ 339
15.1 DOCUMENTIMAGEREQUEST - DESCRIPTION ............................................................................ 339
15.2 DOCUMENTIMAGEREQUEST - INPUT........................................................................................... 340
15.3 DOCUMENTIMAGEREQUEST – INPUT FIELD LIST ................................................................. 345
15.4 DOCUMENTIMAGERESPONSE - OUTPUT .................................................................................... 348
15.5 DOCUMENTIMAGERESPONSE – OUTPUT FIELD LIST............................................................. 351
16 APPENDIX .................................................................................................................................................. 353
RATE REQUEST AND SHIPMENT REQUEST ERROR CODES AND MESSAGES ............................. 353
CAPABILITY AND QUOTATION ERRORS- RATEREQUEST AND SHIPMENTREQUEST................ 353
ROUTE CODE ERRORS ................................................................................................................................ 356
SHIPMENT DATE VALIDATION ................................................................................................................. 356
ACCOUNT VALIDATION .............................................................................................................................. 357
LABEL GENERATION ERRORS................................................................................................................... 357
MANIFEST SUBMISSION ERRORS ........................................................................................................... 358
PICKUP ERRORS ........................................................................................................................................... 358
GENERAL ERRORS ....................................................................................................................................... 360
TRACKING ERRORS ..................................................................................................................................... 360
RATEREQUEST LANDEDCOST ERRORS ................................................................................................. 361
RATEREQUEST LANDEDCOST WARNINGS ........................................................................................... 367
RATEREQUEST LANDEDCOST ADDITIONALQUANTITYTYPE ALLOWED VALUES ..................... 368
RATEREQUEST LANDEDCOST CATEGORY CODES.............................................................................. 373
CREATESHIPMENT AND UPLOADINVOICEDATA REGISTRATION NUMBER TYPE CODES ....... 376
SHIPMENT DOCUMENT RETRIEVE ERRORS (EPOD) .......................................................................... 378
COMMERCIAL INVOICE TEMPLATES: ROLE REGISTRATION NUMBER TYPE CODES AND
CHARGES ........................................................................................................................................................ 379
ADDRESSVALIDATE ERRORS .................................................................................................................... 379
UPLOADINVOICEDATA ERRORS ............................................................................................................... 380
CREATESHIPMENT ERRORS ..................................................................................................................... 382
REQUESTPICKUP ERRORS ......................................................................................................................... 390
UPDATEPICKUP ERRORS ........................................................................................................................... 392
DOCUMENTIMAGEREQUEST ERRORS ................................................................................................... 392

PAGE 8 OF 417
MYDHL API – DEVELOPER GUIDE

UPDATESHIPMENT WARNINGS ............................................................................................................... 393

17 SERVICE INPUT/OUTPUT EXAMPLES FOR RATEREQUEST.......................................................... 393
18 SERVICE INPUT/OUTPUT EXAMPLES FOR SHIPMENTREQUEST ............................................... 400
19 SERVICE INPUT/OUTPUT EXAMPLES FOR SHIPMENTDELETEREQUEST ................................ 403
20 SERVICE INPUT/OUTPUT EXAMPLES FOR TRACKINGREQUEST................................................ 404
21 SERVICE INPUT/OUTPUT EXAMPLES FOR EPOD ........................................................................... 407
22 SERVICE INPUT/OUTPUT EXAMPLES FOR UPDATESHIPMENT ................................................. 409
23 SERVICE INPUT/OUTPUT EXAMPLES FOR REQUESTPICKUP ..................................................... 411
24 SERVICE INPUT/OUTPUT EXAMPLES FOR UPDATEPICKUP ........................................................ 413
25 SERVICE INPUT/OUTPUT EXAMPLES FOR DOCUMENTIMAGEREQUEST ................................ 415
26 HELPFUL XML AND WEB SERVICES LINKS ...................................................................................... 417

PAGE 9 OF 417
MYDHL API – DEVELOPER GUIDE

1. INTRODUCTION

1.1 MYDHL API OVERVIEW

MyDHL API are a set of operations offering DHL’s core services like capability, rating or booking a
pickup request to any customer. This enables the customer to integrate these services seamlessly
into their own IT infrastructure. Customers can then ask for the available products and their prices
(where applicable) online as well as creating a shipment together with a courier pickup.

This document describes how to integrate these services to your own applications and is intended as
a user guide for developers.

1.2 REQUIREMENTS – TECHNICAL SKILLS

Technically speaking, MyDHL API is a set of Operations accessible by a standardized web protocol.
Each operation can be called by a client application to request shipment capability, estimated
shipping price or even book a pickup of a shipment. Client applications will request a certain operation
to be executed with the application specific request data. MyDHL API then responds synchronously
by sending back response data in a standard pre-defined format. The client application can then
process the response data to complete the subsequent workflow.

In order to access the web service, a SOAP protocol, RESTful Services or plain XML is used and
developers should be familiar with XML/JSON and have a basic understanding of web services.
Please find a list of helping resources in the Appendix.

1.3 REQUIREMENTS – BUSINESS UNDERSTANDING

Developers who plan to connect their tools or services to MyDHL API should also have a closer look
into DHL’s product and services offering. More details about DHL products and services are available
at www.dhl.com and your DHL Sales representative.

PAGE 10 OF 417
MYDHL API – DEVELOPER GUIDE

2. MYDHL API OVERVIEW OVERVIEW

There are some main points that must be noted before getting started with MyDHL API integration -
• The DHL customer web services consist of Port types and bindings that contain
information about the service operation, service endpoints and service location.
• MyDHL API can used via SOAP & REST(visit developer.dhl.com/express for the REST
documentation and discard this document including the endpoints)

2.1 WEB SERVICE DEFINITION LANGUAGE AND REFERENCE DOCUMENTS

These documents will be used to integrate to MyDHL API, including WSDL and SOAP UI project.
Your DHL contact can provide the production endpoint upon completion of certification
testing.

Reference Description Document

WSDL RateRequest See WSDL attached in this

Description ShipmentRequest document or contact your DHL
ShipmentDeleteRequest Express IT representative

TrackingRequest See WSDL attached in this

WSDL
document or contact your DHL
Description
Express IT representative
DocumentRetrieve (ePOD) See WSDL attached in this
WSDL
document or contact your DHL
Description
Express IT representative
updateShipment See WSDL attached in this
WSDL
document or contact your DHL
Description
Express IT representative
requestPickup See WSDL attached in this
WSDL
document or contact your DHL
Description
Express IT representative
updatePickup See WSDL attached in this
WSDL
document or contact your DHL
Description
Express IT representative
addressValidate See WSDL attached in this
WSDL
document or contact your DHL
Description
Express IT representative
requestIdentifier See WSDL attached in this
WSDL
document or contact your DHL
Description
Express IT representative

PAGE 11 OF 417
MYDHL API – DEVELOPER GUIDE

uploadInvoiceData See WSDL attached in this

WSDL
document or contact your DHL
Description
Express IT representative
documentImageRequest See WSDL attached in this
WSDL
document or contact your DHL
Description
Express IT representative

Service endpoints on the Test Environment

Service name Endpoint

RateRequest
ShipmentRequest https://wsbexpress.dhl.com/sndpt/expressRateBook
ShipmentDeleteRequest

TrackingRequest https://wsbexpress.dhl.com/sndpt/glDHLExpressTrack

DocumentRetrieve
https://wsbexpress.dhl.com/sndpt/getePOD
(ePOD)

updateShipment https://wsbexpress.dhl.com/sndpt/updateShipment

requestPickup https://wsbexpress.dhl.com/sndpt/requestPickup

updatePickup https://wsbexpress.dhl.com/sndpt/updatePickup

addressValidate https://wsbexpress.dhl.com/sndpt/addressValidate

requestIdentifier https://wsbexpress.dhl.com/sndpt/requestIdentifier

uploadInvoiceData https://wsbexpress.dhl.com/sndpt/uploadInvoiceData

documentImageRequest https://wsbexpress.dhl.com/sndpt/documentImageRequest

Testing DHL Web Services with SOAP UI

The product SoapUI (http://www.soapui.org/) provides advanced support for testing Web Services.
Prior to development cycle, this tool can be used to independently verify the DHL services in a test
environment, and provide verification and context during the system development life cycle. It is also
useful in providing functionality context to the consumer prior to development and independently
validating security credentials.

PAGE 12 OF 417
MYDHL API – DEVELOPER GUIDE

Validation of the Input Data

The input data for MyDHL API is validated in several steps. The first step is general XML validation
based on data cardinality and data content restrictions defined by the request message format (i.e.
schema validation). In a second step, several business rules are applied on the passed data. The
results of these validations are placed in the result message of the service operation. The service
operation always delivers a result message. All errors or validation errors are stored in this result
messages. Please refer to the Appendix for complete list of error codes.
2.2 SECURITY AND AUTHENTICATION
External Web Service calls from the customer to DHL will be handled through the DHL Web Services
Broker. The Web Services Broker is an XML and web services gateway used by DHL providing
governance, security, virtualization, and enhanced performance for web service transactions.

The primary transport protocol for these calls is https (standard port 443). For this solution, the DHL
Web Service Broker will validate that the messages are well formed and provide security and data
encryption. DHL utilizes WS-Security features of the SOAP protocol.

Authentication using WS-Security

WS-Security offers a general-purpose mechanism for associating security tokens with message
content. The specification defines three approved token types, but for the purposes of these services,
UsernameToken will be used.

For example, the UsernameToken Profile describes how a Web service client can supply a
UsernameToken as a way to identify the requestor by a username and by supplying a password. The
SOAP header also requires the setting of Password Type as ‘PasswordText’. The following XML
snippet shows a sample WS-Security UsernameToken:
<wsse:UsernameToken wsu:Id="Example">
<wsse:Username> ... </wsse:Username>
<wsse:Password Type="..."> ... </wsse:Password>
<wsse:Nonce EncodingType="..."> ... </wsse:Nonce>
<wsu:Created> ... </wsu:Created>
</wsse:UsernameToken>

To authenticate using WS-Security for DHL Web Services, the consumer would need to add a SOAP
header to the SOAP envelope. This header would contain the WS-Security information.

For more information about this please take a look into http://docs.oasis-open.org/wss/

User access rights

The applicable statement for user access relates to the authentication properties enforced at the web
service broker. Authentication details will be stored on the Web Service broker as a configuration,
and this solution assumes the customer will have established integration credentials at application
level. Credentials will not be managed at the customer user level.
Example:
Customer XYZ is building a web portal ABC with internal user administration. This web portal will
call MyDHL API. Just the application itself will get access to MyDHL API and not each user registered
in the application ABC.

PAGE 13 OF 417
MYDHL API – DEVELOPER GUIDE

How to get access?

The authentication credentials will be provided by your DHL point of contact for the integration
project.

3. WHAT WEB SERVICES OPERATIONS ARE AVAILABLE?

For the orchestrated DHL web services offering, there are the following operations available for
use.

a) RateRequest – This service allows the customer to

a. Input characteristics about a prospective shipment, and outputs the
corresponding available DHL products, along with rate estimates and
estimated delivery date/time.
b. Get Total Landed Cost calculation based on provided product characteristics.

b) ShipmentRequest – This service allows the customer to input characteristics about a

requested shipment and pickup, and outputs reference information (waybill and piece
ID) as well as a shipping label. If a pickup has been requested then the pickup
confirmation number will also be sent back as an output.

c) ShipmentDeleteRequest – This service allows the customer to request the deletion

of a pickup, if it was requested in the original ShipmentRequest.

d) TrackingRequest – This service allows the customer to input specific waybill

numbers, and outputs tracking checkpoint information at the shipment or piece level.

e) DocumentRetrieve – This service allows the customer to input parameters indicating

which ePOD or ePODs is requesting and the content of the ePODs. The operation
outputs the ePOD(s) as a base64 encoded string.

f) updateShipment – This service allows the customer to add pieces to a previously

created shipment that has not been picked up/scanned by DHL and is for the same
day.
The term used for this process is Shipment Consolidation

g) requestPickup – This service allows for a stand-alone pickup request to be sent to the
DHL Express Customer Services team for Export and Import bookings.

h) updatePickup – This service allows for a pickup initated via MyDHL API to be
modified

i) addressValidate – This service validates DHL’s nearest service area details for a
certain origin or destination address in the input data.

PAGE 14 OF 417
MYDHL API – DEVELOPER GUIDE

j) requestIdentifier – This service returns list of identifiers for different type of

shipment usage. (authorization required by your local DHL Express IT representative
to activate and forecasting of number usages)

k) uploadInvoiceData – This service accepts Commercial Invoice details of a given

shipment that may be needed for customs clearance.

l) documentImageRequest – This service allows the customer to input parameters

indicating the waybill number, shipper account number and the document image
types to be searched from DHL Image Archive. The operation outputs the searched
document image(s) as a base64 encoded string.

The services are called independently, but can also be used in concert (i.e. using output from one
service as input into the next service) to meet the consumer requirements.

REST – visit developer.dhl.com/express for full REST documentation and discard this
document.

PAGE 15 OF 417
MYDHL API – DEVELOPER GUIDE

4. RATEREQUEST

4.1 RATEREQUEST - DESCRIPTION

The Rate request will return DHL’s product capabilities (products, services and estimated delivery
time) and prices (where applicable) for a certain set of input data.

Using the shipper and receiver address as well as the dimension and weights of the pieces
belonging to a shipment, this operation returns the available products and service including the
shipping price (where applicable) and the potential delivery date considering the planned pickup
date.

A shipment request can just be successfully executed (assuming the same input data) for a
product and service combination which is returned by the rate request.

If the <LandedCost> segment is provided within the Request then the Service will return the Total
Costs (Landed Costs) for all Items specified in the request.

4.2 RATEREQUEST - INPUT

The following diagram shows an overview of the request input structure.

Within the RateRequest, the ClientDetail and Request are optional nodes for reference use, and
does not affect functionality. The critical elements are contained within the RequestedShipment
node.

PAGE 16 OF 417
MYDHL API – DEVELOPER GUIDE

4.2.1 RateRequest Schema Diagram

Each of the individual sections of RequestedShipment is represented below in the schema
diagram, with context, and a detailed description of each field follows in the Input Field List.

4.2.2 RateRequest Input: Service Header

PAGE 17 OF 417
MYDHL API – DEVELOPER GUIDE

Optional section to populate information used to identify customer request for troubleshooting
or tracking. DHL Express recommends that this information is provided. For Third party
vendors/ecommerce this is mandatory to provide continuous support.

For Landed Cost Request the “<MessageTime>” and “<MessageReference>” is Mandatory.

4.2.3 RateRequest Input: RequestedShipment

This section is used to populate all the required data about the prospect shipment to have rates
returned.

PAGE 18 OF 417
MYDHL API – DEVELOPER GUIDE

For LandedCost details please refer to section 4.2.27

PAGE 19 OF 417
MYDHL API – DEVELOPER GUIDE

4.2.4 RateRequest Input: GetRateEstimates

The GetRateEstimates element is used to provide options to return DHL products and services
without showing the price. This will further improve response times for those who simply would
like to know the available products and services that DHL offer for the prospective shipments.
This element is not to be used in combination with the LandedCost element. There are three
possible cases for this field.

• GetRateEstimates = Y – the response message will show all charges related to the DHL
products and services

• GetRateEstimates = N – the response message will show all charges related elements as
empty (0.00) for the available DHL products and services

• GetRateEstimates is not provided. If value is not provided for this field, the default value is
Y. Hence, the response message will show charges for the related DHL products and
services.

• When <LandedCost> elements are in the request, <GetRateEstimates> shouldn’t be used

in the Request Message. Otherwise, an error will be returned in the response message

4.2.5 RateRequest Input: GetDetailedRateBreakdown

The GetDetailedBreakdown element is used to to receive a detailed breakdown of charges

including taxes and discounts. This element is not to be used in combination with the LandedCost
element.
The possible values for this element are as below;

• GetDetailedRateBreakdown = Y – detailed product information will be returned such as

transit days, shipment weight and origin/destination service area codes.

• GetDetailedRateBreakdown = N – a highlevel rate breakdown is shown with key

information.

• When <LandedCost> elements are in the request, <GetDetailedBreakdown> shouldn’t be

used in the Request Message. Otherwise, an error will be returned in the response
message.

4.2.6 RateRequest Input: IncludeAdditionalCurrencies

IncludeAdditionalCurrencies is used to provide options to return rates in other currencies such as

provided by pickup location currency and base currency.

This element can return currencies based on ‘BILLC’ – billing currency, ‘PULCL’ – pickup location
currency, ‘BASEC’ – base currency. The possible values for this element are as below;

PAGE 20 OF 417
MYDHL API – DEVELOPER GUIDE

• IncludeAdditionalCurrencies = Y, the response will return all the rates in Biling,

PickupLocation and Base currency.

• IncludeAdditionalCurrencies = N, the response will return all the rates in Billing currency
only.

• IncludeAdditionalCurrencies is not provided, the default value will be

IncludeAdditionalCurrencies = N where the response will return all the rates in the Billing
currency only.

4.2.7 RateRequest Input: DropOffType

The DropoffType is used to indicate whether a scheduled pickup is required as part of the
consideration for the rate request. There are two possible values to indicate whether a pickup is
considered. The possible values are as follows;
• REGULAR_PICKUP – The pickup location is already serviced by regularly scheduled
courier pickup and an additional pickup does not need to be considered for this service.

• REQUEST_COURIER- The rating response returns products, for which the pickup
capability is given, based on ShipmentTimeStamp.

4.2.8 RateRequest Input: NextBusinessDay

The NextBusinessDay field is used to indicate that the Rate Request process should query the next
business day for available services if the current request is beyond cutoff, or occurs on a weekend
or holiday. There are three possible use cases for this field.
• NextBusinessDay is null (node not included) – This represents the base functionality. In
this case, the process will filter out any services which has a pickup date <> to the
requested ship date. For example, if the requested shipment date is a Monday, but the
next available pickup date is a Tuesday, this option will not present these services.

• NextBusinessDay = N – This case will behave identically to the above null case.

• NextBusinessDay = Y – This case will provide services for the subsequent business day, if
available.

4.2.9 RateRequest Input: Ship

The Ship section outlines the shipper and receiver for the specific rate request. In the context to
rate requests, the street address elements are not critical, since capability and rate are determined

PAGE 21 OF 417
MYDHL API – DEVELOPER GUIDE

based on city, postal code, and country code. Please note that the Shipper and Recipient
structures are identical.

4.2.10 RateRequest Input: Packages

The Packages section details the weight and dimensions of the individual pieces of the shipment.
For example, the shipper may tender a single shipment with multiple pieces, and each piece may
have a distinct shipping label. In this context, a RequestedPackage node represents each
individual piece, and there is a limitation of 999 RequestedPackage nodes in the request.

4.2.11 RateRequest Input: ShipTimeStamp

The ShipmentTimeStamp node is the date/time stamp (including GMT offset) when the shipment
will be ready for shipping and tendered to the carrier, either as part of a scheduled pickup, regular

PAGE 22 OF 417
MYDHL API – DEVELOPER GUIDE

pickup, station dropoff, etc. Please note that the timestamp for this event does not represent the
time of the execution of the service, and should not be considered a system event.

4.2.12 RateRequest Input: UnitOfMeasurement

The UnitOfMeasurement node conveys the unit of measurements used in the operation. This
single value corresponds to the units of weight and measurement which are used throughout the
message processing. The value of ‘SI’ corresponds to KG and CM, respectively, while the value of
‘SU’ corresponds to LB and IN, respectively.

4.2.13 RateRequest Input: Contents

The Contents node details whether a shipment is non-dutiable (value DOCUMENTS) or dutiable
(NON_DOCUMENTS). Depending on the nature of the contents of the shipment, if customs duties
are applicable, different products may be offered by the DHL web services.

4.2.14 RateRequest Input: DeclaredValue

The DeclaredValue contains the value of the shipment. The field is optional decimal with a total
length of 18 characters 3 corresponding to the fraction part.

4.2.15 RateRequest Input: DeclaredValueCurrencyCode

This is to specify the currency code for the declared value. It is an optional field with a length of 3
characters.

4.2.16 RateRequest Input: PaymentInfo

The PaymentInfo node details the potential terms of trade for this specific shipment, and the
possible enumerated values for this field are;
- CFR – Cost And Freight
- CIF – Cost, Insurance and Freight
- CIP – Carriage And Insurance Paid To
- CPT – Carriage Paid To

PAGE 23 OF 417
MYDHL API – DEVELOPER GUIDE

- DAF – Delivered At Frontier

- DDP – Delivery Duty Paid
- DDU – Delivery Duty Unpaid
- DAP – Delivered At Place
- DEQ – Delivered Ex Quay (Duty Paid)
- DES – Delivered Ex Ship
- EXW – Ex Works
- FAS – Free Alongside Ship
- FCA – Free Carrier
- FOB – Free On Board

4.2.17 RateRequest Input: Account

The Account field details the DHL account number used for the rate request. When the account
number is in this field, this account number serves as both the shipper account as well as payer
account. DHL recommends to use the more robust “Billing” structure (detailed further below)

4.2.18 RateRequest Input: PayerCountryCode

This field (when enabled by DHL Express) is to allow rate requests with no account number to be
provided. If you need this function to enabled, please contact your DHL Express IT Consultant.
DHL customers will receive the rate response if the request complies as below;

• Customer is enabled AND Account number is not provided AND PayerCountryCode is

provided – the charges will be calculated by using country-default account number
(standard country rates)

4.2.19 RateRequest Input: Billing

The Billing structure functions as a more robust alternative to the single Account field, and allows
for using a payer account different than the shipper account (to allow for bill-to receiver or bill-to
third party). The web service requestor should use either the Account field or the Billing structure
to communicate account information, and DHL recommends this Billing structure.

PAGE 24 OF 417
MYDHL API – DEVELOPER GUIDE

4.2.20 RateRequest Input: SpecialServices

The SpecialServices section communicates additional shipping services, such as Insurance (or
Shipment Value Protection).

4.2.21 RateRequest Input: RequestValueAddedServices

Flag used to request all the existing special services for the requested product in the response
message. If the value is "Y" all the additional services available for the product selected will be
returned. The default value is "N".

4.2.22 RateRequest Input: ServiceType

If you wish to retrieve the rates and capability for a specific DHL product then provide this in the
ServiceType element. Only the product provided will be validated.

4.2.23 RateRequest Input: NetworkTypeCode

The NetworkTypeCode field is used to filter the facility network type code. The default value is
“AL” (return all products).”DD” for Economy Select products and “TD” for Time Definite products

4.2.24 RateRequest Input: CustomerAgreementInd

PAGE 25 OF 417
MYDHL API – DEVELOPER GUIDE

This element is used for filtering standard and non-standard products. If the value is “N”, the
response message will return the standard products only. The default value for this field is “Y”.

4.2.25 RateRequest Input: ValidateReadyTime

ValidateReadyTime is used to validate the ready time for the shipment to be picked up from the
customer against the pickup window start on Economy Select products. The default value is “N”,
where MyDHL API will NOT validate the shipment to be picked up from customer against pickup
window start.

4.2.26 RateRequest Input: ProductAndServices

ProductsAndServices section is used to query multiple products and combination of special

services. This element cannot be use in combination of <SpecialServices> section and
<LandedCost> section in the request message. The web service request should use either the
ServiceType and
SpecialServices field or the ProductsAndServices structure to retrieve rates and capability for a
specific DHL product, and DHL recommends the ProductsAndServices structure.

4.2.27 RateRequest Input: LandedCost

The Landed Cost section allows further information around products being sold to be provided.
In return the duty, tax and shipping charges are calculated in real time and provides
transparency about any extra costs the buyer may have to pay before they reach them.

If Freight charges are not provided in the request then the ServiceType (DHL Express Product
Code) has to be provided.

GetItemCostBreakdown – if set to “Y” the service returns the Landed Cost quotation with all
breakdowns for all Items.

ShipmentCurrencyCode - currency code for the item price (the product being sold) and freight
charge. The Landed Cost calculation result will be returned in this defined currency.

ShipmentPurpose - Purpose of the shipment. PERSONAL, COMMERCIAL.

PAGE 26 OF 417
MYDHL API – DEVELOPER GUIDE

ShipmentTransportationMode - Mode of transportation – “AIR”, “OCEAN” and “GROUND”.

MerchantSelectedCarrierName – Name of the carrier being shipped with (DHL, UPS, FEDEX, TNT,
POST or OTHERS).

GetTariffFormula – if set to “Y”, the service returns the Tariff Rate Formula for the duty/tax/fee
calculation on Line Item Level and/or Shipment Level. To receive the Line Item and/or Shipment
Level Tariff Formula it is also mandatory to provide the <GetItemCostBreakdown> element value
“Y”.

GetQuotationID – if set to “Y”, the service returns the unique quotation id for successful landed
cost estimation which may be used internally to correlate the estimated landed cost and actual
cost charged.

GetDetailedLineItemLevelStatus – if set to “Y”, the service returns error details with line item
number which helps to identify the respective Item Number segment caused issue.

Duty and Tax is billed outside destination (DTP)

In this case the request for the LandedCost requires Special Services segment – the Service Code
for DTP service is “DD” (please refer to section 4.2.20).

If the duties and taxes are billed at destination then the Special Services segment with Service
Code “DD” is not required.

PAGE 27 OF 417
MYDHL API – DEVELOPER GUIDE

4.2.28 Rate Request Input: LandedCost – Items

This section describes all Items to get the Total Landed Costs. As an example this information
could be found on your Commercial invoice.

4.2.29 Rate Request Input: LandedCost – Items/Item/GoodsCharacteristics

Regulatory bodies in some countries may apply additional fees based on the characteristics of the
goods being sold. We recommend to provide this information.

For example:

PAGE 28 OF 417
MYDHL API – DEVELOPER GUIDE

GoodsCharacteristic Codes are stored within Trade system and directly related to HS
Codes.
This section is mandatory; and therefore at least one characteristic is required (even with EMPTY
Code and Value).

4.2.30 Rate Request Input: LandedCost – Items/Item/AdditionalQuantityDefinitions

For some Items additional quantity type has to be provided on top of specified under
QuantityType.

Please refer to RateRequest LandedCost AdditionalQuantityType allowed values

4.2.31 Rate Request Input: LandedCost – ShipmentMonetaryAmount

Should you wish to aggregate additional charges such as Insurance or Freight the please provide
this here and then total sum including the additional charges will be provided in the Total
Landed Cost. Allowed types are:

“FREIGHT”

“ADDITIONAL_CHARGE”

“INSURANCE”

If the “FREIGHT” charge is not provided then the ServiceType has to be populated.

PAGE 29 OF 417
MYDHL API – DEVELOPER GUIDE

4.3 RATEREQUEST – INPUT FIELD LIST

Mandatory Value
Rate Request fields Comments
/Optional constraints

RateRequest

RateRequest/ClientDetail

sso O This field is for internal use only

plant O This field is for internal use only

RateRequest/Request

RateRequest/Request/ServiceHeader (0:1)

MessageTime O (M) TIMESTAMP Timestamp when the request has

been created. Mandatory when
Landed Cost is requested.

Format:

YYYY-MM-
DD(T)hh:mm:ssGMTTIMEOFFSET

e.g.

2010-11-24T00:17:20+01:00
MessageReference O (M) AN 36 Used for tracking purpose on the
customer side. The same ID will be
returned within response per
request if it is provided. Mandatory
when Landed Cost is requested.
WebstorePlatform O AN 20 Reserved for Third Party Vendors
identification

PAGE 30 OF 417
MYDHL API – DEVELOPER GUIDE

WebstorePlatformVersion O AN 15 Reserved for Third Party Vendors

identification
ShippingSystemPlatform O AN 20 Reserved for Third Party Vendors
identification
ShippingSystemPlatform O AN 15 Reserved for Third Party Vendors
Version identification
PlugIn O AN 20 Reserved for Third Party Vendors
identification
PlugInVersion O AN 15 Reserved for Third Party Vendors
identification
RateRequest/RequestedShipment

GetRateEstimates O “Y” , “N” This element is to provide customers

with options to see DHL products
and services without price. This
improves response times for the
requests.

If this optional tag is used then the

default value of Y is used to show
rates in the billing account currency.
GetDetailedRateBreakdo O “Y” , “N” This option is to receive a
wn breakdown of charges including
taxes and discounts.

The default value is N, a high level

breakdown is provided then.
IncludeAdditionalCurrenc O “Y” , “N” To show charges in other currencies.
ies
When the
<IncludeAdditionalCurrencies>
value is “Y”, value of currencies will
be returned based on below ;

- ‘BILLC’, billing currency

- ‘PULCL’, country public rates
currency
- ‘BASEC’, base currency

The default value is N, response to

show TotalNet and all other rates in
Billing currency only.
DropOffType M Enumerated Possible values:

REGULAR_PICKUP, the pickup

location is already served by a

PAGE 31 OF 417
MYDHL API – DEVELOPER GUIDE

regular courier and an additional

pickup does not need to be
considered for this service

REQUEST_COURIER, the rating

response returns products for which
the pickup capability is given, based
on ShipmentTimeStamp.

NextBusinessDay O AN 1 If set to Y then the query will check

the Next business day for products
and services if your requested
shipping date does not provide any
products and services.

Possible values include Y, N

ShipTimestamp M TIMESTAMP This timestamp identifies the ready
date and time of the rated shipment.

It needs to be provided in the

following format with GMT offset

YYYY-MM-DDTHH:MM:SSGMT+k

2010-02-26T17:00:00GMT+01:00

If the date is on a public holiday,

sunday or any other day where there
is no pickup Capability for DHL
Express then no products and
services will be returned.
PickupLocationCloseTime O AN 26 For future use
UnitOfMeasurement M Enumerated Possible values:
- SI, international metric system (KG,
CM)
- SU, United States system of
measurement (LB, IN)
The unit of measurement for the
dimensions of the package.
Content O Enumerated Possible values :
- DOCUMENTS
- NON_DOCUMENTS
DeclaredValue O N 18.3 Declared value of the shipment
DeclaredValueCurrecyCo de O AN 3 3 character currency code for the
declared value
PaymentInfo M Enumerated The Incoterms applicable to your
shipment.

PAGE 32 OF 417
MYDHL API – DEVELOPER GUIDE

Possible values:
- CFR, Cost And Freight
- CIF, Cost, Insurance and Freight
- CIP, Carriage And Insurance Paid
To
- CPT, Carriage Paid To
- DAF, Delivered At Frontier
- DDP, Delivery Duty Paid
- DDU, Delivery Duty Unpaid
- DAP, Delivered At Place
- DEQ, Delivered Ex Quay (Duty Paid)
- DES, Delivered Ex Ship
- EXW, Ex Works
- FAS, Free Alongside Ship
- FCA, Free Carrier
- FOB, Free On Board

Account M AN 12 The DHL account number that is

used for the shipment. Internally
attached to this account are the
customer specific rates. Please note
if you use the <Account> tag then
the Billing section below is not
needed.
PayerCountryCode O AN 2 The country code of the payer. This
field is to allow rate requests with no
account number provided.

It is mandatory to provide this input

field if DHL customers want to
request for standard country rates
but no account number is provided.

This function needs to be enabled for

your username by your DHL Express
IT Consultant.
RequestValueAddedServi O AN 1 If the value is "Y" all the additional
ces services available for the product
selected will be returned. The
default value is "N".
ServiceType O (M) AN 6 DHL Product Code used to ship the
items; If Freight charges are not
provided in the Landed Cost request
then the ServiceType (DHL Express
Product Code) has to be provided.

PAGE 33 OF 417
MYDHL API – DEVELOPER GUIDE

NetworkTypeCode O "AL", "DD", "TD" The NetworkTypeCode field is used

to filter facility network type code.

The default value is AL, return all

products. DD is for Economy Select
products and TD for Time Definite
products.
CustomerAgreementInd O "Y", "N" Customer agreement indicator for
product and services. This field is for
filtering agreement and non-
agreement products.

The default value is ‘Y’. All standard

and non-agreement products will be
returned.

An example of a customer
agreement product is Medical
Express.
ValidateReadyTime O "Y", "N" Validate ready time against pickup
window start on Economy Select
products.
RateRequest/RequestedShipment/Ship
RateRequest/RequestedShipment/Ship/Shipper
StreetLines O AN 45 Shipper street name and number
StreetName O AN 250 Shipper street name if you wish to
break StreetLines into Street Name
and number instead of using the
StreetLines element.
StreetNumber O AN 50 Shipper street number if you wish to
break StreeLines into Street Name
and number instead of using the
StreetLines element.
StreetLines2 O AN 45 Shipper additional address
information
StreetLines3 O AN 45 Shipper additional address
information
City M AN 45 Shipper city name
CityDistrict O AN 45 Shipper city district/county name
StateOrProvinceCode O AN 2 2 letter state code for the USA only
PostalCode M AN 12 Shipper postal code
CountryCode M AN 2 ISO 2 character codes of the Shipper
country.

PAGE 34 OF 417
MYDHL API – DEVELOPER GUIDE

RateRequest/RequestedShipment/Ship/Shipper/Contact
PersonName M AN 255 A contact name of a person who will
ship the shipment.
CompanyName M AN 100 The company name shipping
PhoneNumber M AN 70 The contact person phone number.
In case of questions, this person can
be called by the courier.
EmailAddress O AN 70 The email address of the contact
person. Has to be a valid formatted
email address
MobilePhoneNumber O AN 70 The mobile phone number of the
contact person.

RateRequest/RequestedShipment/Ship/Recipient
StreetLines O AN 45 Recipient street name and number
StreetName O AN 250 Receiver street name if you wish to
break StreetLines into Street Name
and number instead of using the
StreetLines element.

StreetNumber O AN 50 Receiver street number if you wish to

break StreetLines into Street Name
and number instead of using the
StreetLines element.
StreetLines2 O AN 45 Recipient additional address
information
StreetLines3 O AN 45 Recipient additional address
information
City M AN 45 Recipient city name
CityDistrict O AN 45 Recipient city district/county name
StateOrProvinceCode O AN 2 2 Letter State code for the USA only
PostalCode M AN 12 Recipient postal code
CountryCode M AN 2 ISO 2 character codes of the Receiver
country.
RateRequest/RequestedShipment/Ship/Recipient/Contact

PersonName M AN 255 A contact name of a person who will

receive the shipment.

PAGE 35 OF 417
MYDHL API – DEVELOPER GUIDE

CompanyName M AN 100 The company receiving the

shipment.

PhoneNumber M AN 70 The contact person phone number.

In case of questions, this person can
be called by the courier.

EmailAddress O AN 70 The email address of the contact

person.

MobilePhoneNumber O AN 70 The mobile phone number of the

contact person.

RateRequest/RequestedShipment/Packages (1:1)
RateRequest/RequestedShipment/Packages/RequestedPackages (1:999)
@number M N Will be used as Piece Sequence
number and returned in the
response.
PackageTypeCode O AN 3 Global package type

Valid enumeration;

Please contact your DHL Express

representative if you wish to use a
DHL specific package otherwise
ignore this element.

- 3BX
- 2BC
- 2BP
- CE1
- 7BX
- 6BX
- 4BX
- 2BX
- 1CE
- WB1
- WB3
- XPD
- 8BX
- 5BX
- WB6
- TBL
- TBS
- WB2

PAGE 36 OF 417
MYDHL API – DEVELOPER GUIDE

RateRequest/RequestedShipment/Packages/RequestedPackages/Weight
Value M N 15.3 Weight of the individual
pieces/packages the rating request
is for. Minimum allowed weight is
0.1kg – please see your DHL
Account rate card for more
information on minimum and
maximum weights per piece.
RateRequest/RequestedShipment/Packages/RequestedPackages/Dimensions
Length M 10.3 D Length of the piece listed.
Width M 10.3 D Width of the piece listed.
Height M 10.3 D Height of the piece listed.
RateRequest/RequestedShipment/Billing
ShipperAccountNumber M AN 12 The DHL account number used for
the shipment. Used as the shipper
account number.
Please note if you use this billing
section then the above <Account>
tag is not needed.

<ShipperAccountNumber> is
mandatory then.
ShippingPaymentType M AN 1 Possible values:
- S (use ShipperAccountNumber as
payer)
- R (use BillingAccountNumber as
bill-to receiver account number)
- T (use BillingAccountNumber as
bill-to third party account number)
Please note if you use value R or T
in this tag then the next tag

<BillingAccountNumber> is also
mandatory
BillingAccountNumber O AN 12 The DHL account number used for
the shipment, if
ShippingPaymentType is equal to R
or T.
RateRequest/RequestedShipment/SpecialServices
RateRequest/RequestedShipment/SpecialServices/Service (1:99)
ServiceType M AN 6 Enter II if you wish to get a quote for
Insurance with your prospect

PAGE 37 OF 417
MYDHL API – DEVELOPER GUIDE

shipment. If not needed then leave

the
SpecialServices section out.
Note: Insurance Charge is only
applicable for the RateRequest
service
LocalServiceType O AN 3 The DHL local or country specific
Product Code used to ship the items
ServiceValue O N 18.3 Monetary value of service (e.g.
Insured Value) – this is needed if you
wish to get a quote on Insurance
with your prospect shipment
CurrencyCode O AN 3 Currency code) – this is needed if you
wish to get a quote on Insurance
with your prospect shipment
PaymentCode O AN 3 For future use.
StartDate O Date For future use.
EndDate O Date For future use.
TextInstruction O AN 50 For future use.
RateRequest/RequestedShipment/ProductsAndServices
RateRequest/RequestedShipment/ProductsAndServices/ProductAndServices (0:99)
ServiceType M AN 6 The shipping product requested for
this shipment, corresponding to the
DHL Global Product codes.
LocalServiceType O AN 3 DHL “local / country specific”
Product Code used to ship the items.
RateRequest/RequestedShipment/ProductsAndServices/ProductAndServices/SpecialServices
RateRequest/RequestedShipment/ProductsAndServices/ProductAndServices/SpecialServices
/Service (0:99)
ServiceType M AN 6 Enter II if you wish to get a quote for
Insurance with your prospect
shipment. If not needed then leave
the
SpecialServices section out.
LocalServiceType O AN 3 The DHL local or country specific
Product Code used to ship the items

ServiceValue O N 18.3 Monetary value of service (e.g.

Insured Value) – this is needed if you
wish to get a quote on Insurance
with your prospect shipment

CurrencyCode O AN 3 Currency code) – this is needed if you

wish to get a quote on Insurance
with your prospect shipment

PAGE 38 OF 417
MYDHL API – DEVELOPER GUIDE

PaymentCode O AN 3 For future use.

StartDate O Date For future use.
RateRequest/RequestedShipment/LandedCost
GetItemCostBreakdown M Enumerated Allowed values “Y” - item cost
breakdown will be returned, “N” -
item cost breakdown will not be
returned
ShipmentCurrencyCode M AN 3 Currency code for the item price (the
product being sold) and freight
charge. The Landed Cost calculation
result will be returned in this defined
currency
ShipmentPurpose O Enumerated Possible values:

"COMMERCIAL" – B2B

"PERSONAL" – B2C
ShipmentTransportation O Enumerated Possible value:
Mode
"AIR"

"OCEAN"

"GROUND"
MerchantSelectedCarrier O Enumerated Carrier being used to ship with.
Name Allowed values are:

“DHL”,”UPS”,”FEDEX”,”TNT”,”POST”,
”OTHERS”
GetTariffFormula O Enumerated Possible value:

“Y”, returns line item level and/or

shipment level Tariff Formula.

To receive the Line Item and/or

Shipment Level Tariff Formula it
is also mandatory to provide the
<GetItemCostBreakdown>
element value “Y”.

“N”(default), Tariff Formula will not

be returned.

GetQuotationID O Enumerated Possible value:

“Y”, returns quotation id in response.

PAGE 39 OF 417
MYDHL API – DEVELOPER GUIDE

“N”(default), quotation id will not be

returned in response.

GetDetailedLineItemLevelSt O Enumerated Possible value:

atus
“Y”, returns line item number for
error response.

“N”(default), line item number will

not be returned.

RateRequest/RequestedShipment/LandedCost/Items (1:1)
RateRequest/RequestedShipment/LandedCost/Items/Item (1:1000)

ItemNumber O N Line item number

Description O AN 512 Description of the item.

Remark O AN 255 Item full description

ManufacturingCountryC O AN 2 ISO Country code of the goods

ode manufacturer

SKUPartNumber O AN 35 SKU number

Quantity O N 12.3 Total quantity of the item(s) to be

shipped.

QuantityType O AN 20 Allowed values are

“PRT” – Part/ Article

“BOX” - Box

UnitPrice O 20.5D Product Unit price

UnitPriceCurrencyCode O AN 3 Currency code of the Unit Price

CustomsValue O N 18.3 Not used

CustomsValueCurrencyC O AN 3 Not used

ode

HarmonizedSystemCode O AN 18 HS Code identifies the item for the

Import country to identify the
import duty rate for the item.

PAGE 40 OF 417
MYDHL API – DEVELOPER GUIDE

Can be provided with or without

dots.

Conditional Validation Logic:

HarmonizedSystemCode is
mandatory if
EstimatedTariffRateType
("DERIVED_RATE" or
"HIGHEST_RATE" or
"LOWEST_RATE" or
"CENTER_RATE") not provided in the
request otherwise it is considered as
Optional.

ItemWeight O N 15.3 Weight of the item

ItemWeightUnitofMeasur O Enumerated Unit of measurement – “SI” or “SU”

ement

Category O AN 50 Product Category Code of the Item.

Please refer to Appendix section

RATEREQUEST LANDEDCOST
CATEGORY CODES for possible
values.

Brand O AN 50 Item’s brand

EstimatedTariffRateType O AN 25 Estimated Tariff Rate Type

Possible Values:
DEFAULT_RATE - Actual rate (either
standard or preferential rate) is
returned only if full Harmonized
System Code (HS Code) is provided.
Error is returned when full HS code
is not provided.

DERIVED_RATE - Actual rate is

returned if full import Harmonized
System code (HS Code) is provided
otherwise default derived rate is
returned.

HIGHEST_RATE - Actual rate is

returned if full import Harmonized
System code (HS Code) is provided

PAGE 41 OF 417
MYDHL API – DEVELOPER GUIDE

otherwise highest derived rate is

returned.

CENTER_RATE - Actual rate is

returned if full import Harmonized
System code (HS Code) is provided
otherwise measure of center (mode/
average) derived rate is returned.

LOWEST_RATE - Actual rate is

returned if full import Harmonized
System code (HS Code) is provided
otherwise lowest derived rate is
returned.

When none of the above is provided,

returns actual rate (either standard
or preferential rate) only if full HS
code is provided. Error is returned
when full HS code is not provided.

RateRequest/RequestedShipment/LandedCost/Items/Item/GoodsCharacteristics (1:1)

RateRequest/RequestedShipment/LandedCost/Items/Item/GoodsCharacteristics/GoodsCh
aracteristic (1:999)

CharacteristicCode M AN 35 Please contact Express country

representative to provide all
applicable codes

CharacteristicValue M AN 50 Value related to the code

RateRequest/RequestedShipment/LandedCost/Items/Item/AdditionalQuantityDefinitions

RateRequest/RequestedShipment/LandedCost/Items/Item/AdditionalQuantityDefinitions
/AdditionalQuantityDefinition (0:100)

AdditionalQuantity M N 15.3 An Item's additional quantity value:

example is percent of alcohol

AdditionalQuantityType M AN 20 Item additional quantity value UOM:

example PFL=percent of alcohol

RateRequest/RequestedShipment/LandedCost/ShipmentMonetaryAmount

RateRequest/RequestedShipment/LandedCost/ShipmentMonetaryAmount/Charges
(1:20)

ChargeType M LIST The additional charges from

merchant that they would like to

PAGE 42 OF 417
MYDHL API – DEVELOPER GUIDE

aggregate and sum up as part of

Total Landed Cost. Allowed values
are:

“FREIGHT”

“ADDITIONAL_CHARGE”

“INSURANCE”

ChargeAmount M N 18.3 The total charge amount of the

specific charge

CurrencyCode M AN 3 The currency code

4.4 RATEREQUEST - OUTPUT

The following diagram shows an overview of the rate response structure. The critical information
to derive from this response are the notification codes for the response, the products returned,
the estimated charges, and the expected delivery time for the shipment.

4.4.1 RateResponse Schema Diagram

Each of the individual sections of Rate Response is represented below in schema diagram, with
context, and a detailed description of each field follows in the Output Field List.

4.4.2 RateResponse Output: ServiceHeader

The ServiceHeader structure includes MessageReference which is taken from the request as
well as MessageTime showing when the request has been processed on DHL side. The

PAGE 43 OF 417
MYDHL API – DEVELOPER GUIDE

ServiceInvocationID is DHL internal Service invoation ID to expedite support. The QuotationID

returns for every successful landed cost estimation only when it is requested in LandedCost
segment of request message(<GetQuotationID>Y<GetQuotationID>).

This is only available when the LandedCost segment is part of the request.

4.4.3 RateResponse Output: Notification

The Notification structure includes the result code and message, based on the results of the
processing. Successful messages will include a zero error code and no corresponding message,
while exceptions will be noted with both code and message. MessageDetail will return line item
number with error details for LandedCost. MessageDetail returns only when line item level error
is requested in LandedCost segment of request message (<GetDetailedLineItemLevelStatus>Y<
GetDetailedLineItemLevelStatus>).

4.4.4 RateResponse Output: Service

For successful responses, there will be 1-to-M Service nodes returned, which will include all of
the information about the DHL product returned. A critical element of the Service structure is
the @type attribute, which designates the DHL global product code that corresponds to that
service quotation. The charges and delivery times for that product are in the subsequent nodes
within Service.

PAGE 44 OF 417
MYDHL API – DEVELOPER GUIDE

PAGE 45 OF 417
MYDHL API – DEVELOPER GUIDE

4.4.5 RateResponse Output: TotalNet

For successful responses, the total net structure shows the summary of the net estimated charges
(plus currency) for a given Service. Please note that the subsequent nodes, under Charges,
provides line item detail of the estimated charge. Nevertheless, for consumers only interested in
the total estimate, these nodes will have the summary estimates.

4.4.6 RateResponse Output: TotalChargeTypes

TotalChargeTypes pertains to the type of charges returned. This element will only show when
GetRateEstimates = Y and GetDetailedRateBreakdown = Y.

Different types of total charges will be returned in Breakdown/Type element with possible values

as:

STTXA – Total tax for the shipment

STDIS – Total discount for the shipment

SPRQT – Net shipment / weight charge

4.4.7 RateResponse Output: Items

PAGE 46 OF 417
MYDHL API – DEVELOPER GUIDE

Items in the response contain one or many charge details (if explicitly requested providing
<GetItemCostBreakdown>Y</GetItemCostBreakdown>) for all Landed Cost Items.

TariffRateFormula returns formula used for charges (duty/tax/fee) calculation only when
requested in LandedCost segment of request
message(<GetTariffFormula>Y</GetTariffFormula>) for one or many charge details for all
Landed Cost Items.

PAGE 47 OF 417
MYDHL API – DEVELOPER GUIDE

4.4.8 RateResponse Output: Charges

This section provides line item visibility into the components of that charge and value added
service codes that are available for the prospect shipment. In this context, the sum of the charges
communicated in this structure will be equal to the charge in TotalNet. The Currency field will
apply for all of the subsequent charges, and the ChargeType is a description of the local charge
code description for that charge. The text in the ChargeType may vary, depending on locale.

Important: The <ChargeCode> field is the Value Added Service code you can use in your prospect
shipment when using ShipmentRequest. Please note that FF (Fuel Surcharge) should not be used
as this is automatically added during billing.

<ChargeType> is the name of the service i.e. Shipment Insurance or Dangerous Goods.

<TariffRateFormula> returns formula used for charges (duty/tax/fee) calculation in shipment

only when requested in LandedCost segment of request message (GetTariffFormula=Y and
GetItemCostBreakdown=Y) for one or many charge details.

When LandedCost is requested then following Charge Types might be returned

PAGE 48 OF 417
MYDHL API – DEVELOPER GUIDE

Charge Type Description

STDIS Quoted shipment total discount

SCUSV Shipment Customs value
SINSV Insured value
SPRQD Shipment product quote discount
The price quoted to the Customer by DHL at the time of the booking. This quote
SPRQN
covers the weight price including discounts and without taxes.
The total of service charges quoted to customer for DHL Express value added
STSCH
services, the amount is after discounts and doesn't include tax amounts.
The total of service charges as provided by Merchant for the purpose of landed cost
MACHG
calculation.
The freight charge as provided by Merchant for the purpose of landed cost
MFCHG
calculation.

4.4.9 RateResponse Output: DeliveryTime

The DeliveryTime field is provided for each Service, and details the local timestamp (based on
delivery location) when the shipment will be delivered by.

4.4.10 RateResponse Output: DeliveryType

The DeliveryType field is a delivery date capabilities considering customs clearance days. The
possible value of this field is as below;

• QDDF - is the fastest ("docs") transit time as quoted to the customer at booking or
shipment creation. No custom clearance is considered.

• QDDC - constitutes DHL's service commitment as quoted at booking/shipment creation.

QDDc builds in clearance time, and potentially other special operational non-transport
component(s), when relevant.

PAGE 49 OF 417
MYDHL API – DEVELOPER GUIDE

4.4.11 RateResponse Output: CutoffTime

The CutoffTime field is optionally provided for each Service, and details the local timestamp
(based on origin location) when the service offered in the response has its operational cutoff. This
is the timestamp when the shipment needs to be tendered to the courier in order to meet the
cutoff for that day’s shipping. When the GetDetailedBreakdown = Y, the CutOffTime will be
returned in GMT format and respective offset in the CutoffTimeGMT and CutoffTimeOffset field.

4.4.12 RateResponse Output: NextBusinessDayInd

The NextBusinessDayInd field is optionally provided for each Service, and is a Y/N indicator to
alert the consumer that the next available pickup date is beyond the requested shipment date.
When the Request NextBusinessDay flag is not used (or N), this value will always be N. Otherwise,
this value may have a value of Y or N, depending on how the next available pickup date relates to
the requested shipment date/time.

4.4.13 RateResponse Output: OriginServiceArea

This complex element contains the Service Area code and Service Area description for the origin
of the shipment.

4.4.14 RateResponse Output: DestinationServiceArea

This complex element contains the Service Area Code and Service Area Description for the
destination of the shipment.

PAGE 50 OF 417
MYDHL API – DEVELOPER GUIDE

4.4.15 RateResponse Output: ExchangeRates

The ExchangeRates is used to show exchange of Billing vs Base Currency and Origin/Pickup Local
vs Base Currency. This element will only show in the response when the IncludeAllCurriences = Y.

PAGE 51 OF 417
MYDHL API – DEVELOPER GUIDE

4.5 RATE RESPONSE – OUTPUT FIELD LIST

Mandatory Value
Rate Response fields /Optional constraints Comments

RateResponse

RateResponse/Provider

"@code" M AN 1 Provider Code, always contains DHL.

RateResponse/Provider/ServiceHeader

MessageTime O TIMESTAMP Timestamp when DHL processed request

yyyy-MM-ddTHH:mm:sszzz (2020-02-
13T17:54:12+04:00)

MessageReference O AN 32 Mapped directly from request if provided.

Merchant can track messages by this reference

ServiceInvocationID O AN DHL internal Service invoation ID to expedite

support

QuotationID O AN Unique quotation id for internal use.

RateResponse/Provider/Notification

"@code" M N Error > 0 or Success Code = 0

Message M AN Response Message, see Error codes for more

details

MessageDetail O AN Line Item number with error details for

LandedCost.

RateResponse/Provider/Service

"@type" M AN This is the code for the product for which the
delivery is feasible respecting the input data
from the request.

"@account" O Not used.

DeliveryTime O TIMESTAMP This is the estimated date/time the shipment

will be delivered by for the rated shipment and
product listed
Example: (e.g. 2019-06-26T17:00:00)

PAGE 52 OF 417
MYDHL API – DEVELOPER GUIDE

DeliveryType O Enumerated Delivery Date capabilities considering customs

clearance days.

QDDF - is the fastest ("docs") transit time as

quoted to the customer at booking or shipment
creation. No custom clearance is considered.

QDDC - constitutes DHL's service commitment

as quoted at booking/shipment creation. QDDc
builds in clearance time, and potentially other
special operational non-transport
component(s), when relevant.

CutoffTime O TIMESTAMP This is the cutoff time for the service offered in
the response. This represents the latest time
(local to origin) which the shipment can be
tendered to the courier for that service on that
day.
Example: (e.g. 2019-06-26T17:00:00)
CutoffTimeGMT O TIME Pickup cut off time in GMT

HH:MM:SS
CutoffTimeOffset O TIME Pickup cut off time GMT Offset
NextBusinessDayInd O A1 This indicator has values of Y or N, and tells the
consumer if the service in the response has a
pickup date on the same day as the requested
shipment date (per the request).
PickupWindowEarliestTime O TIME The DHL earliest time possible for pickup
PickupWindowLatestTime O TIME The DHL latest time possible for pickup
ServiceName O A1 Local service name
LocalServiceType O A DHL “local / country specific” Product Code
used to ship the items. Optional and applicable
only to get Landed Cost
LocalServiceCountryCode O AN 2 The country code for the local service used
NetworkTypeCode O Enumerated The NetworkTypeCode element indicates the
product belongs to the Day Definite (DD) or
Time Definite (TD) network.

Possible Values;

- ‘DD’, Day Definite product

- ‘TD’, Time Definite product
CustomerAgreementInd O A1 Indicator that the product only can be offered
to customers with prior agreement.
TotalTransitDays O INTEGER The number of transit days

PAGE 53 OF 417
MYDHL API – DEVELOPER GUIDE

PickupAdditionalDays O AN This is additional transit delays (in days) for

shipment picked up from the mentioned city or
postal area to arrival at the service area.
DeliveryAdditionalDays O AN This is additional transit delays (in days) for
shipment delivered to the mentioned city or
postal area following arrival at the service area.
VolumetricWeight O 12.3 D The dimensional weight of the shipment
QuotedWeight O 12.3 D The quoted weight of the shipment
UnitOfMeasurement O Enumerated Possible values:

- SI, international metric system (KG, CM)

- SU, the US system of measurement (LB, IN)
The unit of measurement for the dimensions of
the package.
PickupDayOfWeek O AN Pickup day of the week number
DestinationDayOfWeek O AN Destination day of the week number
PricingDate O DATE The date when the rates for DHL products and
services is provided
RateResponse/Provider/Service/OriginServiceArea
FacilityCode O AN 3 The DHL Facility Code for the Origin
ServiceAreaCode O AN 3 The DHL Service Area Code for the origin of the
Shipment
RateResponse/Provider/Service/DestinationServiceArea
FacilityCode O AN 3 The DHL Facility Code for the Destination
ServiceAreaCode O AN 3 The DHL Service Area Code for the destination of
the Shipment
RateResponse/Provider/Service/TotalNet (1:3)
Currency M AN 3 This the currency of the rated shipment for the
product listed.
Amount M N This is the total prize of the rated shipment for
the product listed.
@type O Enumerated Possible Values :

- ‘BILLC’, billing currency

- ‘PULCL’, country public rates currency
- ‘BASEC’, base currency
RateResponse/Provider/Service/Charges (0:3)
@type O Enumerated Possible Values :

- ‘BILLC’, billing currency

- ‘PULCL’, country public rates currency
- ‘BASEC’, base currency
Currency M AN 3 This the currency for all line item charges listed
in the Charge section

PAGE 54 OF 417
MYDHL API – DEVELOPER GUIDE

RateResponse/Provider/Service/Charges/Charge (1:999)
ChargeCode O AN 2 Special service or extra charge code – this is the
code you would have to use in the
ShipmentRequest message if you wish to add
an optional Service such as Insurance.
LocalChargeCode O AN 2 Local service code
ChargeType M AN Name of the Value Added Service
ChargeAmount M Token The charge amount of the line item charge.
ChargeName O AN 35 Name of the charge
ChargeCurrencyCode O AN 3 Currency code of the charge
ChargeCodeTypeCode O AN Special service charge code type for service.
BillingServiceInd O "Y", "N" Indicator if there is any discount allowed .

CustomerAgreementInd O "Y", "N" Customer agreement indicator for product and

services, if service is offered with prior
customer agreement.

MarketedServiceInd O "Y", "N" Indicator if the special service is marketed

service.

TariffRateFormula O AN Returns Formula used for charges

(duty/tax/fee) calculation on shipment level.

RateResponse/Provider/Service/Charges/Charge/ChargeBreakdown
RateResponse/Provider/Service/Charges/Charge/ChargeBreakdown/Breakdown (0:99)
ChargeType O AN If a breakdown is provided, details can either
be;

- "TAX",
- "DISCOUNT"
Type O AN Discount or tax type codes as provided by
DHL Express. Example values;
For discount;

P – promotional

S – special
Amount O N The actual amount of the discount/tax
Rate O N Percentage of the discount/tax

PAGE 55 OF 417
MYDHL API – DEVELOPER GUIDE

BaseAmount O N The base amount of the service charge

RateResponse/Provider/Service/TotalChargeTypes (0:3)
@type O Enumerated Possible Values :

- ‘BILLC’, billing currency

- ‘PULCL’, country public rates currency
- ‘BASEC’, base currency
Currency M AN 3 This is the currency of the rated shipment for
the product listed.
RateResponse/Provider/Service/TotalChargeTypes/TotalChargeType (1:99)
Type M Expected values in Breakdown/Type are below:
Enumerated
STTXA – Total tax for the shipment
STDIS – Total discount for the shipment
SPRQT – Net shipment / weight charge
Amount M N The amount price of DHL product and services
RateResponse/Provider/Service/Items (0:1)
RateResponse/Provider/Service/Items/Item (0:999)
ItemNumber M Integer Item line number
RateResponse/Provider/Service/Items/Item/Charge (1:50)
ChargeCode O AN 2 Code of the charge
LocalChargeCode O AN 2 Local code of the charge
ChargeType M AN Charge type or category.

Possible values;

- DUTY
- TAX
- FEE
ChargeAmount M N
The charge amount of the line item charge.

ChargeName O AN 35 Name of the charge

ChargeCurrencyCode O AN 3 Currency code of the charge
ChargeCodeTypeCode O AN Special service charge code type for service.
XCH type charge codes are Optional Services
and should be displayed to users for selection.
The possible values are;

- XCH = Extra charge

- FEE = Fee
- SCH = Surcharge
- NRI = Non Revenue Item

PAGE 56 OF 417
MYDHL API – DEVELOPER GUIDE

Other charges may be automatically returned

when applicable.
BillingServiceInd O "Y", "N" Indicator if there is any discount allowed
CustomerAgreementInd O "Y", "N" Customer agreement indicator for product and
services, if service is offered with prior
customer agreement
MarketedServiceInd O "Y", "N" Indicator if the special service is marketed
service
TariffRateFormula O AN Returns Formula used for charges
(duty/tax/fee) calculation.

RateResponse/Provider/Service/Items/Item/Charge/ChargeBreakdown
RateResponse/Provider/Service/Items/Item/Charge/ChargeBreakdown/Breakdown (0:99)
ChargeType O AN If a breakdown is provided, details can either
be; - "TAX",

- "DISCOUNT"
Type O AN Discount or tax type codes as provided by DHL.
Example values;
For discount;
P – promotional
S – special
Amount O N The actual amount of the discount/tax
Rate O N Percentage of the discount/tax
BaseAmount O N The base amount of the service charge
RateResponse/Provider/Service/Items/Item/Notification (0:1)
“@Code” O String Error/Warning > 0 or Success Code = 0
Message O AN 128 Short description of the error / status
DetailedMessage O AN 1024 Detailed description of the error / status
RateResponse/Provider/ExchangeRates
RateResponse/Provider/ExchangeRates/ExchangeRate (1:3)
Rate M N Rate of the currency exchange
Currency M AN 3 The currency code
BaseCurrency M AN 3 The currency code of the base currency is either
USD or EUR

PAGE 57 OF 417
MYDHL API – DEVELOPER GUIDE

5. SHIPMENTREQUEST

5.1 SHIPMENTREQUEST - DESCRIPTION

The ShipmentRequest Operation will allow you to generate an AWB number and piece IDs,
generate a shipping label, transmit manifest shipment detail to DHL, and optionally book a courier
for the pickup of a shipment. The key elements in the response of the Shipment Request will be a
base64 encoded PDF label and the Shipment and Piece identification numbers, which you can use
for tracking on the DHL web site.

While the RateRequest and ShipmentRequest services can be used independently, DHL
recommends the use of RateRequest to first validate the products available for the
shipper/receiver. The global product codes which are output during the RateResponse can be
used directly as input into the Shipment Request, as both perform similar validations in terms of
service capability.

5.2 SHIPMENTREQUEST - INPUT

The following diagram shows an overview of the request input structure.

Within the ShipmentRequest, the ClientDetail is an optional node for reference use, and does not
affect functionality. The critical elements are contained within the RequestedShipment node.

PAGE 58 OF 417
MYDHL API – DEVELOPER GUIDE

PAGE 59 OF 417
MYDHL API – DEVELOPER GUIDE

5.2.1 ShipmentRequest Schema Diagram

Each of the individual sections of RequestedShipment is shown below in schema diagram, with
context, and a detailed description of each field follows in the Input Field List.

5.2.2 ShipmentRequest Input: Request

Optional section to populate information used to identify customer request for troubleshooting
or tracking. DHL Express recommends that this information is provided.

5.2.3 ShipmentRequest Input: ShipmentInfo

PAGE 60 OF 417
MYDHL API – DEVELOPER GUIDE

The ShipmentInfo section provides general shipment detail, pertaining to operational and billing
features. The Billing, Special Services, Document Images, Label Option and Shipment Reference
substructures are detailed in below sections.

PAGE 61 OF 417
MYDHL API – DEVELOPER GUIDE

5.2.4 ShipmentRequest Input: ShipmentInfo DropOffType

The DropOffType is a required field with two possible values, and these values are used to
determine whether a driver pickup will be scheduled as part of this orchestrated service. If a
pickup is requested (REQUEST_COURIER), the web service consumer can expect the optional
DispatchConfirmationNumber to be populated in the response. Otherwise, no pickup will be
scheduled, and no pickup reference information will be provided in the response.

5.2.5 ShipmentRequest Input: ShipmentInfo ServiceType

The ServiceType is a required field which corresponds to the DHL global product code, which
describes the product requested for this shipment. These product codes are available as output
from Rate Request, and the product codes provided will be validated against the origin-
destination requested in the Shipment Request.

5.2.6 ShipmentRequest Input: ShipmentInfo Account

The Account field is a required business field, but is optional within the schema as this information
can be provided in one of two structures. It must either be provided in this field or within the
Billing structure (see below). DHL recommends use of more robust Billing structure. This field
corresponds to the Shipper account number and usage of this field presumes that the account will
also be used as the Payer account. This field is validated as a valid account for usage within this
process. For dutiable shipment, account will be assumed as the
DutyAndTaxPayerAccountNumber if the
DutyAndTaxPyerAccountNumber is not provided under Billing section.

PAGE 62 OF 417
MYDHL API – DEVELOPER GUIDE

5.2.7 ShipmentRequest Input: ShipmentInfo Billing

If the Billing structure is included, the first two fields are required. This schema structure
conveys the Shipper Account Number, as well as extensibility to convey receiver or third party
account number as payer. The DutyAndTaxPayerAccountNumber field indicates the DHL
account number used for duties payment.

The ShipmentPrepaidTotalCharge is an optional field used to support Cash Shipments where

agreed with DHL Express. Cash shipments will only work if the DHL Express Account number
used is a valid account with account type of “C” – Cash account in the DHL systems, the
ShippingPaymentType value is ‘S’ - shipper and this feature is enabled within the customer
profile.

The NeverOverrideBillingServices is an optional flag to indicate whether to override the DHL

Billing Service should it be incorrectly provided. This is automatically derived based on the
Shipper/Receiver Address, Shipper/Payer Account number and type of shipment.

N (No) - overwrite with derived DHL Billing Service via Account Validation - Create Shipment
service - default behavior

Y (Yes) - use customers provided billing special service code to derive the DHL Billing service (not
recommended)

PAGE 63 OF 417
MYDHL API – DEVELOPER GUIDE

5.2.8 ShipmentRequest Input: ShipmentInfo SpecialServices

The SpecialServices section communicates additional shipping services, such as Insurance (or
Shipment Value Protection). For example, to support Insurance, the ServiceType would have a
value of ‘II, which the ServiceValue and CurrencyCode containing the insured value and currency,
respectively. Please note that for all other Value Added Service like Saturday Delivery, Dangerous
goods etc you do not need to declare the service charge and currency.

For indicating Cash on Delivery service (ServiceType value of ‘KB’), details of amount to be
collected needs to be provided in fields ServiceValue, CurrencyCode and
PaymentMethods/PaymentMethod to indicate the mode of payment.

A. Steps to create PLT Shipments using Service Type “WY”

Below steps describe two possible options of creating a PLT Shipment Request:

a. <ServiceType> value as ‘WY’:

Customer sends the CreateShipment request with relevant shipment information and
below mandatory fields:
1. <SpecialServices/Service[n]/ServiceType> element must contain value of ‘WY.
2. <DocumentImages> element must contain the commercial invoice or other
supporting document images required for Customs clearance, encoded in base64,
and the image file type which has been encoded can also be defined here.
3. Request for customs invoice rendering using <RequestDHLCustomsInvoice>
option and provide the sufficient <ExportDeclaration> element details.
Note: If providing this element, it does not require providing <DocumentImages>
element with customs invoice images.

B. CreateShipment with UploadInvoiceData request shipment processing – requires

approval from your local DHL Express IT representative and DHL Express Operations.

PAGE 64 OF 417
MYDHL API – DEVELOPER GUIDE

Usage of <ServiceType> value of ‘PM’ in CreateShipment Request message indicates that

the shipment has a commercial invoice data coming in separately. This is an indicator for
DHL backend application that a subsequent data merging process is expected of the
Shipment Detail and Commercial Invoice Detail.
Below steps describes two possible options of submitting a CreateShipment together with a
UploadInvoiceData request:

a) Customer submits the Shipment Request followed by Commercial Invoice data

1. Customer sends the CreateShipment request with relevant shipment information and
below mandatory fields:
<SpecialServices/Service[n]/ServiceType> element must contain value of ‘PM’.
2. CreateShipment request is not expected to contain the ExportDeclaration element and its
child nodes. However, if request message does contain the ExportDeclaration element
this section is ignored during the data merge process. Instead, the ExportDeclaration data
from UploadInvoiceData service will be taken as part of the data merging process.

3. It is customer’s responsibility to declare the shipments with accurate amount in

<CustomsValue> node that will be printed in the Waybill document.

4. Customer receives CreateShipment response message with

<ShipmentIdentificationNumber>.

5. Customer sends the UploadInvoiceData request message with commercial invoice data to
complete the process. Refer to Section 14 UploadInvoiceData Service for detailed
information on Request and Response structure.
• <ShipmentInfo/ShipmentIdentificationNumber> in request message must be the
value from CreateShipment response in step 3.

b) Customer submits the Commercial Invoice data followed by the Shipment Request

1. Customer sends the UploadInvoiceData request message with commercial invoice data.
Refer to Section 14 UploadInvoiceData Service for detailed information on Request and
Response structure.
Request message must contain the below mandatory fields:
• Shipment reference must be provided in
<InvoiceReferences/InvoiceReference/InvoiceReferenceNumber> where
<InvoiceReferences/InvoiceReference/InvoiceReferenceType> value of ‘CU’
• <Billing/ShipperAccountNumber> must contain the payer account number

Note: If submitting multiple <ExportDeclaration> in the request message, each

<ExportDeclaration> must contain the same value of InvoiceReferenceNumber
with InvoiceReferenceType value of ‘CU’.

2. Customer receives UploadInvoiceData response message with success notification code.

PAGE 65 OF 417
MYDHL API – DEVELOPER GUIDE

3. Customer sends the CreateShipment request with relevant shipment information and
below mandatory fields:
a. <SpecialServices/Service[n]/ServiceType> element must contain value of ‘PM’.
b. <ShipmentReferences/ShipmentReference/ShipmentReference> where
<ShipmentReferences/ShipmentReference/ShipmentReferenceType> element must
contain value of ‘CU’ with Shipment Reference number from step 1.
c. <Billing/ShipperAccountNumber> must contain the same payer account number
provided in step 1.
Note: To effectively merge the Shipment Details and Commercial Invoice, values
provided in Shipment Reference and ShipperAccountNumber in step 1 and step
3 must be the same.

4. Customer receives CreateShipment response message with

<ShipmentIdentificationNumber>.

5.2.9 ShipmentRequest Input: ShipmentInfo Currency

The Currency field is a required field which details the currency for the Customs Value.

5.2.10 ShipmentRequest Input: ShipmentInfo UnitOfMeasurement

The UnitOfMeasurement node conveys the unit of measurements used in the operation. This
single value corresponds to the units of weight and measurement used throughout the message
processing. The value of ‘SI’ corresponds to KG and CM, respectively, while the value of ‘SU’
corresponds to LB and IN, respectively.

5.2.11 ShipmentRequest Input: ShipmentInfo ShipmentIdentificationNumber

The ShipmentIdentificationNumber should only be used if discussed with your DHL Express IT
Consultant. This field (when enabled by DHL Express) allows you to use your own DHL Express
allocated Waybill number range to be used – please note that the norm is to not use this field and
each shipment will automatically have its own Waybill number assigned when creating the
shipment.

5.2.12 ShipmentRequest Input: ShipmentInfo UseOwnShipmentIdentificationNumber

The UseOwnShipmentIdentificationNumber should only be used if discussed with your DHL

Express IT Consultant. This field (when enabled by DHL Express) allows you to use your own DHL
Express allocated Waybill number range to be used and tells MyDHL API that you wish to provide
your own Waybill number for each shipment – please note that the norm is to not use this field

PAGE 66 OF 417
MYDHL API – DEVELOPER GUIDE

and each shipment will automatically have its own Waybill number assigned when creating the
shipment.

5.2.13 ShipmentRequest Input: ShipmentInfo LabelType

The LabelType node conveys the label type used in the operation. It is an optional field. This single
value corresponds to the label type returned to customer. Customer can send one of the four
values in this field (PDF, ZPL, EPL, LP2). If customer didn’t include this tag, the default is PDF.

5.2.14 ShipmentRequest Input: ShipmentInfo LabelTemplate

The LabelTemplate node conveys the label template used in the operation. It is an optional field.
This single value corresponds to the label template used to generate labels. – Please check with
your DHL Express IT representative which templates meets your requirements. If this tag is not
included, then the default of ECOM26_84_001 will be used

5.2.15 ShipmentRequest Input: ShipmentInfo ArchiveLabelTemplate

The ArchiveLabelTemplate node conveys the label template used in the operation. It is an
optional field. This single value corresponds to the label template used to generate the Archive
labels. Please check with your DHL Express IT representative which templates meets your
requirements. If this tag is not included, then the default of ARCH_8x4 will be used

5.2.16 ShipmentRequest Input: ShipmentInfo QRCodeTemplate

The QRCodeTemplate node conveys the QRCode template used in the operation. It is an optional
field. This single value corresponds to the QR template used to generate the QR code image.
Please check with your DHL Express IT representative which template meets your requirements.
If this tag is not included, then the default of QR_1_00_LL_PNG_001 will be used.

PAGE 67 OF 417
MYDHL API – DEVELOPER GUIDE

5.2.17 ShipmentRequest Input: ShipmentInfo QRCodeImageFormat

The QRCodeImageFormat node conveys the QRCode image type used in the operation. It is an
optional field. If this tag is not included, then the default of PNG image format will be used.

5.2.18 ShipmentRequest Input: ShipmentInfo CustomsInvoiceTemplate

The CustomsInvoiceTemplate node conveys the Customs Invoice template used in the operation.
It is an optional field. This single value corresponds to the customs invoice template used to
generate customs invoice only when the RequestDHLCustomsInvoice= Y. The default template is
'COMMERCIAL_INVOICE_P_10'.

There are several template options to choose from. Below are the possible template values and
their description:

- COMMERCIAL_INVOICE_04
This template can print the Shipper, Recipient, Buyer and Importer address details and is on
portrait orientation. This template is for exclusive use for preparing Loose BBX (LBBX) shipment.

- COMMERCIAL_INVOICE_L_10
This template can print the Shipper, Recipient, Seller, Buyer, Importer and Exporter address
details and is on landscape orientation.

- COMMERCIAL_INVOICE_P_10 (default)
This template can print the Shipper, Recipient and upto two more additional address details,
as this template can print upto four address details. This template is on portrait orientation.
Note: If customer provided more than four address roles in the request message and this
template is selected, the rendered invoice will only contain four address roles based on order
of priority: Shipper, Recipient, Seller, Importer, Exporter, Buyer - and a warning message will
be included in shipment response. Payer role is not printed in any customs invoice template.

- RET_COM_INVOICE_A4_01
This template can print the Shipper, Recipient and Importer of Record address details and is
on landscape orientation. This template is for exclusive use for those shipments where the
goods are actual ‘returns’. The Shipper is the party that earlier has received the goods, but now
wishes to return the goods to its originating party. The Recipient in this shipment scenario will
receive the ‘returned goods’. Therefore such request of shipment with an invoice rendering
may utilize the specific invoice template for ‘Returns Invoice’.

Refer to Appendix: Commercial Invoice Template Guide on what

RegistrationNumber/NumberTypeCode and OtherCharge/ChargeType values that can be
printed across different Commercial Invoice templates.

PAGE 68 OF 417
MYDHL API – DEVELOPER GUIDE

5.2.19 ShipmentRequest Input: ShipmentInfo ShipmentReceiptTemplate

The ShipmentReceiptTemplate node conveys the Shipment Receipt template used in the
operation. It is an optional field. This element is currently only published with Russia’s Shipment
Receipt’s template which is mainly used for Russia only when the RequestShipmentReceipt = Y.
The default and valid template for this field is ‘SHIP_RECPT_A4_RU_002’.

5.2.20 ShipmentRequest Input: ShipmentInfo DocumentImages

The DocumentImages node is to support multiple base64 encoded string with the image of export
documentation for Paperless Trade images. When an invalid base64 encoded string is provided, an
error message will be returned.

PAGE 69 OF 417
MYDHL API – DEVELOPER GUIDE

5.2.21 ShipmentRequest Input: ShipmentInfo LabelOptions

The LabelOptions section give customer options to generate the Transport documents in several
configurable options. The options are as follow;

• CustomerLogo: The customer company logo. This will enable the customer to
generate the Transport label using their own company logo. The children elements
are;
- LogoImage: The customer logo image. Supported image file format are RGB
and B&W
- LogoImageFormat : Format of the logo image
• CustomerBarcode: Customer can print their barcode content as well as the text
below barcode. Can only be used if the following label template is used:
‘ECOM26_84CI_002’
The children element are:
- BarcodeType: Type of barcode (39,93,128)
- BarcodeContent: The content in the barcode
- TextBelowBarcode: Thext below barcode
• PrinterDPI: The value will be passed as input parameter of resolution on the barcode
quality on the shipping labels. The default is 200.

PAGE 70 OF 417
MYDHL API – DEVELOPER GUIDE

• RequestWaybillDocument: For all dutiable shipment (except PLT shipment), waybill

document will be rendered in the response message. If the value provided is Y,
waybill document is printed for all shipments including the non-dutiable and
dutiable shipments.
- If the shipment is dutiable, PLT Shipment (SpecialService = WY), and the
RequestWaybillDocument = N or not provided, the Waybill Document will
NOT be printed
- If the shipment is dutiable, Non-PLT Shipment (SpecialService is not equal to
WY), and the RequestWaybillDocument = N or not provided, the Waybill
Document will be printed
- If the shipment is Non-dutiable, PLT Shipment (SpecialService = WY), and the
RequestWaybillDocument = N or not provided, the Waybill Document will NOT
be printed
- If the shipement is Non-dutiable, Non-PLT Shipment (SpecialService = WY),
and the RequestWaybillDocument = N or not provided, the Waybill Document
will NOT be printed.

• HideAccountInWaybillDocument: The flag used to not print the account number on

the waybill document for within the freight and duty tax account field. The default
value is N. If the value is set to Y, account number will NOT be printed on the waybill
document for both freight and duty tax account field.

• NumberOfWaybillDocumentCopies: You can optionally request up to 2 Waybill

documents to be generated automatically

• RequestDHLCustomsInvoice: This flag is used to generate Customs Invoice using a

DHL Express invoice template. The default is N, customers using their own invoice
and MyDHL API will not generate the invoice. If the flag is set to Y, and
CustomsInvoiceTemplate is not provided, the Customs Invoice is generated using the
“COMMERCIAL_INVOICE_P_10” template.

• DHLCustomsInvoiceLanguageCode: The language code input that will be used to

generate the Customs Invoice and language used in it. The default value is ‘eng’
(English). The supported languages for this field is stated in section 5.3.

• DHLCustomsInvoiceLanguageCountryCode: The language country code used to

generate the Customs Invoice.

• DHLCustomsInvoiceType: The type of customs invoice to be generated. The possible

value is COMMERCIAL_INVOICE (default), PROFORMA_INVOICE and
RETURNS_INVOICE.

• RequestShipmentReceipt: The flag to generate Shipment Receipt document. The

default value is N, Shipment Receipt document will not be renderd in the response
message.

PAGE 71 OF 417
MYDHL API – DEVELOPER GUIDE

5.2.22 ShipmentRequest Input: LabelOptions DetachOptions

The detach options section will determine the label and/or document image output in the Create
Shipment response for Transport Label, Waybill Document, Shipment Receipt and Customs
Invoice document image depending on the options. The children element for this section are as
below;

• AllInOnePDF: Flag used to generate a single PDF consisting of Transport Label,

Waybill Document, Shipment Receipt and Commercial Invoice. The default value is N,
a single PDF or thermal output image file consists of Transport Label + Waybill
Document and single PDF or thermal output image file for Shipment Receipt and
Customs Invoice will be returned in create shipment response.

• SplitShipmentReceiptAndCustomsInvoice: Flag to generate a single PDF or thermal

output image file consisting of Transport Label + Waybill Document, a single file
consist of Commercial Invoice and a single file consist of Shipment Receipt. The
default value is N, a single PDF or thermal output image file consists of Transport Label
+ Waybill Document and single PDF or thermal output image file for Shipment Receipt
and Customs Invoice will be returned in create shipment response.

• SplitTransportLabelAndWaybillDocument: Flag to generate a single PDF or thermal

output file for the Transport Label, a single PDF or thermal output file for the Waybill
document and a single PDF file consisting of Commercial Invoice and Shipment
Receipt. The default value is N, a single PDF or thermal output image file consists of
Transport Label and single PDF or thermal output image file for Waybill Document will
be returned in create shipment response.

• SplitLabelsByPieces: This field provide the option to generate a single PDF or thermal
output image file for each pieces for the Transport Label and single PDF or thermal
output image file for Waybill Document will be returned in the create shipment
response. The default value is N, a single PDF or thermal output image file for each
pieces for Transport Label and single PDF or thermal output image file for Waybill
Document will be returned in create shipment response

• ShipmentReceiptWithLabels: This field provide the option to generate a single PDF

consisting of Transport Label, Waybill Document and Shipment Receipt. The default
value is N, a single PDF or thermal output image file consists of Transport Label +
Waybill Document and single PDF or thermal output image file for Shipment Receipt
will be returned in create shipment response.

5.2.23 ShipmentRequest Input: LabelOptions RequestBarcodeInfo

PAGE 72 OF 417
MYDHL API – DEVELOPER GUIDE

The RequestBarcodeInfo element is an optional value to include response fields such as waybill
number, license plate(s) for each piece(s), origin and destination service area code, DHL routing
and Client ID barcode in base64 image format.
N (No) – response will not include additional barcode information - default behavior
Y (Yes) – response will include aforementioned additional barcode fields

5.2.24 ShipmentRequest Input: LabelOptions RequestLabelsToFitA4

The RequestLabelsToFitA4 element is an optional value to print the Transport Label and Waybill
document into A4 margin PDF. Note: Applicable to ECOM26_A6_002, ECOM26_84CI_001,
ECOM26_84CI_002, ARCH_6X4, ARCH_8X4 templates. This option is applicable only for PDF
LabelType selection.

N (No) – Transport Label and Waybill document will use default margin settings - default
behavior

Y (Yes) – Transport Label and Waybill document will print into A4 margin PDF

5.2.25 ShipmentRequest Input: LabelOptions RequestDHLLogoOnLabel

The RequestDHLLogoOnLabel element is an optional value to include DHL Logo on Transport Label
and Waybill document. Default value is Y, DHL Logo will be printed in the Label and Waybill
document.

N (No) – Transport Label and Waybill document will not print DHL Logo

Y (Yes) – Transport Label and Waybill document will print DHL Logo

5.2.26 ShipmentRequest Input: LabelOptions RequestTransportLabel

The RequestTransportLabel element is an optional value to request for Transport Label. This
element can be set as N only when requesting for a QRCode in the Shipment response
(RequestQRCode = Y ).

N (No) – Transport Label is not returned in response

Y (Yes) – Transport Label is returned in response

5.2.27 ShipmentRequest Input: LabelOptions RequestQRCode

PAGE 73 OF 417
MYDHL API – DEVELOPER GUIDE

The RequestQRCode element is an optional value to request for QR Code image in replacement of a
printable Transport Label. Default value is N, QRCode is not returned in Shipment response
message.

N (No) – QRCode is not returned in response

Y (Yes) – QRCode is returned in response

Label-Free shipment processing – requires approval from your local DHL Express IT
representative and DHL Express Operations.

A. Steps to prepare a Label-Free shipment to receive QR Code image in Response:

1. Customer sends the CreateShipment request with mandatory fields
a. The <RequestQRCode> element must contain value ‘Y’
b. <SpecialServices/Service[n]/ServiceType> element must contain value of ‘PZ’
c. <SpecialServices/Service[n]/ServiceType> element must contain any one advance
shipment special service type PT / PU / PV / PW. Providing more than one advance
shipment special service code will result to error in response.
d. <SpecialServices/Service[n]/ServiceType> element must contain the Paperless
Trade service value of ‘WY’ (note: Paperless Trade service may not be available
everywhere).

2. There will be no Transport Label image and Waybill doc image returned in response by
default. <RequestTransportLabel> element value must be ‘Y’ if requiring a Transport
Label image returned in response, together with the QR code image.
<RequestWaybillDoc> element value must be ‘Y’ if requiring a Waybill doc image
returned in response.

3. <QRCodeImageFormat> element must contain value ‘PNG’.

4. <QRCodeTemplate> element must contain value ‘QR_1_00_LL_PNG_001’.

5. Customer receives CreateShipment response message containing QR Code image in

ShipmentResponse/PackagesResult/PackageResult/QRCode/Image element. Customer
may use the QR Code to be scanned upon courier pickup or dropoff at Service Point.

PAGE 74 OF 417
MYDHL API – DEVELOPER GUIDE

5.2.28 ShipmentRequest Input: ShipmentInfo ShipmentReferences

The ShipmentReferences is an optional value that supported for maximum 999 occurrences.
The first reference will be printed on the transport label. If this field is not provided in the
request message, the 1st entry of PackageReferences will be used and printed on the transport
label. If the shipment reference is provided more than 1 in the request message, only the first
ShipmentReference will be printed in the transport label. There are 2 children element under
this field, ShipmentReferences and ShipmentReferenceType.

5.2.29 ShipmentRequest Input: ShipmentInfo ParentShipmentIdentificationNumber

The ParentShipmentIdentificationNumber is the Parent (Mother) Shipment ID and the

ParentPieceIdentificationNumber is the Parent (Mother) Piece ID number. This field will be used
for linkage purposes when the customer is using the conventional BreakBulk Express (BBX)
service.

BBX shipment processing – requires approval from your local DHL Express IT representative
and DHL Express Operations.
Steps to prepare a conventional BBX shipment:
1) Customer sends the create shipment request message for Mother Shipment with relevant
shipment information and the below information:
a. The <RequestedPackages> element should declare the relevant package’s piece
details.
b. <SpecialServices/Service[n]/ServiceType> element must contain value of ‘YW’
c. <ShipmentInfo/ServiceType> element must contain value of ‘P’ or ‘H’
2) Customer receives create shipment response message for Mother Shipment with the
Pieces IDs (<TrackingNumber> in MyDHL API create shipment response). The successful
response is used to create the Mother shipment label.
3) Customer sends the create shipment request message for Baby Shipment with relevant
shipment information and the below information:
a. At the baby shipment level,
• <ParentShipmentIdentificationNumber> element must contain the
Mother Shipment ID
• <ShipmentInfo/ServiceType> element must contain value of ‘B’
b. For each baby piece id

PAGE 75 OF 417
MYDHL API – DEVELOPER GUIDE

• <ParentPieceIdentificationNumber> element must contain the corresponding

Mother Shipment’s piece ID
4) Customer receives shipment validation response message for Baby Shipment. The
successful response can be used to create the Baby shipment label.

Steps to prepare BBX shipment for Unknown Pallets scenario:

1) Customer to invoke MyDHL API RequestIdentifier service (refer section #13) to retrieve the
Parent Shipment ID and Parent Pallet ID.
2) Customer sends the Create Shipment request message for Baby Shipment with relevant
shipment information and the below information:
a. At the baby shipment level,
• <ParentShipmentIdentificationNumber> element must contain the
Parent Shipment ID from Step 1.
• <ShipmentInfo/ServiceType> element must contain value of ‘B’
b. For each baby piece ID,
• <ParentPieceIdentificationNumber> element must contain the corresponding
Parent Pallet ID from Step 1.
3) Customer receives Create Shipment response message for Baby Shipment. The successful
Create Shipment response can be used to create the Baby shipment label.
4) Customer to decide if required additional pallet (Parent Pallet ID) or ready to complete the
BBX process by creating the Parent Shipment.
5) If customer requires additional pallet, customer to invoke MyDHL API RequestIdentifier
service to retrieve the Parent Pallet ID. Customer to request only the PID in this step.
6) Repeat steps 2, 3, and 4 to create Baby Shipment for additional pallet.
7) Customer to invoke MyDHL API CreateShipment service to create the Parent Shipment. In this
step, customer to use the “UseOwnShipmentIdentificationNumber” and
“UseOwnPieceIdentifierNumber” elements and provide the Parent Shipment ID and Piece ID
retrieved in Step 1 and Step 5 (if applicable).
a. <ShipmentIdentificationNumber> element must contain the Parent Shipment ID from
Step 1.
b. <PieceIdentifierNumber> element must contain the Parent Piece ID from Step 1 and
Step 5 (if applicable)
c. <UseOwnShipmentIdentificationNumber> element contain value of ‘Y’
d. SpecialServices/Service/ServiceType element must contain value of ‘YW’
e. ShipmentInfo/ServiceType element must contain value of ‘P’ or ‘H’
f. Parent Shipment’s related information must contain correct total weight, customs
value and piece details of all baby shipments created in Step 2.
8) Customer receives CreateShipment response message for Parent Shipment. The
successful response can be used to create the Parent’s shipment label.

Steps to prepare Loose BBX Customer Controlled shipment:

1) Customer to invoke MyDHL API RequestIdentifier service (refer Section 13. RequestIdentifier)
to retrieve the Parent Shipment ID.

2) Customer sends the Create Shipment request message for Baby Shipment with relevant
shipment information below:

PAGE 76 OF 417
MYDHL API – DEVELOPER GUIDE

a. <ParentShipmentIdentificationNumber> element must contain the Parent

Shipment ID from Step 1.
b. ShipmentInfo/ServiceType element must contain value of ‘B’
c. SpecialServices/Service/ServiceType element must contain value of ‘YZ’
d. Baby Shipment’s Shipper, Recipient and its children fields to contain contact
and address details
i. ShipmentRequest/RequestedShipment/Ship/Shipper
ii. ShipmentRequest/RequestedShipment/Ship/Recipient
e. Importer of Records (IOR) details such as Importer’s contact and address
details
i. ShipmentRequest/RequestedShipment/Ship/Importer
f. ShipmentInfo/ParentShipmentServiceType element must contain Parent
Shipment’s Global Product Code
g. ShipmentInfo/ParentShipmentPackagesCount element to contain Parent
Shipment total number of Packages if available.
h. LabelTemplate must contain value of ‘ECOM26_84_LBBX_001’

3) Customer receives Create Shipment response message for Baby Shipment. The successful
Create Shipment response can be used to create the Baby shipment Transport label and Waybill
document.

4) Repeat Step 2 and 3 for additional Baby Shipment

5) Complete Loose BBX process by creating the Parent Shipment. Provide relevant Parent
shipment details below:
a. Parent shipment must include correct Weight, Customs Value, and Piece
details of all Baby Shipments’ Piece Identification Number (PID) created in
Step 2 and 4.
b. <ShipmentIdentificationNumber> element must contain the Parent’s
Shipment ID from Step 1.
c. <UseOwnShipmentIdentificationNumber> element contain value of ‘Y’
d. SpecialServices/Service/ServiceType element must contain value of ‘YM’
e. ShipmentInfo/ServiceType element must contain value of ‘P’, the Parent
Shipment’s Global Product Code
f. RequestedPackages/UseOwnPieceIdentificationNumber must contain value
of ‘Y’
g. RequestedPackages/PieceIdentificationNumber must contain the Baby
Shipment’s Piece Identification Number, repeated for all Baby Shipments’
pieces.
Additional notes for Loose BBX Parent shipment:
• It is customer’s responsibility to declare the shipments with accurate shipment
weight from each baby shipment pieces in
RequestedShipment/Packages/RequestedPackages/Weight and total customs value
in RequestedShipment/InternationalDetail/ /CustomsValue in the Create Shipment
request message. Note that there is no auto-calculate functionality available
currently for all baby shipments linked to their respective mother shipment.
• Customer may prepare PLT shipment, upload own Customs Invoice or request for DHL
Customs Invoice by declaring all the export declaration line items in the request
message.

PAGE 77 OF 417
MYDHL API – DEVELOPER GUIDE

• To request for DHL Customs Invoice, customer must use customs invoice template
‘COMMERCIAL_INVOICE_04’.

6) Customer receives Create Shipment response message for Parent Shipment. The
successful response can be used to create the Parent Shipment’s Customs Invoice
document if RequestDHLCustomsInvoice option is selected.
Note: Response message for Parent Shipment will always return Transport Label. It
is not necessary for customer to print the Transport Label as Parent Shipment is a
virtual shipment.

PAGE 78 OF 417
MYDHL API – DEVELOPER GUIDE

5.2.30 ShipmentRequest Input: ShipmentInfo RequestTransliterateResponse

The RequestTransliterateResponse is the flag to request transliteration text in response. The

default value is N, the create shipment response will be returned as it is without any
transliteration texts. If the value is set to Y, the response message will returned transliteration
texts for all fields in Create Shipment request message of international shipments except
*_BASE64 AND *_SYMBOLOGY fields. The language to be translated will be based on the
shipper country code. The only supported language is Russian currently.

5.2.31 ShipmentRequest Input: Shipmentnfo RequestAdditionalInformation

The RequestAdditionalInformation node is an optional field to have additional information in the

shipment response. The default value is N, where the response message is return as it is. If the
value is set as Y, the response message will include the AdditionalInformation field in the
response message.

5.2.32 ShipmentRequest Input: ShipmentInfo RequestEstimatedDeliveryDate

The RequestEstimatedDeliveryDate node is an optional field to have Estimated Delivery Date (EDD)
details in the shipment response. The default value is N, where no additional fields related to
Estimated Delivery Date is included in response.

5.2.33 ShipmentRequest Input: ShipmentInfo EstimatedDeliveryType

This node comes in pair with RequestEstimatedDeliveryDate field. There are two options of EDD
type – QDDF or QDDC.

QDDC - constitutes DHL's service commitment as quoted at booking/shipment creation. QDDC

builds in clearance time, and potentially other special operational non-transport component(s),
when relevant.

QDDF - is the fastest ("docs") transit time as quoted to the customer at booking or shipment
creation. When clearance or any other non-transport operational component is expected to impact
transit time, QDDF does not constitute DHL's service commitment.

5.2.34 ShipmentRequest Input: ShipmentInfo RequestPickupDetails

The RequestPickupDetails node is an optional field to have pickup related details such as
ReadyByTime, CallInTime, Pickup Location Additional Day to be returned in shipment response

PAGE 79 OF 417
MYDHL API – DEVELOPER GUIDE

5.2.35 ShipmentRequest Input: ShipmentInfo ParentShipmentServiceType

The ParentShipmentServiceType node is an optional field to indicate the global product code of a
Loose BBX parent shipment.

5.2.36 ShipmentRequest Input: ShipmentInfo ParentShipmentPackagesCount

The ParentShipmentPackagesCount node is an optional field to indicate the total pieces count of a
Loose BBX parent shipment.

5.2.37 ShipmentRequest Input: ShipTimeStamp

The ShipmentTimeStamp node is the date/time stamp (including GMT offset) when the shipment
will be ready for shipping and tendered to the carrier, either as part of a scheduled pickup, regular
pickup, station dropoff, etc. Please note that the timestamp for this event does not represent the
time of the execution of the service, and should not be considered a system event.

5.2.38 ShipmentRequest Input: PickupLocationCloseTime

The PickupLocationCloseTime node identifies the pickup location close time (i.e. what time do the
premises where the collection is supposed to happen close). The value must be in local time. The
value component must be HH:MM (using a 24-hours clock format, e.g. 14:00). This node is
optional and must be used with DropOffType = ‘REQUEST_COURIER’.

5.2.39 ShipmentRequest Input: SpecialPickupInstruction

The SpecialPickupInstruction node details any special instructions you wish to send to the courier
for the order pick-up. This node is optional and must be used with DropOffType =
‘REQUEST_COURIER’.

5.2.41 ShipmentRequest Input: PickupLocation

The PickupLocation node provides information on where the package should be picked up by DHL
courier. This node is optional and must be used with DropOffType = ‘REQUEST_COURIER’.

5.2.42 ShipmentRequest Input: PaymentInfo

PAGE 80 OF 417
MYDHL API – DEVELOPER GUIDE

The PaymentInfo node details the potential terms of trade for this specific shipment, and the
schema itself defines the possible enumerated values for this field.

5.2.43 ShipmentRequest Input: International Detail

The InternationalDetail section conveys data elements for international shipping.

The Description field is used as a description of goods for the label and manifest.

The CustomsValue field communicates the customs value of the shipment, used for manifesting.

The USFilingTypeValue is used for the US AES4, FTR and ITN numbers to be printed on the
Transport Label

5.2.44 ShipmentRequest Input: Content

The Content node details whether a shipment is non-dutiable (value DOCUMENTS) or dutiable
(NON_DOCUMENTS). Depending on the nature of the contents of the shipment, is customs duties
are applicable, different products may be offered by the DHL web services.

PAGE 81 OF 417
MYDHL API – DEVELOPER GUIDE

5.2.45 ShipmentRequest Input: ExportDeclaration

The ExportDeclaration section is for DHL Customer to declare dutiable shipment.

If requesting to render a Commercial Invoice PDF, optional elements may be provided in request
such as InvoiceDeclarationTexts, InvoiceSignatureDetails, OtherCharges, Remarks,
InvoiceInstructions and CustomerDataTextEntries.

PAGE 82 OF 417
MYDHL API – DEVELOPER GUIDE

5.2.45.1 ShipmentRequest Input: CustomsDocuments (0:1)

CustomsDocuments will contain child node CustomsDocument and used to indicate the document
type code and document ID that corresponds to one ore more associated document(s) for customs
declaration purposes.

Listed below are allowed Customs document type codes:

Document Type Description

972 T2LF Dispense Paiement Droits
AHC Analysis and Health Certificate
ATA ATA Carnet
ATR Preference Certificate ATR
CHD CHED-D (Common Health Entry Document for Feed and Food of Non-Animal Origin
CHP CHED-P (Common Health Entry Document for Products)
CIT CITES Certificate
COO Generic Certificate of Origin
DEX Duty Exemption Certificate
EU1 Preference Certificate EUR1
EU2 Preferential Declaration of Origin on the Invoice - EUR2
EUS End Use Authorization
FMA Certificate of Origin (Form A)
PHY Phytosanitary Certificate
VET Veterinary Entry Document
VEX VAT Exemption Certificate
CRL Control Document
CSD Consolidated Customs Entry
PPY Proof Of Payment
CI2 Export-only Invoice
CIV Customs Invoice Value
DOV Invoice
INV Commercial Invoice
PFI Pro-Forma
ALC Agricultural License
HLC Health Products Regulatory Authority (HPRA) Licensing Requirements
JLC Justice License
LIC Specific Export Licenses
LNP License or Permit
PLI Permits & Licenses

PAGE 83 OF 417
MYDHL API – DEVELOPER GUIDE

DLI Driver's License

NID National Identity Card
PAS Passport
CHA Power of Attorney
CPA Consignee Power of Attorney
POA Power of Attorney (Customer-based)
BEX Branch Letter of Exemption
DGD Dangerous Goods Declaration
IPA Intellectual Property Authorization
T2M T2M Transport Accompanying Document
TAD TAD Transport Accompanying Document T1
TCS Transportation Charges Statement
ROD Receipt on Delivery
EXL DCE Export of Customs Data
HWB House Waybill

5.2.45.2 ShipmentRequest Input: InvoiceReferences (0:1)

InvoiceReferences section contains child node InvoiceReference that can be repeated up to max
100 occurences. Data provided in this section is passed on to the manifest data.

Listed below are allowed invoice level reference type codes:

Reference type Description

ACL Parent Shipment ID for BBX
CID Customer Identifier
CN Contract Number
CU Consignor reference number
ITN US Export declaration reference ID
MRN Movement Reference number
UCN Unique reference of a consignment (UCRN)
OID Order Number
PON Purchase Order Number

5.2.45.3 ShipmentRequest Input: Remarks (0:1)

Remarks will contain repeating child node Remark of up to max 3 occurences. This element will be
printed to the commercial invoice PDF.

PAGE 84 OF 417
MYDHL API – DEVELOPER GUIDE

5.2.45.4 ShipmentRequest Input: OtherCharges (0:1)

OtherCharges will contain repeating child node OtherCharge. This section can be used to input
any other monetary charges associated with the shipment such as Freight, Insurance, Fuel
Surchage etc.

ChargeValue is mandatory element and are included in calculation of Shipment Total Declared
Amount.

ChargeType is mandatory element together with ChargeValue and provides more detail as to
categorize the charge being provided. Refer to below tables for list of charge type codes and
descriptions.

For printing charges in commercial invoice, refer to Appendix: Commercial Invoice Template Guide
on what ChargeType codes can be printed across different Commercial Invoice templates.

Listed below are allowed charge type codes:

ChargeType Description of charge

ADMIN Administration Charge/Fee/Cost
DELIV Delivery Charge/Fee/Cost
DOCUM Documentation Charge/Fee/Cost
EXPED Expedite Charge/Fee/Cost
EXCHA Export Charge/Fee/Cost
FRCST Freight/Shipping Charge/Fee/Cost
SSRGE Fuel Surcharge
LOGST Logistic Charge/Fee/Cost
SOTHR Other Charge/Fee/Cost
SPKGN Packaging/Packing Charge/Fee/Cost
PICUP Pickup Charge/Fee/Cost
HRCRG Handling Charge/Fee/Cost
VATCR VAT Charge/Fee/Cost

PAGE 85 OF 417
MYDHL API – DEVELOPER GUIDE

INSCH Insurance Cost (Fee)

REVCH Reverse Charge

5.2.45.5 ShipmentRequest Input: InvoiceSignatureDetails (0:1)

InvoiceSignatureDetails is used if requested commercial invoice PDF will contain client-specified

signature information such as SignatureName, SignatureTitle and SignatureImage.

5.2.45.6 ShipmentRequest Input: InvoiceDeclarationTexts (0:1)

InvoiceDeclarationTexts contains child node InvoiceDeclarationText. This element can be used to

input the shipper’s declaration statement and will be printed in commercial invoice PDF.

5.2.45.7 ShipmentRequest Input: CustomerDataTextEntries (0:1)

CustomerDataTextEntries contain child node CustomsDataTextEntry that repeats up to max 6

occurrences.

This section is used exclusively for Loose BBX template COMMERCIAL_INVOICE_04.

5.2.45.8 ShipmentRequest Input: ExportLineItems (1:1)

ExportLineItems contains a child node ExportLineItem which can repeat up to 999 occurences.
This section is used to provide details of invididual items to be listed in the commercial invoice.

ExportLineItem requires several mandatory fields – ItemNumber, Quantity,

QuantityUnitOfMeasurement, ItemDescription, UnitPrice, NetWeight, GrossWeight and
ManufacturingCountryCode.

PAGE 86 OF 417
MYDHL API – DEVELOPER GUIDE

If requesting to render a Commercial Invoice PDF, optional elements may be provided in request
such as CommodityCode, LicenseNumber and AdditionalInformation.

PAGE 87 OF 417
MYDHL API – DEVELOPER GUIDE

5.2.45.9 ShipmentRequest Input: ExportLineItem/AdditionalInformation (0:1)

AdditionalInformation contains child node AdditionalInformationText that can repeat up to 8 times.

This field contain the item’s additional packaging information that will be printed to the invoice PDF.
This section is used for Loose BBX template COMMERCIAL_INVOICE_04,
COMMERCIAL_INVOICE_P_10 and COMMERCIAL_INVOICE_L_10.

5.2.45.10 ShipmentRequest Input: ExportLineItem/ItemReferences (0:1)

ItemReferences section contains child node ItemReference that can be repeated up to max 100
occurences. Data provided in this section is passed on to the manifest data. First five
ItemReference in request message can be printed in templates COMMERCIAL_INVOICE_P_10 and
COMMERCIAL_INVOICE_L_10.

Listed below are allowed item level reference type codes:

Reference type Description

AAJ Delivery Order number
ABW Stock Keeping Unit
ALX Model
AFE Export Control Commodity number (ECCN)
BRD Brand
DGC Dangerous Goods Content Identifier
ECN Export Clearance Number
INB In Bond shipment
MAK Make
PAN Part No
PON Purchase Order Number
SE Serial number
SON Sales order No
OID Order ID

PAGE 88 OF 417
MYDHL API – DEVELOPER GUIDE

5.2.45.11 ShipmentRequest Input: ExportLineItem/CustomsPaperworks (0:1)

CustomsPaperworks will contain child node CustomsPaperwork and used to indicate the document
type code and document ID that corresponds to one ore more associated document(s) for customs
declaration purposes.

Listed below are allowed Customs document type codes:

Paperwork Type Description

972 T2LF Dispense Paiement Droits
AHC Analysis and Health Certificate
ATA ATA Carnet
ATR Preference Certificate ATR
CHD CHED-D (Common Health Entry Document for Feed and Food of Non-Animal Origin
CHP CHED-P (Common Health Entry Document for Products)
CIT CITES Certificate
COO Generic Certificate of Origin
DEX Duty Exemption Certificate
EU1 Preference Certificate EUR1
EU2 Preferential Declaration of Origin on the Invoice - EUR2
EUS End Use Authorization
FMA Certificate of Origin (Form A)
PHY Phytosanitary Certificate
VET Veterinary Entry Document
VEX VAT Exemption Certificate
CRL Control Document
CSD Consolidated Customs Entry
PPY Proof Of Payment
CI2 Export-only Invoice
CIV Customs Invoice Value
DOV Invoice
INV Commercial Invoice
PFI Pro-Forma
ALC Agricultural License
HLC Health Products Regulatory Authority (HPRA) Licensing Requirements
JLC Justice License
LIC Specific Export Licenses
LNP License or Permit
PLI Permits & Licenses

PAGE 89 OF 417
MYDHL API – DEVELOPER GUIDE

DLI Driver's License

NID National Identity Card
PAS Passport
CHA Power of Attorney
CPA Consignee Power of Attorney
POA Power of Attorney (Customer-based)
BEX Branch Letter of Exemption
DGD Dangerous Goods Declaration
IPA Intellectual Property Authorization
T2M T2M Transport Accompanying Document
TAD TAD Transport Accompanying Document T1
TCS Transportation Charges Statement
ROD Receipt on Delivery
EXL DCE Export of Customs Data
HWB House Waybill

5.2.46 ShipmentRequest Input: OnDemandDeliveryOptions (0:1)

The OnDemandDeliveryOptions section conveys data elements for On Demand Delivery (ODD)
service.

The Delivery option is to define which on demand delivery option you wish to choose optionally
when your shipment is to be delivered. The options are:

- TV (Deliver to a DHL Express Servicepoint)

- SW (Leave with neighbour)

- SX (Signature release)

The Location is mandatory if the above delivery option is SX and should advise DHL where exactly
to leave the shipment (ie.front door etc)

The instructions is optional – additional information that is useful for the DHL Express courier

The GateCode is optional – is the entry code to gain access to an apartment complex or gate

The LWNTypeCode is mandatory if the above delivery option is SW. The possible values are

- N – Leave with neighbour

- C – Leave with concierge

The NeighbourName Is mandatory if the delivery option is SW and the LWNTypeCode is N

(Neighbour) – this is where the name of the neighbour is required

The NeighbourHouseNumber Is mandatory if the delivery option is SW and the LWNTypeCode is

N (Neighbour) – this is the house number of the neighbour

The AuthorizerName is mandatory if delivery option is SX – this is the person that this authorised
to sign and receive the DHL Express shipment.

PAGE 90 OF 417
MYDHL API – DEVELOPER GUIDE

The SelectedServicePointID is mandatory if delivery option is TV – this is the unique DHL Express
Service point location ID of where the parcel should be delieverd (please contact your local DHL
Express Account Manager to obtain the list of the servicepoint IDs)

5.2.47 ShipmentRequest Input: OnDemandDeliveryURLRequest

The OnDemandDeliveryURLRequest is an optional field to request the On Demand Delivery
(ODD) link. It will provide an URL link for the specified Waybill Number, Shipper Account
Number. The default value is N, no ODD link URL is provided in the response message.

PAGE 91 OF 417
MYDHL API – DEVELOPER GUIDE

5.2.48 ShipmentRequest Input: Ship

The Ship section outlines the shipper, receiver and optional buyer, importer, exporter, seller, payer
and pickup address for the specific shipment request. In the context to rate requests, the street
address elements are not critical, since capability and rate are determined based on city, postal
code, and country code.

Please note that the Shipper, Pickup, BookingRequestor, Buyer, Recipient, Exporter, Importer,
Seller and Payer structures are identical.

If included in the message, this optional Pickup structure will be used as precedence over the
Shipper address when the Pickup service is invoked. The Pickup address will not be used in
manifesting.

PAGE 92 OF 417
MYDHL API – DEVELOPER GUIDE

PAGE 93 OF 417
MYDHL API – DEVELOPER GUIDE

5.2.49 RegistrationNumbers

Is used to provide Registration Number(s) of the Shipper and/ or Recipient issued by any country
regulatory office. This is applicable for Shipper, Buyer, Recipient, Exporter, Importer and Seller
and Payer segments.

Refer to Appendix: Registration Number Type Codes attached in this document for full list of
codes, their description and applicable issuing country and shipping roles.

For printing registration numbers in commercial invoice, refer to Appendix: Commercial Invoice
Template Guide on what NumberTypeCode values can be printed across different Commercial
Invoice templates.

PAGE 94 OF 417
MYDHL API – DEVELOPER GUIDE

5.2.50 ShipmentRequest Input: Packages

The Packages section details the contents of individual pieces (or discrete shipping containers)
within the shipment. The minimum number of packages or pieces in a shipment is one and the
upper limit is 999.

The InsuredValue field is an optional field in the Packages section which will be deprecated from
the interface, as the SpecialServices section should be used to convey Insured Value.

The Weight and Dimensions fields represent the weight and dims of the individual pieces.

The PackageReference field is used as the Piece Reference and the first instance is also used as
the Shipment Reference. Currently only the Shipment Reference appears on the label.

The ParentPieceIdentificationNumber is the Parent (Mother) Piece ID number. This field will be
used to indicate the Mother Shipment's Piece ID for linkage purposes when the customer is using
the conventional BreakBulk Express (BBX) service.

The BespokeLabelData is to print additional customer information in the Transport Label. This
segment is required when the LabelTemplate value is ECOM26_84CI_003.

PAGE 95 OF 417
MYDHL API – DEVELOPER GUIDE

5.2.51 ShipmentRequest Input: DangerousGoods

The DangerousGoods section indicates if there is dangerous good content within the shipment.
The
ContentID node contains the Content ID for the Dangerous Good classification (please contact
your
DHL Express representative for the list of the codes). If the shipment is Dry Ice UN1845 (Content
ID – 901) then the additional node needs to be populated - “DryIceTotalNetWeight.”

If is the shipment is “Excepted Quantities” then the additional node needs to be populated –
“UNCode”

5.2.52 ShipmentRequest Input: GetRateEstimates

The GetRateEstimates node is a flag that will provide customers the option to receive total
shipping charges and special services charges in the response. The default value for this flag is
N. If the value is set to Y, the shipping charge will be returned in the response message if
applicable.Please note that this may increase the response times of the service.

PAGE 96 OF 417
MYDHL API – DEVELOPER GUIDE

5.2.53 ShipmentRequest Input: ShipmentNotifications

This ShipmentNotifications section is to support sending email notification once the shipment is
created. The email will contain the basic information on the shipper, recipient, waybill number,
and shipment information. The minimum number of shipment email notification to be sent is
one and the upper limit is 5.

• NotificationMethod: Mandatory field for method of notification to be sent. The valid

value is ‘EMAIL’
• EmailAddress: Email address to receive the notification mail.
• BespokeMessage: Any additional message from the shipper to be added to the body
of the mail
• LanguageCode: Email content language. Please refer to the input field table for list of
supported language in this field.
• LanguageCountryCode: Email notification language country code.

PAGE 97 OF 417
MYDHL API – DEVELOPER GUIDE

5.3 SHIPMENT REQUEST – INPUT FIELD LIST

Values or
Shipment Request fields M/O Comments
Constraints
ShipmentRequest
ShipmentRequest/ClientDetail
sso O This field is for internal use only
plant O This field is for internal use only
ShipmentRequest/Request
ShipmentRequest/Request/ServiceHeader
MessageTime O TIMESTAMP Format:

YYYY-MM-DD(T)hh:mm:ss-

GMTTIMEOFFSET e.g.

2010-11-24T00:17:20+01:00
MessageReference O AN 36 Message reference, between 28-36
characters in length.
WebstorePlatform O AN 20 Reserved for Third Party Vendors
identification
Reserved for Third Party Vendors
WebstorePlatformVersion O AN 15
identification
ShippingSystemPlatform O AN 30 Reserved for Third Party Vendors
identification
O AN 15 Reserved for Third Party Vendors
ShippingSystemPlatformVersion
identification
PlugIn O AN 20 Reserved for Third Party Vendors
identification
PlugInVersion O AN 15 Reserved for Third Party Vendors
identification
ShipmentRequest/RequestedShipment

ShipTimestamp M YYYY- This timestamp identifies the pickup

MMDDT24HH:M date and time of the rated shipment.
M:SS GMT+k
It needs to be provided in the following
format with GMT offset

YYYY-MM-DDTHH:MM:SSGMT+k

2010-02-26T17:00:00GMT+01:00

PAGE 98 OF 417
MYDHL API – DEVELOPER GUIDE

If the date is on a public holiday,

Sunday or any other day where there
is no pickup, the shipment request will
return this in the error code as it is a
non valid request.
PickupLocationCloseTime O HH:mm This node identifies the closing time
of your pickup location in local time.

It needs to be provided in the

following 24hours time format:

HH:mm

Sample: 17:00
SpecialPickupInstruction O AN 75 This node details special pickup
instructions you may wish to send to
the DHL Courier
PickupLocation O AN 80 This node provides information on
where the package should be picked
up by DHL courier.
PaymentInfo M AN 3 Possible values:
- CFR – Cost And Freight
- CIF – Cost, Insurance and
Freight
- CIP – Carriage And
Insurance Paid To
- CPT – Carriage Paid To
- DAF – Delivered At Frontier
- DDP – Delivery Duty Paid
- DDU – Delivery Duty
Unpaid
- DAP – Delivered At Place
- DAT – Delivered At
Terminal
- DEQ – Delivered Ex Quay
(Duty Paid)
- DES – Delivered Ex Ship
- EXW – Ex Works
- FAS – Free Alongside Ship
- FCA – Free Carrier
- FOB – Free On Board
- DPU – Delivered at Place
Unloaded
OnDemandDeliveryURLRequest O A1 Request for ODD link URL for the
specified

PAGE 99 OF 417
MYDHL API – DEVELOPER GUIDE

Waybill Number, Shipper Account

Number

Possible values;

- Y
- N (default)
GetRateEstimates O A1 This field is used to return the
TotalNet in the response message.
The default value for this field is N.
Please note that this may increase
response times.

Possible values;

- Y
- N (default)

ShipmentRequest/RequestedShipment/ShipmentInfo

DropOffType M Enumerated Possible values:

-REGULAR_PICKUP, the pickup

location is already served by a regular
courier and an additional pickup does
not need to be considered for this
service

- REQUEST_COURIER, The rating

response returns products for which
the pickup capability is given, based
on ShipmentTimeStamp.
ServiceType M AN 6 The shipping product requested for
this shipment, corresponding to the
DHL Global Product codes.
LocalServiceType O AN 3 DHL “local / country specific” Product
Code used to ship the items.
Important when shipping domestic
products – please consult your DHL
Express IT consultant if needed.
Account M/O AN 12 The customer account to be used as
payer in the request. If the <Account>
tag is used then there is no need to
populate the Billing section further
down below in this table as the
<Account> tag will override any other
accounts entered.

PAGE 100 OF 417

MYDHL API – DEVELOPER GUIDE

However if you do wish to charge

your shipment to a third party or
receiver then please leave the
ACCOUNT section out and populate
the Billing section below
Currency M AN 3 The currency of the monetary values
presented in the request.
UnitOfMeasurement M AN 2 The unit of measurement for the
dimensions of the package.

Possible values:

- SI, international metric system (KG,

CM)
- SU, the US system of measurement
(LB, IN)
ShipmentIdentificationNumber O AN 35 The shipment identification number
does not need to be transmitted in the
request as the operation will assign a
new number and return it in the
response. Only used when
UseOwnShipmentdentificationNumb
er set to Y and this feature enabled
within customer profile.
UseOwnShipmentIdentificationN O A1 Y or 1 = allows you to define your own
umber AWB in the tag above

N or 0 = Auto-allocates the AWB from

DHL Express

You can request your own AWB range

from your DHL Express IT consultant
and store these locally in your
integration however this is not needed
as if you leave this tag then DHL will
automatically assign the AWB
centrally.

In addition this special function needs

to be enabled for your username by
your DHL Express IT Consultant.
LabelType O AN 3 Possible values:
- PDF
- ZPL
- EPL
- LP2
LabelTemplate O AN 25 Any valid DHL Express label template
(please contact your DHL Express IT

PAGE 101 OF 417

MYDHL API – DEVELOPER GUIDE

representative for a list of labels) – If

this node is left blank then the default
DHL ecommerce label template will
be used.

Possible values;
- ECOM26_84_A4_001
- ECOM26_84_001
- ECOM_TC_A4
- ECOM26_A6_002
- ECOM26_84CI_001
- ECOM_A4_RU_002
- ECOM26_84CI_002
- ECOM26_84CI_003
- ECOM26_84_LBBX_001
ArchiveLabelTemplate O AN 25 Any valid DHL Express archive label
template
(please contact your DHL Express IT
representative for a list of labels) – If
this node is left blank then the default
DHL ecommerce label template will
be used.
Possible values;
- ARCH_8X4_A4_002
- ARCH_8X4
- ARCH_6X4
- ARCH_A4_RU_002
QRCodeTemplate O AN 25 QR Code template name

Possible value:
- QR_1_00_LL_PNG_001
(default)
QRCodeImageFormat O Enumerated QR Code image format

Possible value:
- PNG
CustomsInvoiceTemplate O AN 25 Customs invoice template name.

Possible values:

- COMMERCIAL_INVOICE_04
This template can print the Shipper,
Recipient, Buyer and Importer
address details and is on portrait

PAGE 102 OF 417

MYDHL API – DEVELOPER GUIDE

orientation. (note: this template is

for exclusive use for preparing
Loose BBX shipment.)

- COMMERCIAL_INVOICE_L_10
This template can print the
“Shipper”, “Recipient”, “Seller”,
“Importer”, “Exporter” and “Buyer”
address details and is on landscape
orientation.

- COMMERCIAL_INVOICE_P_10
(default)
This template can print the
Shipper, Recipient and upto two
more additional address details,
as this template can print upto
four address details. This
template is on portrait
orientation. Note: If customer
provided more than four
address roles in the request
message and this template is
selected, the rendered invoice
will only contain four address
roles based on order of priority:
Shipper, Recipient, Seller,
Importer, Exporter, Buyer - and
a warning message will be
included in shipment response.
Payer role is not printed in any
customs invoice template.

- RET_COM_INVOICE_A4_01
This template can print the
Shipper, Recipient and Importer
of record address details and is
on landscape orientation. This
template is for exclusive use for
certain shipment where the
goods are actual ‘returns’. The
Shipper is the party that earlier
has received the goods, but now
wishes to return the goods to its
originating party. The Recipient
in this shipment scenario will
receive the ‘returned goods’.

PAGE 103 OF 417

MYDHL API – DEVELOPER GUIDE

Therefore such request of

shipment with an invoice
rendering may utilize the
specific invoice template for
‘Returns Invoice’.

Refer to Appendix: Commercial

Invoice Template Guide on what
RegistrationNumber/NumberType
Code and
OtherCharge/ChargeType can be
printed across different
Commercial Invoice templates.
ShipmentReceiptTemplate O AN 25 Shipment receipt template name.
Possible value:

- SHIP_RECPT_A4_RU_002

ParentShipmentIdentification O AN 25 Parent (Mother) Shipment ID number

Number used for Break Bulk Shipments (BBX)

O A1 Request transliteration text in

response. Currently only Russian is
supported.

Possible values:

RequestTransliterateResponse - Y, the response message will

return Transliterated Value for
the supported fields
- N, the response message will
return as per request message
field values (Default)
RequestAdditionalInformation O Enumerated Possible values:

- Y, the response message will

include
<AdditionalInformation>
section and its children nodes
such as BillingCode, Service
Area, Shipper and Recipient
details, etc.
- N, the response message will
return as per request message
field values (Default)
RequestEstimatedDeliveryDate O Enumerated To request for an estimated delivery
date (EDD) in the shipment response.

PAGE 104 OF 417

MYDHL API – DEVELOPER GUIDE

This field can be provided together

with <EstimatedDeliveryDateType>
element.

Possible values:

- Y, the response message will

include EDD
- N, the response message will not
contain any EDD information
EstimatedDeliveryDateType O Enumerated Possible values:

QDDC – includes in clearance time,

and potentially other special
operational non-transport
component(s), when relevant.

QDDF - is the fastest ("docs") transit

time as quoted to the customer at
booking or shipment creation.

RequestPickupDetails O Enumerated To request for pickup-related details

such as CutoffTime, CutoffTimeGMT,
PickupWindowEarliestTime, etc to be
returned in the Shipment response.

Possible values:

- Y, the response message will

include <PickupDetails> section
and its children nodes such as
CutoffTime, CutoffTimeGMT,
PickupWindowEarliestTime etc.
- N, the response message will not
contain <PickupDetails> section
(Default)
ParentShipmentServiceType O AN 3 Global product code of a LBBX parent
shipment. Must include this value
when creating LBBX baby shipment.

Applicable for
ECOM26_84_LBBX_001 template
only.

ParentShipmentPackagesCount O Integer Total count of pieces of a LBBX parent

shipment. Include this value when
creating LBBX baby shipment.

PAGE 105 OF 417

MYDHL API – DEVELOPER GUIDE

Applicable for
ECOM26_84_LBBX_001 template
only.

ShipmentRequest/RequestedShipment/ShipmentInfo/Billing
ShipperAccountNumber M/O AN 12 The DHL account number used for the
shipment. Used as the shipper
account number. Please note if you
use this billing section then the above
<Account> tag is not needed.
<ShipperAccountNumber> is
mandatory then.
ShippingPaymentType M/O AN 1 Possible values:
- S (use ShipperAccountNumber
as payer)
- R (use BillingAccountNumber as
bill-to receiver account number)
T (use BillingAccountNumber as bill-
to third party account number) Please
note if you use value R or T in this tag
then the next tag
<BillingAccountNumber> is also
mandatory
BillingAccountNumber O AN 12 The DHL account number used for the
shipment, if ShippingPaymentType is
equal to R or T.
DutyAndTaxPayerAccountNumb O AN 12 The DHL account number used for
er duties and tax payments.
NeverOverrideBillingService O A1 The NeverOverrideBillingServices is
an optional flag to indicate whether to
override the DHL Billing Service
should it be incorrectly provided.
This is automatically derived based on
the Shipper/Receiver Address,
Shipper/Payer Account number and
type of shipment.

N (No) - overwrite with derived DHL

Billing
Service via Account Validation -
Create
Shipment service - default behavior

Y (Yes) - use customers provided

billing special
service code to derive the DHL Billing
service
(not recommended)

PAGE 106 OF 417

MYDHL API – DEVELOPER GUIDE

ShipmentRequest/RequestedShipment/ShipmentInfo/Billing/ShipmentPrepaidTotalCharge
CurrencyCode M AN 3 Payment currency code
Amount M 12.2D Amount of payment
PaymentMethod M AN Payment method. Valid enumeration;

- CASH
ShipmentRequest/RequestedShipment/ShipmentInfo/DocumentImages
ShipmentRequest/RequestedShipment/ShipmentInfo/DocumentImages/DocumentImage
(1:1000)
DocumentImageType O Enumerated The type of document for the image
provided

Possible values;
- INV, Invoice
- PNV, Proforma
- COO, Certificate of Origin
- NAF, Nafta Certificate of Origin
- CIN, Commercial Invoice
- DCL, Custom Declaration
- AWB, Air Waybill and Waybill
Document
DocumentImage M The image of the document.
Base64 Binary
Maximum size: 2 MB
DocumentImageFormat O AN 5 Possible values;
- PDF
- PNG
- TIFF
- GIF
- JPEG
ShipmentRequest/RequestedShipment/ShipmentInfo/LabelOptions
PrinterDPI O Enumerated Resolution for X-axis and Y-axis (in
DPI) for transport label and waybill
document output

Possible values:
- 200
- 300
HideAccountInWaybillDocumen O AN 1 Hide account number in waybill
t document.

Possible values;

PAGE 107 OF 417

MYDHL API – DEVELOPER GUIDE

- Y, account number will NOT be

printed on the label for both
FRT and DTP account field.
- N, account number will be
printed on the Waybill
Document (Default)
RequestWaybillDocument O AN 1 Possible values;
- Y, Waybill document will be
returned in shipment response.
- N, Waybill document will not be
returned in shipment response.
(Default)
NumberOfWaybillDocument O INT Number of copies of Waybill
Copies document printout to be generated
and returned in shipment response.
Min Value : 1 ; Max Value : 2
RequestDHLCustomsInvoice O AN 1 Possible values;

- Y (Yes – using DHL Invoice)

- N (No – using Own Invoice) –

(Default)
DHLCustomsInvoiceLanguag O AN 3 To retrieve the language code based
eCode on customer input value. The
default value for this field is eng
(English). The supported language
code are as below; eng=English
bul=Bulgarian cze=Czech
dan=Danish ger=German
gre=Greek est=Estonian fin=Finnish
fre=French hun=Hungaria
ice=Icelandic ita=Italian
lit=Lithuanian lav=Latvian
dut=Dutch nno=Norwegian
pol=Polish por=Portuguese
rum=Romanian rus=Russian
slv=Slovenian slo=Slovak
spa=Spanish
DHLCustomsInvoiceLanguage O AN 2 ISO 2 character code of the
CountryCode language used for generating the
customs invoice

DHLCustomsInvoiceType O AN 20 The type for commercial invoice

PAGE 108 OF 417

MYDHL API – DEVELOPER GUIDE

Possible values;

- COMMERCIAL_INVOICE
(default)
- PROFORMA_INVOICE
- RETURNS_INVOICE
LabelRegText O AN 150 Customer data that can be printed in
certain Transport Label template.

Applicable only to:

ECOM26_A6_002
ECOM_TC_A4
ECOM26_84CI_001
CustData O AN 250 Customer data that can be printed in
certain Transport Label templates.

Applicable only to:

ECOM26_84_A4_001
ECOM_TC_A4
ECOM26_84CI_001
RequestShipmentReceipt O AN 1 Possible values;

- Y, request to generate the

shipment receipt
- N, no shipment receipt
generation is required (default)
RequestBarcodeInfo O AN 1 Possible values;

- Y, request to include additional

barcode details in response
- N, no additional barcode details
is required (default)

RequestLabelsToFitA4 O AN 1 Possible values;

- Y, request to print Transport

Label and Waybill Document in
A4 margin PDF format
- N, TransportLabel and Waybill
Document will use the selected
template page layout (default)

RequestDHLLogoOnLabel O AN 1 Possible values;

- Y, request to print DHL Logo in

Transport Label and Waybill
Document (default)

PAGE 109 OF 417

MYDHL API – DEVELOPER GUIDE

- N, request to not print DHL Logo

in Transport Label and Waybill
Document

RequestTransportLabel O AN 1 Return Transport Label in Shipment

Response when requesting for
QRCode.

Possible values:

- Y, request to include transport

label in shipment response
- N, no transport label returned in
shipment response

RequestQRCode O AN 1 Return QR Code in Shipment

Response

Possible values:

- Y, request to include QR code in

shipment response
- N, no QR code in shipment
response (default)

ShipmentRequest/RequestedShipment/ShipmentInfo/LabelOptions/CustomerLogo

LogoImage M Base64 Binary The customer logo image in base64

encoding

Supported image file format;

- RGB
- B&W, Black and White

Maximum size: 1 MB
LogoImageFormat M Enumerated Possible values;

- GIF
- JPEG
- JPG
- PNG
ShipmentRequest/RequestedShipment/ShipmentInfo/LabelOptions/CustomerBarcode (0:1)
(CustomerBarcode is only applicable when LabelTemplate=‘ECOM26_84CI_002’)
BarcodeType O AN The customer barcode type

Possible values:
- 93 , Code 93

PAGE 110 OF 417

MYDHL API – DEVELOPER GUIDE

- 39 , Code 39
- 128, Code 128

BarcodeContent O AN Customer barcode code

TextBelowBarcode O AN Customer barcode text
ShipmentRequest/RequestedShipment/ShipmentInfo/LabelOptions/DetachOptions
AllInOnePDF O AN 1 This field provide option to generate
a single
PDF file consists of Transport Label,
Waybill Document, Shipment Receipt
and Commercial Invoice.

Possible values:

- Y, response returns single

PDF file consisting of
TransportLabel, Waybill
Document, Shipment Receipt
and Commercial Invoice

- N (Default), where a single

PDF or thermal output image file
consists of Transport Label +
Waybill Document and single
PDF or thermal output image file
for Shipment Receipt and
Customs Invoice will be
returned.

SplitShipmentReceiptAndCu O AN 1 This field provide option to generate a

stomsInvoice single file consist of a single PDF or
thermal output image file consists of
Transport Label + Waybill Document,
a single file consist of Commercial
Invoice and a single file consist of
Shipment Receipt.

Possible values:

- Y, response returns single PDF

or thermal output image file
consists of Transport Label +
Waybill Document, a single file
consists of Commercial Invoice
and a single file consists of
Shipment Receipt

- N (Default), response returns

a single PDF or thermal output
image file consists of Transport
Label + Waybill Document and

PAGE 111 OF 417

MYDHL API – DEVELOPER GUIDE

single PDF or thermal output

image file for Shipment Receipt
and Customs Invoice

SplitTransportLabelAndWayb O AN 1 This field provide option to generate a

illDocument single
PDF or thermal output file for the
Transport
Label, a single PDF or thermal output
file for the Waybill document and a
single file consist of Commercial
Invoice and Shipment Receipt.

Possible values:

- Y, response returns single PDF

or thermal output file for the
Transport Label, a single PDF or
single PDF or thermal output file
for the Waybill document and a
single file consists of Commercial
Invoice and Shipment Receipt.

- N (Default), response returns

a single PDF or thermal output
image file consists of Transport
Label + Waybill Document and
single PDF or thermal output
image file for Shipment Receipt
and Customs Invoice

SplitLabelsByPieces O AN 1 This field provide option to generate a

single PDF or thermal output image
file for each pieces for Transport
Label and single PDF or thermal
output image file for Waybill
Document will be returned in create
shipment response.

Possible values:

- Y, response returns single PDF

or thermal output file for each
pieces for Transport Label and
single PDF or single PDF or
thermal output image file for
Waybill document

- N (Default), response returns

a single PDF or thermal output
image file consists of Transport
Label + Waybill Document and

PAGE 112 OF 417

MYDHL API – DEVELOPER GUIDE

single PDF or thermal output

image file for Shipment Receipt
and Customs Invoice

ShipmentReceiptWithLabels O AN 1 This field provide option to generate a

single PDF of Transport Label, Waybill
Document and Shipment Receipt.

Applicable only when LabelType is

PDF and when
RequestShipmentReceipt is Y.

Possible values:

- Y, response returns single PDF

of Transport Label, Waybill
Document and Shipment
Receipt.

- N (Default), response returns

single PDF or thermal output
image file consists of Transport
Label + Waybill Document and
single PDF or thermal output
image file for Shipment Receipt
and Customs Invoice

ShipmentRequest/RequestedShipment/ShipmentInfo/ShipmentReferences

ShipmentRequest/RequestedShipment/ShipmentInfo/ShipmentReferences/ShipmentRefere
nce (1:999)

ShipmentReference M AN 35 Shipment reference number

ShipmentReferenceType O Enumerated Shipment Reference Type code

Possible values;

- AAO, shipment reference

number of receiver
- CU, reference number of
consignor
- FF, reference number of freight
forwarder
- FN, freight bill number for <ex
works invoice number>
- IBC, inbound center reference
number
- LLR, load list reference for <10-
digit Shipment ID>

PAGE 113 OF 417

MYDHL API – DEVELOPER GUIDE

- OBC, outbound center reference

number for <SHIPMEN
IDENTIFIER (COUNTRY OF
ORIGIN)>
- PRN, pickup request number for
<BOOKING REFERENCE
NUMBER>
- ACP, local payer account
number
- ACS, local shipper account
number
- ACR, local receiver account
number
- CDN, customs declaration
number
- STD, eurolog 15-digit shipment
id
- CO, buyers order number
ShipmentRequest/RequestedShipment/ShipmentInfo/SpecialServices
ShipmentRequest/RequestedShipment/ShipmentInfo/SpecialServices/Service (1:99)

ServiceType M AN 6 Enter the DHL Express Service code

you wish to add – i.e. II for insurance
ServiceValue O 18.3 D Monetary value of service (currently
only applicable for Insurance & COD)
CurrencyCode O AN 3 Currency code

This element needs to be used, if the

corresponding ServiceValue is
provided. ServiceValue and
CurrencyCode should always be
provided together or none of them.
StartDate O Date For future use.
EndDate O Date For future use.
TextInstruction O AN50 For future use.
ShipmentRequest/RequestedShipment/ShipmentInfo/SpecialServices/Service/PaymentMeth
ods (0:1)
PaymentMethod M AN 3 Payment method code for indicating
a mode of payment such as when
adding Cash on Delivery service.

Possible values:
- CSH (cash)

PAGE 114 OF 417

MYDHL API – DEVELOPER GUIDE

- CRC (credit card)

- CHQ (cheque)
- DRD (direct debit)
- MOB (payment with mobile
phone)
ShipmentRequest/RequestedShipment/InternationalDetail

Content M Enumerated Possible values

- DOCUMENTS

- NON_DOCUMENTS

ShipmentRequest/RequestedShipment/InternationalDetail/Commodities
The description of the content of the
Description M AN 70
shipment.
CustomsValue O 18.3 D The value which needs to be declared
for customs.
USFilingTypeValue O AN 20 The US filing Type Value for
shipments from the US
ShipmentRequest/RequestedShipment/InternationalDetail/ExportDeclaration
ExporterCode O AN Exporter Code

Optional field to indicate the type code

of Exporter’s ID number provided in
ExporterID tag – e.g. DUN, SSN, EIN.
Identification Number of the Exporter
ExporterID O AN party.

ExportLicense O AN 16 Export license info

ExportReasonType O AN Export Reason Type

Possible values:
PERMANENT
TEMPORARY
RETURN
USED_EXHIBITION_GOODS_TO_ORIG
IN
INTERCOMPANY_USE
COMMERCIAL_PURPOSE_OR_SALE
PERSONAL_BELONGINGS_OR_PERSO
NAL_USE
SAMPLE
GIFT

PAGE 115 OF 417

MYDHL API – DEVELOPER GUIDE

RETURN_TO_ORIGIN
WARRANTY_REPLACEMENT
DIPLOMATIC_GOODS
DEFENCE_MATERIAL
ExportReason O AN 30 Export Reason

ImportLicense O AN 16 Consignee import license

InvoiceDate M Date Invoice date.

InvoiceNumber O/M AN 35 Invoice number.

This field is mandatory when
RequestDHLCustomsInvoice = Y.
PlaceOfIncoterm O AN 256 Name of port of departure, shipment
or destination, as required under the
applicable delivery term.

If using Customs Invoice template

COMMERCIAL_INVOICE_P_10 and
COMMERCIAL_INVOICE_L_10,
recommended max length is 25
characters.
ShipmentPurpose O Enumerated Indicates if the shipment was sent for
Personal or Commercial reasons.

Possible values:
- PERSONAL
- COMMERCIAL
PackageMarks O AN Package marks

PayerGSTVAT O AN Payer GST VAT details

RecipientReference O AN Recipient reference
TermsOfPayment O AN Terms of payment

Recommended max length for

Customs Invoice printing is 20
characters.
InvoiceTotalNetWeight O 15.3 D Total of line items net weight
InvoiceTotalGrossWeight O 15.3 D Total of line items gross weight
InvoiceInstructions O AN 300 Shipment instructions for customs
invoice printing purposes.

PAGE 116 OF 417

MYDHL API – DEVELOPER GUIDE

Printed only when using Customs

Invoice template
COMMERCIAL_INVOICE_04

If using Customs Invoice template

COMMERCIAL_INVOICE_04,
recommended max length is 120
characters.
ShipmentRequest/RequestedShipment/InternationalDetail/ExportDeclaration/CustomsDocu
ments
ShipmentRequest/RequestedShipment/InternationalDetail/ExportDeclaration/CustomsDocu
ments/CustomsDocument (1:50)
CustomsDocumentType M AN 3 Export declaration customs document
type code

Possible values:

- 972, T2LF Dispense Paiement

Droits

- AHC, Analysis and Health Certificate

- ATA, ATA Carnet

- ATR, Preference Certificate ATR

- CHD, CHED-D (Common Health

Entry Document for Feed and Food
of Non-Animal Origin

- CHP, CHED-P (Common Health Entry

Document for Products)

- CIT, CITES Certificate

- COO, Generic Certificate of Origin

- DEX, Duty Exemption Certificate

- EU1, Preference Certificate EUR1

- EU2, Preferential Declaration of

Origin on the Invoice - EUR2

- EUS, End Use Authorization

- FMA, Certificate of Origin (Form A)

- PHY, Phytosanitary Certificate

- VET, Veterinary Entry Document

PAGE 117 OF 417

MYDHL API – DEVELOPER GUIDE

- VEX, VAT Exemption Certificate

- CRL, Control Document

- CSD, Consolidated Customs Entry

- PPY, Proof Of Payment

- CI2, Export-only Invoice

- CIV, Customs Invoice Value

- DOV, Invoice

- INV, Commercial Invoice

- PFI, Pro-Forma

- ALC, Agricultural License

- HLC, Health Products Regulatory

Authority (HPRA) Licensing
Requirements

- JLC, Justice License

- LIC, Specific Export Licenses

- LNP, License or Permit

- PLI, Permits & Licenses

- DLI, Driver's License

- NID, National Identity Card

- PAS, Passport

- CHA, Power of Attorney

- CPA, Consignee Power of Attorney

- POA, Power of Attorney (Customer-

based)

- BEX, Branch Letter of Exemption

- DGD, Dangerous Goods Declaration

- IPA, Intellectual Property

Authorization

- T2M, T2M Transport Accompanying

Document

PAGE 118 OF 417

MYDHL API – DEVELOPER GUIDE

- TAD, TAD Transport Accompanying

Document T1

- TCS, Transportation Charges

Statement

- ROD, Receipt on Delivery

- EXL, DCE Export of Customs Data

- HWB, House Waybill

- ELP, Export Licenses and Permits

CustomsDocumentID M AN 35 Export declaration customs document

ID
ShipmentRequest/RequestedShipment/InternationalDetail/ExportDeclaration/Remarks
ShipmentRequest/RequestedShipment/InternationalDetail/ExportDeclaration/Remarks/Rem
ark (1:3)
RemarkDescription M AN Customs Invoice's Remarks
Description maximum of 3.

If using Customs Invoice template

COMMERCIAL_INVOICE_04, the
invoice can only print the first
RemarkDescription field. The
recommended max length is 20
characters.

If using Customs Invoice template

COMMERCIAL_INVOICE_L_10 or
COMMERCIAL_INVOICE_P_10, the
invoice can print all three
RemarkDescription fields. The
recommended max length is 45
characters.
ShipmentRequest/RequestedShipment/InternationalDetail/ExportDeclaration/OtherCharges
ShipmentRequest/RequestedShipment/InternationalDetail/ExportDeclaration/OtherCharge
s/OtherCharge (1:5)
Caption O AN Customs Invoice's Other Charges
maximum of 5 fields:

Caption can be passed to print in this

field.

Note:

PAGE 119 OF 417

MYDHL API – DEVELOPER GUIDE

Printed only when using Customs

Invoice template
COMMERCIAL_INVOICE_03,
COMMERCIAL_INVOICE_P_10 and
COMMERCIAL_INVOICE_L_10.
ChargeValue M 18.3 D Customs Invoice's Other Charges
maximum of 5 fields:

charge value can be passed to print in

this field
ChargeType M AN 5 5-character Charge Type code

Possible values

- ADMIN, administration fee

- DELIV, delivery fee

- DOCUM, documentation fee

- EXPED, expedite fee

- EXCHA, export fee

- FRCST , freight cost

- SSRGE, fuel surcharge

- LOGST, logistic fee

- SOTHR , other fee

- SPKGN, packaging/packing fee

- PICUP, pickup fee

- HRCRG, handling fee

- VATCR, VAT fee

- INSCH , insurance cost

- REVCH, reverse charge

For printing charges in commercial

invoice, refer to Appendix:
Commercial Invoice Template Guide
on charge types can be printed across
different Commercial Invoice
templates.

ShipmentRequest/RequestedShipment/InternationalDetail/ExportDeclaration/InvoiceSignatu
reDetails

PAGE 120 OF 417

MYDHL API – DEVELOPER GUIDE

SignatureName O AN 35 Name of signatory

SignatureTitle O AN 35 Title of signatory
SignatureImage O Signature image in base64 format

Max of size is 1 MB
Base64 Binary
Valid format of image are: PNG, GIF,
JPEG, JPG.
ShipmentRequest/RequestedShipment/InternationalDetail/ExportDeclaration/InvoiceDeclar
ationTexts
ShipmentRequest/RequestedShipment/InternationalDetail/ExportDeclaration/InvoiceDeclar
ationTexts/InvoiceDeclarationText (1:3)
Additional Declaration text maximum
of 3.

If using Customs Invoice template

COMMERCIAL_INVOICE_04, the
invoice can print the first
DeclarationText field (only to be used
DeclarationText M AN 700 for Loose BBX shipments)

If using Customs Invoice template

COMMERCIAL_INVOICE_P_10 or
COMMERCIAL_INVOICE_L_10, the
invoice can print the first
DeclarationText field.

ShipmentRequest/RequestedShipment/InternationalDetail/ExportDeclaration/CustomerData
TextEntries
(CustomerDataTextEntries is only applicable when
CustomsInvoiceTemplate=‘COMMERCIAL_INVOICE_04’)
ShipmentRequest/RequestedShipment/InternationalDetail/ExportDeclaration/CustomerData
TextEntries/CustomerDataTextEntry (1:6)
CustomerDataTextNumber M INT 1-6 Running sequence number of data
text
CustomerDataText M AN 45 Customer data text to be printed in
customs invoice

Printed only when using Customs

Invoice template
COMMERCIAL_INVOICE_04
ShipmentRequest/RequestedShipment/InternationalDetail/ExportDeclaration/InvoiceRefere
nces
ShipmentRequest/RequestedShipment/InternationalDetail/ExportDeclaration/InvoiceRefere
nces/InvoiceReference (1:100)

PAGE 121 OF 417

MYDHL API – DEVELOPER GUIDE

InvoiceReferenceType M AN 3 Export declaration level reference

type code

Possible values:
- ACL, Parent Shipment ID for BBX

- CID, Customer Identifier

- CN, Contract Number

- CU, Consignor reference number

- ITN, US Export declaration

reference ID

- MRN, Movement Reference number

- UCN, Unique reference of a

consignment (UCRN)

- OID, Order Number

- PON, Purchase Order Number

- RMA, RMA Number

- AAM, AWB Ref #

- ABT, Goods Declaration number

- ADA, Buyer Reference number

- AES, AES Post Clearance

- AFD, 1496 Item number

- ANT, Consignee Reference number

- BKN, Booking Number

- BOL, Bill of Lading Number

- CDN, Customs Declaration number

- COD, Cash On Delivery

- DSC, Weltpaket Reference

- FF, Freight forwarder's reference

number

- FN, Freight bill number

- FTR, Post Clearance Exemption US

- HWB, Shipment Identifiers

PAGE 122 OF 417

MYDHL API – DEVELOPER GUIDE

- IBC, Inbound center reference

number

- IPP, Insurance Policy Provider

- LLR, Load list reference

- MAB, Master Airwaybill Number

- MWB, MAWB Reference number

- OBC, Outbound center reference

number

- PD, Vendor Reference Number

- PRN, Pickup request number

- RTL, Return Leg waybill number

- SID, Shipment ID 15 Digit CODA

- SS, Seller Reference number

- SWN, Original Waybill number

(Return)

InvoiceReferenceNumber M AN 35 Export declaration level reference

number

If using Order Number for printing

Customs Invoice template
COMMERCIAL_INVOICE_04,
recommended max length is 20
characters.
ShipmentRequest/RequestedShipment/InternationalDetail/ExportDeclaration/ExportLineIte
ms
ShipmentRequest/RequestedShipment/InternationalDetail/ExportDeclaration/ExportLineIte
ms/ExportLineItem (1:999)
CommodityCode O AN 18 Export Commodity code for the
shipment at item line level
ImportCommodityCode O AN 18 Import Commodity code for the
shipment at item line level

ExportReasonType O Enumerated Possible values;

PERMANENT
TEMPORARY
RETURN
USED_EXIBITION_GOODS_TO_ORIGI
N

PAGE 123 OF 417

MYDHL API – DEVELOPER GUIDE

INTERCOMPANY_USE
COMMERCIAL_PURPOSE_OR_SALE
PERSONAL_BELONGINGS_OR_PERS
ONAL_USE
SAMPLE
GIFT
RETURN_TO_ORIGIN
WARRANTY_REPLACEMENT
DIPLOMATIC_GOODS
DEFENCE_MATERIAL
ItemNumber M Digit 1-999 Item sequence number e.g. 1, 2, 3 …
999
Quantity M INT 1 -
Quantity of the particular line item
1000000000
QuantityUnitOfMeasurement M Enumerated The quantity unit of measurement

- BOX Boxes
- 2GM Centigram
- 2M Centimeters
- 2M3 Cubic Centimeters
- 3M3 Cubic Feet
- M3 Cubic Meters
- DPR Dozen Pairs
- DOZ Dozen
- 2NO Each
- PCS Pieces
- GM Grams
- GRS Gross
- KG Kilograms
- L Liters
- M Meters
- 3GM Milligrams
- 3L Milliliters
- X No Unit Required
- NO Number
- 2KG Ounces
- PRS Pairs
- 2L Gallons
- 3KG Pounds
- CM2 Square Centimeters
- 2M2 Square Feet
- 3M2 Square Inches
- M2 Square Meters
- 4M2 Square Yards
- 3M Yards

PAGE 124 OF 417

MYDHL API – DEVELOPER GUIDE

- CM Centimeters
- CONE Cone
- CT Carat
- EA Each
- LBS Pounds
- RILL Rill
- ROLL Roll
- SET Set
- TU Time Unit
- YDS Yard
ItemDescription M AN 512 The description of the line item

When using Commercial Invoice

template
COMMERCIAL_INVOICE_P_10 or
COMMERCIAL_INVOICE_L_10,
Recommended max length is 170
characters.
UnitPrice M D 18.3 Monetary value of each line item

NetWeight M D 15.3 Net weight of the line item

GrossWeight M D 15.3 Gross weight of the line item
ManufacturingCountryCode M AN 2 Manufacturing ISO country code

TaxesPaid O Enumerated TaxesPaid if set to N. The default is N

Possible values;

- Y
- N

LicenseNumber O AN 16 Shipper export license (only to be

used for legacy invoice printing)

ShipmentRequest/RequestedShipment/InternationalDetail/ExportDeclaration/ExportLineIte
ms/ExportLineItem/AdditionalInformation

AdditionalInformationText M AN Additional information text for the line

item maximum of 8 fields.

Printed only when using Customs

Invoice templates
COMMERCIAL_INVOICE_04
COMMERCIAL_INVOICE_P_10
COMMERCIAL_INVOICE_L_10

PAGE 125 OF 417

MYDHL API – DEVELOPER GUIDE

ShipmentRequest/RequestedShipment/InternationalDetail/ExportDeclaration/ExportLineIte
ms/ExportLineItem/ItemReferences

ShipmentRequest/RequestedShipment/InternationalDetail/ExportDeclaration/ExportLineIte
ms/ExportLineItem/ItemReferences/ItemReference (1:100)

ItemReferenceType M AN 3 Line item reference type code

Possible values:

- AFE, Export Control Classification

Number (ECCN)

- AAJ, Delivery Order number

- ABW, Stock Keeping Unit

- ALX, Model

- BRD, Brand

- DGC, Dangerous Goods Content

Identifier

- DTC, DDTC Eligibility indicator

- DTM, DDTC UOM

- DTQ, DDTC Quantity

- DTR, DDTC Registraton No

- INB, In Bond shipment

- ITR, DDTC ITAR Exemption No

- MAK, Make

- MID, Manufacturers IDentification

code

- OED, Original Export Date

- OET, Original Export OB Tracking ID

- OID, Order ID

- OOR, Original Outbound Carrier

- PAN, Part No

- PON, Purchase Order Number

- SE, Serial number

- SON, Sales order No

PAGE 126 OF 417

MYDHL API – DEVELOPER GUIDE

- SME, DDTC SME Indicator

- USM, DDTC USML Category Code

- AAM, AWB Ref #

- CFR, ECCN License Exemption

(CFR#)

- DOM, Domestic indicator CoO (US)

- FOR, Foreign indicator CoO (US)

- USG, Usage

- MAT, Material

- NLR, ECCN No License Required

Indicator

ItemReferenceNumber M AN 35 Line item reference number

First five ItemReference in request

message can be printed in templates
COMMERCIAL_INVOICE_P_10 and
COMMERCIAL_INVOICE_L_10.

ShipmentRequest/RequestedShipment/InternationalDetail/ExportDeclaration/ExportLineIte
ms/ExportLineItem/CustomPaperworks

ShipmentRequest/RequestedShipment/InternationalDetail/ExportDeclaration/ExportLineIte
ms/ExportLineItem/CustomPaperworks/CustomPaperwork (1:50)

CustomsPaperworkType M AN 3 Line item customs paperwork type

code

Possible values:

- 972, T2LF Dispense Paiement

Droits

- AHC, Analysis and Health Certificate

- ATA, ATA Carnet

- ATR, Preference Certificate ATR

- CHD, CHED-D (Common Health

Entry Document for Feed and Food
of Non-Animal Origin

- CHP, CHED-P (Common Health Entry

Document for Products)

PAGE 127 OF 417

MYDHL API – DEVELOPER GUIDE

- CIT, CITES Certificate

- COO, Generic Certificate of Origin

- DEX, Duty Exemption Certificate

- EU1, Preference Certificate EUR1

- EU2, Preferential Declaration of

Origin on the Invoice - EUR2

- EUS, End Use Authorization

- FMA, Certificate of Origin (Form A)

- PHY, Phytosanitary Certificate

- VET, Veterinary Entry Document

- VEX, VAT Exemption Certificate

- CRL, Control Document

- CSD, Consolidated Customs Entry

- PPY, Proof Of Payment

- CI2, Export-only Invoice

- CIV, Customs Invoice Value

- DOV, Invoice

- INV, Commercial Invoice

- PFI, Pro-Forma

- ALC, Agricultural License

- HLC, Health Products Regulatory

Authority (HPRA) Licensing
Requirements

- JLC, Justice License

- LIC, Specific Export Licenses

- LNP, License or Permit

- PLI, Permits & Licenses

- DLI, Driver's License

- NID, National Identity Card

- PAS, Passport

PAGE 128 OF 417

MYDHL API – DEVELOPER GUIDE

- CHA, Power of Attorney

- CPA, Consignee Power of Attorney

- POA, Power of Attorney (Customer-

based)

- BEX, Branch Letter of Exemption

- DGD, Dangerous Goods Declaration

- IPA, Intellectual Property

Authorization

- T2M, T2M Transport Accompanying

Document

- TAD, TAD Transport Accompanying

Document T1

- TCS, Transportation Charges

Statement

- ROD, Receipt on Delivery

- EXL, DCE Export of Customs Data

- HWB, House Waybill

- ELP, Export Licenses and Permits

CustomsPaperworkID M AN 35
Line item customs paperwork ID

ShipmentRequest/RequestedShipment/OnDemandDeliveryOptions (Please note if you use this

optional segment then the Buyer segment is also required)

DeliveryOption M Enumerated The Delivery option is to define which

on demand delivery option you wish to
choose optionally when your
shipment is to be delivered.

The options are:

- TV Deliver to a DHL Express
Servicepoint

- SW, Leave with neighbour

- SX, Signature release

Location O AN15 Mandatory if the above delivery option

is SX and should advise DHL where

PAGE 129 OF 417

MYDHL API – DEVELOPER GUIDE

exactly to leave the shipment (ie.front

door etc)
Instructions O AN110 Additional information that is useful
for the DHL Express courier
GateCode O AN10 Entry code to gain access to an
apartment complex or gate
LWNTypeCode O “N”,”C” Mandatory if the above delivery
option is SW. The possible values are

N – Leave with neighbour

C – Leave with concierge

NeighbourName O AN20 Mandatory if the delivery option is SW
and the LWNTypeCode is N
(Neighbour) – this is where the name
of the neighbour is required
NeighbourHouseNumber O AN20 Mandatory if the delivery option is SW
and the LWNTypeCode is N
(Neighbour) – this is the house
number of the neighbour
AuthorizerName O AN20 Mandatory if delivery option is SX or
SW– this is the person that this
authorised to sign and receive the
DHL Express shipment
SelectedServicePointID O AN6 Mandatory if delivery option is TV –
this is the unique DHL Express Service
point location ID of where the parcel
should be delieverd (please contact
your local DHL Express Account
Manager to obtain the list of the
servicepoint IDs)
RequestedDeliveryDate O AN29 Reserved for future use
ShipmentRequest/RequestedShipment/Ship
ShipmentRequest/RequestedShipment/Ship/Shipper
BusinessPartyTypeCode O AN 2 Shipping party type code

Possible values:
- BU (business)
- DC (direct consumer)
- GV (government)
- OT (other)
- PR (private)
- RE (reseller)
ShipmentRequest/RequestedShipment/Ship/Shipper/Contact

PAGE 130 OF 417

MYDHL API – DEVELOPER GUIDE

PersonName M AN 255 A contact name of a person who will

ship the shipment.

When using Shipment Receipt

template 'SHIP_RECPT_A4_RU_PDF',
recommended max length is 50
characters.

When using Commercial Invoice

template
COMMERCIAL_INVOICE_P_10 or
COMMERCIAL_INVOICE_L_10,
Recommended max length is 48
characters.
CompanyName M AN 100 The company name the person is
working in.

When using Shipment Receipt

template 'SHIP_RECPT_A4_RU_PDF',
recommended max length is 50
characters.

When using Commercial Invoice

template
COMMERCIAL_INVOICE_P_10 or
COMMERCIAL_INVOICE_L_10,
Recommended max length is 47
characters.
PhoneNumber M AN 70 The contact person phone number. In
case of questions, this person can be
called by the courier.
EmailAddress O AN 70 The email address of the contact
person.

When using Commercial Invoice

template
COMMERCIAL_INVOICE_P_10 or
COMMERCIAL_INVOICE_L_10,
Recommended max length is 50
characters.
MobilePhoneNumber O AN 70 The mobile phone number of the
contact person.
ShipmentRequest/RequestedShipment/Ship/Shipper/Address
StreetLines M AN 45 The street line should contain street
name and number of the shipper.

PAGE 131 OF 417

MYDHL API – DEVELOPER GUIDE

StreetName O AN 250 Shipper street name should be sent as

separate attribute if feasible.
BuildingName O AN 50 Shipper building name
StreetNumber O AN 50 Shipper street number should be sent
as separate attribute, if feasible.
StreetLines2 O AN 45 Shipper additional address
information
StreetLines3 O AN 45 Shipper additional address
information
City M AN 45 Shipper city name
StateOrProvinceCode O AN 2 2 Letter state code for the USA only
PostalCode M AN 12 Shipper postal code
CountryCode M AN 2 ISO 2 character code of the Shipper
country.
Suburb O AN 45 Shipper suburb name
StateOrProvinceName O AN 35 Shipper State or Province Name
CountryName O AN 35 Shipper Country Name
ShipmentRequest/RequestedShipment/Ship/Shipper/RegistrationNumbers
ShipmentRequest/RequestedShipment/Ship/Shipper/RegistrationNumbers/RegistrationNum
ber (1:50)
Number M AN 35 Registration Number of the Shipper.
NumberTypeCode M AN 3 Type of the registration number.

Possible values:

- CNP, Brazil CNPJ/CPF Federal Tax

- DUN, Data Universal Numbering

System

- EIN, Employer Identification Number

- EOR, Economic Operator

Registration ID

- FED, Federal Tax ID

- FTZ, Free Trade Zone ID

- SDT, Import One-Stop-Shop (IOSS)

- SDT, Overseas Registered Supplier

(LVG)

PAGE 132 OF 417

MYDHL API – DEVELOPER GUIDE

- SDT, AUSid GST Registration (OSR)

- SSN, Social Security Number

- STA, State Tax ID

- VAT, VAT Registration (VAT / GST)

- SDT, VAT on E-Commerce (VOEC),

- GST, Goods and Service Tax

- IE, Brazil type IE/RG Federal Tax

- INN, Russia bank details section –

INN

- KPP, Russia bank details section –

KPP

- OGR, Russia bank details section –

OGRN

- OKP, Russia bank details section –

OKPO

- MRN, Germany Movement

Reference Number

- RGP, EU Registered Exporters

Registration ID

- DLI, Driver’s License

- NID, National Identity Card

- PAS, Passport

- MID, Manufacturer ID

Not all type codes are applicable for

all countries and address types. Refer
to Appendix: Registration Number
Type Codes attached in this document
for full list of type codes, their
description and applicable issuing
country and shipping roles.

NumberIssuerCountryCode M AN 2 ISO 2 character code of the country

where the Registration Number has
been issued by.
ShipmentRequest/RequestedShipment/Ship/Shipper/BankDetails
ShipmentRequest/RequestedShipment/Ship/Shipper/BankDetails/BankDetail

PAGE 133 OF 417

MYDHL API – DEVELOPER GUIDE

BankName O AN To be mapped in Customs Invoice -

Russia Bank Name field
O AN To be mapped in Customs Invoice -
BankSettlementAccountNum
Russia Bank Settlement Account
berInLocalCurrency
Number in RUR field
O AN To be mapped in Customs Invoice -
BankSettlementAccountNum
Russia Bank Settlement Account
berInForeignCurrency
Number in USD/EUR
ShipmentRequest/RequestedShipment/Ship/Pickup
BusinessPartyTypeCode O AN 2 Pickup party type code

Possible values:
- BU (business)
- DC (direct consumer)
- GV (government)
- OT (other)
- PR (private)
- RE (reseller)
ShipmentRequest/RequestedShipment/Ship/Pickup/Contact
PersonName M AN 255 A contact name of a person who will
give the shipment.to the courier
CompanyName M AN 100 The company name the person is
working in.
PhoneNumber M AN 70 The contact person phone number. In
case of questions, this person can be
called by the courier.
EmailAddress O AN 70 The email address of the contact
person.
MobilePhoneNumber O AN 70 The mobile phone number of the
contact person.
ShipmentRequest/RequestedShipment/Ship/Pickup/Address

StreetLines M AN 45 The street line should contain street

name and number of the pickup place.

StreetName O AN 250 Pickup street name should be sent as

separate attribute if feasible.
BuildingName O AN 50 Pickup building name
StreetNumber O AN 50 Pickup street number should be sent
as separate attribute, if feasible.
StreetLines2 O AN 45 Pickup additional address information

PAGE 134 OF 417

MYDHL API – DEVELOPER GUIDE

StreetLines3 O AN 45 Pickup additional address information

City M AN 45 Pickup city name
StateOrProvinceCode O AN 2 2 Letter state code for the USA only
PostalCode M AN 12 Pickup postal code
CountryCode M AN 2 ISO 2 character codes of the Pickup
country.
Suburb O AN 45 Suburb name for pickup
StateOrProvinceName O AN 35 Pickup State or Province Name
CountryName O AN 35 Pickup Country Name
ShipmentRequest/RequestedShipment/Ship/Pickup/RegistrationNumbers
ShipmentRequest/RequestedShipment/Ship/Pickup/RegistrationNumbers/RegistrationNumb
er (1:50)

Number M AN 35 Registration Number of the Pickup.

NumberTypeCode M AN 3 Type of the registration number.

Possible values:

- CNP, Brazil CNPJ/CPF Federal Tax

- DUN, Data Universal Numbering

System

- EIN, Employer Identification Number

- EOR, Economic Operator Registration

ID

- FED, Federal Tax ID

- FTZ, Free Trade Zone ID

- SDT, Import One-Stop-Shop (IOSS)

- SDT, Overseas Registered Supplier

(LVG)

- SDT, AUSid GST Registration (OSR)

- SSN, Social Security Number

- STA, State Tax ID

- VAT, VAT Registration (VAT / GST)

- SDT, VAT on E-Commerce (VOEC)

PAGE 135 OF 417

MYDHL API – DEVELOPER GUIDE

- RGP, EU Registered Exporters

Registration ID

- DLI, Driver’s License

- NID, National Identity Card

- PAS, Passport

- MID, Manufacturer ID

Not all type codes are applicable for all

countries and address types. Refer to
Appendix: Registration Number Type
Codes attached in this document for
full list of type codes, their description
and applicable issuing country and
shipping roles.

NumberIssuerCountryCode M AN 2 ISO 2 character code of the country

where the Registration Number has
been issued by.
ShipmentRequest/RequestedShipment/Ship/Pickup/BankDetails
ShipmentRequest/RequestedShipment/Ship/Pickup/BankDetails/BankDetail
BankName O AN To be mapped in Customs Invoice -
Russia Bank Name field
O AN To be mapped in Customs Invoice -
BankSettlementAccountNum
Russia Bank Settlement Account
berInLocalCurrency
Number in RUR field
O AM To be mapped in Customs Invoice -
BankSettlementAccountNum
Russia Bank Settlement Account
berInForeignCurrency
Number in USD/EUR
ShipmentRequest/RequestedShipment/Ship/BookingRequestor
BusinessPartyTypeCode O AN 2 Booking Requestor party type code

Possible values:
- BU (business)
- DC (direct consumer)
- GV (government)
- OT (other)
- PR (private)
- RE (reseller)
ShipmentRequest/RequestedShipment/Ship/BookingRequestor/Contact
PersonName M AN 255 A contact name of a person who is
requesting the pickup.

PAGE 136 OF 417

MYDHL API – DEVELOPER GUIDE

When using Shipment Receipt template

'SHIP_RECPT_A4_RU_PDF',
recommended max length is 50
characters.
CompanyName M AN 100 The company name the person is
working in.

When using Shipment Receipt template

'SHIP_RECPT_A4_RU_PDF',
recommended max length is 50
characters.
PhoneNumber M AN 70 The contact person phone number. In
case of questions, this person can be
called by the courier.
The email address of the contact
EmailAddress O AN 70
person.
MobilePhoneNumber O AN 70 The mobile phone number of the
contact person.
ShipmentRequest/RequestedShipment/Ship/BookingRequestor/Address
StreetLines M AN 45 The street line should contain street
name and number of pickup requestor
StreetName O AN 250 Pickup street name should be sent as
separate attribute if feasible.
BuildingName AN 50 Building name for pickup requestor
StreetNumber O AN 50 Pickup street number should be sent as
separate attribute, if feasible.
StreetLines2 O AN 45 Pickup additional address information
StreetLines3 O AN 45 Pickup additional address information
City M AN 45 Pickup city name
StateOrProvinceCode O AN 2 2 Letter state code for the USA only
PostalCode M AN 12 Pickup postal code
CountryCode M AN 2 ISO 2 character codes of the Pickup
Requestor country.
Suburb O AN 45 Suburb name for pickup

StateOrProvinceName O AN 35 State or Province Name of the

Requestor Country
CountryName O AN 35 Country Name of the Requestor
Country
ShipmentRequest/RequestedShipment/Ship/BookingRequestor/RegistrationNumbers
ShipmentRequest/RequestedShipment/Ship/BookingRequestor/RegistrationNumbers/Regist
rationNumber (1:50)
Registration Number of the pickup
Number M AN 35
requestor.

PAGE 137 OF 417

MYDHL API – DEVELOPER GUIDE

NumberTypeCode M AN 3 Type of the registration number.

Possible values:

- CNP, Brazil CNPJ/CPF Federal Tax

- DUN, Data Universal Numbering

System

- EIN, Employer Identification Number

- EOR, Economic Operator Registration

ID

- FED, Federal Tax ID

- FTZ, Free Trade Zone ID

- SDT, Import One-Stop-Shop (IOSS)

- SDT, Overseas Registered Supplier

(LVG)

- SDT, AUSid GST Registration (OSR)

- SSN, Social Security Number

- STA, State Tax ID

- VAT, VAT Registration (VAT / GST)

- SDT, VAT on E-Commerce (VOEC)

- RGP, EU Registered Exporters

Registration ID

- DLI, Driver’s License

- NID, National Identity Card

- PAS, Passport

- MID, Manufacturer ID

Not all type codes are applicable for all

countries and address types. Refer to
Appendix: Registration Number Type
Codes attached in this document for
full list of type codes, their description
and applicable issuing country and
shipping roles.
NumberIssuerCountryCode M AN 2 ISO 2 character code of the country
where the Registration Number has
been issued by.

PAGE 138 OF 417

MYDHL API – DEVELOPER GUIDE

ShipmentRequest/RequestedShipment/Ship/BookingRequestor/BankDetails
ShipmentRequest/RequestedShipment/Ship/BookingRequestor/BankDetails/BankDetail
BankName O AN To be mapped in Customs Invoice -
Russia Bank Name field
O AN To be mapped in Customs Invoice -
BankSettlementAccountNum
Russia Bank Settlement Account
berInLocalCurrency
Number in RUR field
BankSettlementAccountNum O AN To be mapped in Customs Invoice -
berInForeignCurrency Russia Bank Settlement Account
Number in USD/EUR
ShipmentRequest/RequestedShipment/Ship/Buyer
BusinessPartyTypeCode O AN 2 Buyer party type code

Possible values:
- BU (business)
- DC (direct consumer)
- GV (government)
- OT (other)
- PR (private)
- RE (reseller)
ShipmentRequest/RequestedShipment/Ship/Buyer/Contact
A contact name of a person who acts as
Buyer

When using Commercial Invoice

PersonName M AN 255 template
COMMERCIAL_INVOICE_P_10 or
COMMERCIAL_INVOICE_L_10,
Recommended max length is 48
characters.
The company name the person is
working in.

When using Commercial Invoice

CompanyName M AN 100 template
COMMERCIAL_INVOICE_P_10 or
COMMERCIAL_INVOICE_L_10,
Recommended max length is 47
characters.
PhoneNumber M AN 70 The contact person phone number. In
case of questions, this person can be
called by the courier.

PAGE 139 OF 417

MYDHL API – DEVELOPER GUIDE

EmailAddress O AN 70 The email address of the contact

person.

When using Commercial Invoice

template
COMMERCIAL_INVOICE_P_10 or
COMMERCIAL_INVOICE_L_10,
Recommended max length is 50
characters.
MobilePhoneNumber O AN 70 The mobile phone number of the
contact person.
ShipmentRequest/RequestedShipment/Ship/Buyer/Address
StreetLines M AN 45 The street line should contain street
name and number of the shipper.
StreetName O AN 250 Buyer street name should be sent as
separate attribute if feasible.
BuildingName O AN 50 The buyer building name
StreetNumber O AN 50 Buyer street number should be sent as
separate attribute, if feasible.
StreetLines2 O AN 45 Buyer additional address information
StreetLines3 O AN 45 Buyer additional address information
CityDistrict O AN 35 Buyer city district
City M AN 45 Buyer city name
StateOrProvinceCode O AN 2 2 Letter state code for the USA only
PostalCode M AN 12 Pickup postal code
CountryName O AN 35 Buyer country name
CountryCode M AN 2 ISO 2 character codes of the Buyer
country.
Suburb O AN 45 Buyer suburb
StateOrProvinceName O AN 35 Buyer State or Province Name
ShipmentRequest/RequestedShipment/Ship/Buyer/RegistrationNumbers
ShipmentRequest/RequestedShipment/Ship/Buyer/RegistrationNumbers/RegistrationNumbe
r (1:50)

Number M AN 35 Registration Number of the buyer.

NumberTypeCode M AN 3 Type of the registration number.

Possible values:

PAGE 140 OF 417

MYDHL API – DEVELOPER GUIDE

- CNP, Brazil CNPJ/CPF Federal Tax

- DUN, Data Universal Numbering

System

- EIN, Employer Identification Number

- EOR, Economic Operator Registration

ID

- FED, Federal Tax ID

- FTZ, Free Trade Zone ID

- SSN, Social Security Number

- STA, State Tax ID

- VAT, VAT Registration (VAT / GST)

- RGP, EU Registered Exporters

Registration ID

Not all type codes are applicable for all

countries and address types. Refer to
Appendix: Registration Number Type
Codes attached in this document for
full list of type codes, their description
and applicable issuing country and
shipping roles.
NumberIssuerCountryCode M AN 2 ISO 2 character code of the country
where the Registration Number has
been issued by.
ShipmentRequest/RequestedShipment/Ship/Buyer/BankDetails
ShipmentRequest/RequestedShipment/Ship/Buyer/BankDetails/BankDetail
BankName O AN To be mapped in Customs Invoice -
Russia Bank Name field
O AN To be mapped in Customs Invoice -
BankSettlementAccountNum
Russia Bank Settlement Account
berInLocalCurrency
Number in RUR field
O AN To be mapped in Customs Invoice -
BankSettlementAccountNum
Russia Bank Settlement Account
berInForeignCurrency
Number in USD/EUR
ShipmentRequest/RequestedShipment/Ship/Recipient
BusinessPartyTypeCode O AN 2 Recipient party type code

Possible values:
- BU (business)

PAGE 141 OF 417

MYDHL API – DEVELOPER GUIDE

- DC (direct consumer)
- GV (government)
- OT (other)
- PR (private)
- RE (reseller)
ShipmentRequest/RequestedShipment/Ship/Recipient/Contact
PersonName M AN 255 A contact name of a person who will
ship the shipment.

When using Shipment Receipt

template 'SHIP_RECPT_A4_RU_PDF',
recommended max length is 50
characters.

When using Commercial Invoice

template
COMMERCIAL_INVOICE_P_10 or
COMMERCIAL_INVOICE_L_10,
Recommended max length is 48
characters.
CompanyName M AN 100 The company name the person is
working in.

When using Shipment Receipt

template 'SHIP_RECPT_A4_RU_PDF',
recommended max length is 50
characters.

When using Commercial Invoice

template
COMMERCIAL_INVOICE_P_10 or
COMMERCIAL_INVOICE_L_10,
recommended max length is 47
characters.
PhoneNumber M AN 70 The contact person phone number. In
case of questions, this person can be
called by the courier.

When using
OnDemandDeliveryOptions (ODD),
recommended max length is 40
characters.
EmailAddress O AN 70 The email address of the contact
person.

PAGE 142 OF 417

MYDHL API – DEVELOPER GUIDE

When using Commercial Invoice

template
COMMERCIAL_INVOICE_P_10 or
COMMERCIAL_INVOICE_L_10,
recommended max length is 50
characters.

When using
OnDemandDeliveryOptions (ODD),
recommended max length is 40
characters.
MobilePhoneNumber O AN 70 The mobile phone number of the
contact person.

When using
OnDemandDeliveryOptions (ODD),
recommended max length is 40
characters.
ShipmentRequest/RequestedShipment/Ship/Recipient/Address
StreetLines M AN 45 The street line should contain street
name and number of the shipper.
StreetName O AN 250 Recipient street name should be sent as
separate attribute if feasible.
BuildingName O AN 50 The Recipient building number
StreetNumber O AN 50 Recipient street number should be
sent as separate attribute, if feasible.
O Recipient additional address
StreetLines2 AN 45
information
StreetLines3 O AN 45 Recipient additional address
information
City M AN 45 Recipient city name
StateOrProvinceCode O AN 2 2 Letter state code for the USA only
PostalCode M AN 12 Recipient postal code
CountryCode M AN 2 ISO 2 character codes of the Receiver
country.
Suburb O AN 45 Recipient suburb
StateOrProvinceName O AN 35 Recipient State or Province Name
CountryName O AN 35 Recipient Country Name
ShipmentRequest/RequestedShipment/Ship/Recipient/RegistrationNumbers

PAGE 143 OF 417

MYDHL API – DEVELOPER GUIDE

ShipmentRequest/RequestedShipment/Ship/Recipient/RegistrationNumbers/RegistrationNu
mber (1:50)
Number M AN 35 Registration Number of the Recipient
NumberTypeCode M AN 3 Type of the registration number.

Possible values:

- CNP, Brazil CNPJ/CPF Federal Tax

- DUN, Data Universal Numbering

System

- EIN, Employer Identification Number

- EOR, Economic Operator Registration

ID

- FED, Federal Tax ID

- FTZ, Free Trade Zone ID

- SSN, Social Security Number

- STA, State Tax ID

- VAT, VAT Registration (VAT / GST)

- RGP, EU Registered Exporters

Registration ID

- DLI, Driver’s License

- NID, National Identity Card

- PAS, Passport

- MID, Manufacturer ID

Not all type codes are applicable for all

countries and address types. Refer to
Appendix: Registration Number Type
Codes attached in this document for
full list of type codes, their description
and applicable issuing country and
shipping roles.
NumberIssuerCountryCode M AN 2 ISO 2 character code of the country
where the Registration Number has
been issued by.
ShipmentRequest/RequestedShipment/Ship/Recipient/BankDetails
ShipmentRequest/RequestedShipment/Ship/Recipient/BankDetails/BankDetail

PAGE 144 OF 417

MYDHL API – DEVELOPER GUIDE

BankName O AN To be mapped in Customs Invoice -

Russia Bank Name field
O AN To be mapped in Customs Invoice -
BankSettlementAccountNum
Russia Bank Settlement Account
berInLocalCurrency
Number in RUR field
BankSettlementAccountNum O AN To be mapped in Customs Invoice -
berInForeignCurrency Russia Bank Settlement Account
Number in USD/EUR
ShipmentRequest/RequestedShipment/Ship/Exporter
BusinessPartyTypeCode O AN 2 Exporter party type code

Possible values:
- BU (business)
- DC (direct consumer)
- GV (government)
- OT (other)
- PR (private)
- RE (reseller)
ShipmentRequest/RequestedShipment/Ship/Exporter/Contact
PersonName M AN 255 A contact name of a person who acts as
Exporter

When using Commercial Invoice

template
COMMERCIAL_INVOICE_P_10 or
COMMERCIAL_INVOICE_L_10,
Recommended max length is 48
characters.
CompanyName M AN 100 The company name of the Exporter

When using Commercial Invoice

template
COMMERCIAL_INVOICE_P_10 or
COMMERCIAL_INVOICE_L_10,
recommended max length is 47
characters.
PhoneNumber M AN 70 The contact person phone number
EmailAddress O AN 70 The email address of the contact
person.

When using Commercial Invoice

template
COMMERCIAL_INVOICE_P_10 or

PAGE 145 OF 417

MYDHL API – DEVELOPER GUIDE

COMMERCIAL_INVOICE_L_10,
recommended max length is 50
characters.
MobilePhoneNumber O AN 70 The mobile phone number of the
contact person.
ShipmentRequest/RequestedShipment/Ship/Exporter/Address
StreetLines M AN 45 The street line should contain street
name and number of the Exporter.
StreetName O AN 250 Importer street name should be sent as
separate attribute if feasible.
BuildingName O AN 50 The exporter building name
StreetNumber O AN 50 Exporter street number should be sent
as separate attribute, if feasible.
StreetLines2 O AN 45 Exporter additional address
information
StreetLines3 O AN 45 Exporter additional address
information
City M AN 45 Exporter city name
StateOrProvinceCode O AN 2 2 Letter state code for the USA only
PostalCode M AN 12 Exporter postal code
CountryCode M AN 2 ISO 2 character codes of the Exporter
country.
Suburb O AN 45 Exporter suburb
StateOrProvinceName O AN 35 Exporter State or Province Name
CountryName O AN 35 Exporter Country Name
ShipmentRequest/RequestedShipment/Ship/Exporter/RegistrationNumbers
ShipmentRequest/RequestedShipment/Ship/Exporter/RegistrationNumbers/RegistrationNu
mber (1:50)

Number M AN 35 Registration Number of the exporter.

NumberTypeCode M AN 3 Type of the registration number.

Possible values:

- CNP, Brazil CNPJ/CPF Federal Tax

- DAN, Deferment Account Duties Only

- DTF, Deferment Account Duties,

Taxes and Fees Only

PAGE 146 OF 417

MYDHL API – DEVELOPER GUIDE

- DUN, Data Universal Numbering

System

- EIN, Employer Identification Number

- EOR, Economic Operator Registration

ID

- FED, Federal Tax ID

- FTZ, Free Trade Zone ID

- SSN, Social Security Number

- STA, State Tax ID

- TAN, Deferment Account Tax Only

- VAT, VAT Registration (VAT / GST)

- RGP, EU Registered Exporters

Registration ID

- DLI, Driver’s License

- NID, National Identity Card

- PAS, Passport

- MID, Manufacturer ID

Not all type codes are applicable for all

countries and address types. Refer to
Appendix: Registration Number Type
Codes attached in this document for
full list of type codes, their description
and applicable issuing country and
shipping roles.
NumberIssuerCountryCode M AN 2 ISO 2 character code of the country
where the Registration Number has
been issued by.
ShipmentRequest/RequestedShipment/Ship/Exporter/BankDetails
ShipmentRequest/RequestedShipment/Ship/Exporter/BankDetails/BankDetail
BankName O AN To be mapped in Customs Invoice -
Russia Bank Name field
O AN To be mapped in Customs Invoice -
BankSettlementAccountNum
Russia Bank Settlement Account
berInLocalCurrency
Number in RUR field

PAGE 147 OF 417

MYDHL API – DEVELOPER GUIDE

BankSettlementAccountNum O AN To be mapped in Customs Invoice -

berInForeignCurrency Russia Bank Settlement Account
Number in USD/EUR
ShipmentRequest/RequestedShipment/Ship/Importer
BusinessPartyTypeCode O AN 2 Importer party type code

Possible values:
- BU (business)
- DC (direct consumer)
- GV (government)
- OT (other)
- PR (private)
- RE (reseller)
ShipmentRequest/RequestedShipment/Ship/Importer/Contact
PersonName M AN 255 A contact name of a person who acts as
Importer

When using Commercial Invoice

template
COMMERCIAL_INVOICE_P_10 or
COMMERCIAL_INVOICE_L_10,
recommended max length is 48
characters.
CompanyName M AN 100 The company name the Importer

When using Commercial Invoice

template
COMMERCIAL_INVOICE_P_10 or
COMMERCIAL_INVOICE_L_10,
recommended max length is 47
characters.
PhoneNumber M AN 70 The contact person phone number
EmailAddress O AN 70 The email address of the contact
person.

When using Commercial Invoice

template
COMMERCIAL_INVOICE_P_10 or
COMMERCIAL_INVOICE_L_10,
recommended max length is 50
characters.
MobilePhoneNumber O AN 70 The mobile phone number of the
contact person.

PAGE 148 OF 417

MYDHL API – DEVELOPER GUIDE

ShipmentRequest/RequestedShipment/Ship/Importer/Address
StreetLines M AN 45 The street line should contain street
name and number of the importer.
StreetName O AN 250 Importer street name should be sent as
separate attribute if feasible.
BuildingName O AN 50 The importer building name
StreetNumber O AN 50 Importer street number should be sent
as separate attribute, if feasible.
StreetLines2 O AN 45 Importer additional address
information
StreetLines3 O AN 45 Importer additional address
information
City M AN 45 Importer city name
StateOrProvinceCode O AN 2 2 Letter state code for the USA only
PostalCode M AN 12 Importer postal code
CountryCode M AN 2 ISO 2 character codes of the Importer
country.
Suburb O AN 45 Importer suburb
StateOrProvinceName O AN 35 Importer State or Province Name
CountryName O AN 35 Importer Country Name
ShipmentRequest/RequestedShipment/Ship/Importer/RegistrationNumbers
ShipmentRequest/RequestedShipment/Ship/Importer/RegistrationNumbers/RegistrationNu
mber (1:50)

Number M AN 35 Registration Number of the importer.

NumberTypeCode M AN 3 Type of the registration number.

Possible values:

- CNP, Brazil CNPJ/CPF Federal Tax

- DAN, Deferment Account Duties Only

- DTF, Deferment Account Duties,

Taxes and Fees Only

- DUN, Data Universal Numbering

System

- EIN, Employer Identification Number

- EOR, Economic Operator Registration

ID

PAGE 149 OF 417

MYDHL API – DEVELOPER GUIDE

- FED, Federal Tax ID

- FTZ, Free Trade Zone ID

- SSN, Social Security Number

- STA, State Tax ID

- TAN, Deferment Account Tax Only

- VAT, VAT Registration (VAT / GST)

- RGP, EU Registered Exporters

Registration ID

- DLI, Driver’s License

- NID, National Identity Card

- PAS, Passport

- MID, Manufacturer ID

Not all type codes are applicable for

all countries and address types.
Refer to Appendix: Registration
Number Type Codes attached in
this document for full list of type
codes, their description and
applicable issuing country and
shipping roles.

NumberIssuerCountryCode M AN 2 ISO 2 character code of the country

where the Registration Number has
been issued by.
ShipmentRequest/RequestedShipment/Ship/Importer/BankDetails
ShipmentRequest/RequestedShipment/Ship/Importer/BankDetails/BankDetail
BankName O AN To be mapped in Customs Invoice -
Russia Bank Name field
O AN To be mapped in Customs Invoice -
BankSettlementAccountNum
Russia Bank Settlement Account
berInLocalCurrency
Number in RUR field
BankSettlementAccountNum O AN To be mapped in Customs Invoice -
berInForeignCurrency Russia Bank Settlement Account
Number in USD/EUR
ShipmentRequest/RequestedShipment/Ship/Seller
BusinessPartyTypeCode O AN 2 Seller party type code

Possible values:

PAGE 150 OF 417

MYDHL API – DEVELOPER GUIDE

- BU (business)
- DC (direct consumer)
- GV (government)
- OT (other)
- PR (private)
- RE (reseller)
ShipmentRequest/RequestedShipment/Ship/Seller/Contact
PersonName M AN 255 A contact name of a person who acts as
Seller

When using Commercial Invoice

template
COMMERCIAL_INVOICE_P_10 or
COMMERCIAL_INVOICE_L_10,
recommended max length is 48
characters.
CompanyName M AN 100 The company name the Seller

When using Commercial Invoice

template
COMMERCIAL_INVOICE_P_10 or
COMMERCIAL_INVOICE_L_10,
recommended max length is 47
characters.
PhoneNumber M AN 70 The contact person phone number
EmailAddress O AN 70 The email address of the contact
person.

When using Commercial Invoice

template
COMMERCIAL_INVOICE_P_10 or
COMMERCIAL_INVOICE_L_10,
recommended max length is 50
characters.
MobilePhoneNumber O AN 70 The mobile phone number of the
contact person.
ShipmentRequest/RequestedShipment/Ship/Seller/Address
StreetLines M AN 45 The street line should contain street
name and number of the Seller.
StreetName O AN 250 Seller street name should be sent as
separate attribute if feasible.
BuildingName O AN 50 The Seller building name

PAGE 151 OF 417

MYDHL API – DEVELOPER GUIDE

StreetNumber O AN 50 Seller street number should be sent as

separate attribute, if feasible.
StreetLines2 O AN 45 Seller additional address information
StreetLines3 O AN 45 Seller additional address information
City M AN 45 Seller city name
StateOrProvinceCode O AN 2 2 Letter state code for the USA only
PostalCode M AN 12 Seller postal code
CountryCode M AN 2 ISO 2 character codes of the Seller
country.
Suburb O AN 45 Seller suburb
StateOrProvinceName O AN 35 Seller State or Province Name
CountryName O AN 35 Seller Country Name
ShipmentRequest/RequestedShipment/Ship/Seller/RegistrationNumbers
ShipmentRequest/RequestedShipment/Ship/Seller/RegistrationNumbers/RegistrationNumbe
r (1:50)
Number M AN 35 Registration Number of the Seller.
NumberTypeCode M AN 3 Type of the registration number.

Possible values:

- CNP, Brazil CNPJ/CPF Federal Tax

- DAN, Deferment Account Duties Only

- DTF, Deferment Account Duties,

Taxes and Fees Only

- DUN, Data Universal Numbering

System

- EIN, Employer Identification Number

- EOR, Economic Operator Registration

ID

- FED, Federal Tax ID

- FTZ, Free Trade Zone ID

- SSN, Social Security Number

- STA, State Tax ID

- TAN, Deferment Account Tax Only

- VAT, VAT Registration (VAT / GST)

PAGE 152 OF 417

MYDHL API – DEVELOPER GUIDE

- RGP, EU Registered Exporters

Registration ID

- DLI, Driver’s License

- NID, National Identity Card

- PAS, Passport

- MID, Manufacturer ID

Not all type codes are applicable for all

countries and address types. Refer to
Appendix: Registration Number Type
Codes attached in this document for
full list of type codes, their description
and applicable issuing country and
shipping roles.
NumberIssuerCountryCode M AN 2 ISO 2 character code of the country
where the Registration Number has
been issued by.
ShipmentRequest/RequestedShipment/Ship/Seller/BankDetails
ShipmentRequest/RequestedShipment/Ship/Seller/BankDetails/BankDetail
BankName O AN To be mapped in Customs Invoice -
Russia Bank Name field
O AN To be mapped in Customs Invoice -
BankSettlementAccountNum
Russia Bank Settlement Account
berInLocalCurrency
Number in RUR field
BankSettlementAccountNum O AN To be mapped in Customs Invoice -
berInForeignCurrency Russia Bank Settlement Account
Number in USD/EUR
ShipmentRequest/RequestedShipment/Ship/Payer
BusinessPartyTypeCode O AN 2 Payer party type code

Possible values:
- BU (business)
- DC (direct consumer)
- GV (government)
- OT (other)
- PR (private)
- RE (reseller)
ShipmentRequest/RequestedShipment/Ship/Payer/Contact
PersonName M AN 255 A contact name of a person who acts as
Payer

PAGE 153 OF 417

MYDHL API – DEVELOPER GUIDE

CompanyName M AN 100 The company name the Payer

PhoneNumber M AN 70 The contact person phone number
EmailAddress O AN 70 The email address of the contact
person.
MobilePhoneNumber O AN 70 The mobile phone number of the
contact person.
ShipmentRequest/RequestedShipment/Ship/Payer/Address
StreetLines M AN 45 The street line should contain street
name and number of the Payer.
StreetName O AN 250 Payer street name should be sent as
separate attribute if feasible.
BuildingName O AN 50 The Payer building name
StreetNumber O AN 50 Payer street number should be sent as
separate attribute, if feasible.
StreetLines2 O AN 45 Payer additional address information
StreetLines3 O AN 45 Payer additional address information
City M AN 45 Payer city name
StateOrProvinceCode O AN 2 2 Letter state code for the USA only
PostalCode M AN 12 Payer postal code
CountryCode M AN 2 ISO 2 character codes of the Payer
country.
Suburb O AN 45 Payer suburb
StateOrProvinceName O AN 35 Payer State or Province Name
CountryName O AN 35 Payer Country Name
ShipmentRequest/RequestedShipment/Ship/Payer/RegistrationNumbers
ShipmentRequest/RequestedShipment/Ship/Payer/RegistrationNumbers/RegistrationNumbe
r (1:50)
Number M AN 35 Registration Number of the Payer.
NumberTypeCode M AN 3 Type of the registration number.

Possible values:

- CNP, Brazil CNPJ/CPF Federal Tax

- DAN, Deferment Account Duties Only

- DTF, Deferment Account Duties,

Taxes and Fees Only

PAGE 154 OF 417

MYDHL API – DEVELOPER GUIDE

- DUN, Data Universal Numbering

System

- EIN, Employer Identification Number

- EOR, Economic Operator Registration

ID

- FED, Federal Tax ID

- FTZ, Free Trade Zone ID

- SSN, Social Security Number

- STA, State Tax ID

- TAN, Deferment Account Tax Only

- VAT, VAT Registration (VAT / GST)

- RGP, EU Registered Exporters

Registration ID

- DLI, Driver’s License

- NID, National Identity Card

- PAS, Passport

- MID, Manufacturer ID

Not all type codes are applicable for all

countries and address types. Refer to
Appendix: Registration Number Type
Codes attached in this document for
full list of type codes, their description
and applicable issuing country and
shipping roles.
NumberIssuerCountryCode M AN 2 ISO 2 character code of the country
where the Registration Number has
been issued by.
ShipmentRequest/RequestedShipment/Ship/Payer/BankDetails
ShipmentRequest/RequestedShipment/Ship/Payer/BankDetails/BankDetail
BankName O AN To be mapped in Customs Invoice -
Russia Bank Name field
O AN To be mapped in Customs Invoice -
BankSettlementAccountNum
Russia Bank Settlement Account
berInLocalCurrency
Number in RUR field

PAGE 155 OF 417

MYDHL API – DEVELOPER GUIDE

BankSettlementAccountNum O AN To be mapped in Customs Invoice -

berInForeignCurrency Russia Bank Settlement Account
Number in USD/EUR
ShipmentRequest/RequestedShipment/Packages (1:1)
ShipmentRequest/RequestedShipment/Packages/RequestedPackages (1:999)
@number M Integer Running number of the packages.
InsuredValue O 15.3 D Insurance values of the package.
Weight M 15.3 D The weight of the package.
UseOwnPieceIdentificationNumb O A1 Y = allows you to define your own
er PieceID in the tag below

N = Auto-allocates the PieceID from

DHL Express (Default)

You can request your own Piece ID

range from your DHL Express IT
consultant and store these locally in
your integration however this is not
needed as if you leave this tag then DHL
will automatically assign the piece ID
centrally.

In addition this special function needs

to be enabled for your username by
your DHL Express IT Consultant.
PieceIdentificationNumber O AN35 You can request your own Piece ID
range from your DHL Express IT
consultant and store these locally in
your integration however this is not
needed as if you leave this tag then DHL
will automatically assign the piece ID
centrally.

If you wish to use this function then the

above tag
UseOwnPieceIdentificationNumber
needs to be set as Y
PackageContentDescription O AN70 This optional field allows you to provide
the content description on a piece level
instead of Shipment level.
ParentPieceIdentificationNumbe O AN 35 Parent (Mother) Piece ID number.
r
This field will be used to indicate the
Mother Shipment's Piece ID for linkage
purposes.

PAGE 156 OF 417

MYDHL API – DEVELOPER GUIDE

PackageTypeCode O AN 3 Package type code

Valid enumeration;
- 3BX
- 2BC
- 2BP
- CE1
- 7BX
- 6BX
- 4BX
- 2BX
- 1CE
- WB1
- WB3
- XPD
- 8BX
- 5BX
- WB6
- TBL
- TBS
- WB2
PieceIdentificationNumberDataI O AN 4 Piece Identification Number Data
dentifier Identifier

Possible Values:

“J”, “00”, “1J”, “2J”, “3J”, “4J”, “5J”, “6J”

Default: “J”

Note: Piece identification data identifier

should be same for all the pieces provided
in single shipment.

ShipmentRequest/RequestedShipment/Packages/RequestedPackages/Dimensions
Length M 10.3 D Length of the piece listed.
Width M 10.3 D Width of the piece listed.
Height M 10.3 D Height of the piece listed.
ShipmentRequest/RequestedShipment/Packages/RequestedPackages/BespokeLabelData
(BespokeLabelData is only applicable when LabelTemplate=‘ECOM26_84CI_003’)
LabelDescription M AN 80 The additional customer description
ShipmentRequest/RequestedShipment/Packages/RequestedPackages/BespokeLabelData/La
belBarcodes/LabelBarcode (1:2)
BarcodeNumber M AN 1 Barcode number

PAGE 157 OF 417

MYDHL API – DEVELOPER GUIDE

The Symbology code for this barcode is

BarcodeType O AN
128
BarcodeContent M AN Barcode content
TextBelowBarcode M AN Text below barcode
ShipmentRequest/RequestedShipment/Packages/RequestedPackages/BespokeLabelData/La
belTextEntries/LabelTextEntry (1:6)
LabelNumber M AN 1 Barcode sequence number
LabelCaption M AN 20 The caption to be printed in the tag
value
LabelDescription M AN 40 The value to be printed for the
respective tag in caption

eg. “SALES”, “50”, “CN”,” SG Regional”

ShipmentRequest/RequestedShipment/Packages/RequestedPackages/PackageReferences
(0:99)
ShipmentRequest/RequestedShipment/Packages/RequestedPackages/PackageReferences/Pa
ckageReference (0:1)
PackageReference M AN 35 Customer reference for the piece
PackageReferenceType O AN 3 Reference type code

Possible values;

- AAO, shipment reference number

of receiver
- CU, reference number of
consignor
- FF, reference number of freight
forwarder
- FN, freight bill number for <ex
works invoice number>
- IBC, inbound center reference
number
- LLR, load list reference for <10-
digit Shipment ID>
- OBC, outbound center reference
number for <SHIPMEN
IDENTIFIER (COUNTRY OF
ORIGIN)>
- PRN, pickup request number for
<BOOKING REFERENCE
NUMBER>
- ACP, local payer account number

PAGE 158 OF 417

MYDHL API – DEVELOPER GUIDE

- ACS, local shipper account

number
- ACR, local receiver account
number
- CDN, customs declaration
number
- STD, eurolog 15-digit shipment id
- CO, buyers order number
ShipmentRequest/RequestedShipment/DangerousGoods
ShipmentRequest/RequestedShipment/DangerousGoods/Content (1:99)
ContentID M AN 3 Valid DHL Express Dangerous good
content id
(please contact your DHL Express IT
representative for the relevant content
ID code if you are shipping Dangerous
Goods)
DryIceTotalNetWeight C AN 7 This is a numeric string with up to 7 char
(i.e. 1000,00 or 1000.00)
UNCode C AN Comma separated UN codes – eg.
“UN7843268473”, “7843268473,123”
ShipmentRequest/RequestedShipment/ShipmentNotifications (0:1)
ShipmentRequest/RequestedShipment/ShipmentNotifications/ShipmentNotification (0:5)
NotificationMethod M AN 5 The notification method to be sent.

Valid values; EMAIL

EmailAddress O AN 250 Email address of the party to receive

email notification.
BespokeMessage O AN 250 Additional message to be added to the
body of the mail
LanguageCode O AN 3 LanguageCode used in the email
content. The possible values are;

- eng, (Default)
- eng, British
- zho, Chinese Traditional
- chi, Chinese Simplified
LanguageCountryCode O AN 2 Language country code. The supported
country code area as below;

- CH
- GB
- US

PAGE 159 OF 417

MYDHL API – DEVELOPER GUIDE

5.4 SHIPMENTREQUEST - OUTPUT

The following diagram shows an overview of the shipment response structure. The critical
information to derive from this response are the notification codes for the response, the shipment
and piece identifiers returned, the encoded label image, and the optional pickup confirmation
reference.

PAGE 160 OF 417

MYDHL API – DEVELOPER GUIDE

5.4.1 ShipmentResponse Schema Diagram

Each of the individual sections of ShipmentResponse is shown above in schema diagram, with
context, and a detailed description of each field follows in the Output Field List.

5.4.2 ShipmentResponse Output: Notification

The Notification structure includes the result code and message, based on the results of the
processing. Successful messages will include a zero error code and no corresponding message, while
exceptions have both code and message.

5.4.3 ShipmentResponse Output: PackagesResult

The PackagesResult provides the DHL piece ID associated to each RequestedPackage from the
ShipmentRequest. In this case, the TrackingNumber is the Piece ID returned from the service. In
order to tie the RequestedPackages from the ShipmentRequest with the PackageResult in the
response, the @number attribute is used to referentially link the request and result packages.

The TrackingNumber field is the identifier for that specific piece of the shipment, of which there can
be many.

The QRCode field contains children elements ImageFormat and Image in which contains the QR code
image in base64 binary.

5.4.4 ShipmentResponse Output: LabelImage

PAGE 161 OF 417

MYDHL API – DEVELOPER GUIDE

The Label Image section of the response provides the label format in the LabelImageFormat field (i.e.
PDF), as well as the base64 encoded label image in the GraphicImage field. The HTML Image is not
used.

PAGE 162 OF 417

MYDHL API – DEVELOPER GUIDE

5.4.5 ShipmentResponse Output: Documents

The Documents section will return additional paperwork with its sub-element such as Customs
Invoice and Shipmet Receipt document. This section can return multiple documents in the response
message based on the customer input provided in the request message.

• DocumentName: The name of the document generated

• DocumentFormat: The format of the document returned. This value will be base on
the customer input provided in the request message.

• DocumentImge: The base64 image of the document.

5.4.6 ShipmentResponse Output: ShipmentIdentificationNumber

This field corresponds to the airbill number associated to this shipment. This is the primary tracking
identifier within DHL, and is the DHL primary reference field in calling application.

5.4.7 ShipmentResponse Output: DispatchConfirmationNumber

This field is the confirmation number generated by the creation of a pickup, if requested. This data
will need to be persisted if the web service consumer intends to utilize the DeleteShipment
functionality, as it is a required field.

5.4.8 ShipmentResponse Output: OnDemandDeliveryURL

This field will provide the On Demand Delivery (ODD) URL link.

PAGE 163 OF 417

MYDHL API – DEVELOPER GUIDE

5.4.9 ShipmentResponse Output: TotalNet

The TotalNet section will show total shipping charges in three currencies, BILLC, PULCL, and BASEC.
There are 3 children element under this section.

• Currency: The currency of the total charges

• Amount: The amount of the charges

• Charges: This element will breakdown the charges of the special services if customer
provides it in the request message.

PAGE 164 OF 417

MYDHL API – DEVELOPER GUIDE

5.4.10 ShipmentResponse Output: AdditionalInformation

The AdditionalInformation section is to return additional information in the create shipment response
message. MyDHL API will return this field when the request message have below input;

• RequestAdditionalInformation = Y, all additional response field will be returned in the

response message

• RequestAdditionalInformation = Y AND RequestTransliterateResponse = Y, all

additional response field will be returned and the ship field will be returned with
transliterated characters.

PAGE 165 OF 417

MYDHL API – DEVELOPER GUIDE

5.4.11 ShipmentResponse Output: BarcodeInfo

The BarcodeInfo section will be included in response when RequestBarcodeInfo = Y in request

message. This section includes several barcode fields such as the airwaybill number barcode, DHL
piece ID barcode(s), origin and destination service area code with global product code barcode, and
the DHL routing barcode.

5.4.12 ShipmentResponse Output: EstimatedDeliveryDate

The EstimatedDeliveryDate section will be included in response when

RequestEstimatedDeliveryDate = Y in request message. This section contains two fields –
EstimatedDeliveryDate and EstimatedDeliveryType. EstimatedDeliveryType can either be QDDC
or QDDF.

QDDC - constitutes DHL's service commitment as quoted at booking/shipment creation. QDDC

builds in clearance time, and potentially other special operational non-transport component(s),
when relevant.

QDDF - is the fastest ("docs") transit time as quoted to the customer at booking or shipment
creation. When clearance or any other non-transport operational component is expected to impact
transit time, QDDF does not constitute DHL's service commitment .

PAGE 166 OF 417

MYDHL API – DEVELOPER GUIDE

5.4.13 ShipmentResponse Output: PickupDetails

The PickupDetails section will include fields related to pickup capabilities. This section will include
the origin service area’s cutoff time for pickup and the pickup window hours for the given shipment
date.

PAGE 167 OF 417

MYDHL API – DEVELOPER GUIDE

5.5 SHIPMENT RESPONSE – OUTPUT FIELD LIST

Shipment Response xml fields Mandatory/ Values or

Comments
(Source) Optional Constraints
ShipmentResponse

ShipmentIdentificationNumber O AN 35 The shipment identification

number also named airwaybill
(AWB). This number can be
used to track the progress of
the shipment on the DHL
webside.
DispatchConfirmationNumber O AN 15 The booking reference number.
This number should be used
when interacting with the DHL
customer service regarding the
pickup process.
OnDemandDeliveryURL O AN The On Demand Delivery (ODD)
URL link
ShipmentResponse/Response/ServiceHeader

MessageTime M TIMESTAMP Timestamp when DHL

processed request
MessageReference O AN 36 Mapped directly from request if
provided. Merchant can track
messages by this reference

ServiceInvocationID O This element will get populate

when existing or new
customers has provided the
<Request> element in the
request message.

This information will get

populate in Response in all
Error and Success scenarios.
ShipmentResponse/Notification (1:999)

@code M N6 Error > 0 or Success Code = 0

Message M Response Message, see Error
codes for more details
ShipmentResponse/PackagesResult

ShipmentResponse/PackagesResult/PackageResult (1:999)

PAGE 168 OF 417

MYDHL API – DEVELOPER GUIDE

"@number" O Integer Running number of the

packages.
TrackingNumber M AN 35 This field contains a unique
number for the individual
package.
VolumetricWeight O 12.3 D Dimensional weight of each
piece
ShipmentResponse/PackagesResult/PackageResult/QRCode
(0:1)
ImageFormat M AN 4 Image format

e.g. PNG
Image M Base64 This field contains the actual
Binary QRCode image as Base64
binary.

ShipmentResponse/LabelImage (0:2000)

LabelImageFormat M AN 3 Mapped from Request

Document. Currently always
“PDF”
GraphicImage M Base64 This field contains the actual
Binary label as Base64 Binary. There
will be one document
containing all the labels for
each package/piece on
separate pages.
HTMLImage O Base64 Not used
Binary

ShipmentResponse/Documents

ShipmentResponse/Documents/Document (0:999)

DocumentName M AN The name of the document

DocumentFormat M AN 3 Format of the document
DocumentImage M Base64 Image of the document
binary

ShipmentResponse/TotalNet (0:3)

@type M Enumerated Type of the charge

Possible values;

- ‘BILLC’, billing currency

PAGE 169 OF 417

MYDHL API – DEVELOPER GUIDE

- ‘PULCL’, country public

rates currency
- ‘BASEC’, base currency
Currency M AN 3 Total shipping charge with tax
Amount M AN PackageCharge or the Weight
Charge
ShipmentResponse/TotalNet/Charges

ShipmentResponse/TotalNet/Charges/Charge (1:99)

ChargeType M AN Global Product Name or

Optional Special Services

ChargeAmount M AN PackageCharge or the Weight

Charge or Special Services
Charge
ShipmentResponse/AdditionalInformation
BillingCode M AN 3
VolumetricWeight O 12.3 D DimensionalWeight
DHLRoutingCode O AN Routing Code
DHLRoutingDataID O AN Routing Data ID
ServiceContentCode O AN 3 Product Content Code
DeliveryDateCode O Delivery Date Code
DeliveryTimeCode O Delivery Time Code
ShipmentResponse/AdditionalInformation/OriginServiceArea
FacilityCode O AN 3 The DHL Facility Code for the
origin
ServiceAreaCode O AN 3 The DHL Service Area Code for
the origin of the Shipment
OutboundSortCode O AN 4 Outbound Sort Code of Origin
ShipmentResponse/AdditionalInformation/DestinationServiceArea
FacilityCode O AN 3 The DHL Facility Code for the
Destination
ServiceAreaCode O AN 3 The DHL Service Area Code for
the destination of the Shipment
InboundSortCode O AN 4 Inbound Sort Code of
Destination
ShipmentResponse/AdditionalInformation/Ship

PAGE 170 OF 417

MYDHL API – DEVELOPER GUIDE

ShipmentResponse/AdditionalInformation/Ship/Shipper
ShipmentResponse/AdditionalInformation/Ship/Shipper/Contact
PersonName M AN 255 A contact name of a person who
will ship the shipment.
CompanyName M AN 100 The company name the person
is working in.
ShipmentResponse/AdditionalInformation/Ship/Shipper/Address
StreetLines M AN 45 The street line should contain
street name and number of the
shipper
StreetName O AN 250 Shipper street name should be
sent as separate attribute if
feasible.
BuildingName O AN 50 The Shipper building name
StreetNumber O AN 50 Shipper street number should
be sent as separate attribute, if
feasible.
StreetLines2 O AN 45 Shipper additional address
information
StreetLines3 O AN 45 Shipper additional address
information
City M AN 45 Shipper city name
StateOrProvinceCode O AN 2 2 Letter state code for the USA
only
PostalCode M AN 12 Shipper postal code
CountryCode M AN 2 ISO 2 character code of the
Shipper country.
Suburb O AN 45 Shipper suburb
StateOrProvinceName O AN 35 Shipper State or Province Name
CountryName O AN 35 Shipper Country Name
ShipmentResponse/AdditionalInformation/Ship/Recipient
ShipmentResponse/AdditionalInformation/Ship/Recipient/Contact
PersonName M AN 255 A contact name of a person who
will receive the shipment.
CompanyName M AN 100 The company name the person is
working in.
ShipmentResponse/AdditionalInformation/Ship/Recipient/Address
StreetLines M AN 45 The street line should contain
street name and number of the
recipient
StreetName O AN 250 Recipient street name should be
sent as separate attribute if
feasible.

PAGE 171 OF 417

MYDHL API – DEVELOPER GUIDE

BuildingName O AN 50 The Recipient building name

StreetNumber O AN 50 Recipient street number should
be sent as separate attribute, if
feasible.
StreetLines2 O AN 45 Recipient additional address
information
StreetLines3 O AN 45 Recipient additional address
information
City M AN 45 Recipient city name

StateOrProvinceCode O AN 2 2 Letter state code for the USA

only
PostalCode M AN 12 Recipient postal code
CountryCode M AN 2 ISO 2 character code of the
Recipient country.
Suburb O AN 45 Recipient suburb
StateOrProvinceName O AN 35 Recipient State or Province
Name
CountryName O AN 35 Recipient Country Name
ShipmentResponse/BarcodeInfo
ShipmentIdentificationNumber O Base64 Airwaybill number barcode
BarcodeContent Binary base64 image
OriginDestinationServiceType O Base64 Barcode base64 image of origin
BarcodeContent Binary service area code, destination
service area code and global
product code
DHLRoutingBarcodeContent O Base64 Barcode base64 image of DHL
Binary routing code
ShipmentResponse/BarcodeInfo/TrackingNumberBarcodes
ShipmentResponse/BarcodeInfo/TrackingNumberBarcodes/TrackingNumberBarcode (1:999)
@number O Integer Running number sequence of
TrackingNumberBarcode nodes
TrackingNumberBarcode M Base64 Tracking number barcodes
Content Binary base64 image for each piece in
shipment request
ShipmentResponse/EstimatedDeliveryDate
EstimatedDeliveryDate O DateTime Estimated delivery date (EDD)
EstimatedDeliveryType O Enumerated Type code of EDD

Possible values;
- QDDC, constitutes DHL's
service commitment as
quoted at
booking/shipment
creation

PAGE 172 OF 417

MYDHL API – DEVELOPER GUIDE

- QDDF, is the fastest

("docs") transit time as
quoted to the customer
at booking or shipment
creation
ShipmentResponse/PickupDetails
CutOffTime O TIME This is the cutoff time for the
service offered in the response.
This represents the latest time
(local to origin) which the
shipment can be tendered to
the courier for that service on
that day.
Example: (e.g. 2019-06-
26T17:00:00)
CutoffTimeGMT O AN Pickup cut off time in GMT

HH:MM:SS
CutoffTimeOffset O AN Pickup cut off time GMT Offset
PickupWindowEarliestTime O AN The DHL earliest time possible
for pickup
PickupWindowLatestTime O AN The DHL latest time possible for
pickup
TotalTransitDays O INTEGER The number of transit days

PickupAdditionalDays O AN This is additional transit delays

(in days) for shipment picked up
from the mentioned city or
postal area to arrival at the
service area.
DeliveryAdditionalDays O AN This is additional transit delays
(in days) for shipment delivered
to the mentioned city or postal
area following arrival at the
service area.
PickupDayOfWeek O AN Pickup day of the week number
DestinationDayOfWeek O AN Destination day of the week
number

PAGE 173 OF 417

MYDHL API – DEVELOPER GUIDE

6. SHIPMENTDELETEREQUEST

6.1 SHIPMENTDELETEREQUEST - DESCRIPTION

The ShipmentDeleteRequest Operation will allow the user to synchronously cancel a previous successful
ShipmentRequest. The underlying process for the ShipmentDeleteRequest is a cancellation of a scheduled
driver pickup, if included in the original request. Any shipment manifest data which was included in the
original ShipmentRequest will not be deleted as part of this operation, but will not become an active
shipment if the shipment label does not enter the DHL Network. If a scheduled pickup was not included in
the original ShipmentRequest (i.e. DropOffType = REGULAR_PICKUP), then it is not necessary to delete the
shipment.

6.2 SHIPMENTDELETEREQUEST - INPUT

The following diagram shows an overview of the request input structure.

Within the DeleteRequest, the ClientDetail is an optional node for reference use, and does not affect
functionality. The critical elements are the remaining nodes in the request.

The ServiceHeader element contains the header information about the request message such as
message time, message reference for tracking purpose on customer side.

The PickupDate is the day of the scheduled pickup, previously communicated as part of the
ShipmentTimestamp of the ShipmentRequest. For example, if the ShipmentTimestamp for the
successful shipment was “2010-11-30T12:30:47GMT+01:00”, then the PickupDate would be
“2010-11-30”.

The PickupCountry is the two character country code which was used in the original request.

PAGE 174 OF 417

MYDHL API – DEVELOPER GUIDE

The DispatchConfirmationNumber is the reference value which was in the original

ShipmentResponse for DispatchConfirmationNumber.

The RequestorName is a required field, but is not validated against the original ShipmentRequest.
This value is not validated against the original request, and can be defaulted if necessary.

The Reason value is an optional field, and used to indicate the reason for the cancellation. The
possible values are included in the table below. Value of 7 (“Other”) used in the absence of
transmitted data.

Reason Value

001 Package Not Ready

002 Rates Too High

003 Transit Time Too Slow

004 Take To Service Center or Drop

Box

005 Commitment Time Not Met

006 Reason Not Given

007 Other

008 Pickup Modified

PAGE 175 OF 417

MYDHL API – DEVELOPER GUIDE

6.3 SHIPMENTDELETEREQUEST – INPUT FIELD LIST

Mandatory
Value
ShipmentDeleteRequest fields /Optional constraints Comments
DeleteRequest

PickupDate M YYYY- The scheduled pickup date of the

MMDD shipment to be deleted.
PickupCountry M AN 2 The country code associated to the
origin of the shipment.
DispatchConfirmationNumber M AN 20 The confirmation number returned
from the original shipment request.
RequestorName M AN 45 The delete requestor name
Reason O AN 50 Optional reason code (see above table)
DeleteRequest/ClientDetail

sso O This field is for internal use only

plant O This field is for internal use only
DeleteRequest/Request

DeleteRequest/Request/ServiceHeader

MessageTime O TIMESTAMP Timestamp when request has been

created.

The format should be YYYYMM-

DD(T)hh:mm:ss-Time Zone

e.g.

2010-11-24T00:17:20Z

2010-11-24T00:17:20+08:00

2010-11-24T00:17:20-07:00
MessageReference O AN 36 Shipper Reference Number which is
used for tracking by merchant. The
same transaction ID will be returned as
per request if it is provided.
WebstorePlatform O AN 20 Reserved for Third Party Vendor’s
identification
WebstorePlatformVersion O AN 15 Reserved for Third Party Vendor’s
identification

PAGE 176 OF 417

MYDHL API – DEVELOPER GUIDE

ShippingSystemPlatform O AN 20 Reserved for Third Party Vendor’s

identification
ShippingSystemPlatformVersion O AN 15 Reserved for Third Party Vendor’s
identification
PlugIn O AN 20 Reserved for Third Party Vendor’s
identification
PlugInVersion O AN 15 Reserved for Third Party Vendor’s
identification

6.4 SHIPMENTDELETEREQUEST – OUTPUT

PAGE 177 OF 417

MYDHL API – DEVELOPER GUIDE

6.5 SHIPMENTDELETEREQUEST – OUTPUT FIELD LIST

ShipmentDeleteResponse Mandatory Value

fields /Optional constraints Comments

DeleteResponse

DeleteResponse/Response

DeleteResponse/Response/ServiceHeader

MessageTime M Date Timestamp when request has been

processed on DHL side.

The format should be YYYY-

MMDD(T)hh:mm:ss-Time Zone

MessageReference O AN 36 This information will get populate from

the Request message, if provided.

ServiceInvocationID M This element will get populate when

existing or new customers has provided
the <Request> element in the request
message.

This information will get populate in

Response in all Error and Success
scenarios.

DeleteResponse/Notification (1:1000)

@code M Error > 0 or Success Code = 0

Message M Response Message, see Error codes for

more details

For this service, the potential error use cases include:

• Pickup Not Found, if already deleted

• Pickup Not Found, if manually deleted otherwise
• Pickup Not Found, if still in process of creation

Please note, for the 3rd use case, there is a very small window of time between when the original
pickup request is processed and when the backend system creates the pickup (< 30 secs). During this
time, it may not be possible to delete the pickup request.

PAGE 178 OF 280

MYDHL API – DEVELOPER GUIDE

PAGE 179 OF 280

MYDHL API – DEVELOPER GUIDE

7. TRACKINGREQUEST

7.1 TRACKINGREQUEST - DESCRIPTION

The TrackingRequest operation is used to inform customers about the status of their in-transit
shipments, based on the valid DHL Waybill Number, Shipment Reference and License Plate (LP)
number. The resulting response will provide tracking events at both the Shipment and/or Piece
events corresponding to the DHL Waybill(s), LPNumber(s) and shipment reference submitted.

When presenting the results of the web service, note that the resulting piece and shipment events
should not be grouped separately. Depending on the type of event or DHL processing facility, only
piece or shipment data (or both piece and shipment) may be available. Merging the resulting Piece
and Shipment events will provide a consolidated view of the event history for the DHL Shipment.

7.1.1 TrackingRequest Schema Diagram

The following diagram details the schema diagram for the TrackingRequest, as input. There are three
options available to track the shipment, which is AWBNumber, LPNumber and ShipmentReference
with ShipperAccountNumber.

PAGE 180 OF 280

MYDHL API – DEVELOPER GUIDE

7.2 TRACKINGREQUEST - INPUT

The Request node contains a ServiceHeader structure, which describes the MessageTime and
MessageReference of the request. The Header fields are required fields for the request, used to
distinguish individual requests. The MessageReference is required to be between 28 and 32
characters in length, but is not required to be unique between requests.

7.2.1 TrackingRequest Input: LanguageCode

The LanguageCode element helps to identify the language code and provide the shipment and piece
level translation of checkpoint descriptions based on language code provided by user.

7.2.2 TrackingRequest Input: LanguageScriptCode

The LanguageScriptCode element is used to identify the language script code and provide the
shipment and piece level translation of checkpoint descriptions based on language code, language
country code (if provided) and language script code.

7.2.3 TrackingRequest Input: LanguageCountryCode

The LanguageCountryCode element is to identify the language country code and provide the
shipment and piece level translation of checkpoint descriptions based on language code and
language country code provided by user.

7.2.4 TrackingRequest Input: AWBNumber

The AWBNumber element must contain at least one element within the ArrayOfAWBNumberItem
node. The DHL Waybill element is defined at a maximum length of 11 characters; the standard DHL
Waybill used in shipping will typically be 10 digits. The AWBNumber element allows multiple DHL
Waybill numbers in a single request, as multiple Waybill requests are batched on the backend to
populate the response for multiple shipments.

7.2.5 TrackingRequest Input: LPNumber

The LPNumber element is used as input to track the shipment form the LPNumber provided in the
request message.

PAGE 181 OF 280

MYDHL API – DEVELOPER GUIDE

7.2.6 TrackingRequest Input: ReferenceQuery

The ReferenceQuery element helps to query using the Shipper‘s Reference Number, Account Number
and Shipment Date. This element is not allowed to be use along with the DHL Waybill number and
License Plate Number. There are 3 children under this element;

• ShipperAccountNumber – A mandatory element that will be used to undergo account validation

process (if needed)

• ShipmentReference – A mandatory element that have 2 children element; Value and Type that
will be used to retrieve the response with the Shipment Details and checkpoints associated with
the AccountNumber, ReferenceID and ReferenceType (if provided) in Request message.

• ShipmentDateRange – An optional element that helps to filter data based on the provided dates.
There are 2 children element; From and To.

7.2.7 TrackingRequest Input: LevelOfDetails

The LevelOfDetails element contains an enumerated value for checkpoint details requested in the
response. It is a required element in the request, applies to all shipments in the request and has the
following values.
• ALL_CHECKPOINTS, populates all the customer visible checkpoints available in the response
message.
• LAST_CHECKPOINT_ONLY, this value is used when only the last checkpoint details are required.
• ADVANCE_SHIPMENT, to support advance shipment query. When this value is used, only
shipment details information gets populated in response message. Checkpoint details are not
populated for Advance Shipment.
• BBX_CHILDREN, when the Mother AWB number is provided in the request message, the
shipment details and checkpoints of mother AWB with its children’s AWB numbers will be
returned. However, there will be no checkpoint details for the childrens AWB number provided.
• SHIPMENT_DETAILS_ONLY, only shipment details are provided in the response message. No
checkpoint details are populated.

7.2.8 TrackingRequest Input: PiecesEnabled

The PiecesEnabled element contains an enumerated value for shipment and/or piece details and
events requested in the response. It is an optional element in the request, applies to all shipments in
the request and has the following values.

• B = Both Piece and Shipment Details (recommended value) • S = Shipment Details Only
• P = Piece Details Only.

7.2.9 TrackingRequest Input: EstimatedDeliveryDateEnabled

The EstimatedDeliveryDateEnabled element indicates if estimated delivery date (EDD) should be

included in the service response (Estimated Delivery Date information is not always available).

PAGE 182 OF 417

MYDHL API – DEVELOPER GUIDE

PAGE 183 OF 417

MYDHL API – DEVELOPER GUIDE

7.3 TRACKINGREQUEST – INPUT FIELD LIST

The following table details the fields used by the TrackingRequest, their cardinality and a brief
description of their usage.
Values or
Tracking Request fields M/O Comments
Constraints
TrackingRequest
LanguageCode M/O AN 3 The language code requested by user. This
field is mandatory when
LanguageScriptCode and/or
LanguageCountryCode is provided. The
supported language code are as below;

- eng, English (Default)

- bak,
- bul, Bulgarian
- cze, Czech
- dan, Danish
- ger, German
- ewe,
- gre, Greek
- spa, Spanish
- est, Estonian
- fin, Finnish
- fre, French
- heb, Hebrew
- hrv, Croatian
- hun, Hungarian
- ind, Indonesian
- ita, Italian
- jpn, Japanese
- kor, Korean
- lit, Lithuanian
- lav, Latvian
- mac, Macedonian
- dut, Dutch
- nor, Norwegian
- pol, Polish
- por, Portuguese
- rum, Romanian
- rus, Russian
- srd,
- slo, Slovak
- slv, Slovenian
- alb, Albanian
- srp,

PAGE 184 OF 417

MYDHL API – DEVELOPER GUIDE

- swe, Swedish
- chi, Chinese
- tha, Thai
- tur, Turkish
- twi,
- ukr, Ukrainian
- ice, Icelandic
LanguageScriptCode O AN 4 The script of the language code
LanguageCountryCode O AN 2 The country code of the language
LevelOfDetails M Enumerated Checkpoint Detail Indicator.

Possible values;

- LAST_CHECKPOINT_ONLY
- ALL_CHECKPOINTS
- SHIPMENT_DETAILS_ONLY
- ADVANCE_SHIPMENT
- BBX_CHILDREN

If ReturnServicePointDetails value ‘Y’ is

included in request, then the possible
enumeration value is only
LAST_CHECKPOINT_ONLY or
ALL_CHECKPOINTS

PiecesEnabled O Enumerated Pieces Indicator.

Possible values;

- B = Both Piece and Shipment

- S = Shipment Details Only
- P = Piece Details Only.

If ReturnServicePointDetails value ‘Y’ is

included in request, then the possible
enumeration value is only B or S.
EstimatedDeliveryDateEn O Enumerated Possible values:
abled
- 1 / true, EDD requested
- 0 / false, EDD not requested
(Estimated Delivery Date is not always
returned and is subject to the scans by the
DHL Operations team)
TrackingRequest/Request

TrackingRequest/Request/ServiceHeader

PAGE 185 OF 417

MYDHL API – DEVELOPER GUIDE

MessageTime M Date The format of the should be YYYYMM-

DD(T)hh:mm:ss-Time Zone

e.g.

2010-11-24T00:17:20Z

2010-11-24T00:17:20-07:00
MessageReference M AN 32 Message reference, between 28-32
characters in length.
WebstorePlatform O AN 20 Reserved for Third Party Vendors
identification
WebstorePlatformVersio O AN 15 Reserved for Third Party Vendors
n identification
ShippingSystemPlatfor O AN 20 Reserved for Third Party Vendors
m identification
ShippingSystemPlatfor O AN 15 Reserved for Third Party Vendors
mVersion identification
PlugIn O AN 20 Reserved for Third Party Vendors
identification
PlugInVersion O AN 15 Reserved for Third Party Vendors
identification
TrackingRequest/ClientDetail

sso O This field is for internal use only

plant O This field is for internal use only
TrackingRequest/AWBNumber
(Optional)
ArrayOfAWBNumberItem M AN 11 DHL Waybill number
(1:100)
TrackingRequest/LPNumber (Optional)
ArrayOfTrackingPieceIDIt
M AN 35 DHL Piece ID
em (1:100)
TrackingRequest/ReferenceQuery (Optional)
ShipperAccountNumber M N 12 The account number of the shipper
TrackingRequest/ReferenceQuery/ShipmentReferences
ShipmentReference M AN 35 The ShipmentReference element the
shipper reference ID number.
ShipmentReferenceType O AN 3 The ReferenceType element is the shipper
reference type.

Possible value;

PAGE 186 OF 417

MYDHL API – DEVELOPER GUIDE

- CU, reference number of consignor

TrackingRequest/ReferenceQuery/ShipmentDateRange
From M Date The ShipmentDateFrom element contains
the date from which the shipment should be
queried. The format of the date should be
YYYYMM-DD.
To M Date The ShipmentDateTo element contains the
date to which the shipment should be
queried.The format of the date should be
YYYYMM-DD.

PAGE 187 OF 417

MYDHL API – DEVELOPER GUIDE

Waybill numbers to be used during Testing for Tracking

Please note that when testing the Tracking Web service, only the Waybill numbers below are loaded
and any production Waybill numbers or ones created via CreateShipment will not be trackable.

9356579890 4818240420 5584773180 5786694550 2449648740

5980622760 5980622970 5980623180 5980770460 6781059250

9077880070 5786694760 7957673080 5786696720 8066924740

PAGE 188 OF 417

MYDHL API – DEVELOPER GUIDE

7.4 TRACKINGRESPONSE - OUTPUT

The following diagram details the TrackingResponse. All successful tracking responses will conform
to this schema.

At a high level, the TrackingResponse contains a Response element and an AWBInfo element.
Within the AWBInfo element, each ArrayOfAWBInfoItem corresponds to the response for each DHL
Airbill submitted in the original request.

The remaining subsections of 7.4 will provide additional context to the structures immediately below
TrackingResponse, while the individual nodes are described in further detail in section 7.5.

7.4.1 TrackingResponse Output: Response

The Response element contains the service header information for the message. This includes the
timestamp when the response generated to the consumer, as well as the unique message reference
generated by DHL.

7.4.2 TrackingResponse Output: AWBInfo

The AWBInfo element is a complex element which maintains an array of airbill responses for each airbill
requested. The ArrayOfAWBInfoItem consists of five child elements
• AWBNumber

PAGE 189 OF 417

MYDHL API – DEVELOPER GUIDE

• TrackedBy
• Status
• ShipmentInfo
• Pieces

7.4.3 TrackingResponse Output: AWBNumber

The AWBNumber returned in the response corresponds to the DHL Airbill Number in the Tracking
Request. For multiple shipment requests, this field is used to distinguish between the multiple
responses.

7.4.4 TrackingResponse Output: TrackedBy

This is an optional element which gets populated in response message only when user performed
tracking query by License Plate Number. This is only applicable to track by Piece ID option only.

7.4.5 TrackingResponse Output: Status

The Status element consists of a summary ActionStatus field, which describes the success of the
service. Expected values for this element are “Success” and “No Shipments Found”.

The optional Condition element consists of additional error information, and is only present in the
case of an exception. Appendix A contains specific information on the values of the ConditionCode
and ConditionData returned in the case of a Not Found exception.

PAGE 190 OF 417

MYDHL API – DEVELOPER GUIDE

7.4.6 TrackingResponse Output: ShipmentInfo

The ShipmentInfo element is an optional element within the response, and will be populated for
successful invocations. This element describes the shipment details, as well as provide optional
ShipmentEvents. The ShipmentInfo element consists of the following child elements:

• OriginServiceArea – This complex element contains the Service Area code and Service Area
description for the origin of the shipment.
• DestinationServiceArea – This complex element contains the Service Area Code and Service
Area Description for the destination of the shipment.
• ShipperName – The name or title associated to the shipper.
• ShipperAccountNumber – The account number for shipping, currently not included for tracking
purposes.
• ConsigneeName – The name or title associated to the receiver.
• ShipmentDate – The date of the shipment initiation.
• Pieces – The number of pieces in the shipment.
• Weight – The weight of the shipment.
• WeightUnit – The unit of measure for shipment weight
• ServiceType – The global or network product code of the shipment.
• ShipmentDescription – The description of the shipment

PAGE 191 OF 417

MYDHL API – DEVELOPER GUIDE

• Shipper – The optional element which contains the shipper or origin city, division code, postal
code and country/region code of the shipment.
• Consignee – The optional element which contains the consignee or destination city, division
code, postal code and country/region code of the shipment.

The ShipmentEvent element is an optional complex element detailing the specific shipment events
for the entire shipment, and has a cardinality of zero to many. Each event will be detailed under the
element ArrayOfShipmentEventItem, and the events will appear in descending order by date/time.
The ArrayOfShipmentEventItem element consists of these child elements.

• Date – The date of the Shipment Event

• Time – The time of the Shipment Event (in local time)
• Service Event – The code and description of the event.
• Signatory – The signee for the shipment, if captured.
• EventRemarks- The further details of the event and next step of the shipment
• Service Area – The service area code and description where the event occurred.
The ShipmentReference element is an optional complex element detailing the reference information,
if any, available for this shipment

The EstimatedDeliveryDate is an optional element the populated the estimated delivery date (EDD).

The ArrayOfChildShipmentIdentificationNumber element is an optional element that populates the

children AWB numbers of requested Mother AWB Number.

PAGE 192 OF 417

MYDHL API – DEVELOPER GUIDE

PAGE 193 OF 417

MYDHL API – DEVELOPER GUIDE

7.4.7 TrackingResponse Output: Pieces

The following diagram details the Pieces element of ArrayOfAWBInfoItem. The Pieces element is an
optional element which contains a single complex PieceInfo element. The PieceInfo element consists
of one to many ArrayOfPieceInfoItem elements.

Within the ArrayOfPieceInfoItem element, there are two complex child elements.
• PieceDetails – This element describes attributes of the specific piece, including piece id,
dimensions and weight.
• PieceEvent – This element contains one to many events at the piece level, including a description
of the event, the date/time of the event, and the location of the event. In this sense, it is identical
in structure to the ShipmentEvent element.

PAGE 194 OF 417

MYDHL API – DEVELOPER GUIDE

7.5 TRACKINGRESPONSE – OUTPUT FIELD LIST

Mandatory Value
TrackingResponse /Optional constraints Comments
TrackingResponse/Response
TrackingResponse/Response/ServiceHeader
MessageTime M Date The format of the should be YYYY-MM-
DD(T)hh:mm:ssZ (GMT

e.g 2011-01-12T18:41:12Z
MessageReference M AN 36 The unique message reference for this response.
LanguageCode O AN 3 These elements should populate only if provided
in Request message.
LanguageScriptCode O AN 4 These elements should populate only if provided
in Request message.
LanguageCountryCod O AN 2 These elements should populate only if provided
e in Request message.
ServiceInvocationID O Token This information will get populate in Response
Message for all Error and Success scenarios.

This element will populate only when

<LevelOfDetails> element values are as listed
below:

- ALL_CHECKPOINTS
- LAST_CHECKPOINT_ONLY
- SHIPMENT_DETAILS_ONLY
- BBX_CHILDREN
- ADVANCE_SHIPMENT
TrackingResponse/AWBInfo
TrackingResponse/AWBInfo/ArrayOfAWBInfoItem (1:100)
AWBNumber M AN 11 Identifies the piece number as a counter, same as
input.
TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/TrackedBy
LPNumber M AN 35 License Plate Number
TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/Status
ActionStatus M AN 20 The summary status of the request.

Values include;

“Success”

“No Shipments Found”

TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/Status/Condition
TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/Status/Condition/ArrayOfConditionItem(1:100)
ConditionCode M N3 Error Code associated to the request e.g. 101
ConditionData O AN 50 Error Description

PAGE 195 OF 417

MYDHL API – DEVELOPER GUIDE

TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/ShipmentInfo
ShipperName M AN 45 Shipper Name
ShipperAccountNumb O AN 12 Shipper’s Account Number
er
(currently not populated for tracking)
ConsigneeName M AN 45 Receiver’s Name
ShipmentDate M Date The shipment initiation date, local to origin

YYYY-MM-DD(T)HH:MM:SS+GMT

2010-11-09T14:30:00+01:00
Pieces O N6 Number of pieces in shipment
Weight O AN 15 Weight of shipment

Format 999999999999.999
WeightUnit O AN 1 L = Pounds
K = Kilogram
G = Grams
ServiceType O AN 4 The shipping product requested for this
shipment, corresponding to the DHL Global
Product codes.
ShipmentDescription O AN The description of the shipment
EstimatedDeliveryDat O Date Estimted delivery date (EDD)
e
YYYY-MM-DD(T)HH:MM:SS+GMT

2010-11-09T14:30:00+01:00
TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/ShipmentInfo/OriginServiceArea
ServiceAreaCode O AN 3 The DHL Service Area Code for the origin of the
Shipment
Description O AN 40 The description of the Service Area Code.
OutboundSortCode O AN 4 Outbound Sort Code of Origin
(currently not available)
TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/ShipmentInfo/DestinationServiceArea
ServiceAreaCode O AN 3 The DHL Service Area Code for the destination of
the Shipment
Description O AN 40 Description
FacilityCode O AN 3 The DHL Facility Code for the Destination
InboundSortCode O AN 4 Inbound Sort Code of Destination (currently not
available)
TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/ShipmentInfo/Shipper
City O AN 35 Shipper city name

PAGE 196 OF 417

MYDHL API – DEVELOPER GUIDE

Suburb O AN 35 Shipper suburb name

StateOrProvinceCode O AN Shipper state or province code
PostalCode O AN 12 Shipper postal code
CountryCode O AN 2 ISO 2 character code of the Shipper country.
TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/ShipmentInfo/Consignee
City O AN 35 Consignee city name
Suburb O AN 35 Consignee suburb name
StateOrProvinceCode O AN Consignee state or province code
PostalCode O AN 12 Consignee postal code
CountryCode O AN 2 ISO 2 character code of the Consignee country.
TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/ShipmentInfo/ShipperReference
ReferenceID O AN 35 Reference ID for shipment
ReferenceType O AN 2 Reference Type
TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/ShipmentInfo/ArrayOfChildShipment

IdentificationNumbers
ChildShipmentIdentifi M AN 11 The children AWB numbers of requested Mother
cationNumber AWB Number
TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/ShipmentInfo/ShipmentEvent
TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/ShipmentInfo/ShipmentEvent/

ArrayOfShipmentEventItem(1:100)
Date M Date Local Date of Shipment Event
YYYY-MM-DD
Time M Time Local Time of Shipment Event
Signatory O AN 20 The signee for the shipment, only occurs for final
disposition events (such as OK event)
TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/ShipmentInfo/ShipmentEvent/

ArrayOfShipmentEventItem/ServiceEvent
EventCode M AN 2 The event code for this specific event.
Description M AN 50 The description of the event
TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/ShipmentInfo/ShipmentEvent/

ArrayOfShipmentEventItem/EventRemarks
FurtherDetails M AN The further details describe from the event
description
NextSteps M AN Explained the next step for the shipment

PAGE 197 OF 417

MYDHL API – DEVELOPER GUIDE

TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/ShipmentInfo/ShipmentEvent/

ArrayOfShipmentEventItem/ServiceArea

ServiceAreaCode O AN 3 The DHL Service Area Code for the event

Description O AN 40 The description of the service area code.
TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/Pieces
TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/Pieces/PieceInfo
TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/Pieces/PieceInfo/ArrayOfPieceInfoItem (1:100)
TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/Pieces/PieceInfo/

ArrayOfPieceInfoItem/PieceDetails
AWBNumber M AN 11 Airbill associated to the Piece (same as the parent
node airbill)
LicensePlate M AN 35 Piece ID associated to the Piece
PieceNumber O N6 Number of the Piece
ActualDepth O AN 10 Actual Depth of shipment
Format 9999999.999
ActualWidth O AN 10 Actual Width of shipment
Format 9999999.999
ActualHeight O AN 10 Actual Height of shipment
Format 9999999.999
ActualWeight O AN 15 Actual Weight of shipment
Format 999999999999.999
Depth O AN 10 Depth of shipment
Format 9999999.999
Width O AN 10 Width of shipment
Format 9999999.999
Height O AN 10 Height of shipment
Format 9999999.999
Weight O AN 15 Weight of shipment
Format 999999999999.999
PackageType O AN 3 Package Type of Shipment

DimWeight O AN 15 Volumetric Weight of shipment

Format 999999999999.999
WeightUnit O AN 1 L = Pounds
K = Kilogram
G = Grams
PieceContents O AN 70 Contents or description of the piece

PAGE 198 OF 417

MYDHL API – DEVELOPER GUIDE

TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/Pieces/PieceInfo/
ArrayOfPieceInfoItem/PieceEvent
TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/Pieces/PieceInfo/

ArrayOfPieceInfoItem/PieceEvent/ArrayOfPieceEventItem (1:100)
Date M Date Local Date of Piece Event
YYYY-MM-DD
Time M Time Local Time of Shipment Event
HH:MM:SS
Signatory O AN 20 The signee for the piece, only occurs for final
disposition events (such as OK event)
TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/Pieces/PieceInfo/ArrayOfPieceInfoItem/

PieceEvent/ArrayOfPieceEventItem/ServiceEvent
EventCode M AN 2 The event code for this specific event.
Description O AN 50 The description of the event
TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/Pieces/PieceInfo/ArrayOfPieceInfoItem/

PieceEvent/ArrayOfPieceEventItem/ServiceArea
ServiceAreaCode O AN 3 The DHL Service Area Code for the event
Description O AN 40 The description of the service area code.
TrackingResponse/AWBInfo/ArrayOfAWBInfoItem/Pieces/PieceInfo/ArrayOfPieceInfoItem/

PieceEvent/ArrayOfPieceEventItem/ShipperReference
ReferenceID O AN 35 Reference ID for shipment
ReferenceType O AN 2 Reference Type
TrackingResponse/Fault
TrackingResponse/Fault/PieceFault
TrackingResponse/Fault/PieceFault/ArrayOfPieceFaultItem (1:100)
PieceID M AN 35 License Plate Number
ConditionCode M AN Error code
ConditionData M AN Error Messsage

PAGE 199 OF 417

MYDHL API – DEVELOPER GUIDE

8. DOCUMENTRETRIEVE - EPOD

8.1 DOCUMENTRETRIEVE-EPOD - DESCRIPTION

The Document Retrieve operation will return ePOD image(s) according to how the image was
requested.

Using Waybill number as well as other shipment criteria, this operation returns the available ePOD
image including, if requested, the ePOD details.

A Document Retrieve request is successfully executed if the correct combination of account/Waybill

and image content is sent in the request.

8.2 DOCUMENTRETRIEVE-EPOD - INPUT

The following diagrams show an overview of the request input structure. It is composed of two main
structures. The header (Hdr) and the Body(Bd). The Bd contains two structures, the Shipment (Shp)
elements and the Generic Request (GenrcRq). Most of the parameters defining the image requested
are on the Shp and GenrcRq segments.
Msg

Hdr

Bd

Shp

GenrcRq

The representation of each of the individual sections of shipmentDocumentRetrieve request is below in

schema diagram, with context, and a detailed description of each field follows in the Input Field
List.

PAGE 200 OF 417

MYDHL API – DEVELOPER GUIDE

8.2.1 Header (Hdr) Schema Diagram

8.2.2 Header Input: Id

Unique identification of the request. e.g. 1234567890

8.2.3 Header Input: Ver

Mandatory: Version of the DHL canonical format. This is a constant value that should be set to 1.038.

8.2.4 Header Input: Dtm

Mandatory: Message creation date-time in the following format: 2013-04-07T23:59:59

PAGE 201 OF 417

MYDHL API – DEVELOPER GUIDE

8.2.5 Header Input: CorrId

Correlation id can be used to link a message. It is optional and it is only used in the response.

8.2.6 Header Input: Sndr

The Sndr section provides details about the message sender.

8.2.7 Sndr Input: AppCd

Mandatory: The AppCd identifies the application sending the request to the backend system. In this
case, the value should be DCG.

8.2.8 Sndr Input: AppNm

Optional: The AppNm node contains the name of the sending application.

8.2.9 Sndr Input: CmptNm

Optional: The CmptNm is the name of the component in the application that is sending the request.

PAGE 202 OF 417

MYDHL API – DEVELOPER GUIDE

8.2.10 Sndr Input: GId

Optional: General identification of the message. In this process this group is not used.

8.2.11 Header Input: Rcp.

Optional: Recipient identification. This section is only used in the response no need to use it in the
request.

PAGE 203 OF 417

MYDHL API – DEVELOPER GUIDE

8.2.12 Bd Input: Shp Schema Diagram

8.2.13 Shp Input: Id

Mandatory: Shipment identifier: an identification number assigned to a shipment, controlled by DHL.

PAGE 204 OF 417

MYDHL API – DEVELOPER GUIDE

8.2.14 Shp Input: ShpTr

The ShpTr section contains the fields related to the shipment transaction

8.2.15 ShpTr Input: PuDtm

Optional: Shipment pick-up datetime (Optional (part of Shipment Key)) The date and time when the
goods are collected from shipper. If not provided, the shipment with the most recent pickup date
matching the other search criteria is considered.

8.2.16 ShpTr Input: SCDtl

The SCDtl section contains shipment customer detail

8.2.17 SCDtl Input: AcctNo

PAGE 205 OF 417

MYDHL API – DEVELOPER GUIDE

Account Number. This is optional if requesting a summary ePOD, however it is mandatory for each
Waybill number to declare the corresponding account number.

8.2.18 SCDtl Input: CRlTyCd

Optional: If the AccNo is provided this field also should be provided. Customer role type code: It is
optional for summary ePOD but mandatory for detail ePOD. This is the code that uniquely identifies a
customer role. Values are: PY=Payer RV=Receiver SP=Shipper

8.2.19 SCDtl Input: CtryCd

/Country code: this is optional for ePOD retrieval. The country code is a two-character code that
uniquely identifies a country. The code should be aligned to the ISO (ISO 3166-1-alpha-2 code
elements) standards or in certain circumstances created by DHL. Values are e.g. BE=Belgium
FR=France XC=Curacao (Not ISO - part of Netherlands Antilles).

8.2.20 Shp Input: ShpInDoc

The ShpInDoc includes the SDoc(Shipment Documentation) section

8.2.21 ShpInDoc Input: SDoc

SDoc contains shipment in document

PAGE 206 OF 417

MYDHL API – DEVELOPER GUIDE

8.2.22 SDoc Input: DocTyCd

Mandatory: Document type code: identifies uniquely a document type. In this case POD (electronic proof
of delivery)

8.2.23 SDoc Input: Img

The Img (Image) section contains only the Img (image) field. Image of the document. Please note
that this tag is only used in this service as the place where the ePOD image is returned. Not need to
send it in the request.

8.2.24 Bd Input: GenrcRq

The Generic Request GenrcRq) contains the type and value criteria of the request.

PAGE 207 OF 417

MYDHL API – DEVELOPER GUIDE

8.2.25 GenrcRq Input: TyCd

Generic request criteria type code : There might be up to 7 instances of this element with a matching
value in the Val attribute. These are the values for each instance:

PAGE 208 OF 417

MYDHL API – DEVELOPER GUIDE

1. "IMG_CONTENT" - Mandatory. Specifies the output type for PDF rendering.

2. "IMG_FORMAT" - Mandatory. Document Format.

3. "DOC_RND_REQ" - Optional. Presentation format. If not provided the default is all documents in one
file.

4."EXT_REQ" - Optional. Specifies whether the request is done for DHL internal purpose or whether the
data is requested by a customer.

5. "DUPL_HANDL" - Optional . From a set of matching documents which have identical values in the
specified metadata fields, only one will be returned.

6. "SORT_BY" – Optional. Sort order within a group of matching documents for which only one will be
returned. The top most entry in the sort order will be returned.

7. "LANGUAGE" – Optional. Language code.

8.2.26 GenrcRq Input: Val

Generic request criteria value. One value for each TyCd.

1. IMG_CONTENT. The following values are supported: a. epod-detail-esig / epod-detail: Detailed

ePOD in letter format. b. epod-summary-esig / epod-summary: Summary ePOD in letter format. c.
epod-table-detail / epod-table-esig / epod-table: Detailed ePOD in table format. d. epod-
tablesummary: Summary ePOD in table format. PLEASE NOTE THAT ACCOUNT NUMBER MUST BE
PROVIDED TO REQUEST FOR DETAIL EPOD (a)(c). Remarks: “/” represents aliases. The output will
be the same for all aliases which are under the same category. For example, epod-detail-esig /
epoddetail will both give detailed ePOD in letter format with no difference. All the output types
above will return ePOD with eSIG (if the eSIG is available), else ePOD without eSIG will be returned.

2. IMG_FORMAT. The only possible value is PDF.

3. DOC_RND_REQ. The possible values are: true if one output file for all shipments which is the default
or false one file for each shipment.

4. EXT_REQ. The possible values are: true (default) if the purpose is customer use or false if it is for
internal purpose.

5. DUPL_HANDL. The only available and default value is CORE_WB_NO.

6. SORT_BY. The only available value "$INGEST_DATE,D".

7. Language codes are defined according to ISO 639-1 standard. Thus the 2-character code must be in
lower-case letters. e.g. en, de. If not provided en is the default.

PAGE 209 OF 417

MYDHL API – DEVELOPER GUIDE

8.3 SHIPMENTDOCUMENTRETRIEVE-EPOD – INPUT FILED LIST

Shipment
Mandatory Value
Document Comments
/Optional constraints
Retrieve fields
shipmentDocumentRetrieveReq
./MSG
./Hdr
@Id O AN 30 Request Id
@Ver O AN 7 Use always this value: 1.038
@Dtm O DateTime Format: 2013-04-07T23:59:59
@CorrId O AN 20 Correlation ID. This field is only used in the response. No
need to send in the request.
./Sndr
@AppCd M AN 5 Value: DCGAP
@AppNm O AN 20 Value: DCGAP
@CmptNm O AN 256 Your own unique system name
./Rcp This section is not used in the request, only in the response.
./Bd
./Ship(1:M)
@Id M AN 35 Shipment Id (AWB)
./ShpTr(0:M)
@PuDtm O DateTime Pickup Date-Time: We recommend not to enter the pick
up date. However, the format of the pickup date is
201201-31T00:00:00.
./SCDtl():M)
@AccNo O AN 12 Account No: optional for summary ePOD, mandatory for
detail ePOD. This includes 3 distinct request parameters:
Filter by account number of a specific type (CRlTyCd) (1.
payer - PY 2. receiver - RV 3. shipper - SP).
@CRlTyCd O AN 2 Customer role type code: This code identifies weather the
above account number was used in the Payer, Receiver or
Shipper Account field while creating the shipment.
The possible codes are PY=Payer, RV
=Receiver, SP=Shipper – You only need to specify this field
if you are requesting a detailed ePOD
@CtryCd O AN 2 Country code: this is optional for ePOD retrieval. This is the
origin country code..The country code is a twocharacter
code that uniquely identifies a country. The code should be
aligned to the ISO (ISO 3166-1-alpha-2 code elements)

PAGE 210 OF 417

MYDHL API – DEVELOPER GUIDE

standards or in certain circumstances created by DHL.

Values are e.g. BE=Belgium FR=France
XC=Curacao (Not ISO - part of Netherlands Antilles)
/ShpInDoc(1:M)

./SDoc(1:M)
@DocTyCd M AN3 Document type code: identifies uniquely
a document type. Value = POD
(electronic proof of delivery)
./GenrcRq(0:M)

@ TyCd O AN12 Generic request criteria type code :

There might be up to 7 instances of this element with a

matching value in the Val attribute. These are the values
for each instance:
1. "IMG_CONTENT" - Mandatory. Specifies the output type
for PDF rendering.
2. "IMG_FORMAT" - Mandatory. Document Format.
3. "DOC_RND_REQ" - Optional. Presentation format. If not
provided the default is all documents in one file.
4."EXT_REQ" - Optional. Specifies whether the request is
done for DHL internal purpose or whether the data is
requested by a customer.
5. "DUPL_HANDL" - Optional . From a set of matching
documents which have identical values in the specified
metadata fields, only one will be returned.
6. "SORT_BY" – Optional. Sort order within a group of
matching documents for which only one will be returned.
The top most entry in the sort order will be returned.
7. "LANGUAGE" – Optional. Language code.
@Val O AN75 Generic request criteria value. One value for each TyCd.

1. IMG_CONTENT. The following values are supported:

a. epod-detail-esig / epod-detail: Detailed ePOD in letter
format.
b. epodsummary-esig / epod-summary: Summary ePOD
in letter format.
c. epod-table-detail / epod-table-esig / epod-table:
Detailed ePOD in table format.
d. epod-table-summary: Summary ePOD in table format.

PLEASE NOTE THAT ACCOUNT NUMBER MUST BE

PROVIDED TO REQUEST FOR DETAIL EPOD (a)(c).

Remarks: “/” represents aliases. The output will be the

same for all aliases which are under the same category.
For example, epod-detail-esig / epod-detail will both give
detailed ePOD in letter format with no difference. All the

PAGE 211 OF 417

MYDHL API – DEVELOPER GUIDE

output types above will return ePOD with eSIG (if the eSIG
is available), else ePOD without eSIG will be returned.

2. IMG_FORMAT. The possible value is PDF.

3. DOC_RND_REQ. The possible values are: true if one
output file for all shipments which is the default or false
one file for each shipment.
4. EXT_REQ. The possible values are: true (default) if the
purpose is customer use or false if it is for internal
purpose.
5. DUPL_HANDL. The only available and default value is
CORE_WB_NO.
6. SORT_BY. The only available value "$INGEST_DATE,D".
7. Language codes are defined according to ISO 6391
standard. Thus the 2-character code must be in lower-case
letters. e.g. en, de. If not provided en is the default.

8.4 SHIPMENTDOCUMENTRETRIEVE-EPOD – OUTPUT

The representation of each of the individual sections of shipmentDocumentRetrieve response is
below in schema diagram, with context, and a detailed description of each field follows in the Output
Field List.

8.4.1 Header (Hdr) Schema Diagram

PAGE 212 OF 417

MYDHL API – DEVELOPER GUIDE

8.4.2 Header Output: Id

Unique identification of the response. e.g. 1234567890

8.4.3 Header Output: Ver

Version of the DHL canonical format. This is a value backend returns based on the canonical format
version used. For example 1.038.

8.4.4 Header Output: Dtm

Response’s date-time in the following format: 2013-04-07T23:59:59

PAGE 213 OF 417

MYDHL API – DEVELOPER GUIDE

8.4.5 Header Output: Sndr

The Sndr section provides details about the response sender.

8.4.6 Header Output: AppCd

The AppCd identifies the application sending the response. In this case, the value is ESB.

8.4.7 Header Output: AppNm

The AppNm node contains the name of the responding application. The value is ESB.

8.4.8 Bd Output: Shp Schema Diagram

PAGE 214 OF 417

MYDHL API – DEVELOPER GUIDE

8.4.9 Shp Output: Id

Shipment identifier: This is not returned in the response.

8.4.10 Shp Output: ShpTr

Nothing from ShpTr section is returned.

PAGE 215 OF 417

MYDHL API – DEVELOPER GUIDE

8.4.11 ShpTr Output: PuDtm

This is not returned.

8.4.12 ShpTr Outtput: SCDtl

The SCDtl section contains shipment customer detail. This is not returned.

8.4.13 SCDtl Output: AcctNo

This is not returned.

8.4.14 SCDtl Output: CRlTyCd

This is not returned.

PAGE 216 OF 417

MYDHL API – DEVELOPER GUIDE

8.4.15 SCDtl Output: CtryCd

This is not returned.

8.4.16 Shp Output: ShpInDoc

The ShpInDoc includes the SDoc(Shipment Documentation) section

8.4.17 ShpInDoc Output: SDoc

SDoc contains shipment in document

8.4.18 SDoc Output: DocTyCd

Document type code: Value returned is POD.

8.4.19 SDoc Output: Img

The Img (Image) section contains only the Img (image) field. Image of the document returned in a
base64 encoded string. It also returns the ImgMimeTy with value = application/pdf

PAGE 217 OF 417

MYDHL API – DEVELOPER GUIDE

8.4.20 SDoc Output: ImgMimeTy

Image mime type : Specifies MIME type of Image. In this case the value is application/pdf.

8.4.21 DatTrErr Output

The DatTrErr is where any messages generated during the process of the request are returned.

PAGE 218 OF 417

MYDHL API – DEVELOPER GUIDE

8.4.22 OrgHdr Output: Service

Even though this section has four attributes (Id, Ver, Dtm, and CorrId) and blocks Sndr and Rcp defined,
the first three attributes return with null values. Only CorrId is returned.

8.4.23 OrgHdr Output: CorrId

Correlation Message identification (Referenced to ID). In this case a unique number is returned(e.g.:
72563197).

8.4.24 OrgHdr Output: Sndr

Sndr only returns fields AppNm and CmptNm with values “ESB” and “ESB”

PAGE 219 OF 417

MYDHL API – DEVELOPER GUIDE

8.4.25 OrgHdr Output: Rcp

Rcp returns only AppNm and CmptNm with values “DCG” and “DCG”.

8.4.26 Rp Output

This section returns information about the backend service operation that processed the request. The
below three attributes are returned.

8.4.27 Rp Output: AppCd

Backend returns a null value in this field.

PAGE 220 OF 417

MYDHL API – DEVELOPER GUIDE

8.4.28 Rp Output: AppNm

Backend does not return this field.

8.4.29 Rp Output: CmptNm

Backend returns the name of the operation that processed the ePOD request. It will always be the value
“DocumentManagement.ShipmentDocumentRetrieveProvider”.

8.4.30 Rp Output:GId

General identification of the message. This is optional and might return two attributes: Id which is the
message identification value and IdTp, which is the identification type.

8.4.31 DatTrErr Output: ErrMsgGI

The error message general info (ErrMsgGI) returns attributes that provide information about
messages generated by backend. For this service only returns three attributes: Ty, Pri, and Sev. Only
those three attributes will be described below.

8.4.32 ErrMsgGI Output: Ty

Error message type identifier. The value will always be “CF”.

PAGE 221 OF 417

MYDHL API – DEVELOPER GUIDE

8.4.33 ErrMsgGI Output: Pri

Priority defines the importance of the event. The backend operation will return a value of 2 for ePOD
retrieval.

8.4.34 ErrMsgGI Output: Sev

Severity: the perceived severity of the status the event is describing with respect to the application that
reports the event.

8.4.35 DatTrErr Output: TfErrMsg

Transfer Error Message (TfErrMsg) returns any errors related to the transfer of the message.

8.4.36 TfErrMsgOutput: ErrMsgDtl

This structure display the details of the error related to the transfer of the message. Usually Backend
returns only MsgClgd and Dsc.

8.4.37 ErrMsgDtl Output:MsgClgd

The identifier for the error message. For example 100002.

PAGE 222 OF 417

MYDHL API – DEVELOPER GUIDE

8.4.38 ErrMsgDtl Output:MsgClg

The message name regarding the identifier MsgClgd

8.4.39 ErrMsgDtl Output:Dsc The

error message description

8.4.40 ErrMsgDtl Output: DtlDsc

Additional details about the error message.

8.4.41 DatTrErr Output: DatErrMsg

Data Error Message (DatErrMsg). Information about errors related to data.

8.4.42 DatErrMsg Output:ErrMsgDtl

This structure display the details of the error related to the message data. Usually backend returns only
MsgClgd and Dsc.

8.4.43 ErrMsgDtl Output:MsgClgd

The identifier for the error message. For example 100002.

PAGE 223 OF 417

MYDHL API – DEVELOPER GUIDE

8.4.44 ErrMsgDtl Output:MsgClg

The message name regarding the identifier MsgClgd

8.4.45 ErrMsgDtl Output:Dsc The

error message description

8.4.46 ErrMsgDtl Output: DtlDsc

Additional details about the error message.

8.4.47 DatErrMsg Output:BOErr

Backend returns error messages when mandatory fields are missing. The error message will be in the
section FldErr.

8.4.48 BOErr Output: FldErr

Errors related to mandatory missing fields:

PAGE 224 OF 417

MYDHL API – DEVELOPER GUIDE

8.4.49 FldErr Output: FldId

This structure returns FldXPth with the Xpath of the field that is missing, for example: <FldId
FldXPth="/ns:MSG/Bd/Shp/ShpInDoc/Sdoc@DocTyCd"/>

8.4.50 FldErr Output: ErrMsgDtl

ErrMsgDtl returns the field Dsc with the description of the missing field, for example: <ErrMsgDtl
Dsc="DocTyCd is not set"/>

PAGE 225 OF 417

MYDHL API – DEVELOPER GUIDE

8.5 DOCUMENTRETRIEVE-EPOD – OUTPUT FIELD LIST

Shipment
Mandatory Value
Document Comments
/Optional constraints
Retrieve fields
shipmentDocumentRetrieveResp
./MSG
./Hdr
@Id M AN 30 Response Id
@Ver M AN 7 Version of the response schema used: e.g.: 1.038
@Dtm M DateTime Date-time when the response was created. Format: 2013-
04-07T23:59:59
./Sndr
@AppCd M AN 5 Value: ESB
@AppNm O AN 20 Possible values ESB
@CmptNm O AN 256 This field is not returned.
./Bd
./Ship(1:M)
@Id M AN 35 Shipment Id (AWB). Even though it is defined as mandatory
in the schema, the field is returned with an empty value.
./ShpTr(0:M) Nothing from this section is returned
@PuDtm O DateTime Pickup Date-Time (Not returned)
./SCDtl():M)
@AccNo O AN 12 Account No: optional for summary ePOD, mandatory for
detail ePOD. This includes 3 distinct request parameters:
Filter by account number of a specific type (CRlTyCd) (1.
payer - PY 2. receiver - RV 3. shipper - SP). (NOT
RETURNED)
@CRlTyCd O AN 2 Customer role type code: a code that uniquely identifies a
customer role.
Values are:
PY=Payer
RV=Receiver
SP=Shipper. (NOT RETURNED)
@CtryCd O AN 2 Country code: this is optional for ePOD retrieval. The
country code is a two-character code that uniquely
identifies a country. The code should be aligned to the ISO
(ISO 3166-1alpha-2 code elements) standards or in certain
circumstances created by DHL.
Values are e.g.
BE=Belgium
FR=France

PAGE 226 OF 417

MYDHL API – DEVELOPER GUIDE

XC=Curacao (Not ISO - part of Netherlands Antilles) (NOT

RETURNED)

./ShpInDoc(1:M)
./SDoc(1:M)
@DocTyCd M AN 3 Document type code: Value returned: POD (electronic proof
of delivery)
./Img (0:M)
@Img O Base64Binary Base64 encoded image
./DatTrErr(0:M)
./OrgHdr(0:1)
@Id M AN 20 Unique identifier of the response. In this case the field is
returned with an empty value
@Ver M AN 7 Version schema format. Service returns null value in this
field.
@Dtm M DateTime Response creation date-time. Service returns null value in
this field.
./Sndr(0:1) The service does not return anything from this section
@AppCd M AN 5 This field is not returned.
@AppNm O AN 20 This field is not returned.
@CmptNm O AN 256 This field is not returned.
./Rp(0:1)
@AppCd M AN 5 The service returns a null value in this field.
@AppNm O AN 20 The service does not return this field.
@CmptNm O AN 256 The service returns value
“DocumentManagement.ShipmentDocu
mentRetrieveProvider”
./ErrMsgGI(0:1) Only 3 fields from this section sometimes are returned
@Ty O AN 20 Error message type identifier: e.g.:CF
@Pri O NUMBER Priority:e.g.:2
@Sev O NUMBER Severity: e.g.: 10
./TfErrMsg(0:M)
./ErrMsgDtl(0:1)

@ MsgCIgd O AN 128 Error message identifier. For example: 100000

@ MsgClg O AN 128 The message name regarding the identifier MsgClgd. For
example: IPESB
@Dsc O AN 128 The error message description.
@ DtlDsc O AN 128 Additional details about the error message.
./ DatErrMsg(0:M)

./ErrMsgDtl(0:1)

@ MsgCIgd O AN 128 Error message identifier. For example: 100000

@ MsgClg O AN 128 The message name regarding the identifier MsgClgd. For
example: IPESB
@Dsc O AN 128 The error message description.

PAGE 227 OF 417

MYDHL API – DEVELOPER GUIDE

@ DtlDsc O AN 128 Additional details about the error message.

./ BOErr (0:1)

./FldErr(0:M)

./FldId(0:1)
@ FldXPth O AN 512 This structure returns FldXPth with the Xpath of the field
that is missing, for example: <FldId
FldXPth="/ns:MSG/Bd/Shp/ShpInDoc/Sd oc@DocTyCd"/>
./ErrMsgDtl(0:1)

@ Dsc O AN 128 ErrMsgDtl returns the field Dsc with the description of the
missing field, for example: <ErrMsgDtl Dsc="DocTyCd is
not set"/>

9. UPDATESHIPMENT

9.1 UPDATESHIPMENT - DESCRIPTION

The updateShipment request allows for additional pieces to be added to a previously created
shipment that has not been picked up by DHL Express/had a scan against it. As an example a shipment
was created for customer A in the morning however 2 hours later customer A has ordered something
else and instead of creating two independent shipments to Customer A, you can use the
updateShipment service to search for your previous shipment and add the additional pieces to it.

The updateShipment request also allows for upload and reupload of PLT images to a previously
created shipment. The PLT images for the shipment can be uploaded before the shipment has been
physically collected by DHL courier.However, the original shipment must contain WY as the special
service otherwise, an error will be returned when the customer wants to use the reupload function in
this updateShipment service.

PAGE 228 OF 417

MYDHL API – DEVELOPER GUIDE

As an output you will receive either the additional transport labels only or you can request all the
labels to be printed – this allows flexibility based on your operational processes when labelling the
parcels.

IMPORTANT: Please note that at least 10mins must be given between the initial createShipment
request and then the updateShipment request (including subsequent updateShipment request). This
is to ensure that the shipment data has propagated into the DHL Operations backend and that MyDHL
API retrieves the current number of pieces back to provide an operationally correct Transport Label.

PAGE 229 OF 417

MYDHL API – DEVELOPER GUIDE

9.2 UPDATESHIPMENT - INPUT

The following diagram shows an overview of the request input structure.

9.2.1 updateShipment Schema Diagram

Each of the individual sections of updateShipment is shown below in schema diagram, with context,
and a detailed description of each field follows in the Input Field List.

PAGE 230 OF 417

MYDHL API – DEVELOPER GUIDE

9.2.2 updateShipment Input: ShipmentInfo

The ShipmentInfo section are in essence the search parameters of the previously created shipment
in DHL’s database to be able to add the additional packages that will be declared in the segment
below. The search criteria is by providing the Account number used (this is either from the Account
tag or the Billing section Account in the original ShipmentRequest service), the ServiceType
(product), Shipment Date (based on ShipTimestamp, format YYYY-mm-dd) and the
ShipmentIdentificationNumber (Waybill).

In addition you can optionally define the label/archive template and label type in the request. To give
full operational flexibility you can decide whether you wish to print all labels including the previous
generated ones or only the new additional labels for the additional pieces that are being added.

PAGE 231 OF 417

MYDHL API – DEVELOPER GUIDE

9.2.3 updateShipment Input: DocumentImages

The DocumentImages section is to provide customers the option to upload PLT images. This element
enable customers to upload multiple PLT images. If this DocumentImages section and the Packages
section is both provided in the request message, an error will be returned. Both of this field must be
used separately.

There are 3 children element under this section.

• DocumentImageType – the type of document image uploaded, the default value for this field
is ‘INV’

• DocumentImage – the image of the document

• DocumentImageFormat – the format of the document image

If the DocumentImages section and the Packages section is both provided in the request message, an
error will be returned. This

9.2.4 updateShipment Input: RequestWaybillDocument

The RequestWaybillDocument element provide option to the customer to print or not to print the
waybill document. The default value of this field is N, which is only print the waybill document for all
dutiable shipment. If the value is set to Y, MyDHL API will print for waybill document for all
shipments including non-dutiable and dutiable shipment.

• If the shipment is Dutiable, and RequestWaybillDocument is not provided in request, the

default will be print the waybill document

• If the shipment is Non-Dutiable, and RequestWaybillDocument is not provided in request,

the default will be NOT printing the waybill document.

• If RequestWaybillDocument is set as N, the waybill document is not printed.

PAGE 232 OF 417

MYDHL API – DEVELOPER GUIDE

9.2.5 updateShipment Input: DetachOptions

DetachOption section is to provide the customer flexibility on the label files received in response. There
are 2 children element under this section.

• SplitTransportLabelAndWaybillDocument – the default value is N where both transport

label and waybill document are in single file. If the value is set as Y, the transport label and
waybill document will be provided as separate PDF/thermal files in the response.

• SplitLabelsByPieces – the default value is N, where piece labels will be in a single file. If the
value is set as Y, the transport label will be separated as one file per piece.

9.2.6 updateShipment Input: Packages

The Packages section details the contents of individual pieces (or discrete shipping containers) within
the shipment. The minimum number of packages or pieces in a shipment is one and the upper limit
is 99. If this Packages section and the DocumentImages section is both provided in the request
message, an error will be returned. Both of this field must be used separately.

The Weight and Dimensions fields represent the weight and dims of the individual pieces.

PAGE 233 OF 417

MYDHL API – DEVELOPER GUIDE

9.3 UPDATE SHIPMENT REQUEST – INPUT FIELD LIST

Update Shipment Request Values or

M/O Comments
fields Constrains
UpdateRequest

UpdateRequest/ClientDetail

sso O This field is for internal use only

plant O This field is for internal use only
UpdateRequest/Request

UpdateRequest/Request/ServiceHeader

MessageTime O Timestamp Format:

YYYY-MM-DD(T)hh:mm:ss-Time
Zone
MessageReference O AN 36 Message reference, between 28 to 36
characters in length.
WebstorePlatform O AN 20 Reserved for Third Party Vendors identification
WebstorePlatformVersion O AN 15 Reserved for Third Party Vendors identification
ShippingSystemPlatform O AN 20 Reserved for Third Party Vendors identification
ShippingSystemPlatformVer O AN 15
Reserved for Third Party Vendors identification
sion
PlugIn O AN 20 Reserved for Third Party Vendors identification
PlugInVersion O AN 15 Reserved for Third Party Vendors identification
UpdateRequest/UpdatedShipment

OriginalShipDate M YYYY-mm- Has to match with

dd ShipmentTimestamp from createShipment
(only the date part)

Example (2017-11-15)
UpdateRequest/UpdatedShipment/ShipmentInfo

ServiceType M AN 6 The shipping product requested for this

shipment, corresponding to the DHL Global
Product codes.
Account M/O AN 12 The customer account to be used as payer in the
request. If the <Account> tag is used then there
is no need to populate the Billing section further
down below in this table as the <Account> tag
will override any other accounts entered.

PAGE 234 OF 417

MYDHL API – DEVELOPER GUIDE

However if you do wish to charge your shipment

to a third party or receiver then please leave the
ACCOUNT section out and populate the Billing
section below

ShipmentIdentificationNumb M Token Please provide the Shipment Identification

er Number (Waybill) of the shipment you wish to
update.
LabelType O AN 3 Possible values:

- PDF
- ZPL - EPL
- LP2
LabelTemplate O AN 20 Any valid DHL Express label template (please
contact your DHL Express IT representative for a
list of labels) – If this node is left blank then the
default DHL ecommerce label template will be
used.
ArchiveLabelTemplate O AN 20 Any valid DHL Express archive label template
(please contact your DHL Express IT
representative for a list of labels) – If this node is
left blank then the default DHL ecommerce label
template will be used.
IncludePreviousPieceLabels O AN1 Y or 1= All previously
pieces/packages will be included when the label
image is returned

N or 0 = The previous pieces/packages will not

be included when the label image is returned –
only the new pieces will be provided

This field is mandatory if < Packages> is provided

in the request.

UpdateRequest/UpdatedShipment/ShipmentInfo/Billing
ShipperAccountNumber M AN 12 The DHL account number used for the shipment.
Used as the shipper account number. Please
note if you use this billing section then the above
<Account> tag is not needed.
<ShipperAccountNumber> is mandatory then.

Please note if you did declare the <Account>

section above then the account number within
will overwrite the entire Billing section.
ShippingPaymentType M AN 1 Possible values:
- S (use ShipperAccountNumber as payer)
- R (use BillingAccountNumber as bill-to receiver
account number)
- T (use BillingAccountNumber as bill-to third
party account number) Please note if you use
value R or T in this tag then the next tag

PAGE 235 OF 417

MYDHL API – DEVELOPER GUIDE

<BillingAccountNumber> is also mandatory

BillingAccountNumber O AN 12 The DHL account number used for the shipment,
if
ShippingPaymentType is equal to R or T.
UpdateRequest/UpdatedShipment/ShipmentInfo/DocumentImages
UpdateRequest/UpdatedShipment/ShipmentInfo/DocumentImages/DocumentImage
(0:999)
DocumentImageType O AN 3 Possible values;
- INV, Invoice
- PNV, Proforma
- COO, Certificate of Origin
- NAF, Nafta Certificate of Origin
- CIN, Commercial Invoice
- DCL, Custom Declaration
- AWB, Air Waybill and Waybill
Document
DocumentImage M Base64 The document image

Maximum size: 2 MB
DocumentImageFormat O AN 5 Possible values;
- PDF
- PNG
- TIFF
- GIF
- JPEG
UpdateRequest/UpdatedShipment/ShipmentInfo/LabelOptions
PrinterDPI O “200” , Resolution for X-axis and Y-axis (in DPI) for
“300” transport label and waybill document output
HideAccountInWaybillDocum O AN 1 Hide account number in waybill document.
ent Possible values :
- ‘Y’, account number will NOT be printed on the
label
- ‘N’, account number will be printed on the label
(Default)
RequestWaybillDocument O AN 1 Possible values :
- ‘Y’, waybill document will be returned in
shipment response
- ‘N’, waybill document will NOT be returned in
shipment response (Default)
NumberOfWaybillDocCopies O INT 2 Number of copies of Waybill document printout
to be generated and returned in shipment
response
UpdateRequest/UpdatedShipment/ShipmentInfo/LabelOptions/CustomerLogo
LogoImage M Base64 The customer logo image
LogoImageFormat Possible values;

Enumerate - PNG
M d - GIF

PAGE 236 OF 417

MYDHL API – DEVELOPER GUIDE

- JPEG
- JPG

Maximum size: 1 MB
UpdateRequest/UpdatedShipment/ShipmentInfo/LabelOptions/CustomerBarcode
(CustomerBarcode is only applicable when LabelTemplate=‘ECOM26_84CI_002’)
BarcodeType O N/A The customer barcode type. The first barcode
code type valid value is 93, 39 or 128.
BarcodeContent O AN Customer barcode code content
TextBelowBarcode M/O AN Customer barcode text below the barcode. This
field is mandatory if BarcodeType is provided.
UpdateRequest/UpdatedShipment/ShipmentInfo/LabelOptions/DetachOptions

SplitTransportLabelAndWayb O AN 1 Single PDF or thermal output file consists of

illD ocument Transport Label and single PDF or thermal
output file for Waybill Document

Possible values;

- Y, Transport Label and Waybill Document is

printed in separate PDF or thermal output file.
- N, Transport Label and Waybill Document is
printed in a single PDF or thermal output file.
(Default).
SplitLabelByPieces O AN 1 Single PDF or thermal output file for each pieces
in Transport Label, and Single PDF or thermal
output file for Waybill Document.

Possible values;

- Y, the transport label will be separated as one

file per piece.
- N, piece labels will be in a single file. (Default)
UpdateRequest/UpdatedShipment/Packages
UpdateRequest/UpdatedShipment/Packages/RequestedPackages (1:99)
@number M Integer Running number of the packages.
Weight M 15.3 D The weight of the package.
UseOwnPieceIdentificationNu O AN 1 Y = allows you to define your own PieceID in the
mb er tag below

N = Auto-allocates the PieceID from DHL Express

You can request your own Piece ID range from

your DHL Express IT consultant and store these
locally in your integration however this is not
needed as if you leave this tag then DHL will
automatically assign the piece ID centrally.

In addition this special function needs to be

enabled for your username by your DHL Express
IT Consultant.

PAGE 237 OF 417

MYDHL API – DEVELOPER GUIDE

PieceIdentificationNumber O AN35 You can request your own Piece ID range from
your DHL Express IT consultant and store these
locally in your integration however this is not
needed as if you leave this tag then DHL will
automatically assign the piece ID centrally.
If you wish to use this function then the above tag
UseOwnPieceIdentificationNumber needs to be
set as Y or 1
PackageContentDescription O AN70 This optional field allows you to provide the
content description on a piece level instead of
Shipment level.
CustomerReferences O AN 35 Customer Reference for the piece.
CustomerReferenceType O AN 3 Piece Reference Type

PackageTypeCode O AN 3 Global Package Type

Valid enumeration;

- 3BX
- 2BC
- 2BP
- CE1 - 7BX - 6BX - 4BX - 2BX - 1CE
- WB1
- WB3
- XPD
- 8BX - 5BX
- WB6
- TBL
- TBS
- WB2
PieceIdentificationNumberDa O AN 4 Piece Identification Number Data Identifier
taIdentifier
Possible Values:

“J”, “00”, “1J”, “2J”, “3J”, “4J”, “5J”, “6J”

Default: “J”

Note: Piece identification data identifier should be

same for all the pieces provided in single shipment.

UpdateRequest/UpdatedShipment/Packages/RequestedPackages/Dimensions
Length M 10.3 D Length of the piece listed.

Width M 10.3 D Width of the piece listed.

Height M 10.3D Height of the piece listed.

PAGE 238 OF 417

MYDHL API – DEVELOPER GUIDE

9.4 UPDATESHIPMENT - OUTPUT

The following diagram shows an overview of the shipment response structure. The critical
information to derive from this response are the notification codes for the response, the shipment
and piece identifiers returned and the encoded label image.

9.4.1 updateShipmentResponse Schema Diagram

Each of the individual sections of ShipmentResponse is shown below in schema diagram, with context,
and a detailed description of each field follows in the Output Field List.

9.4.2 updateShipmentResponse Output: ServiceHeader

The ServiceHeader structure includes MessageReference which is taken from the request as well as
MessageTime showing when the request has been processed on DHL side. This is only available in
response when Request/ServiceHeader is present in request.

PAGE 239 OF 417

MYDHL API – DEVELOPER GUIDE

9.4.3 updateShipmentResponse Output: Notification

The Notification structure includes the result code and message, based on the results of the
processing. Successful messages will include a zero error code and no corresponding message, while
exceptions have both code and message.

9.4.4 updateShipmentResponse Output: Warning

The Warning structure includes the warning code and message, based on the results of the
processing. This structure doesn’t return at exceptions.

9.4.5 updateShipmentResponse Output: PackagesResult

The PackagesResult provides the DHL piece ID associated to each RequestedPackage from the
ShipmentRequest. In this case, the TrackingNumber is the Piece ID returned from the service. In
order to tie the RequestedPackages from the ShipmentRequest with the PackageResult in the
response, the @number attribute is used to referentially link the request and result packages.

The TrackingNumber field is the identifier for that specific piece of the shipment, of which there can be
many.

9.4.6 updateShipmentResponse Output: LabelImage

The Label Image section of the response provides the label format in the LabelImageFormat field (i.e.
PDF), as well as the base64 encoded label image in the GraphicImage field. The HTML Image is not
used.

PAGE 240 OF 417

MYDHL API – DEVELOPER GUIDE

9.4.7 updateShipmentResponse Output: ShipmentIdentificationNumber

This field corresponds to the airbill number associated to this shipment. This is the primary tracking
identifier within DHL, and is the DHL primary reference field in calling application.

9.5 UPDATE SHIPMENT RESPONSE – OUTPUT FIELD LIST

Shipment Response xml fields Mandatory/ Values or

Comments
(Source) Optional Constraints
UpdateResponse
ShipmentIdentificationNumber O AN 35 The shipment identification number
also named airwaybill
(AWB). This number can be used to
track the progress of the shipment on
the DHL webside.
UpdateResponse/Response
UpdateResponse/Response/ServiceHeader
MessageTime M TIMESTAMP The format of the should be
YYYY-MM-DD(T)hh:mm:ssZ (GMT

e.g 2011-01-12T18:41:12Z
MessageReference O AN 36 MessageReference as send from
request message
ServiceInvocationID M Format:
ServiceInvocationID =
MyDHLAPIProcessingStartDate
timeGMT_MyDHLAPINodeIdO
bfuscated_GuidV4
UpdateResponse/Notification (1:999)
@code O N6 Error > 0 or Success Code = 0
Message M AN Response Message, see Error codes for
more details
UpdateResponse/Warning (0:999)

PAGE 241 OF 417

MYDHL API – DEVELOPER GUIDE

@code O N6 Warning Code > 0

Message M AN Warning Response Message
UpdateResponse/PackagesResult
UpdateResponse/PackagesResult/PackageResult (1:999)
"@number" O Integer Running number of the packages.
TrackingNumber M AN 35 This field contains a unique number for
the individual package.
UpdateResponse/LabelImage (0:2000)
LabelImageFormat M AN 3 Mapped from Request
Document. Currently always “PDF”
GraphicImage M Base64 This field contains the actual label as
Binary Base64 Binary. There will be one
document
containing all the labels for each
package/piece on separate pages.
HTMLImage O Base64 Not used
Binary

10. REQUESTPICKUP

10.1 REQUESTPICKUP - DESCRIPTION

The RequestPickUp request allows users to request standalone pickup requests for local and
remote/import pickups. This can be used independently to the other services and sends a pickup
booking pickup request to the DHL Express Customer Services systems which forward the request to
the DHL Express courier systems for a courier allocation.

Remote Booking feature

You can request Remote Booking via MyDHL API. When BookingRequestor section is provided and
Country Code is different to the Country Code specified under Shipper section then booking is marked
as “Remote” under CSV. If the BookingRequestor section exists but the Shipper Country Code and
Booking Requestor Country Code is the same, then error message will be send to the customer.

10.2 REQUESTPICKUP - INPUT

The following diagram shows an overview of the request input structure.

PAGE 242 OF 417

MYDHL API – DEVELOPER GUIDE

10.2.1 RequestPickUp Schema Diagram

Each of the individual sections of RequestPickUp is shown below in schema diagram, with context, and
a detailed description of each field follows in the Input Field List.

10.2.2 RequestPickUp Input: ClientDetail

Within the RequestPickUp Service, the ClientDetail is an optional node for reference use, and does not
affect functionality.

10.2.3 RequestPickUp Input: Request

Optional section to populate information used to identify customer request for troubleshooting or
tracking. DHL Express recommends that this information is provided.

PAGE 243 OF 417

MYDHL API – DEVELOPER GUIDE

10.2.3 RequestPickUp Input: PickupShipment

The root of the RequestPickUp holds the shipment details, pickup time stamp, optional pickup location
close time, special pickup instructions, remarks, pickup location (i.e. front door, reception etc.) and
pickup location type. The mandatory elements ShipmentDetails, PickupTimestamp, Billing, and Ship
are required for requesting a pickup.

10.2.3.1 RequestPickUp Input: ShipmentDetails

The ShipmentDetails section contains the ServiceType (Global Product Code ex. “P” for Express
Worldwide), LocalServiceType (Local Product Code), SpecialServices (Special Service Code ex. “II” for
Shipment Insurance), the UnitOfMeasurement (SI or SU), and Content (Documents/Non_Documents),
ShipmentIdentificationNumber (Waybill), NumberOfPieces, ShipmentWeight, DeclaredValue,
DeclaredValueCurrencyCode and Packages that is applicable to the pickup.

PAGE 244 OF 417

MYDHL API – DEVELOPER GUIDE

- ServiceType - The shipping product requested for this shipment, corresponding to the DHL
Global Product codes.

- LocalServiceType - DHL “local / country specific” Product Code used to ship the items.
Important when shipping domestic products – please consult your DHL Express IT consultant if
needed.

- SpecialServices – The SpecialServices section communicates additional shipping services, such

as Insurance (or Shipment Value Protection). For example, to support Insurance, the ServiceType
would have a value of ‘II’, with the ServiceValue and CurrencyCode containing the insured value and
currency, respectively. Please note that for all other Value Added Service like Saturday Delivery,
Dangerous goods etc you do not need to declare the service charge and currency.

PAGE 245 OF 417

MYDHL API – DEVELOPER GUIDE

- UnitOfMeasurement – The UnitOfMeasurement node conveys the unit of measurements

used in the operation. This single value corresponds to the units of weight and measurement used
throughout the message processing. The value of ‘SI’ corresponds to KG and CM, respectively, while
the value of ‘SU’ corresponds to LB and IN, respectively.

An error message will be thrown if UnitOfMeasurement is missing in RequestPickUp.

- Content - The Content field details whether a shipment is non-dutiable (value DOCUMENTS)
or dutiable (NON_DOCUMENTS). Depending on the nature of the contents of the shipment, is
customs duties are applicable, different products may be offered by the DHL web services.

- ShipmentIdentificationNumber - This field corresponds to the waybill number associated to

this shipment.

- NumberOfPieces – The number of pieces in the shipment.

PAGE 246 OF 417

MYDHL API – DEVELOPER GUIDE

- ShipmentWeight – The total weight of the Shipment.

- DeclaredValue – The declared amount for the Shipment.

- DeclaredValueCurrencyCode - The currency code of the declared value for shipment.

PAGE 247 OF 417

MYDHL API – DEVELOPER GUIDE

- Packages – The Packages section details the contents of individual pieces (or discrete
shipping containers) within the shipment. The minimum number of packages or pieces in a
shipment is one and the upper limit is 999. The Weight and Dimensions fields represent the weight
and dimensions of the individual pieces. The CustomerReferences field is used as the Piece
Reference.

An error message will be thrown to customer if Packages is missing. At least one piece details is
required for booking request.

10.2.3.2 RequestPickUp Input: PickupShipment - PickupTimestamp - The provided

PickupTimestamp in the request message will be validated to ensure the format of provided timestamp is
valid. Also, pick up date cannot be in the past or more than 28 days in future. Sample - “2017-10-
12T17:30:00GMT+00:00”.
An error message will be thrown to customer if provided pickup date is more than 28 days.

10.2.3.3 RequestPickUp Input: PickupShipment - PickupLocationCloseTime - When the pickup

location close time is provided in the request message, the close time will be validated against the pickup
timestamp. If the pickup time is later than provided close time, an error message will be thrown.

10.2.3.4 RequestPickUp Input: PickupShipment - SpecialPickupInstructions - any special

instructions you wish to send to the courier for the pick-up is to be provided in the Instruction field.
InstructionTypeCode element is reserved for future use.

10.2.3.5 RequestPickUp Input: PickupShipment – Remarks – any remarks for pickup of the
shipment.

10.2.3.6 RequestPickUp Input: PickupShipment - PickupLocation - where the package should be

picked up by the DHL courier.

PAGE 248 OF 417

MYDHL API – DEVELOPER GUIDE

10.2.3.7 RequestPickUp Input: PickupShipment - PickupLocationType – the type of pickup

location. Possible values B=Business and R=Residence.

10.2.3.8 RequestPickUp Input: PickupShipment - Billing – this section contains the account number
information which is required to create a pickup.

- ShipperAccountNumber
o The DHL account number used for the shipment. Used as the shipper account number.

- ShippingPaymentType
o Possible values:
▪ S (use ShipperAccountNumber as payer)
▪ R (use BillingAccountNumber as bill-to receiver account number)
▪ T (use BillingAccountNumber as bill-to third party account number)

Please note if you use value R or T in this tag then the next tag <BillingAccountNumber> is also
mandatory.

- BillingAccountNumber
o The DHL account number used for the shipment, if ShippingPaymentType is equal to R or T.

An error message will be thrown when customer provided the <ShippingPaymentType> value as R or T
and <BillingAccountNumber> is not provided.

PAGE 249 OF 417

MYDHL API – DEVELOPER GUIDE

10.2.3.9 RequestPickUp Input: PickupShipment - Ship

The Ship section outlines the Shipper, Pickup, Recipient and BookingRequestor addresses.
Shipper – Is the address of the individual/company that is shipping the parcel(s).
Pickup Address – is optional in case the pickup address is different to the shipper address
Booking Requestor – is optional in case the booking requestor is not the same the shipper
Recipient – Is the destination address where the shipment is to be delivered

For Remote Booking Requests, Booking Requestor and Recipient details are mandatory. An error
message will be thrown when Booking Requestor or Recipient details is missing for remote booking.
For Regular Booking Requests, Recipient details is optional.

PAGE 250 OF 417

MYDHL API – DEVELOPER GUIDE

10.3 REQUESTPICKUP REQUEST – INPUT FIELD LIST

Values or
requestPickup fields M/O Comments
Constraints
PickUpRequest

PickUpRequest/ClientDetail

sso O This field is for internal use only

plant O This field is for internal use only
PickUpRequest/Request
PickUpRequest/Request/ServiceHeader
MessageTime O TIMESTAMP The format of the should be
YYYY-MM-DD(T)hh:mm:ss-Time Zone
e.g 2011-01-12T18:41:12Z
MessageReference O AN 36 The unique message reference for this
response.
WebstorePlatform O AN 20 Reserved for Third Party Vendors
identification
WebstorePlatformVersion O AN 15 Reserved for Third Party Vendors
identification
ShippingSystemPlatform O AN 20 Reserved for Third Party Vendors
identification
ShippingSystemPlatformVersio O AN 15 Reserved for Third Party Vendors
n identification
PlugIn O AN 20 Reserved for Third Party Vendors
identification
PlugInVersion O AN 15 Reserved for Third Party Vendors
identification
PickUpRequest/PickUpShipment

PickupTimestamp M AN 29 Identifies the date and time the package is

tendered.

The time is the local time of the shipment

based on the shipper's time zone. The date
component must be in the format: YYYY-
MMDD; the time component must be in the
format: HH:MM:SS using a 24 hour clock. The
date and time parts are separated by the letter
T (e.g. 2010-02-05T14:00:00 GMT+01:00).

PAGE 251 OF 417

MYDHL API – DEVELOPER GUIDE

PickupLocationCloseTime O AN 5 Identifies the pickup location close time (i.e.

what time do the premises where the
collection is supposed to happen close). The
value must be in local time. The value
component must be HH:MM (using a 24-hours
clock format, e.g. 14:00).
Remarks O
PickupLocation O AN 80 where the package should be picked up by
DHL courier
PickupLocationType O “COMMERCIAL” Possible Values:
, COMMERCIAL
“RESIDENTIAL” RESIDENTIAL
PickUpRequest/PickUpShipment/ShipmentDet
ails
PickUpRequest/PickUpShipment/ShipmentDetails/ShipmentDetail

ServiceType O AN 6 The shipping product requested for this

shipment, corresponding to the DHL Global
Product codes.
LocalServiceType O AN 3 DHL “local / country specific” Product Code
used to ship the items. Important when
shipping domestic products – please consult
your DHL Express IT consultant if needed.
UnitOfMeasurement M “SI”,”SU” The unit of measurement for the dimensions
of the package.

Possible values:

- SI, international metric system(KG, CM)

- SU, UK, US system of measurement (LB, IN)

Content O “DOCUMENTS”, The Content field details whether a shipment
“NON_DOCUME is non-dutiable (value DOCUMENTS) or
NTS” dutiable (NON_DOCUMENTS). Depending on
the nature of the contents of the shipment, is
customs duties are applicable, different
products may be offered by the DHL web
services.

ShipmentIdentificationNumber O This field corresponds to the airbill number

associated to this shipment.

NumberOfPieces O The number of pieces in the shipment.

ShipmentWeight O 15.3 D The total weight of the shipment.

DeclaredValue O 18.3 D The declared amount for the Shipment.

PAGE 252 OF 417

MYDHL API – DEVELOPER GUIDE

DeclaredValueCurrencyCode O AN 3 3 character currency code for the declared

value.

PickUpRequest/PickUpShipment/ShipmentDetails/ShipmentDetail/SpecialServices (0:1)
PickUpRequest/PickUpShipment/ShipmentDetails/ShipmentDetail/SpecialServices/Service (1:99)
ServiceType M AN 6 Enter the DHL Express Service code you wish
to add – i.e. II for insurance
ServiceValue O 18.3 D Monetary value of service (currently only
applicable for Insurance)
CurrencyCode O AN 3 Currency code
PickUpRequest/PickUpShipment/ShipmentDetails/ShipmentDetail/Packages (1:1)

PickUpRequest/PickUpShipment/ShipmentDetails/ShipmentDetail/Packages/RequestedPackages
(1:99)

@number M Integer Running number of the packages.

Weight M 15.3 D The weight of the package.
CustomerReferences O AN 35 Customer Reference for the piece
PickUpRequest/PickUpShipment/ShipmentDetails/ShipmentDetail/Packages/RequestedPackages
/Dimensions
Length M 10.3 D Length of the piece listed.
Width M 10.3 D Width of the piece listed.
Height M 10.3 D Height of the piece listed.
PickUpRequest/PickUpShipment/SpecialPickupInstructions
PickUpRequest/PickUpShipment/SpecialPickupInstructions/SpecialPickupInstruction
Instruction M AN 80 Any special instructions user wish to send to
the courier for the order pick-up
InstructionTypeCode O AN 3 This element is reserved for future use only
PickUpRequest/PickUpShipment/Billing
ShipperAccountNumber M AN 9 The DHL account number used for the
shipment. Used as the shipper account
number.

ShippingPaymentType M AN 1 Possible values:

- S (use
ShipperAccountNumber as payer)
- R (use BillingAccountNumber as bill-to
receiver account number)
- T (use BillingAccountNumber as bill-to
third party account number) Please note
if you use value R or T in this tag then the
next tag

PAGE 253 OF 417

MYDHL API – DEVELOPER GUIDE

<BillingAccountNumber> is also
mandatory

BillingAccountNumber O AN 9
The DHL account number used for the
shipment, if
ShippingPaymentType is equal to R or T.

PickUpRequest/PickUpShipment/Ship (1:1)
PickUpRequest/PickUpShipment/Ship/Shipper (1:1)
PickUpRequest/PickUpShipment/Ship/Shipper/Contact (1:1)
PersonName M AN 255 A contact name of a person who will ship the
shipment.

CompanyName M AN 100 The company name the person is working in.

PhoneNumber M AN 70 The contact person phone number. In case of

questions, this person can be called by the
courier.
EmailAddress O AN 70 The email address of the contact person.
MobilePhoneNumber O AN 70 The mobile phone number of the contact
person.
PickUpRequest/PickUpShipment/Ship/Shipper/Address (1:1)

StreetLines M AN 45 The street line should contain street name

and number of the shipper.
StreetName O AN 45 Shipper street name should be sent as
separate attribute if feasible.
StreetNumber O AN 15 Shipper street number should be sent as
separate attribute, if feasible.
StreetLines2 O AN 45 Shipper additional address information
StreetLines3 O AN 45 Shipper additional address information
City M AN 45 Shipper city name
Suburb O AN 45 Shipper suburb
StateOrProvinceCode O AN 2 2 Letter state code for the USA only
PostalCode M AN 12 Shipper postal code
CountryCode M AN 2 ISO 2 character codes of the Shipper country.
PickUpRequest/PickUpShipment/Ship/Pickup
(0:1)
PickUpRequest/PickUpShipment/Ship/Pickup/Contact (1:1)

PAGE 254 OF 417

MYDHL API – DEVELOPER GUIDE

PersonName M AN 255 A contact person of the pickup location.

CompanyName M AN 100 The company name the person is working in.
PhoneNumber M AN 70 The contact person phone number. In case of
questions, this person can be called by the
courier.
EmailAddress O AN 70 The email address of the contact person.
MobilePhoneNumber O AN 70 The mobile phone number of the contact
person.
PickUpRequest/PickUpShipment/Ship/Pickup/Address (1:1)
StreetLines M AN 45 The street line should contain street name
and number of the pickup location.
StreetName O AN 45 Pickup street name should be sent as
separate attribute if feasible.
StreetNumber O AN 15 Pickup street number should be sent as
separate attribute, if feasible.
StreetLines2 O AN 45 Pickup additional address information
StreetLines3 O AN 45 Pickup additional address information
City M AN 45 Pickup city name
Suburb O AN 45 Pickup suburb
StateOrProvinceCode O AN 2 2 Letter state code for the USA only
PostalCode M AN 12 Pickup postal code
CountryCode M AN 2 ISO 2 character codes of the Pickup country.
PickUpRequest/PickUpShipment/Ship/BookingRequestor (0:1)
PickUpRequest/PickUpShipment/Ship/BookingRequestor/Contact (1:1)
PersonName M AN 255 A contact person of the pickup location.
CompanyName M AN 100 The company name the person is working in.
PhoneNumber M AN 70 The contact person phone number. In case of
questions, this person can be called by the
courier.
EmailAddress O AN 70 The email address of the contact person.
MobilePhoneNumber O AN 70 The mobile phone number of the contact
person.
PickUpRequest/PickUpShipment/Ship/BookingRequestor/Address (1:1)
StreetLines M AN 45 The street line should contain street name
and number of the pickup location.
StreetName O AN 45 Pickup street name should be sent as
separate attribute if feasible.
StreetNumber O AN 15 Pickup street number should be sent as
separate attribute, if feasible.

PAGE 255 OF 417

MYDHL API – DEVELOPER GUIDE

StreetLines2 O AN 45 Pickup additional address information

StreetLines3 O AN 45 Pickup additional address information
City M AN 45 Pickup city name
Suburb O AN 45 Pickup suburb information
StateOrProvinceCode O AN 2 2 Letter state code for the USA only
PostalCode M AN 12 Pickup postal code
CountryCode M AN 2 ISO 2 character codes of the Pickup country.
PickUpRequest/PickUpShipment/Ship/Recipient (0:1)
PickUpRequest/PickUpShipment/Ship/Recipient/Contact (1:1)
PersonName M AN 255 A contact name of a person who will receive
the shipment.
CompanyName M AN 100 The company name the person is working in.
PhoneNumber M AN 70 The contact person phone number. In case of
questions, this person can be called by the
courier.
EmailAddress O AN 70 The email address of the contact person.
MobilePhoneNumber O AN 70 The mobile phone number of the contact
person.
PickUpRequest/PickUpShipment/Ship/Recipient/Address (1:1)

StreetLines M AN 45 The street line should contain street name

and number of the reveiver.
StreetName O AN 45 Recipient street name should be sent as
separate attribute if feasible.
StreetNumber O AN 15 Recipient street number should be sent as
separate attribute, if feasible.
StreetLines2 O AN 45 Recipient additional address information
StreetLines3 O AN 45 Recipient additional address information
City M AN 45 Recipient city name
Suburb O AN 45 Recipient suburb information
StateOrProvinceCode O AN 2 2 Letter state code for the USA only
PostalCode M AN 12 Recipient postal code
CountryCode M AN 2 ISO 2 character codes of the Receiver country.

PAGE 256 OF 417

MYDHL API – DEVELOPER GUIDE

10.4 REQUESTPICKUP - OUTPUT

The following diagram shows an overview of the requestPickup response structure. The critical
information to derive from this response are the notification codes for the response and the DHL
internal dispatch confirmation number.

10.4.1 RequestPickUp Response Schema Diagram

Each of the individual sections of RequestPickUp Response is shown below in the schema diagram, with
context, and a detailed description of each field follows in the Output Field List.

PAGE 257 OF 417

MYDHL API – DEVELOPER GUIDE

10.4.2 RequestPickUp Output: ServiceHeader

The ServiceHeader structure includes the MessageTime which is the time the request was processed and
MessageReference which will have the same value as provided in Request Message. Customer can track
messages by this reference.

10.4.3 RequestPickUp Output: Notification

The Notification structure includes the result code and message, based on the results of the
processing. Successful messages will include a zero error code and no corresponding message, while
exceptions have both code and message.

10.4.4 RequestPickUp Output: Warning

The Warning structure includes the result code and message, based on the results of the processing.
This is for future use.

10.4.4 RequestPickUp Output: DispatchConfirmationNumber

This field is the confirmation number generated by the creation of a pickup. This data will need to be
persisted if the web service consumer intends to utilize the UpdatePickup or DeleteShipment
functionality, as it is a required field.

PAGE 258 OF 417

MYDHL API – DEVELOPER GUIDE

10.5 REQUEST PICKUP RESPONSE – OUTPUT FIELD LIST

Request Pickup Response xml Mandatory/ Values or

Comments
fields (Source) Optional Constraints

PickUpResponse

DispatchConfirmationNumber O AN 15 The booking reference number.

PickUpResponse/ServiceHeader

The format of the should be YYYY-

MessageTime M TIMESTAMP MM-DD(T)hh:mm:ssZ
e.g 2011-01-12T18:41:12Z
MessageReference as send from
MessageReference O AN 36
request message
This element will get populate when
existing or new customers has
provided the <Request> element in
the request message.
ServiceInvocationID M
This information will get populate in
Response in all
Error and Success scenarios

PickUpResponse/Notification

@code M N6 Error > 0 or Success Code = 0

Message M Response Message, see Error codes
for more details
PickUpResponse/Warning
@code M N6 For future use
Message M For future use

11. UPDATEPICKUP

11.1 UPDATEPICKUP - DESCRIPTION

The UpdatePickUp request allows users to modify a previous successful remote/import and local
pickups using the DHL Express Pickup confirmation number - GRN (DispatchConfirmationNumber).

Update booking feature

PAGE 259 OF 417

MYDHL API – DEVELOPER GUIDE

It is not possible to update a local pickup to remote and vice versa. An error message will be thrown
in this instance

11.2 UPDATEPICKUP - INPUT

The following diagram shows an overview of the request input structure.

11.2.1 UpdatePickUp Schema Diagram

Each of the individual sections of UpdatePickUp is shown below in the schema diagram, with context,
and a detailed description of each field.

11.2.2 UpdatePickUp Input: ClientDetail

Within the UpdatePickUp Service, the ClientDetail is an optional node for reference use, and does not
affect functionality.

PAGE 260 OF 417

MYDHL API – DEVELOPER GUIDE

11.2.3 UpdatePickUp Input: Request

Optional section to populate information used to identify customer request for troubleshooting or
tracking. DHL Express recommends that this information is provided.

11.2.4 UpdatePickUp Input: DispatchConfirmationNumber

Mandatory field to populate the confirmation number received from the previous successful request
pickup. Customer can modify/update the pickup request only if it is in an active state. In case the
provided <DispatchConfirmationNumber> is inactive an error message will be returned.

11.2.5 UpdatePickUp Input: OriginalShipperAccountNumber

Customers who wish to perform authentication before modify of pickup must populate this field with
their account number. The account number should match with the original account number which they
used to create the initial pickup request.
An error message will be thrown if there is a mismatch of account number between the original request
and update request.

11.2.6 UpdatePickUp Input: PickupShipment

The root of the UpdatePickUp holds the shipment details, pickup time stamp, optional pickup location
close time, special pickup instructions, remarks, pickup location (i.e. front door, reception etc.) and

PAGE 261 OF 417

MYDHL API – DEVELOPER GUIDE

pickup location type. The mandatory elements ShipmentDetails, PickupTimestamp, Billing, and Ship
are required for creating a request pickup.

11.2.6.1 UpdatePickUp Input: ShipmentDetails

The ShipmentDetails section contains the ServiceType (Global Product Code eg. “P” for Express
Worldwide), LocalServiceType (Local Product Code), SpecialServices (Special Service Code eg. “II” for
Shipment Insurance), the UnitOfMeasurement (SI or SU), and Content (Documents/Non_Documents),
ShipmentIdentificationNumber (Waybill), NumberOfPieces, ShipmentWeight, DeclaredValue,
DeclaredValueCurrencyCode and Packages that is applicable to the pickup.

- ServiceType - The shipping product requested for this shipment, corresponding to the DHL
Global Product codes.

PAGE 262 OF 417

MYDHL API – DEVELOPER GUIDE

- LocalServiceType - DHL “local / country specific” Product Code used to ship the items.
Important when shipping domestic products – please consult your DHL Express IT consultant if
needed.

- SpecialServices – The SpecialServices section communicates additional shipping services, such

as Insurance (or Shipment Value Protection). For example, to support Insurance, the ServiceType
would have a value of ‘II’, which the ServiceValue and CurrencyCode containing the insured value and
currency, respectively. Please note that for all other Value Added Service like Saturday Delivery,
Dangerous goods etc you do not need to declare the service charge and currency.

- UnitOfMeasurement – The UnitOfMeasurement node conveys the unit of measurements

used in the operation. This single value corresponds to the units of weight and measurement used
throughout the message processing. The value of ‘SI’ corresponds to KG and CM, respectively, while
the value of ‘SU’ corresponds to LB and IN, respectively.

An error message will be thrown to customer if UnitOfMeasurement is missing in RequestPickUp.

- Content - The Content field details whether a shipment is non-dutiable (value DOCUMENTS)
or dutiable (NON_DOCUMENTS). Depending on the nature of the contents of the shipment, is
customs duties are applicable, different products may be offered by the DHL web services.

- ShipmentIdentificationNumber - This field corresponds to the airbill number associated to this

shipment.

- NumberOfPieces – The number of pieces in the shipment.

PAGE 263 OF 417

MYDHL API – DEVELOPER GUIDE

- ShipmentWeight – The total weight of the Shipment.

- DeclaredValue – The declared amount for the Shipment.

- DeclaredValueCurrencyCode - The currency code of the declared value for shipment.

- Packages – The Packages section details the contents of individual pieces (or discrete
shipping containers) within the shipment. The minimum number of packages or pieces in a
shipment is one and the upper limit is 999. The Weight and Dimensions fields represent the weight
and dimensions of the individual pieces. The CustomerReferences field is used as the Piece
Reference.

An error message will be thrown to customer if Packages is missing. At least one piece details is
required for booking request.

11.2.6.2 UpdatePickUp Input: PickupShipment - PickupTimestamp - The provided PickupTimestamp

in the request message will be validated to ensure the format of provided timestamp is valid. Also, pick up
date cannot be in the past or more than 28 days in future. Sample - “2017-10-12T17:30:00GMT+00:00”.
An error message will be thrown to customer if provided pickup date is more than 28 days.

PAGE 264 OF 417

MYDHL API – DEVELOPER GUIDE

11.2.6.3 UpdatePickUp Input: PickupShipment - PickupLocationCloseTime - When the pickup

location close time is provided in the request message, the close time will be validated against pickup
timestamp. If the pickup time is later than provided close time, an error message will be thrown to
customer. Sample – “12:00”.

11.2.6.4 UpdatePickUp Input: PickupShipment - SpecialPickupInstructions - any special

instructions you wish to send to the courier for the order pick-up is to be provided in field Instruction.
InstructionTypeCode element is reserved for future use.

11.2.6.5 RequestPickUp Input: PickupShipment – Remarks – any remarks for pickup of the
shipment.

11.2.6.6 RequestPickUp Input: PickupShipment - PickupLocation - where the package should be

picked up by DHL courier.

11.2.6.7 RequestPickUp Input: PickupShipment - PickupLocationType – the type of pickup

location. Possible values “COMMERCIAL” and “RESIDENTIAL”.

PAGE 265 OF 417

MYDHL API – DEVELOPER GUIDE

11.2.6.8 RequestPickUp Input: PickupShipment - Billing – the Billing structure converys the Shipper
Account Number (Similar like ShipmentRequest and RateRequest). Receiver or third party account number
as payer can be used if required.

- ShipperAccountNumber
o The DHL account number used for the shipment. Used as the shipper account number.

- ShippingPaymentType
o Possible values:
▪ S (use ShipperAccountNumber as payer)
▪ R (use BillingAccountNumber as bill-to receiver account number)
▪ T (use BillingAccountNumber as bill-to third party account number)

Please note if you use value R or T in this tag then the next tag
<BillingAccountNumber> is also mandatory.
- BillingAccountNumber
o The DHL account number used for the shipment, if ShippingPaymentType is equal to R or
T.
An error message will be thrown when customer provided the <ShippingPaymentType> value as R or T
and <BillingAccountNumber> is not provided.

PAGE 266 OF 417

MYDHL API – DEVELOPER GUIDE

11.2.6.9 UpdatePickUp Input: PickupShipment - Ship

The Ship section outlines the Shipper, Pickup, Recipient and BookingRequestor addresses.
Shipper – Is the address of the individual/company that is shipping the parcels
Pickup Address – is optional in case the pickup address is different to the shipper address
Booking Requestor – is optional in case the booking requestor is not the same the shipper
Recipient – Is the destination address where the shipment is to be delivered

For Remote Booking Requests, Booking Requestor and Recipient details are mandatory. An error
message will be thrown when Booking Requestor and Recipient details is missing for remote booking.
For Regular Booking Requests, Recipient details is optional.

PAGE 267 OF 417

MYDHL API – DEVELOPER GUIDE

11.3 UPDATEPICKUP REQUEST – INPUT FIELD LIST

M/ Values or
UpdatePickUp fields Comments
O Constraints
UpdatePickUpRequest

DispatchConfirmationNumber M AN 15 Mandatory field to populate the

confirmation number received from the
previous successful request pickup.
Customer can modify/update the pickup
request only if it is in active state. In case
the provided
DispatchConfirmationNumber> is
inactive user will receive error response.

OriginalShipperAccountNumb M/O AN 12 Customers who wish to perform

er authentication before modify of pickup must
populate this field with their account
number. The account number should match
with the original account number which
they used to create the initial pickup
request.
Customer who wish to perform account
number verification must contact their DHL
integration point of contact for
configuration setup.

UpdatePickUpRequest/ClientDetail

sso O This field is for internal use only

plant O This field is for internal use only
UpdatePickUpRequest/Request
UpdatePickUpRequest/Request/ServiceHeader
MessageTime O TIMESTAMP The format of the should be
YYYY-MM-DD(T)hh:mm:ss-Time Zone
e.g 2011-01-12T18:41:12Z
MessageReference O AN 36 The unique message reference for this
response.
WebstorePlatform O AN 20 Reserved for Third Party Vendors
identification
WebstorePlatformVersion O AN 15 Reserved for Third Party Vendors
identification

PAGE 268 OF 417

MYDHL API – DEVELOPER GUIDE

ShippingSystemPlatform O AN 20 Reserved for Third Party Vendors

identification
ShippingSystemPlatformVersi O AN 15 Reserved for Third Party Vendors
on identification
PlugIn O AN 20 Reserved for Third Party Vendors
identification
PlugInVersion O AN 15 Reserved for Third Party Vendors
identification
UpdatePickUpRequest/PickUpShipment

PickupTimestamp M AN 29 Identifies the date and time the package is

tendered.

The time is the local time of the shipment

based on the shipper's time zone. The date
component must be in the format: YYYY-
MMDD; the time component must be in the
format: HH:MM:SS using a 24 hour clock.
The date and time parts are separated by
the letter T (e.g. 2010-02-05T14:00:00
GMT+01:00).
PickupLocationCloseTime O AN 5 Identifies the pickup location close time (i.e.
what time do the premises where the
collection is supposed to happen close). The
value must be in local time. The value
component must be HH:MM (using a 24-
hours clock format, e.g. 14:00).
Remarks O
PickupLocation O AN 80 where the package should be picked up by
DHL courier
PickupLocationType O “COMMERCIAL”, Possible Values:
“RESIDENTIAL” COMMERCIAL
RESIDENTIAL
UpdatePickUpRequest/PickUpShipment/ShipmentDetai
ls
UpdatePickUpRequest/PickUpShipment/ShipmentDetails/ShipmentDetail

ServiceType O AN 6 The shipping product requested for this

shipment, corresponding to the DHL Global
Product codes.
LocalServiceType O AN 3 DHL “local / country specific” Product Code
used to ship the items. Important when
shipping domestic products – please consult
your DHL Express IT consultant if needed.

PAGE 269 OF 417

MYDHL API – DEVELOPER GUIDE

UnitOfMeasurement M “SI”,”SU” The unit of measurement for the

dimensions of the package. Possible values:

- SI, international metric system(KG, CM)

- SU, UK, US system of measurement (LB,

IN)
Content O “DOCUMENTS”, The Content field details whether a
“NON_DOCUMENT shipment is non-dutiable (value
S” DOCUMENTS) or dutiable
(NON_DOCUMENTS). Depending on the
nature of the contents of the shipment, is
customs duties are applicable, different
products may be offered by the DHL web
services.

ShipmentIdentificationNumbe O This field corresponds to the airbill number

r associated to this shipment.

NumberOfPieces O The number of pieces in the shipment.

ShipmentWeight O 15.3 D The total weight of the shipment.

DeclaredValue O 18.3 D The declared amount for the Shipment.

DeclaredValueCurrencyCode O AN 3 3 character currency code for the declared

value.

UpdatePickUpRequest/PickUpShipment/ShipmentDetails/ShipmentDetail/SpecialServices (0:1)
UpdatePickUpRequest/PickUpShipment/ShipmentDetails/ShipmentDetail/SpecialServices/Service
(1:99)
ServiceType M AN 6 Enter the DHL Express Service code you wish
to add – i.e. II for insurance
ServiceValue O 18.3 D Monetary value of service (currently only
applicable for Insurance)
CurrencyCode O AN 3 Currency code
UpdatePickUpRequest/PickUpShipment/ShipmentDetails/ShipmentDetail/Packages/RequestedPa
ckages
@number M Integer Running number of the packages.
Weight M 15.3 D The weight of the package.
UpdatePickUpRequest/PickUpShipment/ShipmentDetails/ShipmentDetail/Packages/RequestedPa
ckages /Dimensions
Length M 10.3 D Length of the piece listed.
Width M 10.3 D Width of the piece listed.
Height M 10.3 D Height of the piece listed.
UpdatePickUpRequest/PickUpShipment/SpecialPickupInstructions

PAGE 270 OF 417

MYDHL API – DEVELOPER GUIDE

UpdatePickUpRequest/PickUpShipment/SpecialPickupInstructions/SpecialPickupInstruction
Instruction M AN 80 Any special instructions user wish to send to
the courier for the order pick-up
InstructionTypeCode O AN 3 This element is reserved for future use only
UpdatePickUpRequest/PickUpShipment/Billing
ShipperAccountNumber M AN 9 The DHL account number used for the
shipment. Used as the shipper account
number.

ShippingPaymentType M AN 1 Possible values:

- S (use
ShipperAccountNumber as payer)
- R (use BillingAccountNumber as bill-to
receiver account number)
- T (use BillingAccountNumber as bill-to
third party account number) Please
note if you use value R or T in this tag
then the next tag
<BillingAccountNumber> is also
mandatory
BillingAccountNumber O AN 9 The DHL account number used for the
shipment, if
ShippingPaymentType is equal to R or T.
UpdatePickUpRequest/PickUpShipment/Ship (1:1)

UpdatePickUpRequest/PickUpShipment/Ship/Shipper (1:1)
UpdatePickUpRequest/PickUpShipment/Ship/Shipper/Contact (1:1)
PersonName M AN 255 A contact name of a person who will ship
the shipment.
CompanyName M AN 100 The company name the person is working
in.
PhoneNumber M AN 70 The contact person phone number. In case
of questions, this person can be called by
the courier.
EmailAddress O AN 70 The email address of the contact person.
MobilePhoneNumber O AN 70 The mobile phone number of the contact
person.
UpdatePickUpRequest/PickUpShipment/Ship/Shipper/Address (1:1)

StreetLines M AN 45 The street line should contain street name

and number of the shipper.
StreetName O AN 45 Shipper street name should be sent as
separate attribute if feasible.
StreetNumber O AN 15 Shipper street number should be sent as
separate attribute, if feasible.

PAGE 271 OF 417

MYDHL API – DEVELOPER GUIDE

StreetLines2 O AN 45 Shipper additional address information

StreetLines3 O AN 45 Shipper additional address information
City M AN 45 Shipper city name
Suburb O AN 45 Shipper suburb
StateOrProvinceCode O AN 2 2 Letter state code for the USA only
PostalCode M AN 12 Shipper postal code
CountryCode M AN 2 ISO 2 character codes of the Shipper
country.
UpdatePickUpRequest/PickUpShipment/Ship/Pickup(
0:1)
UpdatePickUpRequest/PickUpShipment/Ship/Pickup/Contact (1:1)

PersonName M AN 255 A contact person of the pickup location.

CompanyName M AN 100 The company name the person is working
in.
PhoneNumber M AN 70 The contact person phone number. In case
of questions, this person can be called by
the courier.
EmailAddress O AN 70 The email address of the contact person.
MobilePhoneNumber O AN 70 The mobile phone number of the contact
person.
UpdatePickUpRequest/PickUpShipment/Ship/Pickup/Address (1:1)
StreetLines M AN 45 The street line should contain street name
and number of the pickup location.
StreetName O AN 45 Pickup street name should be sent as
separate attribute if feasible.
StreetNumber O AN 15 Pickup street number should be sent as
separate attribute, if feasible.
StreetLines2 O AN 45 Pickup additional address information
StreetLines3 O AN 45 Pickup additional address information
City M AN 45 Pickup city name
Suburb O AN 45 Pickup suburb
StateOrProvinceCode O AN 2 2 Letter state code for the USA only
PostalCode M AN 12 Pickup postal code
CountryCode M AN 2 ISO 2 character codes of the Pickup country.
UpdatePickUpRequest/PickUpShipment/Ship/BookingRequestor (0:1)
UpdatePickUpRequest/PickUpShipment/Ship/BookingRequestor/Contact (1:1)
PersonName M AN 255 A contact person of the pickup location.

PAGE 272 OF 417

MYDHL API – DEVELOPER GUIDE

CompanyName M AN 100 The company name the person is working

in.
PhoneNumber M AN 70 The contact person phone number. In case
of questions, this person can be called by
the courier.
EmailAddress O AN 70 The email address of the contact person.
MobilePhoneNumber O AN 70 The mobile phone number of the contact
person.
UpdatePickUpRequest/PickUpShipment/Ship/BookingRequestor/Address (1:1)
StreetLines M AN 45 The street line should contain street name
and number of the pickup location.
StreetName O AN 45 Pickup street name should be sent as
separate attribute if feasible.
StreetNumber O AN 15 Pickup street number should be sent as
separate attribute, if feasible.
StreetLines2 O AN 45 Pickup additional address information
StreetLines3 O AN 45 Pickup additional address information
City M AN 45 Pickup city name
Suburb O AN 45 Pickup suburb information
StateOrProvinceCode O AN 2 2 Letter state code for the USA only
PostalCode M AN 12 Pickup postal code
CountryCode M AN 2 ISO 2 character codes of the Pickup country.
UpdatePickUpRequest/PickUpShipment/Ship/Recipient (0:1)
UpdatePickUpRequest/PickUpShipment/Ship/Recipient/Contact (1:1)
PersonName M AN 255 A contact name of a person who will receive
the shipment.
CompanyName M AN 100 The company name the person is working
in.
PhoneNumber M AN 70 The contact person phone number. In case
of questions, this person can be called by
the courier.
EmailAddress O AN 70 The email address of the contact person.
MobilePhoneNumber O AN 70 The mobile phone number of the contact
person.
UpdatePickUpRequest/PickUpShipment/Ship/Recipient/Address (1:1)

StreetLines M AN 45 The street line should contain street name

and number of the reveiver.
StreetName O AN 45 Recipient street name should be sent as
separate attribute if feasible.
StreetNumber O AN 15 Recipient street number should be sent as
separate attribute, if feasible.
StreetLines2 O AN 45 Recipient additional address information

PAGE 273 OF 417

MYDHL API – DEVELOPER GUIDE

StreetLines3 O AN 45 Recipient additional address information

City M AN 45 Recipient city name
Suburb O AN 45 Recipient suburb information
StateOrProvinceCode O AN 2 2 Letter state code for the USA only
PostalCode M AN 12 Recipient postal code
CountryCode M AN 2 ISO 2 character codes of the Receiver
country.

PAGE 274 OF 417

MYDHL API – DEVELOPER GUIDE

11.4 UPDATEPICKUP - OUTPUT

The following diagram shows an overview of the UpdatePickUp response structure. The critical
information to derive from this response are the notification codes for the response and the DHL
internal dispatch confirmation number.

10.4.1 UpdatePickUp Response Schema Diagram

Each of the individual sections of UpdatePickUp Response is shown below in the schema diagram, with
context, and a detailed description of each field follows in the Output Field List.

PAGE 275 OF 417

MYDHL API – DEVELOPER GUIDE

11.4.2 UpdatePickUp Output: Response

The Response structure includes the ServiceHeader which has MessageTime and MessageReference.
MessageTime which is the time the request was processed and MessageReference which will have the
same value as provided in Request Message. Customer can track messages by this reference.

10.4.3 UpdatePickUp Output: Notification

The Notification structure includes the result code and message, based on the results of the
processing. Successful messages will include a zero error code and no corresponding message, while
exceptions have both code and message.

10.4.4 UpdatePickUp Output: Warning

The Warning structure includes the result code and message, based on the results of the processing.
This is for future use.

10.4.4 UpdatePickUp Output: DispatchConfirmationNumber

This field is the confirmation number generated by the creation of a pickup, if requested. This data
will need to be persisted if the web service consumer intends to utilize the UpdatePickup or
DeleteShipment functionality, as it is a required field.

PAGE 276 OF 417

MYDHL API – DEVELOPER GUIDE

11.5 UPDATEPICKUP RESPONSE – OUTPUT FIELD LIST

UpdatePickUp Response xml Mandatory/ Values or

Comments
fields (Source) Optional Constraints

UpdatePickUpResponse

DispatchConfirmationNumber O AN 15 The booking reference number.

UpdatePickUpResponse/ServiceHeader

The format of the should be

MessageTime M TIMESTAMP YYYY-MM-DD(T)hh:mm:ssZ
e.g 2011-01-12T18:41:12Z
MessageReference as send from
MessageReference O AN 36
request message

UpdatePickUpResponse/Notification

@code M N6 Error > 0 or Success Code = 0

Message M Response Message, see Error
codes for more details
UpdatePickUpResponse/Warning
@code M N6 For future use
Message M For future use

12. ADDRESSVALIDATE

12.1 ADDRESSVALIDATE - DESCRIPTION

The AddressValidate request will return DHL’s nearest service area details for a certain origin or
destination address in the input data. Service area details include the GMT offset, city and country
name.

PAGE 277 OF 417

MYDHL API – DEVELOPER GUIDE

There are two modes of address validation that can be performed – 1) StrictValidation is Y, or 2)
StrictValidation is N.

- StrictValidation = Y the service will return a success result only when an exact match is found
with the input city, postal code, country
- StrictValidation = N the service will return success results even when partial match is found
with the input city, postal code, country

12.2 ADDRESSVALIDATE - INPUT

The following diagram shows an overview of the request input structure.

12.2.1 AddressValidate Schema Diagram

Each of the individual sections of AddressValidate request is shown below in schema diagram, with
context, and a detailed description of each field follows in the Input Field List.

12.2.2 AddressValidate Input: ClientDetail

Within the AddressValidate Service, the ClientDetail is an optional node for reference use, and does not
affect functionality.

12.2.3 AddressValidate Input: Request

PAGE 278 OF 417

MYDHL API – DEVELOPER GUIDE

Optional section to populate information used to identify customer request for troubleshooting or
tracking. DHL Express recommends that this information is provided.

12.2.3 AddressValidate Input: AddressValidate

AddressValidate holds the address type, postal code, city name, suburb and country code and the
indicator StrictValidation (Y / N). AddressValidate service will default StrictValidation as Y, if not
provided.

PAGE 279 OF 417

MYDHL API – DEVELOPER GUIDE

12.3 ADDRESSVALIDATE REQUEST – INPUT FIELD LIST

AddressValidate Request Values or

M/O Comments
fields Constraints

AddressValidateRequest

AddressValidateRequest /ClientDetail

sso O This field is for internal use only

plant O This field is for internal use only

AddressValidateRequest/Request

AddressValidateRequest/Request/ServiceHeader

MessageTime O Timestamp Format:

YYYY-MM-DD(T)hh:mm:ssZ
e.g 2020-01-12T08:41:12Z

MessageReference O AN 36 Message reference, between 28

to 36 characters in length.

WebstorePlatform O AN 20 Reserved for Third Party Vendors

identification

WebstorePlatformVersion O AN 15 Reserved for Third Party Vendors

identification

ShippingSystemPlatform O AN 20 Reserved for Third Party Vendors

identification

ShippingSystemPlatformVersion O AN 15 Reserved for Third Party Vendors

identification

PlugIn O AN 20 Reserved for Third Party Vendors

identification

PlugInVersion O AN 15 Reserved for Third Party Vendors

identification

AddressValidateRequest/AddressValidate

PAGE 280 OF 417

MYDHL API – DEVELOPER GUIDE

AddressType M Enumerated
Indicator whether the address in
the input data is an origin address
or destination address

PostalCode M AN 12 Postal code

City M AN 45 City name

Suburb O AN 45 Suburb (if applicable)

CountryCode M AN 2 ISO 2 character code

StrictValidation O Enumerated Optional indicator on mode of
validation to be performed

“Y” – the service will return a

success result only when an exact
match is found with the input city
/ postal code / country

“N” – the service will return

success results even when partial
match is found with the input city
/ postal code / country

12.4 ADDRESSVALIDATE - OUTPUT

The following diagram shows an overview of the AddressValidate response structure. The critical
information to derive from this response are the notification codes for the response, the address

PAGE 281 OF 417

MYDHL API – DEVELOPER GUIDE

returned, the service area code, and the geographical information of the address. All successful
AddressValidate responses will conform to this schema.

12.4.1 AddressValidate Response Schema Diagram

Each of the individual sections of AddressValidate response is represented below in schema diagram,
with context, and a detailed description of each field follows in the Output Field List.

12.4.2 AddressValidate Output: Response/ServiceHeader

PAGE 282 OF 417

MYDHL API – DEVELOPER GUIDE

The ServiceHeader structure includes MessageReference which is taken from the request message as
well as MessageTime showing when the request has been processed on DHL side.

12.4.3 AddressValidate Output: Notification

The Notification structure includes the result code and message, based on the results of the processing.
Successful messages will include a zero error code and no corresponding message, while exceptions
will be noted with both code and message.

12.4.4 AddressValidate Output: Warning

The Warning structure includes the result code and message, based on the results of the processing.
Warning code and message is returned as an indicator that a successful response is returned using partial
match algorithms. A partial match result can be returned in successful response only when request
message flag StrictValidation is set as N.

12.4.4 AddressValidate Output: Addresses

PAGE 283 OF 417

MYDHL API – DEVELOPER GUIDE

Successful response message may include one to many Address records, depending on the number of
matching results found. An Address record may return empty PostalCode or no Suburb depending on
geographical detail of the country.

12.5 ADDRESSVALIDATE RESPONSE – OUTPUT FIELD LIST

AddressValidate Response XML Mandatory / Values or

Comments
fields Optional Constraints

AddressValidateResponse

AddressValidateResponse/Response

AddressValidateResponse/Response/ServiceHeader

Format:
MessageTime M TIMESTAMP YYYY-MM-DD(T)hh:mm:ss
e.g 2020-01-12T18:41:12
MessageReference as sent from
MessageReference O AN 36
request message
DHL internal Service invocation
ServiceInvocationID M
ID to expedite support

AddressValidateResponse/Notification

@code M N6 Error > 0 or Success Code = 0

PAGE 284 OF 417

MYDHL API – DEVELOPER GUIDE

Message M Response Message, see Error

codes for more details
AddressValidateResponse/Warning
@code M N6 Warning code = 3999
Message M Response warning message
AddressValidateResponse/Addresses
AddressValidateResponse/Addresses/Address (1:999)
CountryCode M AN 2 ISO 2 character code
City M AN 45 City name
Suburb O AN 45 Suburb name
PostalCode M AN 12 Postal code
AddressValidateResponse/Addresses/Address/ServiceArea
AN 3 The DHL Service Area Code for
ServiceAreaCode O
the returned address details
Description O City and country name of the
returned service area code
GMTOffset O The time difference between
the service area's timezone and
GMT.

13. REQUESTIDENTIFIER

13.1 REQUESTIDENTIFIER - DESCRIPTION

The RequestIdentifier request will return list of identifiers for different type of shipment usage. For
example are identifiers for normal shipments, advance shipments, break bulk shipments (BBX) –
unknown pallets and piece.

PAGE 285 OF 417

MYDHL API – DEVELOPER GUIDE

13.2 REQUESTIDENTIFIER - INPUT

The following diagram shows an overview of the request input structure.

13.2.1 RequestIdentifier Schema Diagram

Each of the individual sections of RequestIdentifier request is shown below in schema diagram, with
context, and a detailed description of each field follows in the Input Field List.

13.2.2 RequestIdentifier Input: ClientDetail

Within the RequestIdentifier Service, the ClientDetail is an optional node for reference use, and does not
affect functionality.

13.2.3 RequestIdentifier Input: Request

Optional section to populate information used to identify customer request for troubleshooting or
tracking. DHL Express recommends that this information is provided.

PAGE 286 OF 417

MYDHL API – DEVELOPER GUIDE

13.2.4 RequestIdentifier Input: RequestorAccountNumber

The DHL account number with intention to use the requested identifier range. Used as the shipper
account number.

13.2.5 RequestIdentifier Input: IdentifierType and RangeSize

Customer can request for multiple identifier ranges by indicating the IdentifierType.

RangeSize will be the number of identifiers being requested.

Possible values of IdentifierType are:

SID – Shipment ID

PID – Piece ID

ASID3 – Advanced shipment of 3 months

ASID6 – Advanced shipment of 6 months

ASID12 – Advanced shipment of 12 months

ASID24 – Advanced shipment of 24 months

PAGE 287 OF 417

MYDHL API – DEVELOPER GUIDE

HUID – Handling Unit ID

13.3 REQUESTIDENTIFIER REQUEST – INPUT FIELD LIST

RequestIdentifier Request Values or

M/O Comments
fields Constraints

IdentifierRequest

IdentifierRequest/ClientDetail

sso O This field is for internal use only

plant O This field is for internal use only

IdentifierRequest/Request

IdentifierRequest/Request/ServiceHeader

MessageTime O Timestamp Format:

YYYY-MM-DD(T)hh:mm:ssZ
e.g 2020-01-12T08:41:12Z

MessageReference O AN 36 Message reference, between 28

to 36 characters in length.

WebstorePlatform O AN 20 Reserved for Third Party Vendors

identification

WebstorePlatformVersion O AN 15 Reserved for Third Party Vendors

identification

ShippingSystemPlatform O AN 20 Reserved for Third Party Vendors

identification

ShippingSystemPlatformVersion O AN 15 Reserved for Third Party Vendors

identification

PlugIn O AN 20 Reserved for Third Party Vendors

identification

PlugInVersion O AN 15 Reserved for Third Party Vendors

identification

PAGE 288 OF 417

MYDHL API – DEVELOPER GUIDE

IdentifierRequest/Requestor

RequestorAccountNumber M AN 12 DHL account number that intends

to use the requested ranges
IdentifierRequest/Identifiers

IdentifierRequest/Identifiers/Identifier (1:999)

IdentifierType M Enumerated Possible values:

SID – Shipment ID

PID – Piece ID

ASID3 – Advanced shipment of 3

months

ASID6 – Advanced shipment of 6

months

ASID12 – Advanced shipment of

12 months

ASID24 – Advanced shipment of

24 months

HUID – Handling Unit ID

RangeSize M Integer Number of identifiers being

requested

PAGE 289 OF 417

MYDHL API – DEVELOPER GUIDE

13.4 REQUESTIDENTIFIER - OUTPUT

The following diagram shows an overview of the RequestIdentifier response structure. The critical
information to derive from this response are the notification codes for the response and the range of
identifiers together with their identifier type code. All successful RequestIdentifier responses will
conform to this schema.

13.4.1 RequestIdentifier Response Schema Diagram

Each of the individual sections of RequestIdentifier response is represented below in schema diagram,
with context, and a detailed description of each field follows in the Output Field List.

13.4.2 RequestIdentifier Output: Response/ServiceHeader

The ServiceHeader structure includes MessageReference which is taken from the request message as
well as MessageTime showing when the request has been processed on DHL side.

PAGE 290 OF 417

MYDHL API – DEVELOPER GUIDE

13.4.3 RequestIdentifier Output: Notification

The Notification structure includes the result code and message, based on the results of the processing.
Successful messages will include a zero error code and no corresponding message, while exceptions
will be noted with both code and message.

13.4.4 RequestIdentifier Output: Identifiers

Identifiers can have multiple Identifier block that contains unique IdentifierType and the range of
IdentifierNumbers.

IdentifierNumbers will contain an array of unique value of IdentifierNumber elements.

13.5 REQUESTIDENTIFIER RESPONSE – OUTPUT FIELD LIST

PAGE 291 OF 417

MYDHL API – DEVELOPER GUIDE

RequestIdentifier Response Mandatory / Values or

Comments
XML fields Optional Constraints

IdentifierResponse

IdentifierResponse/Response

IdentifierResponse/Response/ServiceHeader

Format:
MessageTime M TIMESTAMP YYYY-MM-DD(T)hh:mm:ss
e.g 2020-01-12T18:41:12
MessageReference as sent from
MessageReference O AN 36
request message
DHL internal service invocation ID to
ServiceInvocationID M
expedite support

IdentifierResponse/Notification

@code M N6 Error > 0 or Success Code = 0

Message M Response Message, see Error codes
for more details
IdentifierResponse/Warning
@code M N6 Future use
Message M Future use
IdentifierResponse/Identifiers
IdentifierResponse/Identifiers/Identifier (1:999)
Enumerated Possible values:

SID – Shipment ID

PID – Piece ID

ASID3 – Advanced shipment of 3

months

IdentifierType M ASID6 – Advanced shipment of 6

months

ASID12 – Advanced shipment of 12

months

ASID24 – Advanced shipment of 24

months

HUID – Handling Unit ID

PAGE 292 OF 417

MYDHL API – DEVELOPER GUIDE

IdentifierResponse/Identifiers/Identifier/IdentifierNumbers
IdentifierNumber M AN 35 Unique value identifier number

PAGE 293 OF 417

MYDHL API – DEVELOPER GUIDE

14. UPLOADINVOICEDATA

14.1 UPLOADINVOICEDATA - DESCRIPTION

The UploadInvoiceData Operation will allow customer to send Commercial Invoice (CIN) data
separately from Shipment Data. Customer can provide Commercial Invoice (CIN) data before Shipment
Data or vice versa.

Important Note: UploadInvoiceData service is not enabled by default and must be requested per
customer. Use of this service is only enabled on exceptional basis and DHL Express recommends to
submit shipment requests together with a commercial invoice data. To enable use of
UploadInvoiceData service, please contact your DHL Express IT representative.

To use UploadInvoiceData service, it is required that ‘PM’ service code is provided in MyDHL API Create
Shipment request. ‘PM’ service code is not enabled by default for the customers, and needs to be
enabled upon request.

When Shipment is created via MyDHL API Create Shipment service before uploading the Commercial
Invoice (CIN) data, it is mandatory to provide the Shipment Identification Number as received in MyDHL
API Create Shipment service Response.

When Commercial Invoice (CIN) data is uploaded prior to creating a shipment via MyDHL API Create
Shipment service, it is mandatory to provide Invoice Reference Number with Invoice Reference Type
value “CU” and Shipper Account Number. These elements are mandatory to facilitate an effective data
merge of the Commercial Invoice (CIN) data with Shipment Data.

As an output customer will receive Notification element value “0” on successful upload of Commercial
Invoice (CIN) data. DHL backend application performs the subsequent data merging process of the
Shipment Data and Commercial Invoice data.

Additional guideline for shipment creation is listed in ShipmentRequest section.

Further consideration points on merging the Shipment Data and Commercial Invoice Data:

1. Shipper and Receiver name and address details are to be taken from Shipment Data, not
Commercial Invoice Data. Other roles in Shipment Data such as Buyer, Seller, Importer and
Exporter will be overwritten by value in Commercial Invoice Data, if provided.

2. Any ExportDeclaration data provided within the Shipment Data will be overwritten by Commercial
Invoice Data.

3. Ensure that Weight and Dimension unit of measurement is consistent between Shipment Data and
Commercial Invoice Data. If ‘kg’ is used as the piece’s weight uom, therefore ‘kg’ must be used as
well as the Commercial Invoice line item weight uom.

4. Shipment’s Total Declared Value will be re-calculated at the backend application based on
Commercial Invoice Data sum of all line item amount and any accessorial charges provided. Thus,
Currency code provided in Commercial Invoice Data will overwrite Currency code in Shipment Data.

5. Incoterm code will be taken from Commercial Invoice Data.

PAGE 294 OF 417

MYDHL API – DEVELOPER GUIDE

6. Once data merge process has taken place at the backend application, subsequent Commercial
Invoice Data submitted will no longer be considered for merging.

7. DHL backend application keeps Shipment Data and Commercial Invoice Data that are pending data
merge for a period of 30 days. Data older than 30 days are deleted.

PAGE 295 OF 417

MYDHL API – DEVELOPER GUIDE

14.2 UPLOADINVOICEDATA - INPUT

The following diagram shows an overview of the request input structure.

14.2.1 UploadInvoiceData Request Schema Diagram

Each of the individual sections of UploadInvoiceData request is shown below in schema diagram, with
context, and a detailed description of each field follows in the Input Field List.

14.2.2 UploadInvoiceData Input: ClientDetail

Within the UploadInvoiceData Service, the ClientDetail is an optional node for internal reference use,
and does not affect functionality.

14.2.3 UploadInvoiceData Input: Request

PAGE 296 OF 417

MYDHL API – DEVELOPER GUIDE

Optional section to populate information used to identify customer request for troubleshooting or
tracking. DHL Express recommends that this information is provided.

PAGE 297 OF 417

MYDHL API – DEVELOPER GUIDE

14.2.4 UploadInvoiceData Input: InvoiceData

Mandatory section to populate Commercial Invoice (CIN) data. The Shipment Information, Export
Declarations and Ship substructures are detailed in below sections.

14.2.4.1 UploadInvoiceData Input: InvoiceData/ShipmentInfo

PAGE 298 OF 417

MYDHL API – DEVELOPER GUIDE

The ShipmentInfo section provides general shipment detail, pertaining to operational and billing
features. The Billing, Output Image Options substructures are detailed in below sections.

14.2.4.1.1 UploadInvoiceData Input: InvoiceData/ShipmentInfo/ShipmentIdentificationNumber

This field is optional which corresponds to the waybill number associated to this shipment.
UploadInvoiceData service will perform validation only when this field is provided to merge the
Commercial Invoice (CIN) data with respective Shipment Data.

Note: Please ensure to provide the correct waybill number for which you wish to merge the Commercial
Invoice (CIN) data with Shipment Data.

14.2.4.1.2 UploadInvoiceData Input: InvoiceData/ShipmentInfo/Currency

This field is mandatory which corresponds to 3 character currency code.

PAGE 299 OF 417

MYDHL API – DEVELOPER GUIDE

14.2.4.1.3 UploadInvoiceData Input: InvoiceData/ShipmentInfo/UnitOfMeasurement

This field is mandatory which corresponds to unit of measurement for the commercial invoice weight
details. Possible values :

- SI, international metric system (KG, CM)

- SU, for UK and US system of measurement (LB, IN)

14.2.4.1.4 UploadInvoiceData Input: InvoiceData/ShipmentInfo/PlannedShipDate

This field is optional which corresponds to planned shipping date or the shipping date indicated in the
shipment request.

14.2.4.1.5 UploadInvoiceData Input: InvoiceData/ShipmentInfo/Billing

This field is optional which corresponds to the Billing structure which conveys the Shipper Account
Number (Similar like ShipmentRequest) and receiver or third party account number as payer can be used
if required.

PAGE 300 OF 417

MYDHL API – DEVELOPER GUIDE

- ShipperAccountNumber
o The DHL account number used for the shipment. Used as the shipper account number.

- BillingAccountNumber
o Optional field which conveys the DHL account number used for the shipment.

Note: Please ensure to provide the same account details which were used to create the shipment for
successful merging of Commercial Invoice data with Shipment Data.

14.2.4.1.6 UploadInvoiceData Input: InvoiceData/ShipmentInfo/OutputImageOptions

This field is optional which corresponds to the Output image options that available for commercial invoice
printing.

- RequestDHLCustomsInvoice
o This flag is used to generate Customs Invoice using a DHL Express invoice template. The
default is N, customers using their own invoice and DHL Express will not generate the
invoice. If the flag is set to Y, and CustomsInvoiceTemplate is not provided, the Customs
Invoice is generated using the “COMMERCIAL_INVOICE_P_10” template.
Possible Values: Y (Yes) and N (No)

- CustomsInvoiceTemplate
o The CustomsInvoiceTemplate node conveys the Customs Invoice template used in the
operation. It is an optional field. This single value corresponds to the Customs Invoice
template used to generate Customs Invoice only when the RequestDHLCustomsInvoice=
Y. The default template is 'COMMERCIAL_INVOICE_P_10'.
o There are several template options to choose from. Below are the possible template
values and their description:

PAGE 301 OF 417

MYDHL API – DEVELOPER GUIDE

COMMERCIAL_INVOICE_04
This template can print the Shipper, Recipient, and Buyer and Importer address details and
is on portrait orientation. This template is for exclusive use for preparing Loose BBX
(LBBX) shipment.

COMMERCIAL_INVOICE_L_10
This template can print the Shipper, Recipient, Seller, Buyer, Importer and Exporter
address details and is on landscape orientation.

COMMERCIAL_INVOICE_P_10 (default)
This template can print the Shipper, Recipient and upto two more additional address
details, as this template can print upto four address details. This template is on portrait
orientation. Note: If customer provided more than four address roles in the request
message and this template is selected, the rendered invoice will only contain four
address roles based on order of priority: Shipper, Recipient, Seller, Importer, Exporter,
Buyer.

14.2.4.2 UploadInvoiceData Input: InvoiceData/ExportDeclarations/ExportDeclaration

The ExportDeclaration section is for DHL Customer to declare dutiable shipment.

PAGE 302 OF 417

MYDHL API – DEVELOPER GUIDE

14.2.4.2.1 UploadInvoiceData Input:

InvoiceData/ExportDeclarations/ExportDeclaration/InvoiceNumber

This field is mandatory which corresponds to Customs Invoice Number.

14.2.4.2.2 UploadInvoiceData Input:

InvoiceData/ExportDeclarations/ExportDeclaration/InvoiceDate

This field is mandatory which corresponds to Customs Invoice Date.

14.2.4.2.3 UploadInvoiceData Input:

InvoiceData/ExportDeclarations/ExportDeclaration/PaymentInfo

This field is mandatory which details the potential terms of trade for this specific shipment, and the
schema itself defines the possible enumerated values for this field.

PAGE 303 OF 417

MYDHL API – DEVELOPER GUIDE

14.2.4.2.4 UploadInvoiceData Input:

InvoiceData/ExportDeclarations/ExportDeclaration/ExportReasonType

This field is optional which corresponds the reason code for exporting and the schema itself defines the
possible enumerated values for this field.

14.2.4.2.5 UploadInvoiceData Input:

InvoiceData/ExportDeclarations/ExportDeclaration/PlaceOfIncoterm

This field is optional which contains the name of port of departure, shipment or destination, as required
under the applicable delivery term.
When using Customs Invoice template COMMERCIAL_INVOICE_P_10 and COMMERCIAL_INVOICE_L_10,
recommended max length is 25 characters.

14.2.4.2.6 UploadInvoiceData Input:

InvoiceData/ExportDeclarations/ExportDeclaration/ShipmentPurpose

This field is optional which indicates if the shipment was sent for Personal or Commercial reasons and
the schema itself defines the possible enumerated values for this field.

PAGE 304 OF 417

MYDHL API – DEVELOPER GUIDE

14.2.4.2.7 UploadInvoiceData Input:

InvoiceData/ExportDeclarations/ExportDeclaration/DocumentFunction

This field is mandatory which describes the purpose of document details captured and are planned to be
used.
Possible values:
- IMPORT
- EXPORT
- BOTH

14.2.4.2.8 UploadInvoiceData Input:

InvoiceData/ExportDeclarations/ExportDeclaration/CustomsDocuments

CustomsDocuments will contain child node CustomsDocument and used to indicate the document type
code and document ID that corresponds to one ore more associated document(s) for customs declaration
purposes.

Listed below are allowed Customs document type codes:

Document Type Description

972 T2LF Dispense Paiement Droits
AHC Analysis and Health Certificate
ATA ATA Carnet
ATR Preference Certificate ATR
CHD CHED-D (Common Health Entry Document for Feed and Food of Non-Animal Origin
CHP CHED-P (Common Health Entry Document for Products)
CIT CITES Certificate
COO Generic Certificate of Origin
DEX Duty Exemption Certificate
EU1 Preference Certificate EUR1

PAGE 305 OF 417

MYDHL API – DEVELOPER GUIDE

EU2 Preferential Declaration of Origin on the Invoice - EUR2

EUS End Use Authorization
FMA Certificate of Origin (Form A)
PHY Phytosanitary Certificate
VET Veterinary Entry Document
VEX VAT Exemption Certificate
CRL Control Document
CSD Consolidated Customs Entry
PPY Proof Of Payment
CI2 Export-only Invoice
CIV Customs Invoice Value
DOV Invoice
INV Commercial Invoice
PFI Pro-Forma
ALC Agricultural License
HLC Health Products Regulatory Authority (HPRA) Licensing Requirements
JLC Justice License
LIC Specific Export Licenses
LNP License or Permit
PLI Permits & Licenses
DLI Driver's License
NID National Identity Card
PAS Passport
CHA Power of Attorney
CPA Consignee Power of Attorney
POA Power of Attorney (Customer-based)
BEX Branch Letter of Exemption
DGD Dangerous Goods Declaration
IPA Intellectual Property Authorization
T2M T2M Transport Accompanying Document
TAD TAD Transport Accompanying Document T1
TCS Transportation Charges Statement
ROD Receipt on Delivery
EXL DCE Export of Customs Data
HWB House Waybill

14.2.4.2.9 UploadInvoiceData Input:

InvoiceData/ExportDeclarations/ExportDeclaration/OtherCharges

OtherCharges will contain repeating child node OtherCharge. This section can be used to input any
other monetary charges associated with the shipment such as Freight, Insurance, and Fuel Surchage etc.

ChargeValue is mandatory element and are included in calculation of Shipment Total Declared Amount.

ChargeType is mandatory element together with ChargeValue and provides more detail as to categorize
the charge being provided. Refer to below tables for list of charge type codes and descriptions.

PAGE 306 OF 417

MYDHL API – DEVELOPER GUIDE

For printing charges in commercial invoice, refer to Appendix: Commercial Invoice Template Guide on
what ChargeType codes can be printed across different Commercial Invoice templates.

Listed below are allowed charge type codes:

ChargeType Description of charge

ADMIN Administration Charge/Fee/Cost
DELIV Delivery Charge/Fee/Cost
DOCUM Documentation Charge/Fee/Cost
EXPED Expedite Charge/Fee/Cost
EXCHA Export Charge/Fee/Cost
FRCST Freight/Shipping Charge/Fee/Cost
SSRGE Fuel Surcharge
LOGST Logistic Charge/Fee/Cost
SOTHR Other Charge/Fee/Cost
SPKGN Packaging/Packing Charge/Fee/Cost
PICUP Pickup Charge/Fee/Cost
HRCRG Handling Charge/Fee/Cost
VATCR VAT Charge/Fee/Cost
INSCH Insurance Cost (Fee)
REVCH Reverse Charge

14.2.4.2.11 UploadInvoiceData Input:

InvoiceData/ExportDeclarations/ExportDeclaration/Remarks

Remarks will contain repeating child node Remark of up to max 3 occurences. This element will be
printed to the commercial invoice PDF.

14.2.4.2.12 UploadInvoiceData Input:

InvoiceData/ExportDeclarations/ExportDeclaration/ExporterCode

PAGE 307 OF 417

MYDHL API – DEVELOPER GUIDE

Optional field to indicate the type code of Exporter’s ID number provided in ExporterID tag – e.g. DUN,
SSN, and EIN.

14.2.4.2.13 UploadInvoiceData Input:

InvoiceData/ExportDeclarations/ExportDeclaration/ExporterID

Optional field to indicate the identification Number of the Exporter party.

14.2.4.2.14 UploadInvoiceData Input:

InvoiceData/ExportDeclarations/ExportDeclaration/InvoiceReferences

InvoiceReferences section contains child node InvoiceReference that can be repeated up to max 100
occurences. Data provided in this section is passed on to the manifest data.

Note: For UploadInvoice Data request without a ShipmentIdentification Number and having multiple
invoices, InvoiceReferenceType with value “CU” must be in each ExportDeclaration instance, so that all
ExportDeclaration instance will be included in merged data.

Listed below are allowed invoice level reference type codes:

Reference type Description

PAGE 308 OF 417

MYDHL API – DEVELOPER GUIDE

ACL Parent Shipment ID for BBX

CID Customer Identifier
CN Contract Number
CU Consignor reference number
ITN US Export declaration reference ID
MRN Movement Reference number
UCN Unique reference of a consignment (UCRN)
OID Order Number
PON Purchase Order Number
RMA RMA Number

14.2.4.2.15 UploadInvoiceData Input:

InvoiceData/ExportDeclarations/ExportDeclaration/ExportLineItems

ExportLineItems contains a child node ExportLineItem which can repeat up to 999 occurences. This
section is used to provide details of invididual items to be listed in the commercial invoice.

PAGE 309 OF 417

MYDHL API – DEVELOPER GUIDE

ExportLineItem requires several mandatory fields – ItemNumber, Quantity,

QuantityUnitOfMeasurement, ItemDescription, UnitPrice and ManufacturingCountryCode.

14.2.4.2.15.1 UploadInvoiceData Input: InvoiceData/ExportDeclarations/ExportDeclaration

/ExportLineItems ExportLineItem/ItemReferences (0:1)

ItemReferences section contains child node ItemReference that can be repeated up to max 100
occurences. Data provided in this section is passed on to the manifest data. First five ItemReference in
request message can be printed in templates COMMERCIAL_INVOICE_P_10 and
COMMERCIAL_INVOICE_L_10.

Listed below are allowed item level reference type codes:

Reference type Description

AAJ Delivery Order number
ABW Stock Keeping Unit
ALX Model
AFE Export Control Classification Number (ECCN)
BRD Brand
DGC Dangerous Goods Content Identifier
DTC DDTC Eligibility Indicator
DTM DDTC UOM
DTQ DDTC Quantity
DTR DDTC Registration No
ITR DDTC ITAR Exemption No
MAK Make
MID Manufacturers Identification Code
OED Original Export Date
OET Original Export OB Tracking ID
OID Order ID
OOR Original Outbound Carrier
PAN Part No
PON Purchase Order Number
SE Serial number
SON Sales order No
SME DDTC SME Indicator
USM DDTC USML Category Code

PAGE 310 OF 417

MYDHL API – DEVELOPER GUIDE

14.2.4.2.15.2 UploadInvoiceData Input:

InvoiceData/ExportDeclarations/ExportDeclaration/ExportLineItems/ExportLineItem/CustomsPape
rworks (0:1)

CustomsPaperworks will contain child node CustomsPaperwork and used to indicate the document type
code and document ID that corresponds to one ore more associated document(s) for customs declaration
purposes.

Listed below are allowed Customs document type codes:

Paperwork Type Description

972 T2LF Dispense Paiement Droits
AHC Analysis and Health Certificate
ATA ATA Carnet
ATR Preference Certificate ATR
CHD CHED-D (Common Health Entry Document for Feed and Food of Non-Animal Origin
CHP CHED-P (Common Health Entry Document for Products)
CIT CITES Certificate
COO Generic Certificate of Origin
DEX Duty Exemption Certificate
EU1 Preference Certificate EUR1
EU2 Preferential Declaration of Origin on the Invoice - EUR2
EUS End Use Authorization
FMA Certificate of Origin (Form A)
PHY Phytosanitary Certificate
VET Veterinary Entry Document
VEX VAT Exemption Certificate
CRL Control Document
CSD Consolidated Customs Entry
PPY Proof Of Payment
CI2 Export-only Invoice
CIV Customs Invoice Value
DOV Invoice
INV Commercial Invoice
PFI Pro-Forma
ALC Agricultural License
HLC Health Products Regulatory Authority (HPRA) Licensing Requirements
JLC Justice License
LIC Specific Export Licenses

PAGE 311 OF 417

MYDHL API – DEVELOPER GUIDE

LNP License or Permit

PLI Permits & Licenses
DLI Driver's License
NID National Identity Card
PAS Passport
CHA Power of Attorney
CPA Consignee Power of Attorney
POA Power of Attorney (Customer-based)
BEX Branch Letter of Exemption
DGD Dangerous Goods Declaration
IPA Intellectual Property Authorization
T2M T2M Transport Accompanying Document
TAD TAD Transport Accompanying Document T1
TCS Transportation Charges Statement
ROD Receipt on Delivery
EXL DCE Export of Customs Data
HWB House Waybill

14.2.4.3 UploadInvoiceData Input: InvoiceData/Ship

The Ship section outlines the Seller, Buyer, Importer and Exporter for the specific UploadInvoiceData
request. Please note that all the roles’ structures are identical.

The subsequent data merge process takes the Seller, Buyer, Exporter and Importer details provided in
UploadInvoiceData request and ignores any Seller, Buyer, Exporter and Importer information provided
in CreateShipment request.

14.2.4.4 RegistrationNumbers
This is applicable for Seller, Buyer, Exporter and Importer segments.

PAGE 312 OF 417

MYDHL API – DEVELOPER GUIDE

For printing registration numbers in commercial invoice, refer to Appendix: Commercial Invoice
Template Guide on what NumberTypeCode values can be printed across different Commercial Invoice
templates.

PAGE 313 OF 417

MYDHL API – DEVELOPER GUIDE

14.3 UPLOADINVOICEDATA REQUEST – INPUT FIELD LIST

UploadInvoiceData Request Values or

M/O Comments
fields Constraints

UploadInvoiceDataRequest

UploadInvoiceDataRequest/ClientDetail

sso O This field is for internal use only

plant O This field is for internal use only

UploadInvoiceDataRequest/Request

UploadInvoiceDataRequest/Request/ServiceHeader

MessageTime O Timestamp Format:

YYYY-MM-DD(T)hh:mm:ssZ
e.g 2020-01-12T08:41:12Z

MessageReference O AN 36 Message reference, between 28 to 36

characters in length.

WebstorePlatform O AN 20
Reserved for Third Party Vendors identification

WebstorePlatformVersion O AN 15
Reserved for Third Party Vendors identification

ShippingSystemPlatform O AN 20
Reserved for Third Party Vendors identification

ShippingSystemPlatformVersio O AN 15
n Reserved for Third Party Vendors identification

PlugIn O AN 20
Reserved for Third Party Vendors identification

PlugInVersion O AN 15
Reserved for Third Party Vendors identification

UploadInvoiceDataRequest/InvoiceData

UploadInvoiceDataRequest/InvoiceData/ShipmentInfo

PAGE 314 OF 417

MYDHL API – DEVELOPER GUIDE

ShipmentIdentificationNumber M AN 10 Please provide the Shipment Identification

Number (Waybill) of the shipment you wish to
upload CIN Data.

Currency M AN 3 Currency code

UnitOfMeasurement M “SI”,”SU” This field is mandatory which corresponds to

unit of measurement for the dimensions of the
package. Possible values :

- SI, international metric system (KG, CM)

- SU, for UK and US system of measurement

(LB, IN)

PlannedShipDate O Date The planned shipment date for the provided

ShipmentID.

The date component must be in the format:

YYYY-MM-DD. (e.g: 2021-07-29)

UploadInvoiceDataRequest/InvoiceData/ShipmentInfo/Billing

ShipperAccountNumber M AN 12 The DHL account number used for the

shipment. Used as the shipper account number.

Note: Please ensure to provide the same

account details which were used to create the
shipment for successful merging of Commercial
Invoice (CIN) data with Shipment Data.

BillingAccountNumber O AN 12 The DHL account number used for the

shipment.

Note: Please ensure to provide the same

account details which were used to create the
shipment for successful merging of
Commercial Invoice (CIN) data with Shipment
Data.

UploadInvoiceDataRequest/InvoiceData/ShipmentInfo/OutputImageOptions

RequestDHLCustomsInvoice O AN 1 Possible values;

- Y (Yes – using DHL Invoice)

- N (No – using Own Invoice) – (Default)

PAGE 315 OF 417

MYDHL API – DEVELOPER GUIDE

CustomsInvoiceTemplate O AN 25 Customs Invoice template name.

Possible values:

- COMMERCIAL_INVOICE_04
This template can print the Shipper,
Recipient, and Buyer and Importer address
details and is on portrait orientation. (Note:
this template is for exclusive use for
preparing Loose BBX shipment.)

- COMMERCIAL_INVOICE_L_10
This template can print the Shipper,
Recipient, Buyer, and Importer and Exporter
address details and is on landscape
orientation.

- COMMERCIAL_INVOICE_P_10 (default)
This template can print the Shipper,
Recipient and upto two more additional
address details. This template is on portrait
orientation. Note: If customer provided
more than four address roles in the request
message and this template is selected, the
rendered invoice will only contain four
address roles based on order of priority:
Shipper, Recipient, Seller, Importer, Exporter,
Buyer.

Refer to Appendix: Commercial Invoice

Template Guide on what
RegistrationNumber/NumberTypeCode and
OtherCharge/ChargeType can be printed across
different Commercial Invoice templates.

UploadInvoiceDataRequest/InvoiceData/ExportDeclarations (1:1)

UploadInvoiceDataRequest/InvoiceData/ExportDeclarations/ExportDeclaration (1:20)

InvoiceNumber M AN 35 Invoice number.

InvoiceDate M Date Invoice date.

PaymentInfo M Enumerated Possible values:

- CFR – Cost And Freight
- CIF – Cost, Insurance and Freight

PAGE 316 OF 417

MYDHL API – DEVELOPER GUIDE

- CIP – Carriage And Insurance Paid To

- CPT – Carriage Paid To
- DAF – Delivered At Frontier
- DDP – Delivery Duty Paid
- DDU – Delivery Duty Unpaid
- DAP – Delivered At Place
- DAT – Delivered At Terminal
- DEQ – Delivered Ex Quay (Duty Paid)
- DES – Delivered Ex Ship
- EXW – Ex Works
- FAS – Free Alongside Ship
- FCA – Free Carrier
- FOB – Free On Board
- DPU – Delivered at Place Unloaded
ExportReasonType O Enumerated Export Reason Type

Possible values:
PERMANENT
TEMPORARY
RETURN
USED_EXHIBITION_GOODS_TO_ORIGIN
INTERCOMPANY_USE
COMMERCIAL_PURPOSE_OR_SALE
PERSONAL_BELONGINGS_OR_PERSONAL_USE
SAMPLE
GIFT
RETURN_TO_ORIGIN
WARRANTY_REPLACEMENT
DIPLOMATIC_GOODS
DEFENCE_MATERIAL

PlaceOfIncoterm O AN 256 Name of port of departure, shipment or

destination, as required under the applicable
delivery term.

If using Customs Invoice template

COMMERCIAL_INVOICE_P_10 and
COMMERCIAL_INVOICE_L_10, recommended
max length is 25 characters.
ShipmentPurpose O Enumerated Indicates if the shipment was sent for Personal
or Commercial reasons.

Possible values:
- PERSONAL
- COMMERCIAL

PAGE 317 OF 417

MYDHL API – DEVELOPER GUIDE

DocumentFunction M Enumerated Describes for what purpose was the document

details captured and are planned to be used.

Possible values:
- IMPORT
- EXPORT
- BOTH
ExporterCode O AN Exporter Code

Optional field to indicate the type code of

Exporter’s ID number provided in ExporterID tag
– e.g. DUN, SSN, and EIN.
ExporterID O AN Identification Number of the Exporter party.

UploadInvoiceDataRequest/InvoiceData/ExportDeclarations/ExportDeclaration/CustomsDocument
s (0:1)
UploadInvoiceDataRequest/InvoiceData/ExportDeclarations/ExportDeclaration/CustomsDocument
s/CustomsDocument (1:50)
CustomsDocumentType M AN 3 Export declaration customs document type code

Possible values :

- 972, T2LF Dispense Paiement Droits

- AHC, Analysis and Health Certificate

- ATA, ATA Carnet

- ATR, Preference Certificate ATR

- CHD, CHED-D (Common Health Entry

Document for Feed and Food of Non-Animal
Origin

- CHP, CHED-P (Common Health Entry Document

for Products)

- CIT, CITES Certificate

- COO, Generic Certificate of Origin

- DEX, Duty Exemption Certificate

- EU1, Preference Certificate EUR1

- EU2, Preferential Declaration of Origin on the

Invoice - EUR2

- EUS, End Use Authorization

- FMA, Certificate of Origin (Form A)

PAGE 318 OF 417

MYDHL API – DEVELOPER GUIDE

- PHY, Phytosanitary Certificate

- VET, Veterinary Entry Document

- VEX, VAT Exemption Certificate

- CRL, Control Document

- CSD, Consolidated Customs Entry

- PPY, Proof Of Payment

- CI2, Export-only Invoice

- CIV, Customs Invoice Value

- DOV, Invoice

- INV, Commercial Invoice

- PFI, Pro-Forma

- ALC, Agricultural License

- HLC, Health Products Regulatory Authority

(HPRA) Licensing Requirements

- JLC, Justice License

- LIC, Specific Export Licenses

- LNP, License or Permit

- PLI, Permits & Licenses

- DLI, Driver's License

- NID, National Identity Card

- PAS, Passport

- CHA, Power of Attorney

- CPA, Consignee Power of Attorney

- POA, Power of Attorney (Customer-based)

- BEX, Branch Letter of Exemption

- DGD, Dangerous Goods Declaration

- IPA, Intellectual Property Authorization

- T2M, T2M Transport Accompanying Document

- TAD, TAD Transport Accompanying Document

T1

- TCS, Transportation Charges Statement

PAGE 319 OF 417

MYDHL API – DEVELOPER GUIDE

- ROD, Receipt on Delivery

- EXL, DCE Export of Customs Data

- HWB, House Waybill

- ELP, Export Licenses and Permits

CustomsDocumentID M AN 35 Export declaration customs document ID

UploadInvoiceDataRequest/InvoiceData/ExportDeclarations/ExportDeclaration/Remarks
UploadInvoiceDataRequest/InvoiceData/ExportDeclarations/ExportDeclaration/Remarks/Remark
(1:3)
RemarkDescription M AN Customs Invoice's Remarks Description
maximum of 3.

If using Customs Invoice template

COMMERCIAL_INVOICE_04, the invoice can only
print the first RemarkDescription field. The
recommended max length is 20 characters.

If using Customs Invoice template

COMMERCIAL_INVOICE_L_10 or
COMMERCIAL_INVOICE_P_10, the invoice can
print all three RemarkDescription fields. The
recommended max length is 45 characters.
UploadInvoiceDataRequest/InvoiceData/ExportDeclarations/ExportDeclaration/OtherCharges
UploadInvoiceDataRequest/InvoiceData/ExportDeclarations/ExportDeclaration/OtherCharge
s/OtherCharge (1:5)
ChargeValue M 18.3 D Customs Invoice's Other Charges maximum of 5
fields:

charge value can be passed to print in this field

ChargeType M AN 5 5-character Charge Type code

Possible values

- ADMIN, administration fee

- DELIV, delivery fee

- DOCUM, documentation fee

- EXPED, expedite fee

- EXCHA, export fee

- FRCST , freight cost

- SSRGE, fuel surcharge

- LOGST, logistic fee

PAGE 320 OF 417

MYDHL API – DEVELOPER GUIDE

- SOTHR , other fee

- SPKGN, packaging/packing fee

- PICUP, pickup fee

- HRCRG, handling fee

- VATCR, VAT fee

- INSCH , insurance cost

- REVCH, reverse charge

For printing charges in commercial invoice, refer

to Appendix: Commercial Invoice Template
Guide on charge types can be printed across
different Commercial Invoice templates.

UploadInvoiceDataRequest/InvoiceData/ExportDeclarations/ExportDeclaration/InvoiceReferences
UploadInvoiceDataRequest/InvoiceData/ExportDeclarations/ExportDeclaration/InvoiceReferences
/InvoiceReference (1:100)
InvoiceReferenceType M AN 3 Export declaration level reference type code

Possible values:
- ACL, Parent Shipment ID for BBX

- CID, Customer Identifier

- CN, Contract Number

- CU, Consignor reference number

- ITN, US Export declaration reference ID

- MRN, Movement Reference number

- UCN, Unique reference of a consignment

(UCRN)

- OID, Order Number

- PON, Purchase Order Number

- RMA, RMA Number

- AAM, AWB Ref #

- ABT, Goods Declaration number

- ADA, Buyer Reference number

- AES, AES Post Clearance

- AFD, 1496 Item number

- ANT, Consignee Reference number

PAGE 321 OF 417

MYDHL API – DEVELOPER GUIDE

- BKN, Booking Number

- BOL, Bill of Lading Number

- CDN, Customs Declaration number

- COD, Cash On Delivery

- DSC, Weltpaket Reference

- FF, Freight forwarder's reference number

- FN, Freight bill number

- FTR, Post Clearance Exemption US

- HWB, Shipment Identifiers

- IBC, Inbound center reference number

- IPP, Insurance Policy Provider

- LLR, Load list reference

- MAB, Master Airwaybill Number

- MWB, MAWB Reference number

- OBC, Outbound center reference number

- PD, Vendor Reference Number

- PRN, Pickup request number

- RTL, Return Leg waybill number

- SID, Shipment ID 15 Digit CODA

- SS, Seller Reference number

- SWN, Original Waybill number (Return)

Note: In case of multiple invoices and no

ShipmentIdentificationNumber in request,
InvoiceReferenceType with value “CU” must be
in each ExportDeclaration instance, so that all
ExportDeclaration instance will be included in
merged data.

InvoiceReferenceNumber M AN 35 Export declaration level reference number

Note: In case of multiple invoices and no

ShipmentIdentificationNumber in request,
InvoiceReferenceType with value “CU” must be
in each ExportDeclaration instance, so that all
ExportDeclaration instance will be included in
merged data.

PAGE 322 OF 417

MYDHL API – DEVELOPER GUIDE

If printing a Commercial Invoice with a

Shipment Reference, provide the Shipment
reference number in this node with
InvoiceReferenceType value “CU”.

UploadInvoiceDataRequest/InvoiceData/ExportDeclarations/ExportDeclaration/ExportLineItems
UploadInvoiceDataRequest/InvoiceData/ExportDeclarations/ExportDeclaration/ExportLineIte
ms/ExportLineItem (1:999)
ItemNumber M Digit 1- Item sequence number e.g. 1, 2, 3 … 999
999
ItemDescription M AN 512 The description of the line item
Quantity M INT 1 -
10000000 Quantity of the particular line item
00
QuantityUnitOfMeasurement M Enumerated The quantity unit of measurement

- BOX Boxes
- 2GM Centigram
- 2M Centimeters
- 2M3 Cubic Centimeters
- 3M3 Cubic Feet
- M3 Cubic Meters
- DPR Dozen Pairs
- DOZ Dozen
- 2NO Each
- PCS Pieces
- GM Grams
- GRS Gross
- KG Kilograms
- L Liters
- M Meters
- 3GM Milligrams
- 3L Milliliters
- X No Unit Required
- NO Number
- 2KG Ounces
- PRS Pairs
- 2L Gallons
- 3KG Pounds
- CM2 Square Centimeters
- 2M2 Square Feet
- 3M2 Square Inches
- M2 Square Meters
- 4M2 Square Yards
- 3M Yards

PAGE 323 OF 417

MYDHL API – DEVELOPER GUIDE

UnitPrice M D 18.3 Monetary value of each line item

Net weight of the line item

NetWeight O D 15.3 Either a NetWeight or GrossWeight must be

provided for the line item

GrossWeight O D 15.3 Gross weight of the line item

Either a NetWeight or GrossWeight must be

provided for the line item

ManufacturingCountryCode M AN 2 Manufacturing ISO country code

ExportCommodityCode O AN 18 Export Commodity code for the shipment at

item line level
ImportCommodityCode O AN 18 Import Commodity code for the shipment at
item line level

ExportReasonType O Enumerated Possible values;

PERMANENT
TEMPORARY
RETURN
USED_EXIBITION_GOODS_TO_ORIGIN
INTERCOMPANY_USE
COMMERCIAL_PURPOSE_OR_SALE
PERSONAL_BELONGINGS_OR_PERSONAL_USE
SAMPLE
GIFT
RETURN_TO_ORIGIN
WARRANTY_REPLACEMENT
DIPLOMATIC_GOODS
DEFENCE_MATERIAL
TaxesPaid O Enumerated TaxesPaid if set to N. The default is N

Possible values;

- Y
- N

UploadInvoiceDataRequest/InvoiceData/ExportDeclarations/ExportDeclaration/ExportLineIte
ms/ExportLineItem/ItemReferences

UploadInvoiceDataRequest/InvoiceData/ExportDeclarations/ExportDeclaration/ExportLineIte
ms/ExportLineItem/ItemReferences/ItemReference (1:100)

ItemReferenceType M AN 3 Line item reference type code

Possible values:

- AAJ, Delivery Order number

PAGE 324 OF 417

MYDHL API – DEVELOPER GUIDE

- ABW, Stock Keeping Unit

- ALX, Model

- AFE, Export Control Classification number

(ECCN)

- BRD, Brand

- DGC, Dangerous Goods Content Identifier

- DTC, DDTC Eligibility Indicator

- DTM, DDTC UOM

- DTQ, DDTC Quantity

- DTR, DDTC Registration No

- INB, In Bond shipment

- ITR, DDTC ITAR Exemption No

- MAK, Make

- MID, Manufacturers Identification Code

- OED, Original Export Date

- OET, Original Export OB Tracking ID

- OID, Order ID

- OOR, Original Outbound Carrier

- PAN, Part No

- PON, Purchase Order Number

- SE, Serial number

- SON, Sales order No

- SME, DDTC SME Indicator

- USM, DDTC USML Category Code

- AAM, AWB Ref #

- CFR, ECCN License Exemption (CFR#)

- DOM, Domestic indicator CoO (US)

- FOR, Foreign indicator CoO (US)

- USG, Usage

- MAT, Material

- NLR, ECCN No License Required Indicator

PAGE 325 OF 417

MYDHL API – DEVELOPER GUIDE

ItemReferenceNumber M AN 35 Line item reference number

First five ItemReference in request message can

be printed in templates
COMMERCIAL_INVOICE_P_10 and
COMMERCIAL_INVOICE_L_10.

UploadInvoiceDataRequest/InvoiceData/ExportDeclarations/ExportDeclaration/ExportLineIte
ms/ExportLineItem/CustomPaperworks

UploadInvoiceDataRequest/InvoiceData/ExportDeclarations/ExportDeclaration/ExportLineIte
ms/ExportLineItem/CustomPaperworks/CustomPaperwork (1:50)

CustomsPaperworkType M AN 3 Line item customs paperwork type code

Possible values:

- 972, T2LF Dispense Paiement Droits

- AHC, Analysis and Health Certificate

- ATA, ATA Carnet

- ATR, Preference Certificate ATR

- CHD, CHED-D (Common Health Entry

Document for Feed and Food of Non-Animal
Origin

- CHP, CHED-P (Common Health Entry Document

for Products)

- CIT, CITES Certificate

- COO, Generic Certificate of Origin

- DEX, Duty Exemption Certificate

- EU1, Preference Certificate EUR1

- EU2, Preferential Declaration of Origin on the

Invoice - EUR2

- EUS, End Use Authorization

- FMA, Certificate of Origin (Form A)

- PHY, Phytosanitary Certificate

- VET, Veterinary Entry Document

- VEX, VAT Exemption Certificate

- CRL, Control Document

- CSD, Consolidated Customs Entry

PAGE 326 OF 417

MYDHL API – DEVELOPER GUIDE

- PPY, Proof Of Payment

- CI2, Export-only Invoice

- CIV, Customs Invoice Value

- DOV, Invoice

- INV, Commercial Invoice

- PFI, Pro-Forma

- ALC, Agricultural License

- HLC, Health Products Regulatory Authority

(HPRA) Licensing Requirements

- JLC, Justice License

- LIC, Specific Export Licenses

- LNP, License or Permit

- PLI, Permits & Licenses

- DLI, Driver's License

- NID, National Identity Card

- PAS, Passport

- CHA, Power of Attorney

- CPA, Consignee Power of Attorney

- POA, Power of Attorney (Customer-based)

- BEX, Branch Letter of Exemption

- DGD, Dangerous Goods Declaration

- IPA, Intellectual Property Authorization

- T2M, T2M Transport Accompanying Document

- TAD, TAD Transport Accompanying Document

T1

- TCS, Transportation Charges Statement

- ROD, Receipt on Delivery

- EXL, DCE Export of Customs Data

- HWB, House Waybill

- ELP, Export Licenses and Permits

PAGE 327 OF 417

MYDHL API – DEVELOPER GUIDE

CustomsPaperworkID M AN 35
Line item customs paperwork ID

UploadInvoiceDataRequest/InvoiceData/Ship

UploadInvoiceDataRequest/InvoiceData/Ship/Seller

BusinessPartyTypeCode O AN 2 Buyer party type code

Possible values:
- BU (business)
- DC (direct consumer)
- GV (government)
- OT (other)
- PR (private)
- RE (reseller)

UploadInvoiceDataRequest/InvoiceData/Ship/Seller/Contact

PersonName M AN 255 A contact name of a person who acts as Seller

CompanyName M AN 100 The company name the person is working in.

PhoneNumber M AN 70 The contact person phone number. In case of

questions, this person can be called by the
courier.
EmailAddress O AN 70 The email address of the contact person.

MobilePhoneNumber O AN 70 The mobile phone number of the contact person.

UploadInvoiceDataRequest/InvoiceData/Ship/Seller/Address

StreetLines M AN 45 The street line should contain street name and

number of the Seller.
StreetName O AN 250 Seller street name should be sent as separate
attribute if feasible.
BuildingName O AN 50 The Seller building name

StreetNumber O AN 50 Seller street number should be sent as separate

attribute, if feasible.
StreetLines2 O AN 45 Seller additional address information

StreetLines3 O AN 45 Seller additional address information

City M AN 45 Seller city name

PAGE 328 OF 417

MYDHL API – DEVELOPER GUIDE

StateOrProvinceCode O AN 2 2 Letter state code for the USA only

PostalCode M AN 12 Seller postal code

Suburb O AN 45 Seller suburb

CountryCode M AN 2 ISO 2 character code of the Seller country.

UploadInvoiceDataRequest/InvoiceData/Ship/Seller/RegistrationNumbers
UploadInvoiceDataRequest/InvoiceData/Ship/Seller/RegistrationNumbers/RegistrationNumber
(1:10)
Number M AN 35 Registration Number of the Seller.
NumberTypeCode M AN 3 Type of the registration number.

Possible values:

- CNP, Brazil CNPJ/CPF Federal Tax

- DAN, Deferment Account Duties Only

- DTF, Deferment Account Duties, Taxes and Fees

Only

- DUN, Data Universal Numbering System

- EIN, Employer Identification Number

- EOR, Economic Operator Registration ID

- FED, Federal Tax ID

- FTZ, Free Trade Zone ID

- RGP, EU Registered Exporters Registration ID

- SSN, Social Security Number

- STA, State Tax ID

- TAN, Deferment Account Tax Only

- VAT, VAT Registration (VAT / GST)

- DLI, Driver’s License

- NID, National Identity Card

- PAS, Passport

- MID, Manufacturer ID

Not all type codes are applicable for all countries

and role types. Refer to Appendix: Registration
Number Type Codes attached in this document

PAGE 329 OF 417

MYDHL API – DEVELOPER GUIDE

for full list of type codes, their description and

applicable issuing country and shipping roles.

NumberIssuerCountryCode M AN 2 ISO 2-character code of the country where the

Registration Number has been issued by.
UploadInvoiceDataRequest/InvoiceData/Ship/Buyer

BusinessPartyTypeCode O AN 2 Buyer party type code

Possible values:
- BU (business)
- DC (direct consumer)
- GV (government)
- OT (other)
- PR (private)
- RE (reseller)

UploadInvoiceDataRequest/InvoiceData/Ship/Buyer/Contact

PersonName M AN 255 A contact name of a person who acts as Buyer

CompanyName M AN 100 The company name the person is working in.

PhoneNumber M AN 70 The contact person phone number. In case of

questions, this person can be called by the
courier.
EmailAddress O AN 70 The email address of the contact person.

MobilePhoneNumber O AN 70 The mobile phone number of the contact person.

UploadInvoiceDataRequest/InvoiceData/Ship/Buyer/Address
StreetLines M AN 45 The street line should contain street name and
number of the Buyer.
StreetName O AN 250 Buyer street name should be sent as separate
attribute if feasible.
BuildingName O AN 50 The Buyer building name

StreetNumber O AN 50 Buyer street number should be sent as separate

attribute, if feasible.
StreetLines2 O AN 45 Buyer additional address information

StreetLines3 O AN 45 Buyer additional address information

City M AN 45 Buyer city name

PAGE 330 OF 417

MYDHL API – DEVELOPER GUIDE

StateOrProvinceCode O AN 2 2 Letter state code for the USA only

PostalCode M AN 12 Buyer postal code

Suburb O AN 45 Buyer suburb

CountryCode M AN 2 ISO 2 character code of the Buyer country.

UploadInvoiceDataRequest/InvoiceData/Ship/Buyer/RegistrationNumbers
UploadInvoiceDataRequest/InvoiceData/Ship/Buyer/RegistrationNumbers/RegistrationNumber
(1:10)
Number M AN 35 Registration Number of the Buyer.
NumberTypeCode M AN 3 Type of the registration number.

Possible values:

- CNP, Brazil CNPJ/CPF Federal Tax

- DAN, Deferment Account Duties Only

- DTF, Deferment Account Duties, Taxes and Fees

Only

- DUN, Data Universal Numbering System

- EIN, Employer Identification Number

- EOR, Economic Operator Registration ID

- FED, Federal Tax ID

- FTZ, Free Trade Zone ID

- RGP, EU Registered Exporters Registration ID

- SSN, Social Security Number

- STA, State Tax ID

- TAN, Deferment Account Tax Only

- VAT, VAT Registration (VAT / GST)

- DLI, Driver’s License

- NID, National Identity Card

- PAS, Passport

- MID, Manufacturer ID

Not all type codes are applicable for all countries

and address types. Refer to Appendix:
Registration Number Type Codes attached in this
document for full list of type codes, their

PAGE 331 OF 417

MYDHL API – DEVELOPER GUIDE

description and applicable issuing country and

shipping roles.

NumberIssuerCountryCode M AN 2 ISO 2-character code of the country where the

Registration Number has been issued by.
UploadInvoiceDataRequest/InvoiceData/Ship/Exporter
BusinessPartyTypeCode O AN 2 Exporter party type code

Possible values:
- BU (business)
- DC (direct consumer)
- GV (government)
- OT (other)
- PR (private)
- RE (reseller)

UploadInvoiceDataRequest/InvoiceData/Ship/Exporter/Contact

PersonName M AN 255 A contact name of a person who acts as Exporter

CompanyName M AN 100 The company name the person is working in.

PhoneNumber M AN 70 The contact person phone number. In case of

questions, this person can be called by the
courier.
EmailAddress O AN 70 The email address of the contact person.

MobilePhoneNumber O AN 70 The mobile phone number of the contact person.

UploadInvoiceDataRequest/InvoiceData/Ship/Exporter/Address
StreetLines M AN 45 The street line should contain street name and
number of the Exporter.
StreetName O AN 250 Exporter street name should be sent as separate
attribute if feasible.
BuildingName O AN 50 The Exporter building name

StreetNumber O AN 50 Exporter street number should be sent as

separate attribute, if feasible.
StreetLines2 O AN 45 Exporter additional address information

StreetLines3 O AN 45 Exporter additional address information

City M AN 45 Exporter city name

StateOrProvinceCode O AN 2 2 Letter state code for the USA only

PostalCode M AN 12 Exporter postal code

PAGE 332 OF 417

MYDHL API – DEVELOPER GUIDE

Suburb O AN 45 Exporter suburb

CountryCode M AN 2 ISO 2 character code of the Exporter country.

UploadInvoiceDataRequest/InvoiceData/Ship/Exporter/RegistrationNumbers
UploadInvoiceDataRequest/InvoiceData/Ship/Exporter/RegistrationNumbers/RegistrationNumber
(1:10)
Number M AN 35 Registration Number of the Exporter.
NumberTypeCode M AN 3 Type of the registration number.

Possible values:

- CNP, Brazil CNPJ/CPF Federal Tax

- DAN, Deferment Account Duties Only

- DTF, Deferment Account Duties, Taxes and Fees

Only

- DUN, Data Universal Numbering System

- EIN, Employer Identification Number

- EOR, Economic Operator Registration ID

- FED, Federal Tax ID

- FTZ, Free Trade Zone ID

- RGP, EU Registered Exporters Registration ID

- SSN, Social Security Number

- STA, State Tax ID

- TAN, Deferment Account Tax Only

- VAT, VAT Registration (VAT / GST)

- DLI, Driver’s License

- NID, National Identity Card

- PAS, Passport

- MID, Manufacturer ID

Not all type codes are applicable for all countries

and address types. Refer to Appendix:
Registration Number Type Codes attached in this
document for full list of type codes, their
description and applicable issuing country and
shipping roles.
NumberIssuerCountryCode M AN 2 ISO 2-character code of the country where the
Registration Number has been issued by.

PAGE 333 OF 417

MYDHL API – DEVELOPER GUIDE

UploadInvoiceDataRequest/InvoiceData/Ship/Importer
BusinessPartyTypeCode O AN 2 Importer party type code

Possible values:
- BU (business)
- DC (direct consumer)
- GV (government)
- OT (other)
- PR (private)
- RE (reseller)

UploadInvoiceDataRequest/InvoiceData/Ship/Importer/Contact

PersonName M AN 255 A contact name of a person who acts as Importer

CompanyName M AN 100 The company name the person is working in.

PhoneNumber M AN 70 The contact person phone number. In case of

questions, this person can be called by the
courier.
EmailAddress O AN 70 The email address of the contact person.

MobilePhoneNumber O AN 70 The mobile phone number of the contact person.

UploadInvoiceDataRequest/InvoiceData/Ship/Importer/Address
StreetLines M AN 45 The street line should contain street name and
number of the Importer.
StreetName O AN 250 Importer street name should be sent as separate
attribute if feasible.
BuildingName O AN 50 The Importer building name

StreetNumber O AN 50 Importer street number should be sent as

separate attribute, if feasible.
StreetLines2 O AN 45 Importer additional address information

StreetLines3 O AN 45 Importer additional address information

City M AN 45 Importer city name

StateOrProvinceCode O AN 2 2 Letter state code for the USA only

PostalCode M AN 12 Importer postal code
Suburb O AN 45 Importer suburb

CountryCode M AN 2 ISO 2 character code of the Importer country.

UploadInvoiceDataRequest/InvoiceData/Ship/Importer/RegistrationNumbers

PAGE 334 OF 417

MYDHL API – DEVELOPER GUIDE

UploadInvoiceDataRequest/InvoiceData/Ship/Importer/RegistrationNumbers/RegistrationNumber
(1:10)
Number M AN 35 Registration Number of the Importer.
NumberTypeCode M AN 3 Type of the registration number.

Possible values:

- CNP, Brazil CNPJ/CPF Federal Tax

- DAN, Deferment Account Duties Only

- DTF, Deferment Account Duties, Taxes and Fees

Only

- DUN, Data Universal Numbering System

- EIN, Employer Identification Number

- EOR, Economic Operator Registration ID

- FED, Federal Tax ID

- FTZ, Free Trade Zone ID

- RGP, EU Registered Exporters Registration ID

- SSN, Social Security Number

- STA, State Tax ID

- TAN, Deferment Account Tax Only

- VAT, VAT Registration (VAT / GST)

- DLI, Driver’s License

- NID, National Identity Card

- PAS, Passport

- MID, Manufacturer ID

Not all type codes are applicable for all countries

and role types. Refer to Appendix: Registration
Number Type Codes attached in this document
for full list of type codes, their description and
applicable issuing country and shipping roles.
NumberIssuerCountryCode M AN 2 ISO 2-character code of the country where the
Registration Number has been issued by.

PAGE 335 OF 417

MYDHL API – DEVELOPER GUIDE

14.4 UPLOADINVOICEDATA - OUTPUT

The following diagram shows an overview of the response structure. The critical information to
derive from this response are the notification codes for the response.

14.4.1 UploadInvoiceData Response Schema Diagram

Each of the individual sections of ShipmentResponse is shown below in schema diagram, with context,
and a detailed description of each field follows in the Output Field List.

PAGE 336 OF 417

MYDHL API – DEVELOPER GUIDE

14.4.2 UploadInvoiceData Response Output: Response

The Response structure includes the ServiceHeader which includes MessageTime, MessageReference
and ServiceInvocationID. MessageReference which is taken from the request and MessageTime
shows when the request has been processed on DHL side. Customer can track messages by
ServiceInvocationID.

14.4.3 UploadInvoiceData Response Output: Notification

The Notification structure includes the result code and message, based on the results of the processing.
Successful messages will include a zero error code and no corresponding message, while exceptions have
both code and message.

14.4.3 UploadInvoiceData Response Output: Warning

The Warning structure includes the result code and message, based on the results of the processing.
This is for future use.

PAGE 337 OF 417

MYDHL API – DEVELOPER GUIDE

14.5 UPLOADINVOICEDATA RESPONSE – OUTPUT FIELD LIST

UploadInvoiceData Response XML Mandatory/ Values or

Comments
fields (Source) Optional Constraints

UploadInvoiceDataResponse/Response/ServiceHeader

The format of the should

be YYYY-MM-
MessageTime M TIMESTAMP DD(T)hh:mm:ssZ
e.g 2011-01-
12T18:41:12Z
MessageReference as sent
MessageReference O AN 36
from request message
DHL internal service
ServiceInvocationID M invocation ID to expedite
support

UploadInvoiceDataResponse/Notification

Error > 0 or Success Code

@code M N6
=0
Message M Response Message, see
Error codes for more
details
UploadInvoiceDataResponse/Warning
@code M N6 For future use
Message M For future use

PAGE 338 OF 417

MYDHL API – DEVELOPER GUIDE

15. DOCUMENTIMAGEREQUEST

15.1 DOCUMENTIMAGEREQUEST - DESCRIPTION

The DocumentImageRequest Operation will allow customer to retrieve their own shipment’s images such
as Commercial Invoice, Waybill Document and Customs Entry paperwork documents from DHL Express
image repository. Customer will receive the image(s) in base64 encoded string.

Customer can perform the document search by:

1. Single AWB + single DocumentType
2. Single AWB + multiple Document Type

The document image retrieve request is successfully executed if the correct combination of shipper
account number, Waybill number, the shipment’s pickup year and month and document type name is
sent in the request.

Important Note: DocumentImageRequest service is not enabled by default and must be requested per
customer. To enable use of DocumentImageRequest service, please contact your DHL Express IT
representative.

PAGE 339 OF 417

MYDHL API – DEVELOPER GUIDE

15.2 DOCUMENTIMAGEREQUEST - INPUT

The following diagram shows an overview of the request input structure.

15.2.1 DocumentImageRequest Schema Diagram

Each of the individual sections of DocumentImageRequest is shown below in schema diagram, with
context, and a detailed description of each field follows in the Input Field List.

15.2.2 DocumentImageRequest Input: ClientDetail

Within the DocumentImageRequest Service, the ClientDetail is an optional node for internal reference
use, and does not affect functionality.

15.2.3 DocumentImageRequest Input: Request

Optional section to populate information used to identify customer request for troubleshooting or
tracking. DHL Express recommends that this information is provided.

PAGE 340 OF 417

MYDHL API – DEVELOPER GUIDE

15.2.4 DocumentImageRequest Input: DocumentImages

Mandatory section to populate information for retrieving the images such as Commercial Invoice and
Waybill Document.

15.2.4.1 DocumentImageRequest Input: DocumentImages/ShipmentIdentificationNumber

PAGE 341 OF 417

MYDHL API – DEVELOPER GUIDE

This field is mandatory which corresponds to the waybill number associated to the shipment.
DocumentImageRequest service will perform validation on this field to retrieve the image data with
respective Shipment Data.

Note: Please ensure to provide the same waybill number which was generated after successful shipment
creation for the successful retrieve of Document Images.

15.2.4.2 DocumentImageRequest Input: DocumentImages/DocumentTypes

This field is mandatory which corresponds to the document type names. DocumentImageRequest service
will perform validation on this field as the only allowed values are:
• CUSTOMS_ENTRY
• WAYBILL
• COMMERCIAL_INVOICE

15.2.4.3 DocumentImageRequest Input: DocumentImages/ShipperAccountNumber

This field is mandatory that will be used to undergo account validation process (if needed).

PAGE 342 OF 417

MYDHL API – DEVELOPER GUIDE

Note: Please ensure to provide the same account details which were used to create the shipment for
successful retrieve of Document Images.

15.2.4.4 DocumentImageRequest Input: DocumentImages/ShipmentPickupYearAndMonth

This field is mandatory having format of YYYY-MM to retrieve the document images from the provided
month.

15.2.4.5 DocumentImageRequest Input: DocumentImages/OutputImageOptions

This field is optional which corresponds to image options for document image result.
There are 3 children elements:
• DocumentImageFormat – this field is optional which corresponds to provide the image mime type
i.e. PDF and TIFF.
• AllInOnePDF – this field is optional with default value as N.
When provided “Y”, merge all resulting images in one PDF file with multiple pages.
• CompressedPackage – this field is optional with default value as N.
When provided “Y”, return zipped file for the resulting images.

PAGE 343 OF 417

MYDHL API – DEVELOPER GUIDE

PAGE 344 OF 417

MYDHL API – DEVELOPER GUIDE

15.3 DOCUMENTIMAGEREQUEST – INPUT FIELD LIST

DocumentImageRequest Values or
M/O Comments
fields Constraints

DocumentImageRequest

DocumentImageRequest/ClientDetail

sso O This field is for internal use only

plant O This field is for internal use only

DocumentImageRequest/Request

DocumentImageRequest/Request/ServiceHeader

MessageTime O Timestamp Format:

YYYY-MM-DD(T)hh:mm:ssZ
e.g 2020-01-12T08:41:12Z

MessageReference O AN 36 Message reference, between 28 to 36

characters in length.

WebstorePlatform O AN 20
Reserved for Third Party Vendors identification

WebstorePlatformVersion O AN 15
Reserved for Third Party Vendors identification

ShippingSystemPlatform O AN 20
Reserved for Third Party Vendors identification

ShippingSystemPlatformVersio O AN 15
n Reserved for Third Party Vendors identification

PlugIn O AN 20
Reserved for Third Party Vendors identification

PlugInVersion O AN 15
Reserved for Third Party Vendors identification

DocumentImageRequest/DocumentImages

DocumentImageRequest/DocumentImages/DocumentImage

PAGE 345 OF 417

MYDHL API – DEVELOPER GUIDE

ShipmentIdentificationNumber M AN 10 Please provide the Shipment Identification

Number (Waybill) of the shipment you wish to
retrieve document images.

ShipperAccountNumber M AN 12 The DHL account number used for the

shipment. Used as the shipper account number.

Note: Please ensure to provide the same

account details which were used to create the
shipment for successful retrieve of Document
Images.

ShipmentPickupYearAndMonth M YYYY-MM This field is mandatory which corresponds to

the month and year when the shipment is
physically handed over to DHL courier.

DocumentImageRequest/DocumentImages/DocumentImage/DocumentTypes(1:1)

DocumentImageRequest/DocumentImages/DocumentImage/DocumentTypes/DocumentType(1:3)

DocumentTypeName M AN This field is mandatory which corresponds to

the document type image to be searched.

Possible Values:

• CUSTOMS_ENTRY
• WAYBILL
• COMMERCIAL_INVOICE

DocumentImageRequest/DocumentImages/DocumentImage/OutputImageOptions(0:1)

DocumentImageFormat O AN4 The preferred image mime type of the image(s)

returned in response

Possible Values:

• PDF
• TIFF

AllInOnePDF O Enum Possible Values: Y and N

“Y”, merge all resulting images in one PDF file
with multiple pages.
“N”, do not merge in one PDF file. This is default.
Note: this option is not applicable when
DocumentImageFormat is set as TIFF.

CompressedPackage O Enum Possible Values: Y and N

“Y”, return zipped file for the resulting images.

PAGE 346 OF 417

MYDHL API – DEVELOPER GUIDE

“N”, default behavior

PAGE 347 OF 417

MYDHL API – DEVELOPER GUIDE

15.4 DOCUMENTIMAGERESPONSE - OUTPUT

The following diagram shows an overview of the response structure. The critical information to derive
from this response are the notification codes for the response together with the DocumentImage
section that will contain the image(s) search results.

15.4.1 DocumentImageResponse Schema Diagram

Each of the individual sections of response is shown below in schema diagram, with context, and a
detailed description of each field follows in the Output Field List.

PAGE 348 OF 417

MYDHL API – DEVELOPER GUIDE

15.4.2 DocumentImageResponse Output: Response

The Response structure includes the ServiceHeader which includes MessageTime, MessageReference
and ServiceInvocationID. MessageReference which is taken from the request and MessageTime shows
when the request has been processed on DHL side. Customer can track messages by
ServiceInvocationID.

15.4.3 DocumentImageResponse Output: Notification

The Notification structure includes the result code and message, based on the results of the processing.
Successful messages will include a zero error code and no corresponding message, while exceptions have
both code and message.

15.4.3 DocumentImageResponse Output: Warning

The Warning structure includes the result code and message, based on the results of the processing.
This is for future use.

15.4.4 DocumentImageResponse Output: DocumentImages

PAGE 349 OF 417

MYDHL API – DEVELOPER GUIDE

This section returns the requested Document Images having 4 children elements as below:

• ShipmentIdentificationNumber - To return shipment identifier tied up to the image /

document

• DocumentType – the same value as provided in request message

• DocumentImageFormat – the format of the document image as provided in request

message. Possible values are PDF, TIFF, ZIP

• DocumentContent – image file or compressed zipped file in encoded base4 string

PAGE 350 OF 417

MYDHL API – DEVELOPER GUIDE

15.5 DOCUMENTIMAGERESPONSE – OUTPUT FIELD LIST

DocumentImageResponse XML fields Mandatory/ Values or

Comments
(Source) Optional Constraints

DocumentImageResponse/Response/ServiceHeader

The format should be YYYY-MM-

MessageTime M TIMESTAMP DD(T)hh:mm:ssZ
e.g 2011-01-12T18:41:12Z
MessageReference as sent from
MessageReference O AN 36
request message
DHL internal service invocation
ServiceInvocationID M
ID to expedite support

DocumentImageResponse/Notification

@code M N6 Error > 0 or Success Code = 0

Message M Response Message, see Error
codes for more details
DocumentImageResponse/Warning
@code M N6 Return Warning Codes
Message M Return Warning Messages
DocumentImageResponse/DocumentImages/DocumentImage(1:50)
To return shipment identifier
ShipmentIdentificationNumber M tied up to the image /
document

DocumentType M The same value as provided in

Request Message

- COMMERCIAL_INVOICE
- WAYBILL
- CUSTOMS_ENTRY
- PDFDOCUMENT
(indicating merged PDF
images)
- ARCHIVE (indicating
compressed zip file)
DocumentImageFormat M The format of the document
image as provided in request
message

- PDF
- TIFF

PAGE 351 OF 417

MYDHL API – DEVELOPER GUIDE

- ZIP

DocumentContent M Encoded base64 image file or

zip file

PAGE 352 OF 417

MYDHL API – DEVELOPER GUIDE

16 APPENDIX

RATE REQUEST AND SHIPMENT REQUEST ERROR CODES AND MESSAGES

The following table contains the possible error for the Rate and Shipment Request processes. The
errors are broken down into categories for presentation.

Rate Request Errors

Error Error Text
Code
8032 Not authorized to use this service. Please contact your DHL Express
representative.

8003 Account not allowed for this service. Please contact your DHL Express
representative.

CAPABILITY AND QUOTATION ERRORS- RATEREQUEST AND

SHIPMENTREQUEST
For capability and quotation error codes, some errors are not possible to achieve based on schema
validation (for required fields, field format, etc).

Capability and Quotation Errors

(Rate and Shipment Requests)
Error Error Text
Code
996 The requested product(s) not available based on your search criteria.
1001 The requested product(s) not available based on your search criteria.
1003 Pick-up service is not provided on this day.
1004 Product not available between this origin and destination.
340001 The origin country code could not be found. Please check the country code.
340002 The destination country code could not be found. Please check the country
code.
340003 The payment country code could not be found.
340004 The location information is missing. At least one attribute post code, city name
or suburb name should be provided
340005 The pickup date is missing. The pickup date is a mandatory field.
340006 The ready time is missing. This is a mandatory parameter.
340007 The commodity code could not be found, please check the commodity code.
340008 The piece weight is missing. This is mandatory information.
340009 The number of pieces is missing.
340010 The total shipment volume is missing.
340011 The maximum piece weight is missing.
340012 The maximum piece height is missing.
340013 The maximum piece length is missing.
340014 The maximum piece width/diameter is missing.

PAGE 353 OF 417

MYDHL API – DEVELOPER GUIDE

340015 The declared value is missing.

340016 The piece type is invalid.
340017 The unit of weight is missing.
340018 The declared value cannot exceed the limit set for the country.
340019 Unknown unit of measure for weight.
340020 Unknown unit of measure for dimensions.
340021 The currency is missing.
340022 The maximum piece weight is greater than the total shipment weight.
340023 Unknown currency symbol.
340024 The global or local product code(s) missing.
340025 The global or local service code(s) missing.
340026 Invalid combination of units of weight and dimension.
340027 Invalid product service combination.
340028 The unit of measure is missing.
340029 UOM should be same for all dimensions
340030 Unknown Generic Criteria code
340031 The format of the dimensions is not correct. Please check the dimensions
format.
340032 The format of the weight is not correct. Please check the weight format.
340033 Invalid ready time format
340035 The unit of dimension is missing
340036 Outbound departure date should have format YYYY-MM-DD
340038 VLDPICKUP = N set in the request then Facility Departure Date should be part
of request
340039 VLDPICKUP = Y set in the request then Facility Departure Date should NOT be
part of request
340040 The only allowed operators are 'eq'- equal, 'ge' - greater than or equal, 'gt' -
greater than
420501 The origin country code could not be found. Please check the country code.
420502 The destination country code could not be found. Please check the country
code.
420503 The payment country code could not be found.
420504 The origin location is invalid. Please check the data.
420505 The destination location is invalid. Please check the data.
420506 Postcode not found. Expected formats: <country specific post code format>
410201 Pick-up service is not provided on this day.
410202 The pickup date is outside of sliding window: dateFrom-dateTo
410203 Ready time is outside of pickup window
410301 Product not available between this origin and destination (network segment).
410302 Temporary network target change
410303 Avaliable products removed by Marketed filtering
410304 No products available
410101 The shipment weight exceeds max
410102 The shipment height exceeds max
410103 The shipment length exceeds max
410104 The shipment width/diameter exceeds max
410105 The requested product(s) not available

PAGE 354 OF 417

MYDHL API – DEVELOPER GUIDE

410106 The piece weight exceeds max

410107 The piece height exceeds max
410108 The piece length exceeds max
410109 The piece width/diameter exceeds max
410110 The shipment weight exceeds min
410111 The shipment height exceeds min
410112 The shipment length is not within the restrictions
410113 The shipment width/diameter under min
410114 The min piece dimension not reached
410115 The mid piece dimension not reached
410116 The max piece dimension not reached
410117 The minimum piece weight not met
410118 Number of pieces exceeded
410119 The min shipment dimension not reached
410120 The mid shipment dimension not reached
410121 The max shipment dimension not reached
410122 The minimum shipment weight not met
410123 The max shipment declared value exceeded
410124 Geographical market rule applied
410125 Minimal inbound currency value not met
410126 Maximum inbound currency value exceeded
410127 Minimum number of pieces not met
410128 Minimal outbound currency value not met
410129 Maximum outbound currency value exceeds
410130 Minimal number of pallet not met
410131 Maximum number of pallet exceeds
410132 Minimal pallet weight not met
410133 Maximum pallet weight exceeds
410134 The max(length; width; height) piece exceeds max
410135 Requested product(s) not available at origin <list of products global/local
separated by ", ">
410136 Requested product(s) not available at destination <list of products global/local
separated by ", ">
410137 Product filtered out on delivery side because actual delivery time configured in
TTS is greater than marketed delivery time configured in GREF <list of
products separated by ", ">
410138 Requested product(s) not available at payer <list of products global/local
separated by ", ">
410139 Requested product(s) available only with contractual agreement <list of
products global/local separated by ", ">

PAGE 355 OF 417

MYDHL API – DEVELOPER GUIDE

410140 Requested product(s) not available in required network <list of products

global/local separated by ", ">
410501 Pickup PL ambiguity rule applied. More than 1 PL is available for the given PL
attributes.
410502 Pickup PL fallback rule applied : PS->CP
410503 Pickup PL fallback rule applied : PS->CP->P
410504 Pickup PL fallback rule applied : PS->CP->P->C
410505 Pickup PL fallback rule applied : CP->P
410506 Pickup PL fallback rule applied : CP->P->C
410507 Pickup PL fallback rule applied : P->C
410508 Pickup PL fallback rule applied : S->C
410509 Delivery PL ambiguity rule applied. More than 1 PL is available for the given PL
attributes.
410510 Delivery PL fallback rule applied : PS->CP
410511 Delivery PL fallback rule applied : PS->CP->P
410512 Delivery PL fallback rule applied : PS->CP->P->C
410513 Delivery PL fallback rule applied : CP->P
410514 Delivery PL fallback rule applied : CP->P->C
410515 Delivery PL fallback rule applied : P->C
410517 The origin facility is suspended
410518 The destination facility is suspended

ROUTE CODE ERRORS

For the Shipment service only, the route code is required for most EU countries, so error handling for
that lookup will only be active for those cases. The specific use case is the scenario where the route
code value is not found for the origin address.
Route Errors
(Shipment Requests Only)
Error Error Text Notes (if applicable)
Code
400501 Route Code not found for <address> Condition met if no products are
available for that pickup date.

SHIPMENT DATE VALIDATION

For the Shipment service only, the ShipmentTimestamp is validated to ensure the proposed shipment
date is not in the past, and within 10 days of current date.

PAGE 356 OF 417

MYDHL API – DEVELOPER GUIDE

Shipment Date Errors

(Shipment Requests Only)

Error Error Text Notes (if applicable)

Code

998 The shipment date cannot be in the past or

more than 10 days in future. Please check
the shipment date and retry.

ACCOUNT VALIDATION
For both Rate and Shipment, the account number must be valid and configured for use within the
services. For help for account setup and configuration, please see your DHL integration point of
contact.
Account Validation Errors
(Rate and Shipment Requests)

Error Error Text Notes (if

Code applicable)

998 The account number is not found or invalid.

Please check the account number and retry.

998 The account number is not allowed for PaperLessTrade.

Please check the account number and retry.

LABEL GENERATION ERRORS

For Shipment service, the following errors may occur during label generation.
Label Generation Errors
(Shipment Requests only)
Error Error Text Notes (if
Code applicable)
20001 Neither local nor Network Product Code is present.
20002 Origin country code is absent.
20003 Origin service area code is absent.
20004 Destination country code is absent.
20017 Neither destination postcode nor destination code is
present.
30001 Maximum length of local specific code exceeded.
30002 Invalid postcode format.
40001 Product short name is not found.
40002 Product content code is not found.
40004 Destination code is not found

PAGE 357 OF 417

MYDHL API – DEVELOPER GUIDE

50003 More than one destination service area codes are found.
90001 Unclassified error.
90002 Invalid XML.
90003 Error while accessing the cache.
99999 GLS servers are not reachable.
100002 The Dangerous Goods Content ID requested is invalid.
Please update and try again
100002 The Dry Ice Net Weight is missing in the request for the
Dangerous Goods Content ID: 901. Please update and
try again.
100002 The UN code is missing in the request for the Dangerous
Goods Content ID: E01.
Please update and try again
MANIFEST SUBMISSION ERRORS
For Shipment service, the following errors may occur during submission of the shipment manifest.
Shipment Manifest Errors
(Shipment Requests only)

Error Error Text Notes (if applicable)

Code

400201 Failure during booking

400202 Missing field(s)",

400203 Error occurred while creating GNS521 file

400204 Error while uploading manifest file to FTP

server

400205 Error while transforming result to XML

411402 ShipmentManifest consumer timed out.

PICKUP ERRORS
For select Shipment requests, which include a pickup request (REQUEST_COURIER), the following
errors may occur during processing of the pickup. Each of the pickup adaptor errors below carries
the same Error Code.

Pickup Errors
(Shipment Requests only)

Error Error Text Notes (if applicable)

Code

PAGE 358 OF 417

MYDHL API – DEVELOPER GUIDE

410928 Booking adapter error response failure

PU009a, 'Pickup NOT scheduled. There is no
weekend pickup service at the location.

Booking adapter error responsefailure

PU003, Routing Service could not
determine Origin Service Area. No pickup
scheduled

Booking adapter error response

failure PU004, Account number or
account type is some type of
external billing account. Pickup
Service requires a domestically
billed shipper account. No pickup
scheduled
Booking adapter error responsefailure
PU005, Account number is not found in IBS
records. No pickup scheduled

Booking adapter error responsefailure

PU007a, Account numberspecified has a
credit status of CUTDirected to IBS. No
pickup scheduled

Booking adapter error response failure

PU007b, Account number does not have a
credit standing of "good standing" or
"removed from credit suspension" No
pickup scheduled

Booking adapter error response failure

PU009a, The pickup date is a weekend at
the origin service area that has no pickup
service. No pickup scheduled

Booking adapter error response failure

PU009b, The Pickup Ready-by time from
the client is before the Station Pickup start
time or after the Station Pickup end time.
No pickup scheduled

Booking adapter error response failure

PU009c, The pickup date is a holiday at
(origin service area). No pickup scheduled

Booking adapter error response failure

PU011a, The pickup request time is less
than 1 hour of the station pickup end time.
No pickup scheduled.

PAGE 359 OF 417

MYDHL API – DEVELOPER GUIDE

Booking adapter error response failure

PU011b, At least one day of advance notice
is required for pickup at <location>.
Sufficient notice not provided. No pickup
scheduled

Booking adapter error response failure

PU012, Ready by time is past the station
ready by cutoff of <x>. No pickup
scheduled.

Booking adapter error response failure

PU013a, Insufficient time between pickup
request time and pickup end time. Pickups
require at least one hour before station
pickup end time.

Booking adapter error response failure

PU013b, Insufficient time between (current
time), and (closing time). A business
pickup requires one hour. A residence
pickup requires two hours.

GENERAL ERRORS
Unexpected errors are handled with a standard error message. These error messages also contain a
process id number, which is used during troubleshooting or follow-up.
Shipment Date Errors
(Shipment Requests Only)
Error Error Text Notes (if applicable)
Code
998 Process failure occurred. Process ID Where 9999999 is the process id
associated for that transaction (9999999)

TRACKING ERRORS
For TrackingRequest service, the primary exception for the service will be “Shipment Not Found”, with a
corresponding ConditionCode of 101.
Tracking Errors
Error Error Text
Code
8032 Not authorized to use this service. Please contact your DHL Express
representative.

PAGE 360 OF 417

MYDHL API – DEVELOPER GUIDE

RATEREQUEST LANDEDCOST ERRORS

RateRequest LandedCost Errors

Error Code Description
200101 Landed cost calculation failed.
(<technical error message generated by the exception>)
200101 Internal GTS error during service call.
(<technical error message generated by the exception>)
200101 GTS Duty and Tax Calculator encountered an internal error.
(Duty and Tax Calculation Failed.)
200101 Duty & tax calculation is not possible since full import HS code is not available
200003 Message header segment is undefined or missing.
(Hdr is required)
200003 Message header version is undefined or missing.
(Hdr Ver is required)
200003 Message header date and time is undefined or missing.
(Hdr Dtm is required)
200003 Message header identification is undefined or missing.
(Hdr Id is required)
200003 Message header type is undefined or missing.
(Hdr Ty is required)
200003 Message header system environment code is undefined or missing.
(Hdr SysEnvCd is required)
200003 Message header general information segment is undefined or missing.
(Hdr GI is required)
200003 Message header tracking identifier is undefined or missing.
(Hdr TID is required)
200003 Message header sender segment is undefined or missing.
(Sndr is required)
200003 Message header sender application code is undefined or missing.
(Sndr AppCd is required)
200003 Message header recipient segment is undefined or missing.
(Rcp is required)
200003 Message header recipient application code is undefined or missing.
(Rcp AppCd is required)
200003 Message originator segment is undefined or missing.
(Orgntr is required)
200003 Message header originator application code is undefined or missing.
(Orgntr AppCd is required)
200003 Message header originator username is undefined or missing.
(Orgntr UsrNm is required)

PAGE 361 OF 417

MYDHL API – DEVELOPER GUIDE

200003 Message header originator country code is undefined or missing.

(Orgntr CtryCd is required)
200003 Message main body segment is undefined or missing.
(Bd is required)
200003 Message shipment quote segment is undefined or missing.
(QtdShp is required)
200003 Currency code of insurance charge is required.
(MonAmt SINSV CurCd is required)
200003 Currency code of other charges is required.
(MonAmt MACHG CurCd is required)
200003 Currency code of freight charge is required.
(MonAmt MFCHG CurCd is required)
200003 Payer segment is undefined or missing.
(PY Cust (Required if freight charge not provided) is required)
200003 Payer Account No is undefined or missing
(PY Cust\NtwAccNo (Required if freight charge not provided) is required)
200003 Payer Country Code is undefined or missing
(PY Cust\Addr\ActPntSp\ CtryCd (Required if freight charge not provided) is
required)
200003 Shipper customer segment is undefined or missing.
(SP Cust is required)
200003 Shipper Country Code is undefined or missing
(SP Cust\Addr\ActPntSp\CtryCd is required)
200003 Receiver customer segment is undefined or missing
(RV Cust is required)
200003 Receiver country code is required.
(RV Cust\Addr\ActPntSp\CtryCd is required)
200003 At least one line item is required.
(QtdShp\Ln is required)
200003 Line item's line number is required.
(Ln\LnNo is required)
200003 Line item's unit price is required.
(Ln\MonAmt ACUSV is required)
200003 Currency code of line item's unit price is required.
(Ln\MonAmt ACUSV CurCd is required)
200003 Line item's weight UOM is required.
(Ln\Meas\Wgt\Uom is required)
200003 Line item's import commodity code is required.
(Missing Ln\CmdtClss\Ib is required)
200003 Shipment piece segment is undefined or missing.

PAGE 362 OF 417

MYDHL API – DEVELOPER GUIDE

(QtdPcs is required)
200003 Shipment piece reference field is undefined or missing.
(QtdPcs\Ref is required)
200003 Shipment piece measurement segment is undefined or missing.
(PcsMeas is required)
200003 Piece weight is undefined or missing.
(PcsMeas\Wgt is required)
200003 Piece weight unit of measure (UOM) is required.
(PcsMeas\Wgt\Uom is required)
200003 Piece height dimension is required.
(PcsMeas\H (Required if freight charge not provided) is required)
200003 Piece height dimension UOM is required.
(PcsMeas\H\Uom is required)
200003 Piece length dimension is required.
(PcsMeas\L (Required if freight charge not provided) is required)
200003 Piece length dimension UOM is required.
(PcsMeas\L\Uom is required)
200003 Piece width dimension is required.
(PcsMeas\W (Required if freight charge not provided) is required)
200003 Piece width dimension UOM is required.
(PcsMeas\W\Uom is required)
200003 Request message GenrcRqCritr\TyCd element is required.
(GenrcRqCritr TyCd is required)
200003 Request message GenrcRqCritr\Val element is required.
(GenrcRqCritr Val is required)
200003 Request item breakdown indicator is required. Indicator to receive details of
duties, taxes, fees and surcharges.
(GenrcRqCritr with TyCd: ItmCstBrkdwnInd is required)
200003 Request currency code is required.
(GenrcRqCritr with TyCd: CurCd is required)
200003 Measurement UOM is not supported in GTS.
(Measurement <sourceMeasurementType> could not be found in database)
200003 Measurement UOM is not convertible.
(Measurement <sourceMeasurementType> is a non convertable SubType)
200003 Measurement UOM cannot be converted to the target measurement UOM.
(Cannot convert <sourceMeasurementType> to <destinationMeasurementType>
Measurement of SubType=<sourceMeasurementType> cannot be converted to
SubType=<destinationMeasurementType>)
200003 Source measurement conversion factor is 0.
(srcMeasurement's conversion factor is 0)

PAGE 363 OF 417

MYDHL API – DEVELOPER GUIDE

200003 Internal GTS conversion error.

(caught exception : <Various Java Exception>)
200003 Measurement UOM cannot be converted to the target measurement UOM.
(applyMeasurementConversion : either src or dest measurement SubType is null)
200003 Required characteristics <CHAR TYPE> value is missing.
(<CHAR TYPE> characteristic is missing)
200003 Required fee <FEE TYPE> is missing. (<FEE TYPE> FEE is missing.)
200003 Shipper's state code is required.
(SP Cust\Addr\ActPntSp\Lty\CtryDiv\TyCd where Cd=S is missing)
200003 Carrier name is required.
(DataEl MrchtSelCrrNm is missing)
200000 Invalid message header request type value. Acceptable value is
LandedCostRequest.
(Invalid Hdr Ty Value. Valid value is LandedCostRequest)
200000 Invalid message header originator country code value. Country code not
supported in GTS.
(Invalid Orngtr CtryCd value. Not Supportable Country)
200000 Invalid message header originator country code value. If provided, should be in
alphabetic format with 2 characters.
(Invalid Orngtr CtryCd value. Valid format is [A-Z]{2})
200000 Invalid piece measurement dimension L, W, H UOM value. Dimensions UOM must
be the same.
(Invalid PcsMeas L, W, H UOM value. Dimensions UOM must be the same)
200000 Invalid monetary amount type code value. Acceptable values are insurance
(SINSV), other (MACHG), and freight (MFCHG) charge codes.
(Invalid MonAmt TyCd value. Valid values are SINSV, MACHG, MFCHG)
200000 Invalid Shipment Currency value. Currency code not supported in GTS.
(Invalid Shipment Currency value. Not Supportable Currency)
200000 Invalid message header request type code. Acceptable values are
ItmCstBrkdwnInd|CurCd|ShpPrps|MdOfTrns.
(Invalid GenrcRqCritr TyCd. Only accept values
ItmCstBrkdwnInd|CurCd|ShpPrps|MdOfTrns)
200000 Invalid line item's line number value. Value should not be zero.
(Invalid Ln\LnNo value. Value must be more than 0)
200000 Invalid line item's manufacturing country code value. Country code not supported
in GTS.
(Invalid Ln\ManCtryCd value. Not Supportable Country)
200000 Invalid line item's unit price currency code value. Currency code not supported in
GTS.
(Invalid Ln\MonAmt ACUSV CurCd value. Not Supportable Currency)

PAGE 364 OF 417

MYDHL API – DEVELOPER GUIDE

200000 Invalid line item's unit price currency code value. If provided, should be in
alphabetic format.
(Invalid Ln\MonAmt ACUSV CurCd value. Expected format is [A-Z]{3})
200000 Invalid line item's unit price value. If provided, should be in decimal format.
(Invalid Ln\MonAmt ACUSV value.Value must be BigDecimal and not empty)
200000 Invalid line item's unit price value. Negative value is not allowed.
(Invalid Ln\MonAmt ACUSV value. Only allow positive value)
200000 Invalid line item's quantity value. If provided, should be in integer format.
(Invalid Ln\Qty value.Value must be BigInteger and not empty)
200000 Invalid line item's quantity value. Negative value is not allowed.
(Invalid Ln\Qty value. Only allow positive value)
200000 Invalid line item's quantity UOM. Acceptable values are [PRT, BOX].
(Invalid Ln\Qty uom value. Valid values are [PRT,BOX])
200000 Invalid line item's weight value. If provided, should be in decimal format.
(Invalid Ln\Meas\Wgt value.Value must be BigDecimal and not empty)
200000 Invalid line item's weight value. Negative value is not allowed.
(Invalid Ln\Meas\Wgt value. Only allow positive value)
200000 Invalid line item's weight value. Value exceeds the limit.
(Invalid Ln\Meas\Wgt value. Not Supportable value)
200000 Invalid insurance charge currency code from merchant. Currency code not
supported in GTS.
(Invalid MonAmt SINSV CurCd value. Not Supportable Currency)
200000 Invalid insurance charge currency code from merchant. If provided, should be in
alphabetic format with 3 characters.
(Invalid MonAmt SINSV CurCd value. Valid format is [A-Z]{3})
200000 Invalid insurance charge from merchant. If provided, should be in decimal format.
(Invalid MonAmt SINSV value.Value must be BigDecimal and not empty)
200000 Invalid insurance charge from merchant. Negative value is not acceptable.
(Invalid MonAmt SINSV value. Only allow positive value)
200000 Invalid other charge currency code from merchant. Currency code not supported
in GTS.
(Invalid MonAmt MACHG CurCd value. Not Supportable Currency)
200000 Invalid other charge currency code from merchant. If provided, should be in
alphabetic format with 3 characters.
(Invalid MonAmt MACHG CurCd value. Valid format is [A-Z]{3})
200000 Invalid other charges value. If provided, should be in decimal format.
(Invalid MonAmt MACHG value.Value must be BigDecimal and not empty)
200000 Invalid other charges value. Negative value is not acceptable.
(Invalid MonAmt MACHG value. Only allow positive value)
200000 Invalid freight charge currency code from merchant. Currency code not supported
in GTS. (Invalid MonAmt MFCHG CurCd value. Not Supportable Currency)

PAGE 365 OF 417

MYDHL API – DEVELOPER GUIDE

200000 Invalid freight charge currency code from merchant. If provided, should be in
alphabetic format with 3 characters.
(Invalid MonAmt MFCHG CurCd value. Valid format is [A-Z]{3})
200000 Invalid freight charge value. If provided, should be in decimal format.
(Invalid MonAmt MFCHG value.Value must be BigDecimal and not empty)
200000 Invalid freight charge value. Negative value is not acceptable.
(Invalid MonAmt MFCHG value. Only allow positive value)
200000 Invalid piece' weight value. If provided, should be in decimal format.
(Invalid PcsMeas\Wgt value.Value must be BigDecimal and not empty)
200000 Invalid piece' weight value. Negative value is not acceptable.
(Invalid PcsMeas\Wgt value. Only allow positive value)
200000 Invalid piece' weight UOM value. Weights' UOM not supported in GTS. .
(Invalid PcsMeas\Wgt uom value. Not Supportable Weights' UOM)
200000 Invalid piece' height dimension value. If provided, should be in decimal format.
(Invalid PcsMeas\H value.Value must be BigDecimal and not empty)
200000 Invalid piece' height dimension value. Negative value is not acceptable.
(Invalid PcsMeas\H value. Only allow positive value)
200000 Invalid piece' height dimension UOM value. Dimensions' UOM not supported in
GTS. .
(Invalid PcsMeas\H uom value. Not Supportable Dimensions' UOM)
200000 Invalid piece' length dimension value. If provided, should be in decimal format.
(Invalid PcsMeas\L value. Value must be BigDecimal and not empty.)
200000 Invalid piece' length dimension value. Negative value is not acceptable.
(Invalid PcsMeas\L value. Only allow positive value.)
200000 Invalid piece' length dimension UOM value. Dimensions' UOM not supported in
GTS. .
(Invalid PcsMeas\L uom value. Not Supportable Dimensions' UOM)
200000 Invalid piece' width dimension value. If provided, should be in decimal format.
(Invalid PcsMeas\W value.Value must be BigDecimal and not empty)
200000 Invalid piece' width dimension value. Negative value is not acceptable.
(Invalid PcsMeas\W value. Only allow positive value)
200000 Invalid piece' width dimension UOM value. Dimensions' UOM not supported in
GTS. .
(Invalid PcsMeas\W uom value. Not Supportable Dimensions' UOM)
200000 Invalid shipper account number value. If provided, should be in numeric format.
(Invalid SP Cust\NtwAccNo value. Valid format is \d+)
200000 Invalid shipper’s country code value. If provided, should be in alphabetic format
with 2 characters.
(Invalid SP Cust\Addr\ActPntSp\CtryCd value. Valid format is [A-Z]{2})
200000 Invalid shipper's country code value. Country not supported in GTS.
(Invalid SP Cust\Addr\ActPntSp\CtryCd value. Not Supportable Country)

PAGE 366 OF 417

MYDHL API – DEVELOPER GUIDE

200000 Invalid receiver's country code value. If provided, should be in alphabetic format
with 2 characters.
(Invalid RV Cust\Addr\ActPntSp\CtryCd value. Valid format is [A-Z]{2})
200000 Invalid receiver's country code value. Country not supported in GTS.
(Invalid RV Cust\Addr\ActPntSp\CtryCd value. Not Supportable Country)
200000 Invalid payer account number value. If provided, should be in numeric format.
(Invalid PY Cust\NtwAccNo value. Valid format is \d+)
200000 Invalid payer's country code value. Country code not supported in GTS.
(Invalid PY Cust\Addr\ActPntSp\CtryCd value. Not Supportable Country)
200000 Invalid line item's import commodity code value. If provided, should be in
alphanumeric and dots format.
(Invalid Ln\CmdtClss\Ib value. Valid format is [a-zA-Z0-9.]+)
200000 Invalid line item's part number value. If provided, should be in numeric format.
(Invalid Ln\PartNo value. Valid format is \d+)
200000 Invalid Shipment Purpose. Acceptable values are [PERSONAL, COMMERCIAL,
GIFT] .
(Invalid ShpPrps GenRqCritr\Val. Valid values are
[PERSONAL,COMMERCIAL,GIFT])
200000 Invalid Transport Mode. Acceptable values are [AIR, OCEAN, LAND].
(Invalid MdOfTrns GenrcRqCritr\Val. Valid values are [AIR,OCEAN,LAND])
200000 Provided product category is invalid. Please look at the possible category values
listed under documentation.
210000 DCT failed to calculate freight charge. DCT response do not have required
information.
(No Response Body / Response Missing Required Info from DCT)
200001 At least one item has invalid HS code.
200002 At least one item is Prohibited.
200004 Requested preferential rate not found.
200102 At least one line item encounter issue in landed cost estimation.
200005 Requested trade regime rate not found. Regime ID does not exist or has expired.

RATEREQUEST LANDEDCOST WARNINGS

RateRequest LandedCost Warnings

Warning Description
Code
200200 Duty calculation is not possible since full import HS code is not available.
200201 Landed cost is estimated based on full Import HS code retrieved from product
catalogue.

PAGE 367 OF 417

MYDHL API – DEVELOPER GUIDE

200202 Ballpark landed cost is returned.

200203 The provided HS code is not a valid full Import HS code. Ballpark landed cost is
estimated using the provided 6-digit HS Code.
200204 Provided Import HS code (full or 6-digit) is invalid. Landed cost is estimated based
on full Import HS code retrieved from product catalogue.
200205 Provided Import HS code (full or 6-digit) is invalid. Ballpark landed cost is returned.
200030 Standard duty is not applicable (<INPUT HS CODE>).
200031 Standard duty is not applicable (<INPUT HS CODE>). This tariff code maybe
prohibited.

RATEREQUEST LANDEDCOST ADDITIONALQUANTITYTYPE ALLOWED VALUES

Allowed values for the AdditionalQuantityType field

Quantity
Code Description
PCS pieces (PCS)
DOZ dozen (DOZ)
DPC dozen pieces (DPC)
DPR dozen pairs (DPR)
GRO gross (GRO)
TEN tens (TEN)
HUN hundreds (HUN)
K thousands (K)
PKG package (PKG)
PKT packet (PKT)
PR pair (PR)
UNT units (UNT)
Volume
LTR litres (LTR)
DAL dekalitres (DAL)
HLT hectolitres (HLT)
KL kilolitres (KL)
CMQ cubic centimetres (CMQ)
MTQ cubic meters (MTQ)
KM3 1,000 cubic meters (KM3)
BBL barrels (BBL)
CPS cups (CPS)

PAGE 368 OF 417

MYDHL API – DEVELOPER GUIDE

PT pints (PT)
QT quarts (QT)
GAL gallons (GAL)
Volume of alcohol
LAL litres of alcohol
Volume proof
PFL proof litres
PFG proof gallons
Volume of wine
WL wine litres
WG wine gallons
Weight clean yield
CYG clean yield gram
CYK clean yield kilogram
Weight content
CGM content gram
CKG content kilogram
CTN content ton
Time
HUR Hours
MIN Minutes
SEC Seconds
Area
MTK square meters (MTK)
CMK square centimetres (CMK)
FTK square feet (FTK)
INK square inches (INK)
KMK square kilometres (KMK)
YDK square yards (YDK)
Energy

GJ Gigajoule (GJ)
KWH kilowatt hour (KWH)
MWH megawatt hour (MWH)
GWH gigawatt hour (GWH)
KCAL kilocalorie (KCAL)

PAGE 369 OF 417

MYDHL API – DEVELOPER GUIDE

Frequency

HTZ hertz
KHZ kilohertz
MHZ megahertz
Length

MMT millimetres (MMT)

CMT centimetres (CMT)
MTR meters (MTR)
KTM kilometres (KTM)
LNM linear meters (LNM)
INH inches (INH)
FOT feet (FOT)
YRD yards (YRD)
Weight

MGM milligrams (MGM)

CGM content grams (CGM)
CG centigrams (CG)
GRM grams (GRM)
KGM kilograms (KGM)
T metric tons (T)
ONZ ounces (ONZ)
LBR pounds (LBR)
STN short tons (STN)
TNE tons (TNE)
Playing cards

PC per card
PHC per hundred cards
Power

WTT watts
KWT kilowatts
Pressure

KPA kilopascals
MPA megapascals

PAGE 370 OF 417

MYDHL API – DEVELOPER GUIDE

Radioactivity

MBQ megabecquerels
GBQ giqabecquerels
MCU millicuries
CUR curies
Radioactivity

AC Alternating Current (AC)

ASTM American Society for Testing Materials (ASTM)
BC Basic Cartons (BC)
BOT Bottle (BOT)
BOX Boxes (BOX)
BTL British Thermal Unit (BTL)
BTU_PER_HR British Thermal Unit Per Hour (BTU_PER_HR)
C Celsius (C)
CE_EL Number of Cells (CE_EL)
CT Cartons (CT)
CTL Carrying Capacity in Tons (CTL)
CU Cubic (CU)
CY Clean Yield (CY)
D Denier (D)
DC Direct Current (DC)
DEG Degrees (DEG)
FBM Fibre Meters (FBM)
FIB Fibres (FIB)
GI_FS Grams of Fissile Isotopes (GI_FS)
GRL Gross Lines (GRL)
GT Gross Ton (GT)
GVW Gross Vehicle Weight (GVW)
HP Horse Power (HP)
IMPERIAL_GALLON Imperial Gallon (IMPERIAL_GALLON)
IRC Internal Revenue Code (IRC)
JWL Jewels (JWL)
KG_90PERCENT_SDT Kilogram of Substance 90% Dry (KG_90PERCENT_SDT)
KG_BDC Kilogram of Bio Diesel Content (KG_BDC)

PAGE 371 OF 417

MYDHL API – DEVELOPER GUIDE

KG_BEC Kilogram of Bio Ethanol Content (KG_BEC)

KG_H2O2 Kilogram of Hydrogen Peroxide (KG_H2O2)
KG_K2O Kilogram of Potassium Oxide (KG_K2O)
KG_KOH Kilogram of Potassium Hydroxide (KG_KOH)
KG_METAM Kilogram Methylamines (KG_METAM)
KG_N Kilogram of Nitrogen (KG_N)
KG_NAOH Kilogram of Sodium Hydroxide (KG_NAOH)
KG_NET_MAS Kilogram Net Weight of Dry Matter (KG_NET_MAS)
KG_NETEDA Kilogram Net Drained (KG_NETEDA)
KG_P2O5 Kilogram of Disphosphorus Pentaoxide (KG_P2O5)
KG_TOT_ALC Kilograms of Total Alcohol (KG_TOT_ALC)
KG_U Kilogram of Uranium (KG_U)
KGB Kilogram Brut (KGB)
KGDL Kilogram Dry Lactic Matter (KGDL)
KGL Kilogram Lactic Matter (KGL)
KGND Kilogram Net Drained (KGND)
KN Kilonewtons (KN)
KSB 1000 Standard Bricks (KSB)
KTC Kilogram of Tobacco Content (KTC)
KVA Kilovolt - Amperes (KVA)
KVAR Kilovolt - Amperes Reactive (KVAR)
LIN Linear (LIN)
NM3 Normal Cubic Meter (NM3)
NOP Number of Pieces (NOP)
ODE Ozone Depletion Equivalent (ODE)
PF Proof (PF)
PK Pack (PK)
PWS Percent Weight of Sucrose (PWS)
RPM Revolutions Per Minute (RPM)
SBE Standard Brick Equivalent (SBE)

SETS Sets of Silverware (SETS)

SQ Square (SQ)
ST Sticks (ST)
TJ Gross Caloric Value (TJ)
V Volts (V)

PAGE 372 OF 417

MYDHL API – DEVELOPER GUIDE

WT Weight (WT)
X Quantity Not Required (X)

RATEREQUEST LANDEDCOST CATEGORY CODES

Product Category Group Product Category Code Product Category Description

101 Coats & Jacket

102 Blazers
103 Suits
104 Ensembles
105 Trousers
1.Apparel
106 Shirts & Blouses
107 Dresses
108 Skirts
109 Jerseys, Sweatshirts & Pullovers
110 Sports & Swimwear

PAGE 373 OF 417

MYDHL API – DEVELOPER GUIDE

111 Night & Underwear

112 T-Shirts
113 Tights & Leggings
114 Socks
115 Baby Clothes
116 Clothing Accessories
201 Sneakers
202 Athletic Footwear
2. Footwear
203 Leather Footwear
204 Textile & Other Footwear
301 Spectacle Lenses
302 Sunglasses
3.Eyewear
303 Eyewear Frames
304 Contact Lenses
401 Watches
402 Jewelry
403 Suitcases & Briefcases
4.Accessories
404 Handbags
405 Wallets & Little Cases
406 Bags & Containers
501 Beer
502 Spirits
5.Alcoholic Drinks
503 Wine
504 Cider, Perry & Rice Wine
601 Bottled Water
602 Soft Drinks
603 Juices
6.Non-Alcoholic Drinks
604 Coffee
605 Tea
606 Cocoa
701 Dairy Products & Eggs
702 Meat
703 Fish & Seafood
704 Fruits & Nuts
705 Vegetables
706 Bread & Cereal Products
7.Foods
707 Oils & Fats
708 Sauces & Spices
709 Convenience Food
710 Spreads & Sweeteners
711 Baby Food
712 Pet Food
801 Cigarettes
8.Tobacco Products
802 Smoking Tobacco

PAGE 374 OF 417

MYDHL API – DEVELOPER GUIDE

803 Cigars
804 E-Cigarettes
901 Household Cleaners
902 Dishwashing Detergents
9.Home & Laundry Care 903 Polishes
904 Room Scents
905 Insecticides
1001 Cosmetics
1002 Skin Care
10.Beauty & Personal Care
1003 Personal Care
1004 Fragrances
1101 Toilet Paper
1102 Paper Tissues
1103 Household Paper
11.Tissue & Hyginene Paper
1104 Feminine Hygiene
1105 Baby Diapers
1106 Incontinence
1202 TV, Radio & Multimedia
1203 TV Peripheral Devices
12.Consumer Electronics 1204 Telephony
1205 Computing
1206 Drones
1301 Refrigerators
1302 Freezers
1303 Dishwashing Machines
1304 Washing Machines
1305 Cookers & Oven
1306 Vacuum Cleaners
1307 Small Kitchen Appliances
13.Household Appliances 1308 Hair Clippers
1309 Irons
1310 Toasters
1311 Grills & Roasters
1312 Hair Dryers
1313 Coffee Machines
1314 Microwave Ovens
1315 Electric Kettles
1401 Seats & Sofas
1402 Beds
1403 Mattresses
14.Furniture 1404 Closets, Nightstands & Dressers
1405 Lamps & Lighting
1406 Floor Covering
1407 Kitchen Furniture

PAGE 375 OF 417

MYDHL API – DEVELOPER GUIDE

1408 Plastic & Other Furniture

1501 Analgesics
1502 Cold & Cough Remedies
1503 Digestives & Intestinal Remedies
15.OTC Pharmaceuticals
1504 Skin Treatment
1505 Vitamins & Minerals
1506 Hand Sanitizer
1601 Toys & Games
16.Toys & Hobby 1602 Musical Instruments
1603 Sports Equipment

CREATESHIPMENT AND UPLOADINVOICEDATA REGISTRATION NUMBER TYPE

CODES
Registration Description Issuing Country Applicable Role
Type Code

CNP Brazil CNPJ/CPF Federal Tax BR All

DAN Deferment Account Duties Only All Importer / Exporter

DTF Deferment Account Duties, Taxes All Importer /Exporter

and Fees Only

DUN Data Universal Numbering US All

System

EIN Employer Identification Number US All

EOR Economic Operator Registration AT, BE, BG, CY, CZ, DE, DK, All
ID EE, ES, FI, FR, GR, HR, HU,
IE, IT, LT, LU, LV, MT, NL, PL,
PT, RO, SE, SI, SK

FED Federal Tax ID US All

FTZ Free Trade Zone ID AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, All
AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE,
BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ,
BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD,
CF, CG, CH, CI, CK, CL, CM, CN, CO, CR,
CU, CV, CW, CX, CY, CZ, DE, DJ, DK,
DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET,
FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE,
GF, GG, GH, GI, GL, GM, GN, GP, GQ,
GR, GS, GT, GU, GW, GY, HK, HM, HN,
HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR,
IS, IT, JE, JM, JO, JP, KE, KG, KH, KI,

PAGE 376 OF 417

MYDHL API – DEVELOPER GUIDE

KM, KN, KP, KR, KW, KY, KZ, LA, LB,

LC, LI, LK, LR, LS, LT, LU, LV, LY, MA,
MC, MD, ME, MF, MG, MH, MK, ML,
MM, MN, MO, MP, MQ, MR, MS, MT,
MU, MV, MW, MX, MY, MZ, NA, NC, NE,
NF, NG, NI, NL, NO, NP, NR, NU, NZ,
OM, PA, PE, PF, PG, PH, PK, PL, PM,
PN, PR, PS, PT, PW, PY, QA, RE, RO, RS,
RU, RW, SA, SB, SC, SD, SE, SG, SH, SI,
SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV,
SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK,
TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA,
UG, UM, US, UY, UZ, VA, VC, VE, VG, VI,
VN, VU, WF, WS, YE, YT, ZA, ZM, ZW

RGP EU Registered Exporters AT, BE, BG, CY, CZ, DE, DK, EE, ES, FI, Exporter
FR, GR, HR, HU, IE, IT, LT, LU, LV, MT,
registration ID NL, PL, PT, RO,SE, SI, SK

SDT Import One-Stop-Shop (IOSS) AT, BE, BG, CN, CY, CZ, DE, Shipper
DK, EE, ES, FI, FR, GR, HR,
HU, IE, IT, LT, LU, LV, MT,
NL, PL, PT, RO, SE, SI, SK

SDT Overseas Registered Supplier NZ Shipper

(LVG)

SDT AUSid GST Registration (OSR) AU Shipper

SDT GB VAT (foreign) registration GB Shipper

SDT VAT on E-Commerce (VOEC) NO Shipper

SSN Social Security Number US All

STA State Tax ID US All

TAN Deferment Account Tax Only All Importer / Exporter

VAT VAT Registration (VAT / GST) AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, All
AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE,
BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ,
BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD,
CF, CG, CH, CI, CK, CL, CM, CN, CO, CR,
CU, CV, CW, CX, CY, CZ, DE, DJ, DK,
DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET,
FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE,
GF, GG, GH, GI, GL, GM, GN, GP, GQ,
GR, GS, GT, GU, GW, GY, HK, HM, HN,
HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR,
IS, IT, JE, JM, JO, JP, KE, KG, KH, KI,
KM, KN, KP, KR, KW, KY, KZ, LA, LB,
LC, LI, LK, LR, LS, LT, LU, LV, LY, MA,
MC, MD, ME, MF, MG, MH, MK, ML,
MM, MN, MO, MP, MQ, MR, MS, MT,
MU, MV, MW, MX, MY, MZ, NA, NC, NE,
NF, NG, NI, NL, NO, NP, NR, NU, NZ,
OM, PA, PE, PF, PG, PH, PK, PL, PM,
PN, PR, PS, PT, PW, PY, QA, RE, RO, RS,
RU, RW, SA, SB, SC, SD, SE, SG, SH, SI,
SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV,
SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK,
TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA,

PAGE 377 OF 417

MYDHL API – DEVELOPER GUIDE

UG, UM, US, UY, UZ, VA, VC, VE, VG, VI,
VN, VU, WF, WS, YE, YT, ZA, ZM, ZW

INN Russia bank details section - INN RU Shipper

KPP Russia bank details section – KPP RU Shipper

OGR Russia bank details section – RU Shipper

OGRN

OKP Russia bank details section - RU Shipper

OKPO

MRN Germany Movement Reference DE Shipper

Number

RGP Customs Registration Number CN All

DUN Unified Social Credit Identifier CN All

VAT VAT Registration ID All

DLI Driver's License ID All

NID National Identity Card ID All

PAS Passport ID All

Manufacturers IDentification
MID Global EP
code

SHIPMENT DOCUMENT RETRIEVE ERRORS (EPOD)

Shipment Document Retrieve Error Codes

Error Error Text Notes (if applicable)

Code

100000 Service operation execution finished

successfully

100002 Service operation request message data HP Global Imaging epod

validation failed Service returned error
code:No matching ePODs
for search query

100010 When requesting ePod details account

number and customer role must be provided

PAGE 378 OF 417

MYDHL API – DEVELOPER GUIDE

COMMERCIAL INVOICE TEMPLATES: ROLE REGISTRATION NUMBER TYPE

CODES AND CHARGES
The following table lists the commercial invoice templates and its supported Charge Types and
Registration number type codes that can be rendered for each roles:

CI Template Name RegistrationNumber/NumberTypeCode OtherCharge/ChargeType

Shipper Recipient Buyer Exporter Importer

COMMERCIAL_INVOICE_P_10 VAT, EOR, VAT, EOR VAT, VAT, EOR VAT, EOR Any 5 charge type
SDT EOR
COMMERCIAL_INVOICE_L_10

COMMERCIAL_INVOICE_04 VAT VAT VAT (n/a) (none) FRCST, INSCH

ADDRESSVALIDATE ERRORS

AddressValidate Error and Warning

Error Error Text Notes (if

Code applicable)

3001 The identified service area for the given address is

currently suspended.

3002 The identified service area for the given address is

currently unavailable.

3003 The identified service area for the given address is not
yet open.

3004 The identified service area for the given address is

closed.

3005 The identified service area for the given address has an
unknown status.

3006 The origin country code could not be found. Please

check the country code.

3007 The origin/destination location is invalid. Please check

the data.

3008 PostalCode not found. Expected formats: <country-

specific post code format.>

3009 Address validation failed.

3010 At least a City or PostalCode must be provided in the

request.

PAGE 379 OF 417

MYDHL API – DEVELOPER GUIDE

3011 Service is unavailable for the given origin address.

8032 Not authorized to use this service. Please contact your

DHL Express representative.

8003 Account not allowed for this service. Please contact

your DHL Express representative.

Warning Warning Text Notes (if

Code applicable)

3998 Partial match result found.

3999 Multiple matches found.

UPLOADINVOICEDATA ERRORS

UploadInvoiceData Error and Warning

Error Error Text Notes (if

Code applicable)

7096 The provided Shipment Identification Number is invalid.

Please check the request message and retry.

7097 Exceeded the maximum invoices allowed for a single

shipment. Please check the request message and retry.

7098 Duplicate values found in <xpath>/InvoiceNumber.

Please check the request message and retry.

7099 Missing the Account Number and Shipper Reference in

UploadInvoiceDataRequest/InvoiceData/ExportDeclarati
ons/ExportDeclaration/InvoiceReferences/InvoiceRefere
nce/InvoiceReferenceNumber with
InvoiceReferenceType = ‘CU’ in request. Please check
the request message and retry.

7100 Invalid value of country code in <xpath>. Please check

the request message and retry.

7102 Invalid CustomsDocumentType

<path>/ExportDeclaration/CustomsDocuments/Customs
Document/CustomsDocumentType, please update and
try again.

7103 Invalid reference type

'<xpath>/ExportDeclaration/InvoiceReferences/InvoiceR
eference/InvoiceReferenceType, please update and try
again.

PAGE 380 OF 417

MYDHL API – DEVELOPER GUIDE

7104 Duplicate values found in

<xpath>/ExportDeclaration/InvoiceReferences/InvoiceR
eference/InvoiceReferenceType, please update and try
again.

7105 Invalid ExportReasonType

<xpath>/ExportDeclaration/ExportReasonType, please
update and try again.

7106 Invalid Charge type

<xpath>/ExportDeclaration/OtherCharges/OtherCharge/
ChargeType, please update and try again.

7107 Duplicate values found in

<xpath>/ExportDeclaration/OtherCharges/OtherCharge/
ChargeType, please update and try again.

7108 Invalid QuantityUnitOfMeasure

<xpath>/ExportDeclaration/ExportLineItems/ExportLine
Item/QuantityUnitOfMeasurement, please update and
try again.

7109 Invalid ExportReasonType

<xpath>/ExportDeclaration/ExportLineItems/ExportLine
Item/ExportReasonType, please update and try again.

7110 Invalid ItemReferenceType

<xpath>/ExportDeclaration/ExportLineItems/ExportLine
Item/ItemReferences/ItemReference/ItemReferenceTyp
e, please update and try again.

7111 Duplicate values found in

<xpath>/ExportDeclaration/ExportLineItems/ExportLine
Item/ItemReferences/ItemReference/ItemReferenceTyp
e, please update and try again.

7112 Invalid CustomsPaperworkType

<xpath>/ExportDeclaration/ExportLineItems/ExportLine
Item/CustomsPaperworks/CustomsPaperwork/CustomsP
aperworkType, please update and try again.

7113 Child nodes exceed limit ---

'<xpath>/ExportDeclaration/OtherCharges/OtherCharge
, please update and try again.”

7114 Missing line item Net weight or Gross Weight at

<xpath>, please update the request and try again.

7115 UploadInvoiceData is not allowed for your username.

Please contact your DHL sales representative.

7117 Duplicate values found in

invdatareq:UploadInvoiceDataRequest/InvoiceData/Ship

PAGE 381 OF 417

MYDHL API – DEVELOPER GUIDE

/{0}/RegistrationNumbers/RegistrationNumber/Number
TypeCode

8003 Account not allowed for this service. Please contact

your DHL Express representative.

Warning Warning Text Notes (if

Code applicable)

CREATESHIPMENT ERRORS

CreateShipment Error and Warning

Error Error Text Notes (if

Code applicable)

7002 Total Customs Value

<ShipmentRequest/RequestedShipment/InternationalDetail/Com
modities/CustomsValue field value>must be same per the total of
all individual items value in export line item section. Please update
and re-try it again.

7003 Document image data “DocumentImages/DocImages” or

“PaperlessTradeImages” failed in validation due to wrong data.
Please provide valid image instead of text data.

7004 Signature image data in "ExportDeclaration/SignatureImage"

failed in validation due to wrong data. Please provide valid image
instead of text data.

7005 Customer logo image data failed in validation due to wrong data.
Please provide valid image instead of text data.

7007 The Special Service Code element must contain the value of
<configurable PLT service code eg. WY> for Paperless Trade (PLT)
shipment.

7008 The requested Special Service Code

“ShipmentRequest/RequestedShipment/ShipmentInfo/SpecialSe
rvices/Service/ServiceType” +
“ShipmentRequest/RequestedShipment/ShipmentInfo/SpecialSe
rvices/Service/ServiceType field value” is not available between
this origin and destination. Please validate the products and
services combination (via the RateRequest service) or contact our
customer service.

PAGE 382 OF 417

MYDHL API – DEVELOPER GUIDE

7009 The
'ShipmentRequest/RequestedShipment/ShipmentInfo/LabelOpti
ons/CustomerLogo/LogoImage' cannot be exceed <configurable
logo image size>. Please check the Customer Logo image size and
retry.

7010 The
"ShipmentRequest/RequestedShipment/ShipmentInfo/LabelOpti
ons/CustomerBarcode/Type" is mandatory when
CustomerBarcode/TextInBarcode or
CustomerBarcode/TextBelowBarcode is provided.

7012 You are not allowed to prepare Paperless Trade (PLT) shipment .
Please contact your DHL account manager.

7014 Shipment consolidation is not possible for the shipper country.

Please contact your DHL account manager.

7015 DocumentImages cannot be provided with Packages (piece

details) in request message. Please check the request message
and retry.

7016 Missing “IncludePreviousPieceLabels” in the request message.

Please check the request message and retry.

7017 Exceeded the maximum pieces allowed for a single shipment.

Please check the request message and retry.

7018 Image Upload is not supported for non-PLT shipment.

7019 An email with invalid format has been provided. Please update and
try again.

7020 Invalid global package type code

'shipreq:ShipmentRequest/RequestedShipment/Packages/Reque
stedPackages/PackageTypeCode', please update and try again.

7021 Shipment reference type:

Invalid reference type
'ShipmentRequest/RequestedShipment/ShipmentInfo/Shipment
References/ShipmentReferenceType', please update and try
again.

Piece reference type:

Invalid reference type
'ShipmentRequest/RequestedShipment/Packages/CustomerRefe
renceType', please update and try again

7022 The Piece weight must be greater than <global or customer

profile level> <global or customer profile level minimum weight>.
Please update

PAGE 383 OF 417

MYDHL API – DEVELOPER GUIDE

shipreq:ShipmentRequest/RequestedShipment/Packages/Reque
stedPackages/Weight field value and try again.

7023 The Customs Value must be greater than <global or customer

profile level><global or customer profile level minimum weight
setting>. Please update
shipreq:ShipmentRequest/RequestedShipment/InternationalDeta
il/Commodities/CustomsValue field value and try again.

7025 Document image data “DocumentImages/DocumentImage”

cannot exceed <configurable document image size>. Please
check the document image size and try again.

7026 Invalid payment method for Cash shipments in

"shipreq:ShipmentRequest/RequestedShipment/ShipmentInfo/Bi
lling/ShipmentCost/PaymentMethod". Please update and try
again.

7027 Failure to upload the Paperless Trade (PLT) image. Please check
the document image and try again or contact your DHL technical
representative.

7028 Net weight value must be greater than <global or customer profile
level> <global or customer profile level minimum weight>. Please
update
shipreq:ShipmentRequest/RequestedShipment/ExportDeclaratio
n/ExportLineItem/NetWeight field value and try again.

7029 Failure to send email.

7030 Unsupported combination. <AllInOnePDF> option is only allowed

for PDF output types. Please update
shipreq:ShipmentRequest/RequestedShipment/ShipmentInfo/La
belOptions/DetachOptions/AllInOnePDF and try again.

7031 Image upload is not possible for this shipment at this point.

7032 When RequestDHLCustomInvoice="Y", then the Invoice Number

and Invoice Date under Export Declaration section are required.
Please check the request message and try again.

7033 Packages section is required to be provided in the request

message to perform shipment consolidation. Please check the
request message and try again.

7013 Pickup is not allowed for this shipment date. Please update and re-
try again.

7024 The Paperless Trade (PLT) image file size of the export
documentation is too large. Please ensure that this does not
exceed ''{0}'' and is either a pdf, jpg or png file type.

PAGE 384 OF 417

MYDHL API – DEVELOPER GUIDE

7011 Email address for shipment email notification is required. Please

update and re-try.

7034 Unit Price value must be greater than <”global or customer profile
level” + global or customer profile level minimum Customs
Value>. Please update
shipreq:ShipmentRequest/RequestedShipment/ExportDeclaratio
n/ExportLineItem/UnitPrice field value and retry it again. ”

7035 Shipment charges is mandatory for a CASH shipment. Please

provide shipment charges and resubmit.

7036 Request labels to fit A4 format is applicable for label type of PDF.
Please update and re-try again

7037 Customer is not allowed to request courier pickup. Please contact

your DHL account manager.

7069 Invalid QuantityUnitOfMeasure

ShipmentRequest/RequestedShipment/InternationalDetail/Expor
tDeclaration/ExportLineItems/ExportLineItem{0}/QuantityUnitOf
Measurement, please update and try again.

7070 Invalid BusinessPartyTypeCode

ShipmentRequest/RequestedShipment/Ship/{role}/BusinessPart
yTypeCode, please update and try again.

7071 Invalid CustomsDocumentType

ShipmentRequest/RequestedShipment/InternationalDetail/Expor
tDeclaration/CustomsDocuments/CustomsDocument/CustomsD
ocumentType, please update and try again.

7072 Invalid ExportReasonType

ShipmentRequest/RequestedShipment/InternationalDetail/Expor
tDeclaration/ExportReasonType, please update and try again.

7073 Duplicate values found in

ShipmentRequest/RequestedShipment/InternationalDetail/Expor
tDeclaration/InvoiceReferences/InvoiceReference/InvoiceReferen
ceType, please update and try again.

7074 Invalid reference type

'ShipmentRequest/RequestedShipment/InternationalDetail/Expo
rtDeclaration/InvoiceReferences/InvoiceReference{0}/InvoiceRef
erenceType, please update and try again.

7075 Duplicate values found in

ShipmentRequest/RequestedShipment/InternationalDetail/Expor
tDeclaration/OtherCharges/OtherCharge/ChargeType, please
update and try again.

PAGE 385 OF 417

MYDHL API – DEVELOPER GUIDE

7076 Invalid Charge type

'ShipmentRequest/RequestedShipment/InternationalDetail/Expo
rtDeclaration/OtherCharges/OtherCharge{0}/ChargeType, please
update and try again.

7077 Duplicate values found in

ShipmentRequest/RequestedShipment/InternationalDetail/Expor
tDeclaration/ExportLineItems/ExportLineItem/ItemReferences/It
emReference/ItemReferenceType, please update and try again.

7078 Invalid reference type

'ShipmentRequest/RequestedShipment/InternationalDetail/Expo
rtDeclaration/ExportLineItems/ExportLineItem{0}/ItemReference
s/ItemReference{0}/ItemReferenceType, please update and try
again.

7079 Invalid CustomsPaperworkType

ShipmentRequest/RequestedShipment/InternationalDetail/Expor
tDeclaration/ExportLineItems/ExportLineItem{0}/CustomsPaper
works/CustomsPaperwork{0}/CustomsPaperworkType, please
update and try again.

7080 Missing required field PlaceOfIncoterm

ShipmentRequest/RequestedShipment/InternationalDetail/Expor
tDeclaration/PlaceOfIncoterm, please update and try again.

7081 Request message must contain all BillTo required fields –

BillToCompanyName, BillToContanctName, BillToAddressLine1,
BillToPostcode, BillToCity, BillToCountryCode,
BillToPhoneNumber. Please check and re-try.

7082 Missing required field ChargeType

ShipmentRequest/RequestedShipment/InternationalDetail/Expor
tDeclaration/OtherCharges/OtherCharge/ChargeType, please
update and try again.

7083 Element LabelOptions/RequestTransportLabel value “N” is only

valid for Label-Free Shipment

7084 For the feature "RequestQRCode", please ensure to provide the

DHL Express Label-Free Service code and Advance Shipment
Service Code under SpecialServices/Service/ServiceType

7087 You are not authorized to prepare Label-Free shipment. Please

contact your DHL account manager.

7089 You have provided multiple advance shipment service types.

Please provide any one DHL Express Advance Shipment Service
code in SpecialServices/Service/ServiceType

PAGE 386 OF 417

MYDHL API – DEVELOPER GUIDE

7090 Child nodes exceed limit ---

'ShipmentRequest/RequestedShipment/InternationalDetail/Expo
rtDeclaration/OtherCharges/OtherCharge , please update and try
again.”

7091 Child nodes exceed limit ---

'ShipmentRequest/RequestedShipment/InternationalDetail/Expo
rtDeclaration/ExportLineItems/ExportLineItem/AdditionalInform
ation/AdditionalInformationText , please update and try again.”

7092 If using label template for LBBX, the

ParentShipmentIdentificationNumber field
ShipmentRequest/RequestedShipment/ShipmentInfo/ParentShip
mentIdentificationNumber is required.

7093 You are not authorized to prepare shipment with feature Service
Type = ‘’PM’. Please contact your DHL account manager.

7094 ExportDeclaration cannot be provided with feature Service Type =

’PM’. Please check the request and retry.

7095 ShipmentReference with ShipmentReferenceType = ‘CU’ is

required for feature Service Type = ’PM’. Please check the request
and retry.

7096 The provided Shipment Identification Number is invalid. Please

check the request message and retry.

7097 Exceeded the maximum invoices allowed for a single shipment.

Please check the request message and retry.

7098 Duplicate values found in <xpath>/InvoiceNumber. Please check

the request message and retry.

7099 Missing the Account Number and Shipper Reference in

UploadCINDataRequest/CINData/ExportDeclarations/ExportDecl
aration/InvoiceReferences/InvoiceReference/InvoiceReferenceNu
mber with InvoiceReferenceType = ‘CU’ in request. Please check
the request message and retry.

7100 Invalid value of country code in <xpath>. Please check the request
message and retry.

7101 Invalid value NumberTypeCode <xpath>. Please update and try

again.

7102 Invalid CustomsDocumentType

<path>/ExportDeclaration/CustomsDocuments/CustomsDocume
nt/CustomsDocumentType, please update and try again.

PAGE 387 OF 417

MYDHL API – DEVELOPER GUIDE

7103 Invalid reference type

'<xpath>/ExportDeclaration/InvoiceReferences/InvoiceReference
/InvoiceReferenceType, please update and try again.

7104 Duplicate values found in

<xpath>/ExportDeclaration/InvoiceReferences/InvoiceReference/
InvoiceReferenceType, please update and try again.

7105 Invalid ExportReasonType

<xpath>/ExportDeclaration/ExportReasonType, please update
and try again.

7106 Invalid Charge type

<xpath>/ExportDeclaration/OtherCharges/OtherCharge/ChargeT
ype, please update and try again.

7107 Duplicate values found in

<xpath>/ExportDeclaration/OtherCharges/OtherCharge/ChargeT
ype, please update and try again.

7108 Invalid QuantityUnitOfMeasure

<xpath>/ExportDeclaration/ExportLineItems/ExportLineItem/Qu
antityUnitOfMeasurement, please update and try again.

7109 Invalid ExportReasonType

<xpath>/ExportDeclaration/ExportLineItems/ExportLineItem/Exp
ortReasonType, please update and try again.

7110 Invalid ItemReferenceType

<xpath>/ExportDeclaration/ExportLineItems/ExportLineItem/Ite
mReferences/ItemReference/ItemReferenceType, please update
and try again.

7111 Duplicate values found in

<xpath>/ExportDeclaration/ExportLineItems/ExportLineItem/Ite
mReferences/ItemReference/ItemReferenceType, please update
and try again.

7112 Invalid CustomsPaperworkType

<xpath>/ExportDeclaration/ExportLineItems/ExportLineItem/Cus
tomsPaperworks/CustomsPaperwork/CustomsPaperworkType,
please update and try again.

7113 Child nodes exceed limit ---

'<xpath>/ExportDeclaration/OtherCharges/OtherCharge , please
update and try again.”

7114 Missing line item Net weight or Gross Weight at <xpath>, please
update the request and try again.

7115 UploadCINData is not allowed for your username. Please contact

your DHL sales representative.

PAGE 388 OF 417

MYDHL API – DEVELOPER GUIDE

7116 Duplicate values found in

shipreq:ShipmentRequest/RequestedShipment/Ship/{ROLE}/Reg
istrationNumbers/RegistrationNumber/NumberTypeCode.

8032 Not authorized to use this service. Please contact your DHL
Express representative.

7118 Provided Piece Identification Number Data Identifier is invalid.

Please check the request message and retry.

7119 Invalid PaymentInfo

shipreq:ShipmentRequest/RequestedShipment/PaymentInfo,
please update and try again.

7120 Field
ShipmentRequest/RequestedShipment/ShipmentInfo/DocumentI
mages/DocumentImage/DocumentImage or
ShipmentRequest/RequestedShipment/ShipmentInfo/LabelOptio
ns/RequestDHLCustomsInvoice is mandatory when ServiceType
is set as WY.

7122 Invalid CustomsInvoiceTemplate

ShipmentRequest/RequestedShipment/ShipmentInfo/CustomsIn
voiceTemplate, please update and try again.

803 Account not allowed for this service. Please contact

your DHL Express representative.

Warning Warning Text Notes (if

Code applicable)

7999 Incorrect ODD request type is provided. Please re-check the

generic type.

7998 Account not white-listed for this On Demand Delivery service.

Please contact your DHL account manager.

7997 Shipment Waybill Number, Origin Service Area Code, Destination

Service Area Code or Shipper Account Number value is not
available in request message. Please re-check.

7996 Shipment's destination country is not On Demand Delivery

deployed country.

7995 No charges returned in response message.

7994 Transliteration texts is not supported for the requested Shipper's

Country Code.

7993 No Estimated Delivery Date details returned in response message.

7992 State or Province code has been replaced to valid GREF State or
Provicen Code.

PAGE 389 OF 417

MYDHL API – DEVELOPER GUIDE

7991 Rate Request service failure. No charges returned in response

message.

7990 Rendered commercial invoice PDF can only print certain number
of shipping roles and addresses.

7989 Provided Piece Identification Number Data Identifier is ignored.

Please provide UseOwnPieceIdentificationNumber value as Y to
use own piece identification number.

7988 Please note on printing the hardcopy of all the shipment

paperwork and affix it to the package.

REQUESTPICKUP ERRORS

RequestPickup Error and Warning

Error Error Text Notes (if

Code applicable)

5001 The pickup request is past the booking cutoff time for
the pickup location (this includes taking the time zone
into consideration if applicable).

5002 The Pickup time window for a collection to take place is

too small (Pickup Location close time –
PickupTimestamp).

5003 The Pickup time window overlap is too small. Please

ensure that the overlap between your provided request
and the courier pickup window has the minimum
required Pickup Time window overlap.

5004 The pickup request must be at least {X hrs} before the

provided PickupLocationClose time.

5005 The minimum pickup time window overlap for your

requested origin is a minimum of {X} minutes with a
same day pickup initiated latest by {A} today. Please
note that couriers are available for a pickup at the
requested origin between {B} and {C}. Times are based
on the origin timezone.

5006 Pickup is not allowed for this shipment date. Please

update and re-try again.

5007 Recipient address is required for remote booking

request. Please provide the Recipient section and retry.

5008 UnitOfMeasurement is required for booking request.

Please provide the UnitOfMeasurement and retry.

PAGE 390 OF 417

MYDHL API – DEVELOPER GUIDE

5009 Shipper/Contact/CompanyName is required for booking

request. Please provide the CompanyName and retry.

5010 Pickup/Contact/CompanyName is required for booking

request. Please provide the CompanyName and retry.

5011 BookingRequestor/Contact/CompanyName is required

for booking request. Please provide the CompanyName
and retry.

5012 Recipient/Contact/CompanyName is required for

booking request. Please provide the CompanyName
and retry.

5013 At least one piece details is required for booking

request. Please provide the Packages section and retry.

5014 Invalid combination ShipmentInfo and ShipmentDetails

are found in request message. Please check the request
message and retry.

5015 Invalid combination ShipmentInfo, ShipmentDetails, and

PickupShipment/Packages are found in request
message. Please check the request message and retry.

5016 Invalid combination ShipmentDetails and

PickupShipment/Packages are found in request
message. Please check the request message and retry.

5017 BookingRequestor Address details is required for

remote booking request.

5018 Account number must be provided to the booking

request.

5019 The shipment date cannot be in the past. Please check

the shipment date and retry.

5020 The shipment date cannot be more than 10 days in

future. Please check the shipment date and retry.

5021 Pickup Location Close Time is not well

formatted.(Expected Sample Format : '17:10')

5022 Pickup Time Stamp is not well formatted.(Expected

Sample Format : '2010-02-11T17:10:09 GMT+01:00’)

5023 The Pickup Location Close Time cannot be earlier than

Shipment Time. Please check the request and retry.

5024 For Remote Booking, Shipper/Pickup Country Code must

be different from Booking Requestor Country Code.
Please check the request message and retry.

PAGE 391 OF 417

MYDHL API – DEVELOPER GUIDE

8032 Not authorized to use this service. Please contact your

DHL Express representative.

8003 Account not allowed for this service. Please contact

your DHL Express representative.

UPDATEPICKUP ERRORS

RequestPickup Error and Warning

Error Error Text Notes (if

Code applicable)

5555 Update of booking was not successful. Requested Pickup

was not found.

5556 The Original Shipper Account Number must match with

the Shipper Account Number used previously to
create/update successful pickup request. Please check
the Original Shipper Account Number and retry.

5557 The Original Shipper Account Number element is

mandatory. Please provide the
updatePickupRequest/OriginalShipperAccountNumber
and retry.

8032 Not authorized to use this service. Please contact your

DHL Express representative.

8003 Account not allowed for this service. Please contact

your DHL Express representative.

DOCUMENTIMAGEREQUEST ERRORS

DocumentImageRequest Error and Warning

Error Error Text Notes (if

Code applicable)

8001 The account number is not found or invalid. Please

check the account number and retry.

8003 Account not allowed for this service. Please contact

your DHL Express representative.

PAGE 392 OF 417

MYDHL API – DEVELOPER GUIDE

8032 Not authorized to use this service. Please contact your

DHL Express representative.

1501 The provided Shipment Identification Number is invalid.

Please check the request message and retry.

1502 Child nodes exceed limit --- '

docimgreq:DocumentImageRequest/DocumentImages/D
ocumentImage/DocumentTypes/DocumentType. Please
update and try again.

1504 No document images found for the provided search

criteria.

1506 AllInOnePDF cannot be set as Y for

DocumentImageFormat TIFF. Please check the request
message and retry.

1505 Unable to query document due to shipment data not

found.

1507 The provided DocumentTypeName is invalid. Please

check the request message and retry.

UPDATESHIPMENT WARNINGS

UpdateShipment Warning

Warning Warning Text Notes (if

Code applicable)

7989 Provided Piece Identification Number Data Identifier is

ignored. Please provide
UseOwnPieceIdentificationNumber value as Y to use
own piece identification number.

8003 Account not allowed for this service. Please contact

your DHL Express representative.

17 SERVICE INPUT/OUTPUT EXAMPLES FOR RATEREQUEST

SOAP RATEREQUEST: SAMPLE INPUT

<RateRequest>
<ClientDetail>
</ClientDetail>
<RequestedShipment>
<DropOffType>REQUEST_COURIER</DropOffType>
<Ship>
<Shipper>

PAGE 393 OF 417

MYDHL API – DEVELOPER GUIDE

<StreetLines>1-16-24, Minami-gyotoku</StreetLines>
<City>Ichikawa-shi, Chiba</City>
<PostalCode>272-0138</PostalCode>
<CountryCode>JP</CountryCode>
</Shipper>
<Recipient>
<StreetLines>63 RENMIN LU, QINGDAO SHI</StreetLines>
<City>QINGDAO SHI</City>
<PostalCode>266033</PostalCode>
<CountryCode>CN</CountryCode>
</Recipient>
</Ship>
<Packages>
<RequestedPackages number="1">
<Weight>
<Value>2.0</Value>
</Weight>
<Dimensions>
<Length>13</Length>
<Width>12</Width>
<Height>9</Height>
</Dimensions>
</RequestedPackages>
</Packages>
<ShipTimestamp>2010-11-26T12:00:00GMT-06:00</ShipTimestamp>
<UnitOfMeasurement>SU</UnitOfMeasurement>
<Content>NON_DOCUMENTS</Content>
<DeclaredValue>200.00</DeclaredValue>
<DeclaredValueCurrecyCode>USD</DeclaredValueCurrecyCode>
<PaymentInfo>DAP</PaymentInfo>
<Account> XXXXXXXXX</Account>
</RequestedShipment>
</RateRequest>

SOAP RATEREQUEST: SAMPLE OUTPUT

<rateresp:RateResponse>
<Provider code="DHL">
<Notification code="0">
<Message/>
</Notification>
<Service type="8">
<TotalNet>
<Currency>JPY</Currency>
<Amount>20475.00</Amount>
</TotalNet>
<Charges>
<Currency>JPY</Currency>
<Charge>
<ChargeType>EXPRESS EASY</ChargeType>
<ChargeAmount>17500.00</ChargeAmount>
</Charge>
<Charge>
<ChargeType>FUEL SURCHARGE</ChargeType>
<ChargeAmount>2975.00</ChargeAmount>
</Charge>
</Charges>
<DeliveryTime>2010-12-02T23:59:00</DeliveryTime>
</Service>
<Service type="P">
<TotalNet>
<Currency>JPY</Currency>

PAGE 394 OF 417

MYDHL API – DEVELOPER GUIDE

<Amount>20569.00</Amount>
</TotalNet>
<Charges>
<Currency>JPY</Currency>
<Charge>
<ChargeType>EXPRESS WORLDWIDE</ChargeType>
<ChargeAmount>17580.00</ChargeAmount>
</Charge>
<Charge>
<ChargeType>FUEL SURCHARGE</ChargeType>
<ChargeAmount>2989.00</ChargeAmount>
</Charge>
</Charges>
<DeliveryTime>2010-12-02T23:59:00</DeliveryTime>
</Service>
</Provider>
</rateresp:RateResponse>

SOAP RATEREQUEST: REQUEST WITH ERROR

<rateresp:RateResponse xmlns:rateresp="http://scxgxtt.phx-dc.dhl.com/euExpressRateBook/RateMsgResponse">
<Provider code="DHL">
<ServiceHeader>
<MessageTime>2020-02-13T05:34:55.874+00:00</MessageTime>
<MessageReference>GGEDS109311111112222222229876</MessageReference>
<ServiceInvocationID>20200213053455_108e_686aa0ea-2319-44d1-b231-8b20a4feba92</ServiceInvocationID>
</ServiceHeader>
<Notification code="420501">
<Message>The origin country code could not be found</Message>
</Notification>
<Notification code="999">
<Message>Process failure occured. Please contact the Administrator with Error Sequence as '1048568768'</Message>
</Notification>
</Provider>
</rateresp:RateResponse>
SOAP RATEREQUEST LANDEDCOST: SAMPLE INPUT
<RateRequest>
<ClientDetail/>
<Request>
<ServiceHeader>
<MessageTime>2018-07-31T13:30:00</MessageTime>
<MessageReference>JWEDS1093EWD0134124994301023431</MessageReference>
</ServiceHeader>
</Request>
<RequestedShipment>
<ServiceType>X</ServiceType>
<DropOffType>REGULAR_PICKUP</DropOffType>
<Ship>
<Shipper>
<City>OVERATH</City>
<PostalCode>51491</PostalCode>
<CountryCode>DE</CountryCode>
</Shipper>
<Recipient>
<City>OSNABRUECK</City>
<PostalCode>49084</PostalCode>
<CountryCode>DE</CountryCode>
</Recipient>
</Ship>
<Packages>
<RequestedPackages number="1">
<Weight>
<Value>3.4</Value>

PAGE 395 OF 417

MYDHL API – DEVELOPER GUIDE

</Weight>
<Dimensions>
<Length>45</Length>
<Width>30</Width>
<Height>10</Height>
</Dimensions>
</RequestedPackages>
</Packages>
<ShipTimestamp>2018-08-22T09:30:00GMT+01:00</ShipTimestamp>
<UnitOfMeasurement>SI</UnitOfMeasurement>
<Content>NON_DOCUMENTS</Content>
<DeclaredValue>20</DeclaredValue>
<DeclaredValueCurrencyCode>EUR</DeclaredValueCurrencyCode>
<Billing>
<ShipperAccountNumber>111111111</ShipperAccountNumber>
<ShippingPaymentType>S</ShippingPaymentType>
<BillingAccountNumber>999999999</BillingAccountNumber>
</Billing>
<LandedCost>
<MerchantSelectedCarrierName>DHL</MerchantSelectedCarrierName>
<GetItemCostBreakdown>Y</GetItemCostBreakdown>
<ShipmentCurrencyCode>EUR</ShipmentCurrencyCode>
<ShipmentPurpose>PERSONAL</ShipmentPurpose>
<ShipmentTransportationMode>AIR</ShipmentTransportationMode>
<Items>
<Item>
<ItemNumber>1</ItemNumber>
<Description>KNITWEAR COTTON</Description>
<Remark>KNITWEAR 100% COTTON REDUCTION PRICE FALL COLLECTION</Remark>
<ManufacturingCountryCode>DE</ManufacturingCountryCode>
<SKUPartNumber>12345555</SKUPartNumber>
<Quantity>150.345</Quantity>
<UnitPrice>12.50</UnitPrice>
<UnitPriceCurrencyCode>EUR</UnitPriceCurrencyCode>
<ItemWeight>1.6</ItemWeight>
<HarmonizedSystemCode>61101XXXXX</HarmonizedSystemCode>
<ItemWeightUnitofMeasurement>SI</ItemWeightUnitofMeasurement>
<Category>204</Category>
<EstimatedTariffRateType>HIGHEST_RATE</EstimatedTariffRateType>
</Item>
</Items>
<ShipmentMonetaryAmount>
<Charges>
<ChargeType>FREIGHT</ChargeType>
<ChargeAmount>19</ChargeAmount>
<CurrencyCode>EUR</CurrencyCode>
</Charges>
</ShipmentMonetaryAmount>
<GetTariffFormula>Y</GetTariffFormula>
<GetQuotationID>Y</GetQuotationID>
<GetDetailedLineItemLevelStatus>Y</GetDetailedLineItemLevelStatus>
</LandedCost>
</RequestedShipment>
</RateRequest>

PAGE 396 OF 417

MYDHL API – DEVELOPER GUIDE

SOAP RATEREQUEST LANDEDCOST: SAMPLE OUTPUT

<RateResponse>
<Provider code="DHL">
<ServiceHeader>
<MessageTime>2018-08-17T10:23:23</MessageTime>
<MessageReference>JWEDS1093EWD0134124994301023431</MessageReference>
<ServiceInvocationID>20210628073435_XXXX_0e9bdbdd-6070-4bc8-aa01-42985a8797d5</ServiceInvocationID>
<QuotationID>Q-2021-100-000008260</QuotationID>
</ServiceHeader>
<Notification code="0">
<Message/>
</Notification>
<Service>
<TotalNet>
<Currency>EUR</Currency>
<Amount>2271.86</Amount>
</TotalNet>
<Charges>
<Currency>EUR</Currency>
<Charge>
<ChargeType>DUTY</ChargeType>
<ChargeAmount>0.00</ChargeAmount>
<ChargeName>TOTAL DUTIES</ChargeName>
<ChargeCurrencyCode>EUR</ChargeCurrencyCode>
</Charge>
<Charge>
<ChargeType>TAX</ChargeType>
<ChargeAmount>359.86</ChargeAmount>
<ChargeName>TOTAL TAXES</ChargeName>
<ChargeCurrencyCode>EUR</ChargeCurrencyCode>
</Charge>
<Charge>
<ChargeType>FEE</ChargeType>
<ChargeAmount>0.00</ChargeAmount>
<ChargeName>TOTAL FEES</ChargeName>
<ChargeCurrencyCode>EUR</ChargeCurrencyCode>
</Charge>
<Charge>
<ChargeType>SINSV</ChargeType>
<ChargeAmount>0.00</ChargeAmount>
<ChargeCurrencyCode>EUR</ChargeCurrencyCode>
</Charge>
<Charge>
<ChargeType>MACHG</ChargeType>
<ChargeAmount>0.00</ChargeAmount>
<ChargeCurrencyCode>EUR</ChargeCurrencyCode>
</Charge>
<Charge>
<ChargeType>MFCHG</ChargeType>
<ChargeAmount>19.00</ChargeAmount>
<ChargeCurrencyCode>EUR</ChargeCurrencyCode>
</Charge>
<Charge>
<ChargeType>SCUSV</ChargeType>
<ChargeAmount>1875.00</ChargeAmount>
<ChargeCurrencyCode>EUR</ChargeCurrencyCode>
</Charge>
<Charge>
<ChargeType>STSCH</ChargeType>
<ChargeAmount>18.00</ChargeAmount>
<ChargeCurrencyCode>EUR</ChargeCurrencyCode>
</Charge>
<Charge>
<ChargeCode>DD</ChargeCode>
<ChargeType>Duty Tax Paid</ChargeType>

PAGE 397 OF 417

MYDHL API – DEVELOPER GUIDE

<ChargeAmount>18.00</ChargeAmount>
</Charge>
<Charge>
<ChargeType>FEE</ChargeType>
<ChargeAmount>250.00</ChargeAmount>
<ChargeName>CONCESSION_FEE</ChargeName>
<ChargeCurrencyCode>EUR</ChargeCurrencyCode>
<TariffRateFormula>((0.3464 % COST) MAX (528.33))</TariffRateFormula>
</Charge>
</Charges>
<Items>
<Item>
<ItemNumber>1</ItemNumber>
<Charge>
<ChargeType/>
<ChargeAmount>94.50</ChargeAmount>
<ChargeName>CIF</ChargeName>
<ChargeCurrencyCode>EUR</ChargeCurrencyCode>
<TariffRateFormula>COST + INSURANCE + FREIGHT</TariffRateFormula>
</Charge>
<Charge>
<ChargeType>DUTY</ChargeType>
<ChargeAmount>2.36</ChargeAmount>
<ChargeName>DUTY</ChargeName>
<ChargeCurrencyCode>EUR</ChargeCurrencyCode>
<TariffRateFormula>Deminimus :: (CIF * 0.025)</TariffRateFormula>
</Charge>
<Charge>
<ChargeType>TAX</ChargeType>
<ChargeAmount>18.40</ChargeAmount>
<ChargeName>VAT</ChargeName>
<ChargeCurrencyCode>EUR</ChargeCurrencyCode>
<TariffRateFormula>(0.19 * (CIF + DUTY + EXCISE + ADDITIONAL_DUTY))</TariffRateFormula>
</Charge>
</Item>
</Items>
</Service>
</Provider>
</RateResponse>

PAGE 398 OF 417

MYDHL API – DEVELOPER GUIDE

SOAP RATEREQUEST LANDEDCOST: RESPONSE WITH ERROR

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAPENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<rateresp:RateResponse xmlns:rateresp="http://scxgxtt.phx-dc.dhl.com/euExpressRateBook/RateMsgResponse">
<Provider code="DHL">
<ServiceHeader>
<MessageTime>2018-08-17T10:35:08</MessageTime>
<MessageReference>JWEDS1093EWD0134124994301023431</MessageReference>
</ServiceHeader>
<Notification code="200000" src="GTS">
<Message>Invalid Message header originator country code value. Country code not supported in GTS. (Invalid Orgntr CtryCd value.
Not Supportable Country)</Message>
</Notification>
<Notification code="999">
<Message>Process failure occurred. Please contact the Administrator with Error Sequence as '437551124'</Message>
</Notification>
</Provider>
</rateresp:RateResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

SOAP RATEREQUEST LANDEDCOST: RESPONSE WITH LINE ITEM NUMBER ERROR DETAILS
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<rateresp:RateResponse xmlns:rateresp="http://scxgxtt.phx-dc.dhl.com/euExpressRateBook/RateMsgResponse">
<Provider code="DHL">
<ServiceHeader>
<MessageTime>2021-06-28T08:14:40.922+00:00</MessageTime>
<MessageReference>GGEDS109311111112222222229876</MessageReference>
<ServiceInvocationID>20210628081440_c027_60d849c9-522e-4571-a41b-544cd772239d</ServiceInvocationID>
</ServiceHeader>
<Notification code="200000">
<Message>At least one item has invalid provided product category.</Message>
</Notification>
<Notification code="200000">
<Message>Invalid message content</Message>
<MessageDetail>Line ItemNumber 1: Provided product category is invalid. Please look at the possible category values listed under
documentation.</MessageDetail>
</Notification>
<Notification code="200000">
<Message>Invalid message content</Message>
<MessageDetail>Line ItemNumber 2: Provided product category is invalid. Please look at the possible category values listed under
documentation.</MessageDetail>
</Notification>
<Notification code="999">
<Message>Process failure occured. Please contact the Administrator with Error Sequence as '82163295'</Message>
</Notification>
</Provider>
</rateresp:RateResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

PAGE 399 OF 417

MYDHL API – DEVELOPER GUIDE

18 SERVICE INPUT/OUTPUT EXAMPLES FOR SHIPMENTREQUEST

SOAP SHIPMENTREQUEST: SAMPLE INPUT

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ship="http://scxgxtt.phx-
dc.dhl.com/euExpressRateBook/ShipmentMsgRequest">
<soapenv:Header/>
<soapenv:Body>
<ShipmentRequest xmlns="http://scxgxtt.phx-dc.dhl.com/euExpressRateBook/ShipmentMsgRequest">
<Request>
<ServiceHeader>
<MessageTime>2020-12-16T07:23:46.762Z</MessageTime>
<MessageReference>1234567890123456789012345678901</MessageReference>
<ShippingSystemPlatform>test</ShippingSystemPlatform>
<ShippingSystemPlatformVersion>7.0</ShippingSystemPlatformVersion>
</ServiceHeader>
</Request>
<RequestedShipment>
<ShipmentInfo>
<DropOffType>REGULAR_PICKUP</DropOffType>
<ServiceType>P</ServiceType>
<Billing>
<ShipperAccountNumber>XXXXXXXXX</ShipperAccountNumber>
<ShippingPaymentType>S</ShippingPaymentType>
<BillingAccountNumber>XXXXXXXXX</BillingAccountNumber>
</Billing>
<SpecialServices>
<Service>
<ServiceType>WY</ServiceType>
</Service>
</SpecialServices>
<Currency>EUR</Currency>
<UnitOfMeasurement>SI</UnitOfMeasurement>
<LabelType>PDF</LabelType>
<LabelOptions>
<RequestDHLCustomsInvoice>Y</RequestDHLCustomsInvoice>
<DHLCustomsInvoiceLanguageCode>eng</DHLCustomsInvoiceLanguageCode>
<DHLCustomsInvoiceType>COMMERCIAL_INVOICE</DHLCustomsInvoiceType>
</LabelOptions>
<ShipmentReferences>
<ShipmentReference>
<ShipmentReference>ShpRef VAT22 test5roles</ShipmentReference>
</ShipmentReference>
</ShipmentReferences>
</ShipmentInfo>
<ShipTimestamp>2021-03-16T09:30:47GMT+01:00</ShipTimestamp>
<PaymentInfo>DAP</PaymentInfo>
<InternationalDetail>
<Commodities>
<Description>1.002 - parcel with clothing</Description>
<CustomsValue>195.000</CustomsValue>
</Commodities>
<Content>NON_DOCUMENTS</Content>
<ExportDeclaration>
<InvoiceDate>2021-03-16</InvoiceDate>
<InvoiceNumber>INV-00211291</InvoiceNumber>
<ExportReasonType>PERMANENT</ExportReasonType>
<ExportReason>sales</ExportReason>
<PlaceOfIncoterm>GAILDORF PORT</PlaceOfIncoterm>
<ShipmentPurpose>COMMERCIAL</ShipmentPurpose>
<ExportLineItems>
<ExportLineItem>
<ItemNumber>1</ItemNumber>
<CommodityCode>4202.91.8090</CommodityCode>

PAGE 400 OF 417

MYDHL API – DEVELOPER GUIDE

<ImportCommodityCode>4202.91.8090</ImportCommodityCode>
<Quantity>1</Quantity>
<QuantityUnitOfMeasurement>PCS</QuantityUnitOfMeasurement>
<ItemDescription>Fall collection: vegan leather pouchette small</ItemDescription>
<UnitPrice>45.00</UnitPrice>
<NetWeight>0.300</NetWeight>
<GrossWeight>0.300</GrossWeight>
<ExportReasonType>PERMANENT</ExportReasonType>
<ManufacturingCountryCode>CN</ManufacturingCountryCode>
<TaxesPaid>N</TaxesPaid>
<ItemReferences>
<ItemReference>
<ItemReferenceType>PAN</ItemReferenceType>
<ItemReferenceNumber>10597122</ItemReferenceNumber>
</ItemReference>
<ItemReference>
<ItemReferenceType>OID</ItemReferenceType>
<ItemReferenceNumber>0323434422</ItemReferenceNumber>
</ItemReference>
</ItemReferences>
<CustomsPaperworks>
<CustomsPaperwork>
<CustomsPaperworkType>INV</CustomsPaperworkType>
<CustomsPaperworkID>MyDHLAPI - LN#1-CUSDOC-001</CustomsPaperworkID>
</CustomsPaperwork>
</CustomsPaperworks>
</ExportLineItem>
</ExportLineItems>
<CustomsDocuments>
<CustomsDocument>
<CustomsDocumentType>INV</CustomsDocumentType>
<CustomsDocumentID>MyDHLAPI - CUSDOC-001</CustomsDocumentID>
</CustomsDocument>
</CustomsDocuments>
<PackageMarks>Package Marks</PackageMarks>
<PayerGSTVAT>yes</PayerGSTVAT>
<RecipientReference>01291344</RecipientReference>
<Remarks>
<Remark>
<RemarkDescription>Invoice Remarks 1st</RemarkDescription>
</Remark>
</Remarks>
<TermsOfPayment>60 days</TermsOfPayment>
<InvoiceTotalNetWeight>1.500</InvoiceTotalNetWeight>
<InvoiceTotalGrossWeight>1.500</InvoiceTotalGrossWeight>
<InvoiceInstructions>This is invoice instruction</InvoiceInstructions>
<InvoiceReferences>
<InvoiceReference>
<InvoiceReferenceType>CU</InvoiceReferenceType>
<InvoiceReferenceNumber>MyDHLAPI - CUREF-001</InvoiceReferenceNumber>
</InvoiceReference>
</InvoiceReferences>
</ExportDeclaration>
</InternationalDetail>
<Ship>
<Shipper>
<Contact>
<PersonName>John Smith</PersonName>
<CompanyName>MyDHL API</CompanyName>
<PhoneNumber>123456789</PhoneNumber>
</Contact>
<Address>
<StreetLines>Address Line 1</StreetLines>
<StreetLines2>Address Line 2</StreetLines2>
<StreetLines3>Address Line 3</StreetLines3>

PAGE 401 OF 417

MYDHL API – DEVELOPER GUIDE

<City>HAIKOU</City>
<PostalCode>570000</PostalCode>
<CountryCode>CN</CountryCode>
</Address>
<RegistrationNumbers>
<RegistrationNumber>
<Number>VAT23249923</Number>
<NumberTypeCode>VAT</NumberTypeCode>
<NumberIssuerCountryCode>CN</NumberIssuerCountryCode>
</RegistrationNumber>
</RegistrationNumbers>
<BusinessPartyTypeCode>BU</BusinessPartyTypeCode>
</Shipper>
<Recipient>
<Contact>
<PersonName>John Smith</PersonName>
<CompanyName>MyDHL API IE</CompanyName>
<PhoneNumber>123456789</PhoneNumber>
<EmailAddress>[email protected]</EmailAddress>
<MobilePhoneNumber>123456789</MobilePhoneNumber>
</Contact>
<Address>
<StreetLines>Address Line 1</StreetLines>
<StreetLines2>Address Line 2</StreetLines2>
<StreetLines3>Address Line 3</StreetLines3>
<City>DUBLIN</City>
<PostalCode/>
<CountryCode>IE</CountryCode>
</Address>
<RegistrationNumbers>
<RegistrationNumber>
<Number>977961111</Number>
<NumberTypeCode>EOR</NumberTypeCode>
<NumberIssuerCountryCode>IE</NumberIssuerCountryCode>
</RegistrationNumber>
</RegistrationNumbers>
<BusinessPartyTypeCode>BU</BusinessPartyTypeCode>
</Recipient>
</Ship>
<Packages>
<RequestedPackages number="1">
<Weight>1.5</Weight>
<PackageContentDescription>travel bags</PackageContentDescription>
<Dimensions>
<Length>30</Length>
<Width>30</Width>
<Height>20</Height>
</Dimensions>
</RequestedPackages>
</Packages>
</RequestedShipment>
</ShipmentRequest>
</soapenv:Body>
</soapenv:Envelope>
SOAP SHIPMENTREQUEST: SAMPLE OUTPUT
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<shipresp:ShipmentResponse xmlns:shipresp="http://scxgxtt.phx-dc.dhl.com/euExpressRateBook/ShipmentMsgResponse">
<Response>
<ServiceHeader>
<MessageTime>2021-03-15T05:35:42.847+00:00</MessageTime>

PAGE 402 OF 417

MYDHL API – DEVELOPER GUIDE

<MessageReference>1234567890123456789012345678901</MessageReference>
<ServiceInvocationID>20210315053542_db0f_efa4868d-5c42-4a6f-83b4-bbc346399160</ServiceInvocationID>
</ServiceHeader>
</Response>
<Notification code="0">
<Message/>
</Notification>
<PackageResult number="1">
<TrackingNumber>JD014600004012015117</TrackingNumber>
</PackageResult>
</PackagesResult>
<LabelImage>
<LabelImageFormat>PDF</LabelImageFormat>
<GraphicImage> BASE64_DOCIMAGE_HERE<GraphicImage>
</LabelImage>
<Documents>
<Document>
<DocumentName>Commercial Invoice</DocumentName>
<DocumentFormat>PDF</DocumentFormat>
<DocumentImage>BASE64_DOCIMAGE_HERE</DocumentImage>
</Document>
</Documents>
<ShipmentIdentificationNumber>6529292884</ShipmentIdentificationNumber>
</shipresp:ShipmentResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

SOAP SHIPMENTREQUEST: SAMPLE REQUEST WITH ERROR

<ShipmentResponse xmlns:shipresp="http://scxgxtt.phx-dc.dhl.com/euExpressRateBook/ShipmentMsgResponse">
<Notification code="1001">
<Message>The requested product(s) (X) not available based on your search criteria.(8614)</Message>
</Notification>
<Notification code="998">
<Message>Process failure occurred. Process ID associated for that transaction (8614)</Message>
</Notification>
</ShipmentResponse>

19 SERVICE INPUT/OUTPUT EXAMPLES FOR SHIPMENTDELETEREQUEST

SOAP SHIPMENTDELETEREQUEST: SAMPLE INPUT

<?xml version="1.0" encoding="UTF-8"?>
<del:DeleteRequest>
<PickupDate>2010-12-03</PickupDate>
<PickupCountry>IT</PickupCountry>
<DispatchConfirmationNumber>FLR-804</DispatchConfirmationNumber>
<RequestorName>Tom Jones</RequestorName>
<Reason>001</Reason>
< /del:DeleteRequest>

SOAP SHIPMENTDELETEREQUEST: SAMPLE OUTPUT

<?xml version="1.0" encoding="UTF-8"?>
<delresp:DeleteResponse>
<Notification code="0">
<Message>Successfully cancelled</Message>
</Notification>

PAGE 403 OF 417

MYDHL API – DEVELOPER GUIDE

</delresp:DeleteResponse>

SOAP SHIPMENTDELETEREQUEST: SAMPLE REQUEST WITH ERROR

<?xml version="1.0" encoding="UTF-8"?>
<delresp:DeleteResponse>
<Notification code="410928">
<Message>Cancellation of booking was not successful. Requested Pickup was not found.</Message>
</Notification>
</delresp:DeleteResponse>

20 SERVICE INPUT/OUTPUT EXAMPLES FOR TRACKINGREQUEST

SOAP TRACKINGREQUEST: SAMPLE INPUT

<trackShipmentRequest>
<trackingRequest>
<TrackingRequest>
<Request>
<ServiceHeader>
<MessageTime>2010-11-24T00:17:20Z</MessageTime>
<MessageReference>1234</MessageReference>
</ServiceHeader>
</Request>
<AWBNumber>
<ArrayOfAWBNumberItem>2330982222</ArrayOfAWBNumberItem>
</AWBNumber>
<LevelOfDetails>ALL_CHECKPOINTS</LevelOfDetails>
<PiecesEnabled>B</PiecesEnabled>
</TrackingRequest>
</trackingRequest>
</trackShipmentRequest>

PAGE 404 OF 417

MYDHL API – DEVELOPER GUIDE

SOAP TRACKINGREQUEST: SAMPLE OUTPUT

<trackingResponse xmlns:ns="http://www.dhl.com">
<TrackingResponse>
<Response>
<ServiceHeader>
<MessageTime>2011-01-12T18:41:12Z</MessageTime>
<MessageReference>86ef86501e7b11e08c81df5507f6bac8</MessageReference>
</ServiceHeader>
</Response>
<AWBInfo>
<ArrayOfAWBInfoItem>
<AWBNumber>2330982222</AWBNumber>
<Status>
<ActionStatus>Success</ActionStatus>
</Status>
<ShipmentInfo>
<OriginServiceArea>
<ServiceAreaCode>FLR</ServiceAreaCode>
<Description>Florence - Italy</Description>
</OriginServiceArea>
<DestinationServiceArea>
<ServiceAreaCode>BRI</ServiceAreaCode>
<Description>Bari - Italy</Description>
<FacilityCode>WAD</FacilityCode>
</DestinationServiceArea>
<ShipperName>NUOVO PIGNONE SPA</ShipperName>
<ConsigneeName>NUOVO PIGNONESPA</ConsigneeName>
<ShipmentDate>2010-11-09T14:33:00+01:00</ShipmentDate>
<Pieces>1</Pieces>
<Weight>0.500</Weight>
<ShipmentEvent>
<ArrayOfShipmentEventItem>
<Date>2010-11-10</Date>
<Time>15:12:00</Time>
<ServiceEvent>
<EventCode>MD</EventCode>
<Description>Missed Delivery Cycle</Description>
</ServiceEvent>
<Signatory/>
<ServiceArea>
<ServiceAreaCode>BRI</ServiceAreaCode>
<Description>Bari - Italy</Description>
</ArrayOfShipmentEventItem>
</ShipmentEvent>
</ShipmentInfo>
<Pieces>
<PieceInfo>
<ArrayOfPieceInfoItem>
<PieceDetails>
<AWBNumber>2331017371</AWBNumber>
<LicensePlate>JD012038742880020267</LicensePlate>
<ActualDepth>0.000</ActualDepth>
<ActualWidth>0.000</ActualWidth>
<ActualHeight>0.000</ActualHeight>
<Depth>1.000</Depth>
<Width>1.000</Width>
<Height>1.000</Height>
<Weight>0.500</Weight>
<PackageType/>
<DimWeight>0.520</DimWeight>
<WeightUnit>KG</WeightUnit>
</PieceDetails>
<PieceEvent>
<Date>2010-11-11</Date>
<Time>11:52:00</Time>
<ServiceEvent>
<EventCode>OK</EventCode>
<Description>Delivery</Description>
</ServiceEvent>
<Signatory>DEPALMA</Signatory>
</PieceEvent>
</ArrayOfPieceInfoItem>
</PieceInfo>

PAGE 405 OF 417

MYDHL API – DEVELOPER GUIDE

</Pieces>
</ArrayOfAWBInfoItem>
</AWBInfo>
</TrackingResponse>
</trackingResponse>

PAGE 406 OF 417

MYDHL API – DEVELOPER GUIDE

SOAP TRACKINGREQUEST: SAMPLE ERROR

<trackingResponse xmlns:ns="http://www.dhl.com">
<TrackingResponse>
<Response>
<ServiceHeader>
<MessageTime>2011-01-12T17:40:58Z</MessageTime>
<MessageReference>1d136ec01e7311e0a468e3cd6e9dbbd4</MessageReference>
</ServiceHeader>
</Response>
<AWBInfo>
<ArrayOfAWBInfoItem>
<AWBNumber>2330982222</AWBNumber>
<Status>
<ActionStatus>No Shipments Found</ActionStatus>
<Condition>
<ArrayOfConditionItem>
<ConditionCode>101</ConditionCode>
<ConditionData>No Shipments Found for AWBNumber |
2330982222</ConditionData>
</ArrayOfConditionItem>
</Condition>
</Status>
</ArrayOfAWBInfoItem>
</AWBInfo>
</TrackingResponse>
</trackingResponse>

21 SERVICE INPUT/OUTPUT EXAMPLES FOR EPOD

SOAP EPOD: SAMPLE INPUT

<doc:shipmentDocumentRetrieveReq>
<MSG>
<Hdr Id="123testrq" Ver="1.038" Dtm="2011-04-07T23:59:59">
<Sndr AppNm="DCG" AppCd="DCG"/>
</Hdr>
<Bd>
<Shp Id="2638825350">
<ShpTr>
<!--Zero or more repetitions:-->
<SCDtl AccNo="000000000" CRlTyCd="TC"/>
</ShpTr>
<ShpInDoc>
<SDoc DocTyCd="POD"/>
</ShpInDoc>
</Shp>
<GenrcRq>
<GenrcRqCritr TyCd="IMG_CONTENT" Val="epod-detail-esig"/>
<GenrcRqCritr TyCd="IMG_FORMAT" Val="PDF"/>
<GenrcRqCritr TyCd="DOC_RND_REQ" Val="true"/>
<GenrcRqCritr TyCd="EXT_REQ" Val="true"/>
<GenrcRqCritr TyCd="DUPL_HANDL" Val="CORE_WB_NO"/>
<GenrcRqCritr TyCd="SORT_BY" Val="$INGEST_DATE,D"/>
<GenrcRqCritr TyCd="LANGUAGE" Val="en"/>
</GenrcRq>
</Bd>
</MSG>
</doc:shipmentDocumentRetrieveReq>

PAGE 407 OF 417

MYDHL API – DEVELOPER GUIDE

SOAP EPOD: SAMPLE OUTPUT

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAPENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<tns:shipmentDocumentRetrieveResp xmlns:tns="glDHLExpressePOD/providers/DocumentRetrieve">
<MSG>
<Hdr Id="73475768" Ver="1.038" Dtm="2013-05-24T20:34:34">
<Sndr AppCd="ESB" AppNm="ESB"/>
<Rcp AppCd="DCG" AppNm="DCG">
<GId Id="SunnyTesting" IdTp="RQMSGID"/>
</Rcp>
</Hdr>
<Bd>
<Shp>
<ShpInDoc>
<SDoc DocTyCd="POD">
<Img Img="JVBERi0xLjQKJeLjz9MKNiAwIG9.....==" ImgMimeTy="application/pdf"/>
</SDoc>
</ShpInDoc>
</Shp>
</Bd>
<DatTrErr>
<OrgHdr CorrId="SunnyTesting"/>
<Rp CmptNm="DocumentManagement.ShipmentDocumentRetrieveProvider"/>
<ErrMsgGI Ty="CF" Pri="2" Sev="10"/>
<DatErrMsg>
<ErrMsgDtl MsgCIgd="100000" MsgClg="IPESB" Dsc="Service operation execution finished successfully" DtlDsc="Service operation
execution finished successfully"/>
</DatErrMsg>
</DatTrErr>
</MSG>
</tns:shipmentDocumentRetrieveResp>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

SOAP EPOD: SAMPLE ERROR RESPONSE

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/20
01/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"></SOAP-ENV:Header><SOAP-ENV:Body>
<tns:shipmentDocumentRetrieveResp xmlns:tns="DocumentManagement/WSConsumer/WS/DocumentManagement">
<MSG>
<Hdr Id="72048040" Ver="1.038" Dtm="2013-05-16T13:58:09">
<Sndr AppCd="ESB" AppNm="ESB"></Sndr>
<Rcp AppCd="WEBP" AppNm="WEBP">
<GId Id="1368626289303" IdTp="RQMSGID"></GId>
</Rcp>
</Hdr>
<DatTrErr>
<OrgHdr CorrId="1368626289303"></OrgHdr>
<Rp CmptNm="DocumentManagement.ShipmentDocumentRetrieveProvider"></Rp>
<ErrMsgGI Ty="CF" Pri="2" Sev="40"></ErrMsgGI>
<DatErrMsg>
<ErrMsgDtl MsgCIgd="100002" MsgClg="IPESB" Dsc="Service operation request message data validation failed" DtlDsc="HP
Global
Imaging epod Service returned error co
de:No matching ePODs for search query"></ErrMsgDtl>
</DatErrMsg>
</DatTrErr>
</MSG></tns:shipmentDocumentRetrieveResp></SOAP-ENV:Body>
</SOAP-ENV:Envelope>

PAGE 408 OF 417

MYDHL API – DEVELOPER GUIDE

22 SERVICE INPUT/OUTPUT EXAMPLES FOR UPDATESHIPMENT

SOAP UPDATESHIPMENT: SAMPLE INPUT

<?xml version="1.0" encoding="UTF-8"?>
<upd:UpdateRequest>
<MessageId>Sample_Message_Id</MessageId>
<UpdatedShipment>
<ShipmentInfo>
<ServiceType>P</ServiceType>
<Account>123456789</Account>
<Billing>
<ShipperAccountNumber>123456789</ShipperAccountNumber>
<ShippingPaymentType>S</ShippingPaymentType>
</Billing>
<ShipmentIdentificationNumber>1234567890</ShipmentIdentificationNumber>
<LabelType>PDF</LabelType>
<LabelTemplate>ECOM_TC_A4</LabelTemplate>
<ArchiveLabelTemplate>ARCH_8x4</ArchiveLabelTemplate>
<IncludePreviousPieceLabels>Y</IncludePreviousPieceLabels>
</ShipmentInfo>
<OriginalShipDate>2018-01-24</OriginalShipDate>
<Packages>
<RequestedPackages number="1">
<Weight>5.350</Weight>
<UseOwnPieceIdentificationNumber>N</UseOwnPieceIdentificationNumber>
<PackageContentDescription>Gloves</PackageContentDescription>
<Dimensions>
<Length>32.0</Length>
<Width>10.0</Width>
<Height>5.0</Height>
</Dimensions>
</RequestedPackages>
</Packages>
</UpdatedShipment>
</upd:UpdateRequest>

SOAP UPDATESHIPMENT: SAMPLE OUTPUT

<updateresp:UpdateResponse xmlns:updateresp="http://scxgxtt.phx-
dc.dhl.com/euExpressRateBook/UpdateShipmentResponse">
<Notification code="0">
<Message/>
</Notification>
<PackagesResult>
<PackageResult number="1">
<TrackingNumber>JDAA06000121212121</TrackingNumber>
</PackageResult>
</PackagesResult>
<LabelImage>
<LabelImageFormat>PDF</LabelImageFormat>
<GraphicImage>JVBERi0xLjQKJfbk/N8KMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovVmVRU9GCg==</GraphicImage>
</LabelImage>
<ShipmentIdentificationNumber>1234567890</ShipmentIdentificationNumber>
</updateresp:UpdateResponse>
SOAP UPDATESHIPMENT: SAMPLE ERROR MESSAGE
<?xml version="1.0" encoding="UTF-8"?><updateresp:UpdateResponse
xmlns:updateresp="http://scxgxtt.phxdc.dhl.com/euExpressRateBook/UpdateShipmentResponse">
<Notification code="400101">

PAGE 409 OF 417

MYDHL API – DEVELOPER GUIDE

<Message>Piece update is not possible as shipment information not found in the database</Message> </Notification>
<Notification code="999">
<Message>Failed to process your request. Process ID associated for this transaction (1234567890)</Message>
</Notification>
</updateresp:UpdateResponse>

SOAP UPDATESHIPMENT: SAMPLE WARNING MESSAGE

<?xml version="1.0" encoding="UTF-8 <updateresp:UpdateResponse xmlns:updateresp="http://scxgxtt.phx-
dc.dhl.com/euExpressRateBook/UpdateShipmentResponse">
<Response>
<ServiceHeader>
<MessageTime>2021-11-15T13:25:13</MessageTime>
<MessageReference>MyDHLAPI_testingreference123</MessageReference>
<ServiceInvocationID>20211115132513_af02_2fad02e2-f228-4f66-b210-dd24c787351d</ServiceInvocationID>
</ServiceHeader>
</Response>
<Notification code="0">
<Message/>
</Notification>
<Warning code="7989">
<Message>Provided Piece Identification Number Data Identifier is ignored. Please provide
UseOwnPieceIdentificationNumber value as Y to use own piece identification number.</Message>
</Warning>
<PackagesResult>
<PackageResult number="1">
<TrackingNumber>JD014600004111941831</TrackingNumber>
</PackageResult>
</PackagesResult>
<LabelImage>
<LabelImageFormat>PDF</LabelImageFormat>
<GraphicImage>JVBERi0xLjQKJfbk/N8KMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovVmVRU9GCg==</GraphicImage>
<ShipmentIdentificationNumber>1234567890</ShipmentIdentificationNumber>
</updateresp:UpdateResponse>

PAGE 410 OF 417

MYDHL API – DEVELOPER GUIDE

23 SERVICE INPUT/OUTPUT EXAMPLES FOR REQUESTPICKUP

SOAP REQUESTPICKUP: SAMPLE INPUT

<pic:PickUpRequest>
<MessageId>2364878234817650001982134234</MessageId>
<PickUpShipment>
<ShipmentInfo>
<ServiceType>U</ServiceType>
<Billing>
<ShipperAccountNumber>140582622</ShipperAccountNumber>
<ShippingPaymentType>S</ShippingPaymentType>
</Billing>
<UnitOfMeasurement>SI</UnitOfMeasurement>
</ShipmentInfo>
<PickupTimestamp>2018-01-26T12:59:00 GMT+01:00</PickupTimestamp>
<PickupLocationCloseTime>17:00</PickupLocationCloseTime>
<SpecialPickupInstruction>Collect at reception</SpecialPickupInstruction>
<PickupLocation>Receptoin</PickupLocation>
<InternationalDetail>
<Commodities>
<NumberOfPieces>1</NumberOfPieces>
<Description>Computer Parts</Description>
</Commodities>
</InternationalDetail>
<Ship>
<Shipper>
<Contact>
<PersonName>Topaz</PersonName>
<CompanyName>DHL Express</CompanyName>
<PhoneNumber>+31 6 53464291</PhoneNumber>
<EmailAddress>[email protected]</EmailAddress>
<MobilePhoneNumber>+31 6 53464291</MobilePhoneNumber>
</Contact>
<Address>
<StreetLines>GloWS</StreetLines>
<City>Eindhoven</City>
<PostalCode>5657 ES</PostalCode>
<CountryCode>NL</CountryCode>
</Address>
</Shipper>
<Recipient>
<Contact>
<PersonName>Jack Jones</PersonName>
<CompanyName>J and J Company</CompanyName>
<PhoneNumber>+44 25 77884444</PhoneNumber>
<EmailAddress>[email protected]</EmailAddress>
<MobilePhoneNumber>+44 5 88648666</MobilePhoneNumber>
</Contact>
<Address>
<StreetLines>Penny lane</StreetLines>
<City>Liverpool</City>
<PostalCode>AA21 9AA</PostalCode>
<CountryCode>GB</CountryCode>
</Address>
</Recipient>
</Ship>
<Packages>
<RequestedPackages number="1">
<Weight>12.0</Weight> <Dimensions>
<Length>70</Length>
<Width>21</Width>
<Height>44</Height>
</Dimensions>
<CustomerReferences>My-PU-Call-1</CustomerReferences>
</RequestedPackages>
</Packages>
</PickUpShipment> </pic:PickUpRequest>

PAGE 411 OF 417

MYDHL API – DEVELOPER GUIDE

SOAP REQUESTPICKUP: SAMPLE OUTPUT

<pickupresp:PickUpResponse xmlns:pickupresp="http://scxgxtt.phx-dc.dhl.com/euExpressRateBook/PickUpResponse">
<Notification code="0">
<Message/>
</Notification>
<DispatchConfirmationNumber>PRG999126012345</DispatchConfirmationNumber>
</pickupresp:PickUpResponse>

SOAP REQUESTPICKUP: SAMPLE ERROR MESSAGE

<pickupresp:PickUpResponse xmlns:pickupresp="http://scxgxtt.phx-dc.dhl.com/euExpressRateBook/PickUpResponse">
<Notification code="998">
<Message>The account number is not found or invalid. Please check the account number and retry.</Message>
</Notification>
<Notification code="999">
<Message>Failed to process your request. Process ID associated for this transaction (1862502637)</Message>
</Notification> </pickupresp:PickUpResponse>

PAGE 412 OF 417

MYDHL API – DEVELOPER GUIDE

24 SERVICE INPUT/OUTPUT EXAMPLES FOR UPDATEPICKUP

SOAP UPDATEPICKUP: SAMPLE INPUT

<upd1:UpdatePickUpRequest xmlns:upd1="http://scxgxtt.phx-dc.dhl.com/ExpressUpdatePickUp/UpdatePickUpRequest">
<Request>
<ServiceHeader>
<MessageTime>2019-01-11T11:30:00Z</MessageTime>
<MessageReference>SAMPLE_MSG_REF_943010224210988367822</MessageReference>
</ServiceHeader>
</Request>
<DispatchConfirmationNumber>CBJ191002000830</DispatchConfirmationNumber>
<OriginalShipperAccountNumber>123456789</OriginalShipperAccountNumber>
<PickUpShipment>
<ShipmentDetails>
<ShipmentDetail>
<ServiceType>P</ServiceType>
<LocalServiceType>P</LocalServiceType>
<SpecialServices>
<Service>
<ServiceType>II</ServiceType>
<ServiceValue>100</ServiceValue>
<CurrencyCode>EUR</CurrencyCode>
</Service>
</SpecialServices>
<UnitOfMeasurement>SU</UnitOfMeasurement>
<Content>NON_DOCUMENTS</Content>
<ShipmentWeight>25.00</ShipmentWeight>
<DeclaredValue>20.00</DeclaredValue>
<DeclaredValueCurrencyCode>EUR</DeclaredValueCurrencyCode>
<Packages>
<RequestedPackages number="1">
<Weight>5.350</Weight>
<Dimensions>
<Length>32.0</Length>
<Width>30.0</Width>
<Height>20.0</Height>
</Dimensions>
<CustomerReferences>Package for booking.</CustomerReferences>
</RequestedPackages>
</Packages>
</ShipmentDetail>
</ShipmentDetails>
<PickupTimestamp>2020-02-11T10:00:00GMT+02:00</PickupTimestamp>
<PickupLocationCloseTime>18:45</PickupLocationCloseTime>
<Remarks>Sample remarks</Remarks>
<PickupLocation>Store Gate C-12</PickupLocation>
<PickupLocationType>COMMERCIAL</PickupLocationType>
<Billing>
<ShipperAccountNumber>123456789</ShipperAccountNumber>
<ShippingPaymentType>S</ShippingPaymentType>
<BillingAccountNumber>123456789</BillingAccountNumber>
</Billing>
<Ship>
<Shipper>
<Contact>
<PersonName>PERSON_NAME</PersonName>
<CompanyName>COMPANY_NAME</CompanyName>
<PhoneNumber>+6012345678</PhoneNumber>
<EmailAddress>[email protected]</EmailAddress>
<MobilePhoneNumber>+6012345654</MobilePhoneNumber>
</Contact>
<Address>
<StreetLines>STREET_LINES</StreetLines>

PAGE 413 OF 417

MYDHL API – DEVELOPER GUIDE

<City>CITY</City>
<PostalCode>11111</PostalCode>
<CountryCode>US</CountryCode>
</Address>
</Shipper>
<Recipient>
<Contact>
<PersonName>PERSON_NAME</PersonName>
<CompanyName>COMPANY_NAME</CompanyName>
<PhoneNumber>+6012345678</PhoneNumber>
<EmailAddress>[email protected]</EmailAddress>
<MobilePhoneNumber>+6012345654</MobilePhoneNumber>
</Contact>
<Address>
<StreetLines>STREET_LINES</StreetLines>
<StreetName>test123</StreetName>
<StreetNumber>10</StreetNumber>
<StreetLines2>StreetLines2</StreetLines2>
<StreetLines3>StreetLines3</StreetLines3>
<City>Cyberjaya</City>
<PostalCode>63000</PostalCode>
<CountryCode>MY</CountryCode>
</Address>
</Recipient>
</Ship>
</PickUpShipment>
</upd1:UpdatePickUpRequest>

PAGE 414 OF 417

MYDHL API – DEVELOPER GUIDE

SOAP UPDATEPICKUP: SAMPLE OUTPUT

<updatePickupRes:UpdatePickUpResponse xmlns:updatePickupRes="http://scxgxtt.phx-
dc.dhl.com/ExpressUpdatePickUp/UpdatePickUpResponse">
<Response>
<ServiceHeader>
<MessageTime>2020-02-11T11:08:14</MessageTime>
<MessageReference>SAMPLE_MSG_REF_943010224210988367822</MessageReference>
<ServiceInvocationID>20200211110814_cdc8_0ffa4add-d77c-4440-a930-9e724bc245ac</ServiceInvocationID>
</ServiceHeader>
</Response>
<Notification code="0">
<Message>Successfully Updated</Message>
</Notification>
<DispatchConfirmationNumber>AME200213000084</DispatchConfirmationNumber>
</updatePickupRes:UpdatePickUpResponse>

SOAP UPDATEPICKUP: SAMPLE ERROR MESSAGE

<updatePickupRes:UpdatePickUpResponse xmlns:updatePickupRes="http://scxgxtt.phx-
dc.dhl.com/ExpressUpdatePickUp/UpdatePickUpResponse">
<Response>
<ServiceHeader>
<MessageTime>2020-02-11T11:06:32</MessageTime>
<MessageReference>SAMPLE_MSG_REF_943010224210988367822</MessageReference>
<ServiceInvocationID>20200211110632_b82c_74c8be85-1d4c-42b0-813f-2d6fa5911a56</ServiceInvocationID>
</ServiceHeader>
</Response>
<Notification code="5556">
<Message>The Original Shipper Account Number must match with the Shipper Account Number used previously to
create/update successful pickup request. Please check the Original Shipper Account Number and retry.</Message>
</Notification>
<Notification code="999">
<Message>Failed to process your request. Process ID associated for this transaction (118340347).</Message>
</Notification>
</updatePickupRes:UpdatePickUpResponse>

25 SERVICE INPUT/OUTPUT EXAMPLES FOR DOCUMENTIMAGEREQUEST

SOAP DOCUMENTIMAGEREQUEST: SAMPLE INPUT

<docimgreq:DocumentImageRequest>
<Request>
<ServiceHeader>
<MessageTime>2021-11-17T09:30:47Z</MessageTime>
<MessageReference>MessageReferenceDocumentImageRequest</MessageReference>
</ServiceHeader>
</Request>
<DocumentImages>
<DocumentImage>
<ShipmentIdentificationNumber>4013543612</ShipmentIdentificationNumber>
<DocumentTypes>
<DocumentType>
<DocumentTypeName>COMMERCIAL_INVOICE</DocumentTypeName>
</DocumentType>
</DocumentTypes>
<ShipperAccountNumber>XXXXXXXXX</ShipperAccountNumber>
<ShipmentPickupYearAndMonth>2021-10</ShipmentPickupYearAndMonth>
<OutputImageOptions>
<DocumentImageFormat>PDF</DocumentImageFormat>

PAGE 415 OF 417

MYDHL API – DEVELOPER GUIDE

<AllInOnePDF>N</AllInOnePDF>
<CompressedPackage>N</CompressedPackage>
</OutputImageOptions>
</DocumentImage>
</DocumentImages>
</docimgreq:DocumentImageRequest>

PAGE 416 OF 417

MYDHL API – DEVELOPER GUIDE

SOAP DOCUMENTIMAGEREQUEST: SAMPLE OUTPUT

<docimgresp:DocumentImageResponse>
<Response>
<ServiceHeader>
<MessageTime>2021-11-17T09:30:47Z</MessageTime>
<MessageReference>MessageReferenceDocumentImageRequest</MessageReference>
<ServiceInvocationID>20211108032437_647f_b254b307-e476-4569-97d1-
aee0128fec76</ServiceInvocationID>
</ServiceHeader>
</Response>
<Notification code="0">
<Message/>
</Notification>
<DocumentImages>
<DocumentImage>
<ShipmentIdentificationNumber>4013543612</ShipmentIdentificationNumber>
<DocumentType>COMMERCIAL_INVOICE</DocumentType>
<DocumentImageFormat>PDF</DocumentImageFormat>
<DocumentContent>UjBsR09EbGhjZ0dTQUxNQUFBUUNBRU1tQ1p0dU1GUXhEUzhi</DocumentContent>
</DocumentImage>
</DocumentImages>
</docimgresp:DocumentImageResponse>

SOAP DOCUMENTIMAGEREQUEST: SAMPLE ERROR MESSAGE

<DocumentImageResponse>
<Notification code=”1501”>
<Message>The provided Shipment Identification Number is invalid. Please check the request message and
retry.</Message>
</Notification>
<Notification code=”999”>
<Message> Process failure occurred. Process ID associated for that transaction
(XXXXXXXXX).</Message>
</Notification>
</DocumentImageResponse>

26 HELPFUL XML AND WEB SERVICES LINKS

XML.Org Home Page, Organization for the Advancement of Structured Information Standards
(OASIS)
http://www.xml.org/

W3 Schools XML Tutorial, Reference Data

http://www.w3schools.com/xml/default.asp

Java Technology and Web Services, Sun Microsystems, Inc.

http://java.sun.com/MyDHL API/

Apache Web Services Project, The Apache Software Foundation

http://ws.apache.org/

W3 Schools Web Services Tutorial, Reference Data

http://www.w3schools.com/MyDHL API/default.asp

PAGE 417 OF 417