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