eCommerce UK
v 1.3.1
Division: DHL eCommerce

Best for:

  • eCommerce UK shipping and tracking
  • Creating Domestic (UK) and International parcel shipments (UK pickup) 
  • Retrieving product and service information, which can be used to integrate and enrich your own IT fulfilment systems
Region: United Kingdom
Used for: Information
Overview

The DHL eCommerceUK API(s) are a set of tools and services that enable customers and partners to integrate directly with our latest products. These services allow you to:

Shipment Tracking Reference
Shipment Tracking Reference
Create shipments and optionally return the labels Track your shipments as they transit our logistics network Retrieve product and service information, which can be used to integrate and enrich your own IT fulfilment systems

Scope

These APIs support the following types of parcel products

  • Domestic (UK) and International delivery
  • Domestic pick-up (UK)
  • Returns (UK)
  • Ability to generate ZPL, PNG, and PDF Labels, including return instructions

Created for developers

  • A single API based on industry standards that developers know and understand
  • Built with the fast-paced warehouse and time-sensitive e-commerce checkout in mind
  • Dedicated API environment to test your solution
  • Developer support from DHL API experts

 

Using the API

The API has been designed for use by developers. You will need basic knowledge of REST APIs, JSON, and HTTPS. Also, your organisation must to have an active customer account with DHL eCommerce UK. If you need to learn more on how to get an account, please use this web form

 

Use Cases

Use Case Overview

Below you can find an overview of the different use cases and supporting APIs

Use Case Service
ACCESS TOKEN Use the Access Token API to get the Oauth 2.0 access token for accessing DHL eCommerce UK API. Access token is valid for 1 hour.
PRODUCT CAPABILITY 

Use the Product Capabilities API to get domestic and international DHL eCommerce UK products available for your shipment. 

Provide the origin, destination country and postcode with weight to get the suitable product list. You can further filter available products with optional parameters e.g. destination address type, length, width, height etc.

CREATE SHIPMENT

Use the Shipping Label API to create DHL eCommerce UK shipments, you can optionally return labels and provide return (labels and instructions) and customs information.

It is recommended to first use the Reference Data API to retrieve valid product and service information. Passing invalid information will result in response errors when creating shipments.

CREATE LABEL Use the Shipping Label API, at this stage labels can only be generated during the create shipment process.
TRACKING Use the Tracking API, this service retrieves tracking statuses for DHL Parcel Shipments
SERVICES

Use the Reference Data APIs to get DHL eCommerce UK domestic and international services. Use the Service code from this API in shipping label API

The domestic UK service is combination of Product (Based on weight and dimensions) and service (Next day. Next day 9AM, Saturday).

PRODUCT INFORMATION

Use the Reference Data APIs, This service offers all of the reference and product data that can be used to crate shipments.

In addition you can use this service to keep your local IT systems and service up to date and synchronised with DHL eCommerce UK.

PRODUCT COUNTRY FEATURE

Use the Reference Data APIs to get DHL eCommerce UK offering in UK and internationally.

This gives reference for availability of particular DHL eCommerce UK product in given country.

US STATES

Use the Reference Data APIs to get US states codes. 

This is useful for sending correct state codes in DHL eCommerce UK shipping label API

COUNTRY DATA

Use the Reference Data API, when creating international shipments, it is important that valid country data be provided.

POST CODE VALIDATION
Use the Reference Data API, when creating domestic shipments, it is important that valid postal code data be provided.
CURRENCY  DATA

Use the Reference Data APIs to get the currency code and name 

This is useful for sending correct currency codes in DHL eCommerce UK shipping label API.

UK PUBLIC HOLIDAY DATA

Use the Reference Data APIs to get the UK public holiday data.

Public holiday information is useful to check days on which collections and deliveries can be arranged by DHL eCommerce UK  

UK POSTCODE DISTRICT DATA

Use the Reference Data APIs to get the UK Post code district data.

