Skip to content

DHL Initial Setup

Step-by-step guide for the initial setup of the DHL Parcel DE Connector.

Prerequisites

Before you begin, ensure the following prerequisites are met:

  • [ ] DHL Business Customer Portal (GKP) β€” Active account at geschaeftskunden.dhl.de
  • [ ] DHL Developer Portal β€” Registration at developer.dhl.com with an app (API Key + Secret)
  • [ ] EKP Number β€” 10-digit DHL customer number from your contract
  • [ ] merchantCENTRAL Hub β€” Installed and active
  • [ ] Module License β€” At least a demo license for MCDHL

Setup Wizard

The setup wizard guides you through the configuration in 6 steps:

Step 1: Welcome

Overview of prerequisites. Verify that all credentials are ready.

Step 2: Authentication

Select the authentication type and enter credentials.

Setting Recommendation
Auth Type OAuth2 (ROPC) β€” recommended by DHL and future-proof
Sandbox Mode Enable for initial testing, disable later

OAuth2 (ROPC) β€” recommended:

  1. Click API Key β†’ Input dialog β†’ Enter API Key from developer.dhl.com
  2. Click API Secret β†’ Input dialog β†’ Enter Client Secret from developer.dhl.com

Basic Authentication (Legacy):

  1. Click Username (GKP) β†’ Enter GKP username
  2. Click Password (GKP) β†’ Enter GKP password
  3. API Key must still be entered separately

OAuth2 vs. Basic Auth

DHL recommends OAuth2 (ROPC) for new installations. OAuth2 uses a token-based mechanism β€” the token is automatically requested and cached until expiry. Basic Auth transmits username/password with every request.

Step 3: Connection Test

Click Test Connection. On success, a green confirmation with the API version appears.

Possible errors:

Error Cause Solution
HTTP 401 Invalid credentials Check API Key and Secret
HTTP 403 App not activated Activate app on developer.dhl.com
Timeout Network issue Check firewall/proxy, api-eu.dhl.com must be reachable

Step 4: Shipper Address

The shipper address appears on all DHL labels.

  • Click Load from Company to import data from BC Company Information
  • Adjust fields as needed (e.g., different shipping address)
  • Required fields: Name, Street, House No., Post Code, City, Country Code

Shipper Reference

Alternatively, you can use a shipper reference stored in the DHL GKP. Enable Use Shipper Reference and enter the reference code.

Step 5: Default Settings

Setting Recommendation Description
Default Weight (g) 1000 Used when no weight is specified on the package
Label Print Format 910-300-600 DHL standard label (105Γ—205mm)
Doc Format PDF For laser printers. ZPL2 for thermal printers.

Step 6: Finish

Summary of all settings. Click Finish to complete the configuration and activate the connector.

After Initial Setup

Set Up Profiles & Contract Lines

After the wizard, you need to create at least one profile with contract lines:

  1. Open DHL Shipment Setup β†’ Click on Default Profile
  2. Create a new profile (e.g., STANDARD_GRUPPENPROFIL)
  3. Add contract lines:
  4. EKP: Your 10-digit DHL customer number
  5. Product: V01PAK for domestic, V53WPAK for international
  6. Participation: 2-digit code from your DHL contract (usually 01)
  7. Zone: Domestic / EU / International
  8. Mark the profile as Default

β†’ Details: Profiles & Billing

For merchantCENTRAL to automatically use the DHL connector for shipments:

  1. Open Shipping Agents in BC
  2. Select your DHL shipping agent
  3. Ensure the code matches the Shipment Provider in merchantCENTRAL

Create a Test Label

  1. Ensure Sandbox Mode is enabled
  2. Create a test delivery (Sales Order β†’ Post with Ship)
  3. Open the posted sales shipment β†’ Create Label
  4. Verify the generated label

β†’ Details: Create Label

Next Steps