Changes

The DHL eCommerce API v4 introduces a number of enhancements, fixes and new features aimed at improving the integration experience:

• Improved availability, enabled by a behind-the-scenes technology refresh
• Improved performance, with aggressive latency and throughput targets
• New product finding and rating capabilities, for accurate up-front rate information
• New estimated delivery date (EDD) functionality, for easier planning and decision-making
• An updated end-of-day closeout and manifesting process, avoiding network timeouts and performance issues
• Additional fields required by some countries in 2021 for cross-border shipments
• Integration of the duty and tax calculator (DTC) as part of a unified API portfolio

Deprecation Schedule

Users of the DHL eCommerce v1, v2 and v3 APIs are encouraged to migrate as soon as possible. In particular, all international customers should migrate to v4 by January 2021 in order to remain compliant with upcoming cross-border regulatory requirements. Domestic customers on the older v1 API should also migrate by January 2021. Domestic-only customers on the v2 API should migrate by July 2021. All customers on the v3 API should migrate by May 28, 2021.

Error Code Nomenclature

The error code returned in the body of the error response is structured as follows:

Example: 400.0204002

400 - HTTP standard Error code. Also returned in the response header.

02 - refers to a specific service.

Following are the service specific codes.

• 00 - Gateway-related errors AND errors returned by more than one API
• 02 - Label
• 03 - Tracking
• 04 - Manifest
• 06 - Product Finder
• 09 - DTC
• 10 - Transportation
• 13 - Return Label

04 - indicates API version number. Currently, only 04 is in use. For generic errors, version number is 00 as this does not change between versions.

002 - refers to a serialized error number to make each error code unique. Refer below for the complete list of error codes.

Sample error response is shown here:

{
  "type": "https://api.dhlecs.com/errors/v4/400.0204001",
  "title": "Mandatory Query Parameter Missing",
  "invalidParams": [
    {
      "name": "format",
      "reason": "Label format is a required query parameter"
    }
  ]
}

invalidParams is an array that provides details on specific error fields and none, one or more errors can be returned. For generic errors, the invalidParams object will be omitted from the response. We recommend using the error type, error code and title to get help regarding the error.

Also, some error messages will not have the name element if the error is generic to the request rather than a specific element. However, the invalidParams object will be returned with just the reason in order to provide more detail on the error beyond what's described in the error title.

Information about each error code can be directly referenced by appending the error code to the URL. For example -

 https://api.dhlecs.com/docs/errors/400.0204003

The same error URLs are also returned in the API responses when there is an error. This allows clients to quickly get detailed information on each type of error.

Error Response

DHL eCommerce uses HTTP status codes for errors (e.g. 400, 401, 403). These error codes are explained in detail in the List of Error Codes section. Within each status code there are more specific error codes available in the body. All error responses use the following format:

M- Mandatory O- Optional C- Conditional N- Not Applicable

General Error Codes

400

A 400 error code is returned when the server cannot or will not process the request due to a client error.

400.0000001

Mandatory query parameter(s) missing or invalid query parameter(s) present

The server cannot or will not process the request due to a client error. In this case, one or more mandatory query parameter name(s) were missing from the request or invalid query parameter name(s) were present.

Used in: POST Label, GET Label, GET Tracking

400.0000002

Query parameter value could not be found or is invalid.

The server cannot or will not process the request due to a client error. In this case, a query parameter value requested was not found in the database.

Used in: GET Label API

400.0000003

Invalid request

The server cannot or will not process the request due to a client error. In this case, a deceptive request was detected hence the request was denied.

Used in: All APIs

400.0000004

Invalid grant type

Invalid Grant type error occurs when the grant type header is not sent in the Auth request or an invalid value has been provided. We use OAuthV2 Basic Authentication that expects a grant_type of client_credentials to authenticate the credentials and provide an access token.

Used in: Access Token API

400.0000999

Unknown exception - bad request

The server cannot or will not process the request due to a client error. Unknown exception due to a bad request occurs when a request could not be processed due to an unexpected error encountered in the API service due to bad data. Unfortunately, additional information cannot be provided about the error in the response itself. Kindly contact support with a snapshot of the error request along with the Correlation ID (if you received one in the response header) and we will be able to assist you.

Used in: Label, Manifest, Tracking, Transportation, Product Finder, DTC API

404

The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.

Just so you know, in a worst case scenario, you might see a generic version of this error that our service is completely down that we are not even able to return a proper error message.

{
  "fault" : {
    "faultstring" : "Unable to identify proxy for host: ecs and url: \/auth\/v4\/accesstoken",
    "detail" : {
      "errorcode" : "messaging.adaptors.http.flow.ApplicationNotFound"
    }
  }
}

404.0000001

Undefined resource

For example, under shipping/v4, the valid resources are /label and /manifest. If the gateway receives a request for any other resources beyond what is recognized, an undefined resource error is returned. This is also true when the request contains URI parameters before and/or after the accepted the resource names.

For example, /shipping/v4/label/print or something equivalent will also return this error.

