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
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, JPEG 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

Get Access

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

1. Contact DHL to align your use case and requirements.
   If you have an active account with DHL eCommerce UK, please contact your Salesperson or Account Manager.
2. 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
3. The DHL API team are unable to accept direct requests.
   They will contact you once your case has been registered by your Salesperson or Account Manager
4. You can make test requests directly from the sandbox APIs.
   The reference documentation allows you to test various API requests to DHL eCommerce UK without an account number using pre-defined credentials (see Access Token). Make sure you review the detailed documentation and schemas on how to use the APIs.

Using the API

To get access to the UAT and production API, you will receive a Client ID and Client Secret for each.
Please contact your Sales or Account Manager who will request these on your behalf.

The API uses OAuth 2.0 with access tokens that include specific authorization scopes.

The “Token” API call provides an OAuth 2.0 Bearer token assigned to your client ID. This token grants access to the APIs and is valid for 1 hour.

It is advisable to start by using the Reference Data APIs to obtain valid service, product, and routing combinations.
Invalid combinations will not be allowed and will result in an error response.
For example, an international shipment cannot be created with a UK domestic service.

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

Client Secret Expiry

Your client secret will automatically expire after 12 months. For the production environment a new client secret will be emailed to you 6 weeks before the expiry date.

Please ensure your contact email details remain up to date by liaising with your Sales or Account Manager and informing them of any changes. 

Failure to update the client secret will prevent you from requesting a token and making subsequent API calls. The API will return an error indicating that the client secret has expired. Please check your email for the updated credentials and update your platform accordingly or contact the DHL IT Service Desk for support and notify your Sales/Account Manager.

Environments

The addressable API base URL/URI environments are:  

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.

Best Practices for API Usage

To optimise your experience and maintain the stability of the API, we strongly encourage you to adopt the following best practices:

• Distribute Requests: Instead of sending a large number of requests in single bursts, please spread out your API requests over a longer period. This will help prevent hitting the rate limits and ensure that your requests are processed smoothly.
• Implement Backoff Strategies: If you receive a rate limit or spike arrest response, consider using a backoff strategy that increases request wait times in your application. This involves waiting progressively longer between retry attempts, which can help reduce the load on the API and improve the chances of successful requests.
• Monitor Usage: Regularly monitor your API usage patterns to identify any potential spikes or trends. This can help you adjust your request strategy proactively and avoid disruptions.

Shipping Label API

This API offers various functionalities that all support you in managing your parcel shipments.

Labels

This API can generate labels as a base64 encoded string, labels are available for all covered products i.e. Domestic, International and Returns. Currently the following formats are available as 203 dpi (default) and 300 dpi resolution with options for either portrait (default) or landscape label orientation, to understand how this works please visit the Reference Docs Shipping Label API V1 parameters section.

• PDF
• ZPL
• PNG
• JPG

Please ensure that you request the correct DPI setting for your printer when generating labels via the API. It is your responsibility to verify that the label is printed at the highest possible quality to meet operational requirements.

Shipment Consolidation

DHL eCommerce UK's Cloud API solution does not support automated shipment consolidation.
It is the client's responsibility to ensure that all items intended for a consolidated shipment are combined before the Shipment API call is submitted and labels are generated.
If additional items need to be added to a shipment, we provide an Amendment API that allows you to update item details and weights so that the shipment accurately reflects the final contents.
For any consolidation requirements at a billing or commercial level, please speak with your Sales or Account Manager.

Windsor Framework – Mandatory Requirements for Northern Ireland Shipments

For shipments destined for Northern Ireland, please ensure compliance with the Windsor Framework requirements.
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

International Shipments – Service Offerings & Customs Requirements

For shipments to international destinations, please review our available service options and the mandatory customs data required for smooth processing.
https://www.dhl.com/gb-en/ecommerce/uk/international-parcel-delivery/international-parcel-delivery-services.html

• When implementing DHL eCommerce Return labels, it is recommended to additionally generate return instructions please visit the reference section to learn more.

Customer Testing, Validation and Operational Readiness

Before you begin sending parcels through the live DHL eCommerce UK network, it’s important that your own systems, processes, and integration have been thoroughly checked and confirmed as ready for day‑to‑day use. The following points outline the key areas you should review during preparation.

1. Data Accuracy
   Make sure the information you pass into the API is complete and correctly formatted. This includes using the right data types, keeping within the defined character limits, filling in all mandatory fields, and ensuring that address and parcel details are accurate. If the data doesn’t meet the expected standards, shipments may fail or be delayed.

2. Service and Destination Checks
   Please confirm that the service you request (the ordered product) is valid for the destination you’re sending to. Any destination‑specific rules or restrictions need to be taken into account. Your system should also be able to cope if a service is unavailable or if an alternative is required.

3. Label and Tracking Verification
   Check that the labels produced are correct and suitable for DHL operations. You should also ensure that tracking updates are captured and processed correctly within your own system.

4. Error Handling and Reliability
   Your integration should deal properly with any error responses, warnings, or temporary failures returned by the API. This includes interpreting error codes correctly and applying sensible retry logic where appropriate.

5. Performance and Volume Testing
   Your system should be tested under the level of activity you expect to process in real operations. This includes busy periods, large batches, and multi‑user environments to make sure everything performs consistently.

6. Collection Arrangements
   Before live parcels are handed over, you must have an agreed collection method in place with DHL eCommerce UK. This may be a scheduled, regular collection arranged through the Sales or Operations teams, or ad‑hoc pickups booked through the Pickup API (Pickup API v1). Please don’t send parcels for dispatch unless the collection process has been confirmed.

7. Pre‑Go‑Live Shipment Check
   Before your full volume goes live, it’s recommended that you send at least one complete test shipment through the network. Let your Sales Manager or Account Manager know when you intend to do this. Running an end‑to‑end test helps confirm that routing, labelling, and operational processes behave as expected.

8. Customer Responsibility
   Any issues caused by incomplete testing, inaccurate data, or unsupported processes cannot be accepted by DHL eCommerce UK. It remains the customer’s responsibility to ensure all technical and operational requirements are met before switching to production.

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 carriage. The 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).