DHL Express XML to REST API Migration Guide

Overview

Starting April 21, 2025, DHL Express is transitioning from the legacy XML API to the new REST API. This migration will occur in three phases and is aimed at improving reliability, security, and feature support.

Key details

The migration from the XML API to the new REST API will occur in the background, with no need for customers to manually update their credentials.
Your existing XML API credentials will automatically be migrated to the new REST API.
New accounts will automatically use the new REST API credentials (Account number, API Key and API Secret).
AfterShip Shipping and AfterShip Returns services will continue without downtime.
The XML API will be fully deprecated on June 3, 2025 for Non-Enterprise customers, and they will need to use the new REST API to access all DHL Express services.

Migration timeline

Phase	Timeline	Customers
Phase 1	April 21 - May 5, 2025	AfterShip Shipping Essentials and selected Pro plan customers
Phase 2	May 6 - 18, 2025	AfterShip Shipping remaining Pro plan and selected AfterShip Returns Non-Enterprise customers
Phase 3	May 19 - June 3, 2025	All remaining Non-Enterprise AfterShip Returns customers

Key changes

Outlined below are the main behavior changes you can expect when transitioning to the new MyDHL integration from XML API. Please review these changes and take actions to ensure smooth operation and avoid issues during label generation and rates calculation.

Require action from your end

These changes require you to take some actions to ensure your shipping and returns services remain compatible with the new REST API and to avoid running into any errors.

invoice.number or order_number required for generating commercial invoice

To generate a DHL commercial invoice, either invoice.number or `order_number`must be provided. If neither is provided for international shipments, label generation will fail with the error data.invoice.number is a required property

ship_to.city is now required

Due to changes in the DHL integration, the ship_to.city field is now required for label generation and rate calculation. If ship_to.city is not included, label generation and rate calculation will fail with an error data.shipment.ship_to.city is a required property.

Address length limitation change

All address fields ( street1, street2, street3) now have a length limitation of 45 characters. If the address length exceeds this limit, label generation will fail with the error data.shipment.ship_to.street1 is too long, maximum length is 45.

New set of box_type enum

Customers using DHL-provided boxes should update their box_type values to match the new ones.

custom
dhl_box_2
dhl_box_3
dhl_box_4
dhl_box_5
dhl_box_6
dhl_box_7
dhl_box_8
dhl_tube_small
dhl_tube_large
dhl_card_envelope

You will not run into any errors if you continue to use the legacy box_type values.

Require no action from your end

These changes don't require any changes or actions from you. The API will continue to work as it did before, but the changes are either internal or will be handled automatically by the API itself. You will greatly benefit from the improvements without needing to modify your integration.

Auto-apply paperless invoice

Paperless invoices are now enabled by default, with no impact on domestic or EU to EU shipments.
For international shipments, qualified shipments not created with paperless_invoice will default to Paperless Trade (PLT), while non-qualified ones will continue as non-PLT.
Shipments created with paperless_invoice will succeed without errors.

💡 What disqualifies shipments for Paperless Trade (PLT) ?

Whether a shipment is eligible for paperless trade can depend on the carrier or the countries involved in shipping. For example, a domestic shipment doesn't require a customs declaration, so no commercial invoice is needed for customs, making it "not qualified" for paperless trade. Example, for shipments to certain countries, such as Vietnam, where hardcopy invoices are required (and electronic commercial invoices are not accepted), the shipment is "qualified" for paperless trade.

Always get DHL commercial invoice

DHL commercial invoices are always provided when requested, as long as the API includes an invoice object.
For customers using the AfterShip Returns product, the commercial invoice will be in DHL Returns format and will display the Original Export Tracking ID if available.

DHL commercial invoice output change

There are two changes to the DHL commercial invoice output:

The Position value will now be empty instead of Manager.
The Signature value will no longer default to using ship_from.contact_name. You can specify the signature name using the API request field invoice.signature_name.

Apply tax_id_type mapping

The tax_id_type will now directly map to registrationNumbers.typeCode, improving tax information accuracy (e.g., vat → VAT, gst → GST). If tax_id_type is not provided, shipment data will be used instead.

DHL service name change

The service name will change from DHL Domestic Express to DHL Express Domestic, but this will not impact API behavior.


Refer to DHL Express Troubleshooting Tips if you need more help on DHL Express.

Updated on: 07/04/2025