DHL Express REST API Enhancements

Overview

Effective April 10, 2025, we’re doing key enhancements to your DHL Express REST API integration. These updates are designed to improve your shipping and returns experience with better API reliability, expanded features, and seamless operation.

Key details

The new REST API features improved shipment data, automatic paperless invoices, and new DHL box types.
Labels will reflect paperless processing (PLT), and rate results are now included in Labels API responses.
This update impacts all existing AfterShip Shipping and Returns customers using a MyDHL Express carrier account, as well as all new customers.
AfterShip Shipping and AfterShip Returns services will continue without downtime.
All enhancements will be made on the backend, so no action is required from the customer.

Key API Enhancements

Require action from your end

These enhancements require you to take some actions to ensure your shipping and returns services remain compatible with the updated API.

API enhancement	Details	Before	After	Action required
New set of `box_type` Enum	Legacy `box_type` values are deprecated. New values should be used for DHL shipments.	The following values were used. `custom, dhl_express_envelope, dhl_other_dhl_packaging, dhl_flyer, dhl_jumbo_box, dhl_junior_jumbo_box, dhl_jumbo_document, dhl_jumbo_parcel, dhl_document, dhl_domestic, dhl_express_document, dhl_jumbo_junior_document, dhl_jumbo_junior_parcel, dhl_parcel`	New values will be used. `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`	Customers using DHL-provided boxes should update their `box_type` values to match the new ones.
Rates API response `detailed_charge.type` value change	`detailed_charge.type` values are now in lowercase instead of uppercase.	`"DEMAND SURCHARGE"`	`"demand_surcharge"`	Customers relying on this field should update parsing logic.
Handling `carrier response charge = 0`	`total_charge` will now be `null` instead of `0` when no rates are returned.	`"total_charge": { "amount": 0, "currency": null }`	`"total_charge": null, "info_message": "No rate quotes returned from carrier."`	No action needed, but customers should expect this updated response format.

Require no action from your end

These enhancements 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.

API enhancement	Details	Before	After	Action required
Include `getAdditionalInformation` when creating shipments	DHL shipments will now always include additional shipment data for future improvements.	Not included in shipment requests.	Now includes `"getAdditionalInformation": [{ "typeCode": "optionalShipmentData", "isRequested": true }]` . Note: This change only affects our API interactions with the carrier and does not impact the customer's API experience with us.	No
Auto-apply `paperless invoice`	Paperless invoices will be enabled by default. Non-paperless-eligible shipments will still succeed with `bypassPLTError=true`.
1. Domestic & EU to EU shipments			No impact on customer-facing API behavior or label output even though we make changes to our raw request to DHL.	No
2. International shipments
Case 1: Non-qualified shipments created with paperless_invoice		Label creation fails with error: `Bad request: 7008`	Label creation will now succeed without error.	No
Case 2: Qualified shipments not created with paperless_invoice		Label shows ADI (Advance Data Included)	Label will show PLT (Paperless Trade) instead of non-PLT.	No
Case 3: Qualified Shipments created with paperless_invoice			No impact. These shipments always succeeded as PLT.	No
Case 4: Non-qualified shipments not created with paperless_invoice			No impact. These shipments will continue as non-PLT.	No
Always get DHL commercial invoice	DHL-generated commercial invoices will always be used when requested.	API response varied and DHL commercial invoice was not always provided.	API response remains unchanged, but now will always retrieve the DHL commercial invoice.	No
Show "Original Export Tracking ID" on Returns commercial invoice	Returns invoices will display the original outbound tracking number if available.	`"Original Export Tracking ID"` was empty	`"Original Export Tracking ID"` will display outbound tracking number if available	No
Trim `parcel.description` and `parcel.items.description`	Extra spaces will be trimmed to prevent label failures.	Label creation fails if descriptions contain leading or trailing spaces.	Label creation will succeed after trimming spaces.	No
Add Dangerous goods `customDescription` for `PI001` shipments	`"LIMITED QUANTITIES ROAD ONLY"` will now appear on labels for these shipments.	No `customDescription` was sent to DHL	`customDescription = "LIMITED QUANTITIES ROAD ONLY"` will appear on labels.	No
Apply `tax_id_type` mapping	`tax_id_type` will now determine `registrationNumbers.typeCode`, improving tax information accuracy.	`registrationNumbers.typeCode` inferred from shipment data	`tax_id_type` will be explicitly mapped to `registrationNumbers.typeCode.` Otherwise, we will refer to shipment data. Example: `vat → VAT`, `gst → GST`, `ioss → SDT`, `eori → EOR`	No action needed, but providing `tax_id_type` ensures better mapping.
Include rate results in Labels API response	Rate results will be returned in the Labels API response.	The response always displayed `No rate quotes returned from carrier`, and `total_charge` had no value.	The Labels API response will now include `total_charge` and `detailed_charges`.	No
Trim address lines in Rates API request	Address fields exceeding 45 characters will be trimmed to prevent rate calculation failures.	Rate calculation fails if street1, street2, or street3 exceeds 45 characters.	Only the first 45 characters will be used to prevent failure.	No
Rates API Response date format update	Date format now includes the organization’s time zone.	`2024-12-06T22:00:00`	`2025-03-03T19:00:00+08:00`	No

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

Updated on: 07/04/2025