Post codes and postcode districts enables with accurate address enables on time deliveries.

Use postcode district API to validate postcode district in UK. Also get the service availability for delivery postcode district.

User Guide

Get Access

For onboarding, you need to follow this process guided by the DHL API team:

  1. Contact DHL to align use case and requirements. If you have an active account with DHL eCommerce UK please contact your Sales person or Account Manager.
    If you do not have an account please use this web form
    https://www.dhl.com/gb-en/home/our-divisions/parcel/business-users/business-services/sales-enquiry.html
  2. The DHL API team are unable to accept direct requests and will contact you directly once your case has been registered
  3. At this stage access to the sandbox API's will be provided - you can try and make requests directly from the reference docs section. Read the detailed documentation on how to use APIs.

Using the API

To get access to the API, you will receive a Client ID and a Client Password; please use the contact form to apply for these.            

The API provides OAuth 2.0 Access Token with various authorization scopes. 

The “Token” API call provides an OAuth 2.0 Bearer token with authorization scope, assigned to your client id. It grants you an access to use the APIs.

It is advisable to first use the Reference Data APIs to obtain valid product and shipping combinations. Invalid parcel combinations will not be allowed and will result in an error response. For example it will not be allowed to create an international shipment with a UK domestic service.

A sound understanding of the Reference Data APIs will accelerate onboarding.

Environments

The addressable API base URL/URI environments are:  

Environment Description
https://api-uat.dhl.com UAT environment
https://api.dhl.com Production environment

The UAT environment can be used for testing and development freely. Only the production environment will trigger underlying processes such as billing and operational procedures.

 

Rate Limits

Rate limits protect the DHL infrastructure from suspicious requests that exceed defined thresholds.

Should you exceed your rate limit you will receive a HTTP status code within the API response that will indicate this. 

In addition to the rate limit a so called “spike arrest” protects our API Platform from potential outages caused by a very large volume of requests sent in a short time span (minutes or seconds). This will be indicated by a different HTTP status code.

 

Shipping Label API

This API offers various functionalities that all support you in managing your parcel shipments. You will find a detailed description on how to use these along with snippets in the reference section 

Labels

  • This API can generate labels as a base64 encoded string
  • Labels are available for all covered products, i.e. DHL Parcel Connect, DHL Parcel Return Connect and DHL Parcel International, to understand how this works please visit the reference section 
  • Currently the following formats and resolutions are available:
  PDF ZPL 203 dpi
(10 x 15cm)
PNG 203 dpi
(10 x 15cm)
Connect P P P
Return
Connect
P P P
Parcel International P P P
  • When implementing DHL Parcel Return labels, it is recommended to additionally generate return instructions please visit the reference section to learn more

 