Used in:
Access token, Label, Manifest, Tracking, Transportation, Product Finder, DTC APIs

500

A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

500.0000001

Internal gateway authorization error

A generic error message, given when an unexpected condition was encountered and no more specific message is suitable. Internal Gateway Authorization error occurs when there is authorization failure between the API gateway and the backend services. This is not a client-side error and is not due to invalid credentials, token or pickup number provided.

Used in:
Label, Manifest, Tracking, Transportation, Product Finder, DTC API

500.0000002

Internal gateway server error

A generic error message, given when an unexpected condition was encountered and no more specific message is suitable. Internal Gateway Server error occurs when an unknown error has occurred in the API gateway or in the backend service or both.

This may/may not be a client-side error and will require further investigation before the cause of the error can be ascertained. Kindly contact support and provide a snapshot of the request along with the Correlation ID (if available) to get assistance.

Used in:
Access token, Label, Manifest, Tracking, Transportation, Product Finder, DTC API

500.0000999

Unknown exception - API service

A generic error message, given when an unexpected condition was encountered and no more specific message is suitable. Unknown Exception in the API service when when we run into a unhandled generic exception in the API service.

While this is completely rare, this may/may not be a client-side error and will require further investigation before the cause of the error can be ascertained. Kindly contact support and provide a snapshot of the request along with the Correlation ID (if available) to get assistance.

Used in:
Label, Manifest, Tracking, Transportation, Product Finder, DTC API

Label API Error Codes

400

400.0204002

The supported label formats are ZPL and PNG

This error occurs when an unsupported label format value is requested. The supported label formats are ZPL and PNG.

• ZPL labelData is provided with an encodeType of PLAIN.
• PNG labelData is provided with an encodeType of BASE64.

400.0204002

Static Validation Failed

The server cannot or will not process the request due to a client error. A static validation error occurs when the request could not be validated successfully against the underlying schema. This can be due to missing mandatory fields, incorrect field types used, invalid JSON request body, invalid enum field values sent and more.

More information about which field(s) failed validation are provided in the invalidParams object in the error response. Refer to the latest service schema for the specifications.

400.0204003

Dynamic Validation Failed

The server cannot or will not process the request due to a client error. A dynamic validation error occurs when the request could not be validated successfully against requirements that are specific to the attributes of the request, such as the Ordered Product ID, Country, Postal Code, Weight, Customs Details and many more. This can be due to missing field values, values above or below a certain threshold, values not in specified format and other reasons.

More information about which field(s) failed validation are provided in the invalidParams object in the error response. There are thousands of dynamic validation rules for different combinations of the above parameters.

404.0404003 - Manifest not found

This error will be returned when the manifest requestId is invalid for the specified pickup.

Used in:
Get Manifest API

404.1004001 - Data Validation Failed

Pickup Shipment does not exist for the given shipment identifier.

Used in:
PICKUP API

500.0204001 - Unknown downstream error

Unknown downstream error occurs when there's an unexpected, unknown exception between the internal DHL systems, such as between the API services and the Domestic/International package processing systems.

This may/may not be a client-side error and will require further investigation before the cause of the error can be ascertained. Kindly contact support and provide a snapshot of the request along with the Correlation ID (if available) to get assistance.

Used in:
Label API

500.0604001 - 500.0604025 - Internal Server Error

A generic error message, given when an unexpected condition was encountered and no more specific message is suitable or relevant for the client. This can be due to a number of internal errors that are masked from the client hence there's a range of error codes possible from 001 to 025.

Used in:
Product Finder API

500.1304001 - 500.1304025 - Internal Server Error

A generic error message, given when an unexpected condition was encountered and no more specific message is suitable or relevant for the client. This can be due to a number of internal errors that are masked from the client hence there's a range of error codes possible from 001 to 025.

Used in:
Return Label API

Product References

Domestic Products

International Products

Return Products

Regulations

International Regulations

Updated October 8, 2021

Additional Information

Distribution Centers

Service Endorsements

Content Categories

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

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

Consignee ID Types

Tax ID Types

Weight Units

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

Dimension Units

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

Service

User Agents

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

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

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

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

User-Agent: <REGISTRATION_ID> <SOFTWARE_NAME>

Example:

User-Agent: ABC123 ShipMaster Pro

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

Country Specific Resources

Canadian Provinces

Brazilian States

Duty & Tax Supported Countries & Currencies

International Destinations Not Serviced

Updated October 8, 2021

Glossary

Identifiers

packageId

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

Example: GM60511234500000001

dhlPackageId

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

Example: 3387191106122423

trackingId

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

Example: 420071149361269903500011492028

deliveryConfirmationNumber

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

Example: 9361269903500011492028

overlabeledDspNumber

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

Example: 9261269903500013618305

intelligentMailBarcode

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

Example: 0031043534391627906195625053434

overlabeledIntelligentMailBarcode

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

Example: 0031043534391640211895625057522

manifestId

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

Example: 532903701308165834461

requestId

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

