The DHL ECOMMERCE AMERICAS API is your one stop solution to get shipping products, calculating duty and tax, generating shipping labels, manifesting packages, tracking packages and generating return labels.

The API can be used for:

• Only DHLeC packages originating within United States and Canada

• Domestic and international packages

• All DHL eCommerce Americas shipping products

Also, information about each error code can be directly referenced by appending the error code to the following URL. For example:

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

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

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 organization must have a customer account with DHL eCommerce Americas.

Example Use Cases

Simply Integrate in your existing website / solution

Easy integration into any eCommerce platform such as your Order Management System, Transportation Management System or an eCommerce website.

Merchants can use the API to get access to DHL Ecommerce Americas portfolio solution

Third Party Vendors (3PVs) and shipping aggregators can use the API to provide their customers with access to DHL ECommerce shipping solutions.

Sandbox

The Sandbox environment is your test bed while you are exploring the APIs and for building and testing your integration. From an application standpoint, the Sandbox environment and the Production environment are like-for-like, which means you can expect them to work exactly the same way. However, there are a few key differences.

• A label / manifest you created in the Sandbox environment won't be available in Production
• List of pickups that your account has access to may vary between Sandbox and Production
• List of API products that you have access to may vary between Sandbox and Production
• Capacity of servers for processing Sandbox requests will be significantly lesser when compared to Production
• Master data setup (Sold-To and Pick-up Account numbers, list of accessible distribution centers, content Category codes allowed) may be different between Sandbox and Production

While you can feel free to explore and test the APIs in the Sandbox environment, kindly work with your Client Success Manager / Implementation manager to ensure the master data setup has been completed before you decide to go live in Production.

To avoid any confusion, the Sandbox environment has it's own URL which is listed below.

There is no cost of using the Sandbox environment although requests can be throttled and/or blocked permanently if the system detects excessive or abusive usage patterns.

Following are the endpoints for the different environments.

Use the Sandbox as your test bed for experimenting with the API collection, for building your integration and testing your workflows. When you're ready, switch to production and you're ready to roll.

To use the DHL eCommerce Americas API, you need to have an understanding of how we limit the number of requests that you can submit to one or more resources at a given point of time and over a period of time.This protects the web services from being overwhelmed with requests beyond their peak capacity and also protects against unwarranted distributed denial-of-service (DDoS) attacks on the system.

All of our APIs are rate-limited on two levels -

• Number of requests you can submit in parallel for a single resource (Spike Arrest)
• Number of requests you can submit over a period of time (1 day, 1 week etc.) for one or more resources (Quota Violation)

The first limit is to protect our resources against sudden traffic surges. This throttles the number of requests sent to the back end, protecting against performance lags and downtime.

The second limit is an outcome of a configuration on the number of request messages that a resource/group of resources allows over a period of time, which in our case is set to a per week basis. This can be different for each client, and is dependent on many factors. Kindly consult your Client Success / implementation manager if you have questions on what these limits are set to specific to your account.

What happens when your request is throttled?

You will receive a 429 error with an error response body that provides more information on if your request was denied due to a spike arrest or a quota violation. The detailed error codes between these two issues are also different.

If you're receiving this error and believe this is incorrect, please contact your implementations/account manager who will be able to verify your quota and increase it if necessary.

How to avoid throttling?

There are a few things you can do to avoid running into the issue of spike arrest or quota violations.

• Know the limits for your account on both these dimensions
• Spread out your requests so they are not submitted all at strike, rather spread out throughout the hour and day
• Design your integration in a way where if your request is throttled, have a mechanism to queue them up and re-submit them later.
• Take advantage of hours where there's usually less traffic, such as between 10 PM and 6 AM Eastern time.