Legal Terms
  1. When using or accessing the DHL eCommerce UK API and its associated services (for the avoidance of doubt, a reference to DHL eCommerce UK API in these Legal Terms is deemed a reference to the DHL eCommerce UK API including the API Services, unless the context suggests otherwise) you are entering into a legal agreement and you agree to all of the terms and conditions set out in these Legal Terms without amendment. In agreeing to these Legal Terms, you have already agreed to abide by the General Developer Portal Terms of Use, which represents an additional binding agreement relating to your use of the DHL eCommerce UK API, whereas these Legal Terms prevail in the event of a conflict or inconsistency between the General Developer Portal Terms of Use and these Legal Terms (also see section “MISCELLANEOUS” of the General Developer Portal Terms of Use). 
  2. To register for the use of DHL eCommerce UK API You and/or the legal entity you are authorized to represent (hereinafter “You”/”Your”) need to have an active customer account with a DHL eCommerce UK entity (hereinafter referred to as “DHL”). An API Productive Key and access details will be provided to You subject to a successful validation of Your credentials by DHL. 
  3. If You engage an external developer, or other IT services provider to develop Your Application or any other third party (“Third Parties”) to access and/or use the DHL eCommerce UK API on Your behalf, You remain fully liable for any acts or omissions of such Third Parties in connection with the access to and/or usage of the DHL eCommerce UK API.
  4. The Legal Terms govern Your use of and/or access to the DHL eCommerce UK API and, unless otherwise stated herein, do not replace and/or modify the applicable terms and conditions of carriage; any transportation services agreement; or any other agreements with DHL 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 UK API the Legal Terms shall take precedence over the terms and conditions in an Agreement, unless an Agreement specifically addresses the use of or access to the DHL eCommerce UK API by You, in which case the Agreement shall prevail. 
  5. You grant DHL the right to use all data, documents, logos or other information transmitted by You to or within the DHL eCommerce UK API (“Information”), for the purposes specified in the API Services. This includes the use of the Information for the purpose of processing and transporting shipments. You shall ensure that all Information which You transmit to DHL via the DHL eCommerce UK API is complete, correct and accurate. You will be solely responsible for any damage or consequence that may arise from the use of false or incorrect or incomplete Information. You shall be solely responsible for, and shall indemnify DHL in full against, any claims, losses, damages or consequences that may arise from the use of or reliance on the Information. 
  6. You are responsible for all activities conducted via the DHL eCommerce UK API in accordance with all applicable laws, in particular competition, data protection and customs laws. You shall be responsible for the provision of the correct legal ground to process personal data in order for DHL to communicate with receivers and consignees of shipments. In particular, in countries where consent is required, You shall obtain the consent of any receiver for the receipt of any e-mail or SMS from DHL or any other data, documents or information in electronic form and in general, from any third party, for personal data owned by any third party and which You provided to DHL. On request of DHL, You shall provide DHL with evidence of such consent. 
  7. DHL will handle personal data in accordance with applicable data protection laws and the Deutsche Post DHL Data Privacy Policy. More information can be found on DHL’s Privacy Notice. You must process all personal data You send to us or obtain from us, according to applicable data protection laws.
  8. The API Services are provided on an "as is" basis. DHL, to the fullest extent permitted by law, excludes all warranties, whether express, implied, statutory or otherwise, including but not limited to the implied warranties of merchantability, non-infringement of third parties rights and fitness for a particular purpose. DHL, its affiliates or agents make no representations or warranties about the accuracy, completeness, security or timeliness of the API Services. No information obtained via the DHL eCommerce UK API shall create any warranty not expressly stated by DHL in the Legal Terms. 
  9. You shall use the DHL eCommerce UK API only for the legitimate contractual purposes and only in connection with Your DHL shipments. 
  10. These Legal Terms and the General Developer Portal Terms of Use as incorporated here into shall be governed by and construed in accordance with English law, without regard to its conflict of law principles. The courts of England shall have exclusive jurisdiction, unless a mandatory place of jurisdiction is applicable. Any references in the General Developer Portal Terms of Use to German or European Union laws shall be enforceable according to English law, and should such references to German or European laws be deemed unenforceable, the most similar legal concept under English law shall apply. 
  11. API Services

The following prerequisites and restrictions apply for the use of and access to the API Services, the data or the information provided via the DHL eCommerce UK API.

  • Shipment

When using the API Service “Shipment” this includes, amongst other things, the possibility to create and print shipping labels, to book shipment collections and access other value added services. Please be aware that the booking of the shipment within DHL eCommerce UK API does not constitute the contract of carriageThe contract of carriage will only be concluded when the shipment is handed over or picked up and accepted by DHL.

  • “Label”