Example: bae87627-3566-4670-b8d2-fe90bfed75a9

Conventions

Package

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

Shipment

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

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

Manifest

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

Order

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

Container

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

De minimis

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

Other

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

SPECIFICS FOR THE USE OF DHL ECOMMERCE AMERICAS API

To register for the use of and/or access to DHL eCommerce Solutions' Americas API and the underlying API Services (label, manifest, tracking) - hereinafter referred to as DHL eCommerce Solutions Americas API - you and/or the entity you are authorized to represent (hereinafter "You"/"Your") need to have an account with and/or have entered into a Customer Services Agreement with Global Mail, Inc. dba DHL eCommerce Solutions. If You engage an external developer or other IT services provider to represent You and to develop Your Application according to the General Developer Portal Terms of Use and these special API terms & conditions (also referred to as "Legal Terms"), You are liable for the acts or omissions of such third party in connection with the access to and/or usage of the DHL eCommerce Solutions Americas API.

These Legal Terms and the General Developer Portal Terms of Use govern your usage of and/or access to the DHL eCommerce Solutions Americas API including the API Services and, unless otherwise stated herein, do not replace and/or modify any other DHL eCommerce Solutions terms and conditions of Carriage, Customer Services Agreements and/or any other agreements, contracts or SOWs with DHL eCommerce Solutions or any of its affiliates, which govern services or products provided to you (separately, each an "Agreement"). Notwithstanding the foregoing, you expressly acknowledge and agree that solely with respect to Your use of and access to the DHL eCommerce Solutions Americas API these Legal Terms and the General Developer Portal Terms of Use shall have preference over the terms and conditions in an Agreement, unless any terms and conditions in an Agreement specifically address the use of/access to the DHL eCommerce Solutions Americas API by You, in which case the specific terms and conditions of the Agreement shall prevail with respect to Your use of/access to the DHL eCommerce Solutions Americas API.

You shall use the services and/or data that You receive via the DHL eCommerce Solutions Americas API only for the legitimate contractual purposes and only in connection with DHL eCommerce Solutions' carriage services. DHL eCommerce may revise and update these Legal Terms at any time. Your continued usage of the Site after any changes to these Legal Terms will mean You accept those changes.

The following prerequisites and/or restrictions apply for the usage of data or information received via the DHL eCommerce Solutions Americas API:

Product Finder

DHL eCommerce Americas Product Finder API enables clients to determine which DHL shipping products are suitable for a given shipping request including estimated rates and estimated delivery dates (EDD). The rates returned are account-specific along with a list of applicable surcharges (if any). The DHL Product Finder API covers most DHL eCommerce Americas shipping products, both Domestic and International.

At this time, dimensions and dimensional weight are not considered when estimating rates.

PLEASE NOTE: The rates and delivery dates provided by the Product Finder are estimates only and may not reflect the actual billed rates or delivery times. The accuracy of the rate information depends on a number of factors, including the accuracy of Your input.

Label

The API Service "label" provides You with the possibility to create and download labels for singular shipments. Please note that the creating and/or downloading of a label does not constitute the contract of carriage. Such contract will be concluded once the labeled package is handed over or picked up and accordingly accepted by DHL eCommerce Solutions.

Manifest

The API Service "manifest" provides You with the possibility to select single items/packages for manifest (via package ID), to generate a Driver's Summary Manifest (DSM) as a pdf-file and download/print the DSM when required in order to facilitate handover of the DSM to the driver at the time of pickup.

It is in Your sole responsibility to select the correct (number of) packages for manifest and to check whether all relevant packages have been included to the manifest.

Tracking

Data requested and received via the DHL eCommerce Solutions Americas API, such as transport status, estimated delivery date, is hereinafter referred to as "Tracking Data".

Tracking Data is Confidential Information in the meaning of section "Communication" of the General Developer Portal Terms of Use. Other than set forth below You must not reveal and/or provide third parties with the Tracking Data and/or analyze, modify such data in any form and/or derive data/information especially for competitive purposes from it without DHL eCommerce Solutions' prior written consent.

You may only submit Tracking Data provided to You via the DHL eCommerce Solutions Americas API to the recipient of the packages and no other person. Such submission shall always be in compliance with applicable laws and regulations, including without limitation data protection laws and competition/antitrust law. Without limiting any of the foregoing, You shall ensure that the data shall not be combined with an advertisement or presented in a way that it could be regarded as advertisement.

If You are neither the Shipper nor the recipient of packages the Tracking Data refers to, the following applies additionally. You represent and warrant that:

• You are duly authorized to act on behalf of the Shipper;
• You shall make the Shipper aware of the restrictions set out in these Legal Terms and the General Developer Portal Terms of Use;
• You shall make the Shipper aware of the necessity to inform the recipient about the processing of his/her personal data according to applicable data protection laws.

Unless otherwise agreed, You shall delete the Tracking Data (including the transport history) 90 days after the delivery is completed. DHL eCommerce Solutions shall not be required to provide Tracking Data to You that is older than 90 days from the delivery date.