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
Thank you!