The API Service “Label” provides You with the possibility to create and download labels for shipments. Please note that the creating and/or downloading of a label does not constitute the shipping contract. Such contract shall be governed separately. 

  • “Tracking”
    • Data requested and received via the API Service “Tracking”, such as transport status, estimated delivery time, including the tracking number 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’s prior written consent.
    • Tracking Data is provided to You and/or the entity you are authorized to represent under the prerequisite, that You retrieved the according tracking number in compliance with the applicable law, especially in the field of data protection and competition law and that You use the Tracking Data solely for Your own or Your customers’ legitimate tracking purposes.
    • You shall not combine Tracking Data with advertisement or present it in a way that it could be regarded as advertisement.
    • Unless otherwise agreed, You shall delete the Tracking Data 180 after the last tracking event is completed. Last tracking event shall be defined as the actual delivery unless otherwise agreed. 
    • The use and submission of Tracking Data – including submission to any of Your subcontractors – shall always be in compliance with applicable laws and regulations, including – without limitation – data protection laws and competition/antitrust law. 
    • If You are neither the sender nor the recipient of DHL eCommerce UK- or DP DHL Group-shipment/s, the Tracking Data refers to,
      • You shall ensure, that you are authorized to act on behalf of the sender and/or the recipient;
      • You shall make the sender and/or the recipient aware of the restrictions set out in this User Guide just as the General Developer Portal Terms of Use;
      • You shall make the sender aware of the necessity to inform the recipient transparently about the processing of his/her personal data according to applicable data protection laws;
      • You shall inform the sender and/or recipient transparently that the use of Your Application may result in the disclosure of data being subject to postal secrecy and data protection laws to third parties (including You).
1.0.0
15.Dec.2020
  • Initial release
1.0.1
20.May.2021

Added below new APIs for Access token, Product selection and Parcel Management reference APIs:

  • Access Token 
  • Product Capabilities API
  • Services
  • Products
  • Product country feature
  • Currency
  • Public holiday
  • UK postcode district
1.0.2
11.Jun.2021

Documentation updates

1.0.3
24.Sep.2021

Updates to documentation and support for IOSS.

1.0.4
05.Nov.2021

Updates to API reference documentation.

1.0.5
16.Dec.2021

Updates to API reference documentation.

1.0.6
02.Mar.2022

New API's

  • Request Pickup
  • Service Point Finder
  • Trading Location
  • Customs Declaration
1.0.7
22.Mar.2022

Updated API Contract

1.0.8
07.Mar.2023

Added What 3 Words parameter under consignee address. Added a new parameter customer ref 2 under shipment details and removed custom clearance reasons for export (returnedgoods and repairs) under customs invoice.

1.0.9
12.May.2023

Label format options updated to include PNG-RAW and JPG-RAW 
Drop off type called DEPOT for customers that exclusively drop their shipments at DHL eCommerce UK depots
New International call examples Internatonal_Shipment_Account_Address_Pickup, International_Shipment_DHL_Depot_Drop_Off, International_Send_To_3rd_Party_Drop_Off.
Incoterms updated for international shipments in the Data Schema.

1.1.0
23.Apr.2024

Implemented Tracking Event status reference call – now provides all tracking event status descriptions.
Introduced Tracking pieces – enables users to track individual shipment items.

1.2.0
02.Jul.2024

Introduced Tracking Images – enables users to download an image of a shipment delivery photo or shipment delivery signature.

1.3.0
08.Aug.2024

Shipment Labels API Update: This includes important changes related to the upcoming Windsor Agreement.

Details on Trade Lane Requirements, UK Internal Market Scheme (UKIMS), Timeline and Support, and Delivery Choices: For more information.

https://www.dhl.com/gb-en/ecommerce/business-users/business-services/technical-specification-update.html

Shipping Label Example: You can find an example in the "Request Body Examples" dropdown referenced as UK_Shipment_Account_Address_Pickup_Delivery_To_NI_B2C

https://developer.dhl.com/api-reference/parcel-uk#operations-tag-Shipping_Label_API_V1

Clearance Declaration Request Formats: These can be found in the "Show Data Schema" section, located below the example request body of the Shipping Label API v1. 

https://developer.dhl.com/api-reference/parcel-uk#operations-tag-Shipping_Label_API_V1

 

1.3.1
10.Oct.2024

Updated landing page, GET STARTED details and spec as part of name change.