DHL Shipping

Carrier-specific setup for DHL Shipping in Shipping Labels.

Purpose

This page describes the DHL Shipping setup in Shipping Labels. It covers domestic parcel scenarios, return labels, SOAP and REST credentials, participation numbers, print format, detailed request properties, and optional international return handling.

Prerequisites

  • The shared Shipping Labels setup is complete.
  • The required DHL Shipping credentials and URLs are available for the target environment.
  • Country data contains the required ISO Alpha-3 values for REST-based scenarios.
  • Default sender contact data and package data are available.
  1. Decide whether the rollout should start directly with REST credentials.
  2. Maintain the required URL entries for test or productive use.
  3. Maintain credentials, participation number, default sender email, and print format.
  4. Configure request properties such as return labels, validation, insurance, and notification behavior.
  5. Add international return settings only for locations and products that actually support them.

Setup components

Prefer REST credentials and keep SOAP only for compatibility

DHL Shipping currently spans older SOAP-based values and newer REST-based access. For public guidance, the safest rule is to prefer REST credentials from the beginning whenever the carrier account supports them.

The setup may contain:

  • REST API username, password, key, and REST URL
  • older SOAP-oriented values such as CIS EKP, signature, user, and SOAP URL
  • participation numbers and additional request properties on the carrier setup

In test mode, Test Cis EKP, Test Cis Signature, Test Cis User, and Test URL SOAP belong to the older SOAP path. The preferred REST path instead uses API Username, API Password, API Key, and Test URL REST.

Once REST credentials are complete, they take priority over SOAP values.

Keep the credential groups operationally separate:

  • Use REST credentials as the preferred target state for new rollouts.
  • Keep SOAP credentials only for older account setups that still require them.
  • Maintain the required test or productive endpoint in Shipping Label URL before you assign it on the DHL Shipping setup.
  • If a default sender email is maintained on the setup, it acts as fallback when the customer email on the sales order is missing.

The same split remains for go-live: Cis EKP, Cis Signature, Cis User, and URL SOAP belong to the older SOAP model, while API Username, API Password, API Key Live, and URL REST form the preferred REST path. For productive REST scenarios, API Username and API Password typically match the DHL customer-portal login.

After the REST credentials are complete, older SOAP-only helper values no longer control the operational request flow.

Once the REST path is fully maintained, the Skip Address Validation setting also becomes relevant. Review deliberately whether the scenario should validate new addresses strictly or allow them more pragmatically.

Maintain print, return, and request properties as business decisions

The DHL Shipping setup contains a larger set of request properties than many other carriers. Relevant examples include print format, premium shipping, insurance, partial delivery, address validation, export documents, GoGreen participation, outbound and return product codes, and multi-package behavior.

These fields should not be filled mechanically. Maintain only the properties that the actual DHL Shipping business scenario requires.

For productive use, some of these fields need especially clear interpretation:

  • The participation number is not just another identifier; it is often used to separate different shipping-cost categories under the same DHL customer number.
  • Insurance also requires a meaningful insurance amount once it is activated.
  • Export documents and a meaningful goods description become relevant mainly for international destinations outside the EU.
  • Contact person and email address are not just master data; they are the basis for notifications and clarification during the delivery flow.
  • Product code and return product code should be maintained only with the DHL values that are contractually released for the account.
  • The print format should match the real output process; A4 is the common default, but not always the correct operational target.
  • Strict address validation can also reject genuinely valid new addresses if they are not yet fully known in DHL’s address data.

Some fields around the return-label type still come from the SOAP model and should only be maintained where that model is still contractually or technically required.

Configure return labels and international returns explicitly

Return labels and international return scenarios require deliberate activation. In addition to the return toggle, maintain the return-related product setup and the receiver IDs needed for participating locations if international returns are used.

Not every location or product combination supports international return processing, so avoid documenting this as a universal default.

For international returns, use a controlled sequence:

  1. Go to the lower international-return section of the DHL Shipping setup.
  2. Activate International Return Shipment only for scenarios that are contractually supported.
  3. Maintain the general receiver ID from the DHL business portal and assign the correct live or test endpoint.
  4. Open Countries/Regions and maintain the receiver IDs for the specific participating locations.

The general receiver ID acts as the default. Country-specific receiver IDs in Countries/Regions override that default for the participating locations.

If the receiver country or location does not participate in DHL Parcel DE Returns, do not activate the scenario for that flow.

Watch the known DHL-specific failure patterns

Several DHL Shipping-specific risks should be checked explicitly:

  • REST should be preferred because SOAP is being phased out.
  • DHL can return a misleading test error that points to the billing number although the invalid value is actually the CIS EKP.
  • Address validation can reject genuinely new addresses if the validation settings are too strict for the scenario.
  • Some return-label combinations are limited in scope.
Process Important DHL Shipping notes These checks keep the DHL Shipping setup aligned with the supported credential and request model.
  • Prefer REST credentials and URLs wherever possible.
  • Maintain ISO Alpha-3 country data before you test REST-based scenarios.
  • Treat participation number, print format, and return settings as productive business parameters, not as optional cosmetics.
  • Investigate misleading billing-number test errors by checking the CIS EKP as well.
  • Add international return handling only where the location and product setup explicitly supports it.

Links

Further Information

Related content