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) that has the required APIs assigned (see APIs in the Developer Portal)
  • [ ] EKP Number — 10-digit DHL customer number from your contract
  • [ ] merchantCENTRAL Hub — Installed and active
  • [ ] Module License — At least a demo license for MCDHL

APIs in the Developer Portal

The table names the APIs exactly as they appear in the selection list under Select APIs in your app. One API key covers every API of its app – you do not need a second key.

API in the Developer Portal Used for Environments Approval
Parcel DE Shipping (Post & Parcel Germany) Shipping labels, cancellation, end-of-day closeout Sandbox and production Production: manually by DHL
Parcel DE Returns (Post & Parcel Germany) Standalone return labels (Returns) Sandbox and production Production: manually by DHL
Shipment Tracking – Unified Shipment tracking (Shipment Tracking) Production only Immediately, self-service

In the portal the sandbox is called Customer (Integration) Testing, production Production (Europe) or Production (Global). If you keep sandbox and production in separate apps, Shipment Tracking – Unified belongs in the production app – there is no sandbox for this API.

Easily confused

The selection list contains further, similarly named APIs that the connector does not use – above all Parcel DE Tracking (Post & Parcel Germany). Shipment tracking means Shipment Tracking – Unified only; you find it alphabetically under "S". Also not needed are, for example, Parcel DE Pickup, Parcel DE Private Shipping or Post DE Internetmarke. An API added on top does no harm, but the connector gains nothing from it.

Quotas apply per API

The portal shows the call quotas per API and environment. The generous quota of the Returns API (in production 500,000 requests per day as of October 2026) applies to return labels only. The tracking API starts at 250 calls per day – see Shipment Tracking.

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