DHL Shipment Setup
Central setup page for the DHL Parcel DE Shipping Connector. This is where API credentials, authentication method, profiles & billing numbers, shipper address, default settings, and customs defaults are configured.
Opening the Page
- Via search: DHL Shipment Setup
- Via the merchantCENTRAL Dashboard → Shipping Providers → DHL
Fields
API Credentials
Credentials and authentication settings for the DHL Parcel DE Shipping API v2.
| Field | Description |
|---|---|
| API Base URL | Base URL of the DHL API. Production: https://api-eu.dhl.com/parcel/de/shipping/v2, Sandbox: https://api-sandbox.dhl.com/parcel/de/shipping/v2 |
| Sandbox Mode | Enables sandbox mode for test environments. URLs automatically switch to api-sandbox.dhl.com |
| API Key | DHL API key (click to configure). Transmitted in the dhl-api-key header. Available via developer.dhl.com → My Apps |
| Auth Type | Authentication method: Basic Authentication (GKP username/password) or OAuth2 (ROPC) (recommended). Switches the credential fields shown below. |
Depending on the selected authentication type, the following fields are shown:
OAuth2 (ROPC) — recommended:
| Field | Description |
|---|---|
| API Secret | Client secret for the OAuth2 ROPC token endpoint (click to configure). Available via developer.dhl.com → My Apps |
| OAuth2 Token URL | Token endpoint URL. Sandbox: https://api-sandbox.dhl.com/parcel/de/account/auth/ropc/v1/token, Production: https://api-eu.dhl.com/parcel/de/account/auth/ropc/v1/token |
| Token Expiry | Expiry timestamp of the currently cached access token (read-only, green when token is present) |
Basic Authentication:
| Field | Description |
|---|---|
| Username (GKP) | Username from the DHL business customer portal (click to configure) |
| Password (GKP) | Password from the DHL business customer portal (click to configure) |
Recommended Authentication
DHL recommends and will migrate to OAuth2 in the future. Use OAuth2 (ROPC) for new installations. With OAuth2, an access token is automatically requested and cached until expiry.
Credential Input
All credentials are entered via a secure dialog. The setup page itself only shows Configured (green) or Not configured (red) — the actual values are never visible.
Profiles & Billing
The billing number is no longer entered statically but is automatically resolved via profiles and contract lines.
| Field | Description |
|---|---|
| Default Profile | Shows the currently default-marked DHL profile. Click to open the Profile List. |
Profiles & Contract Lines
The DHL Profile List is used to manage DHL user group profiles (from the DHL business customer portal) and their associated contract lines. Each contract line contains: EKP (10-digit customer number), DHL product, participation code (2 digits), service variant (Standard / With Services / GoGreen / With Services + GoGreen), shipping zone (Domestic/EU/International), and an optional maximum weight.
The Contract Resolver automatically determines the appropriate contract line for each shipment based on the destination country (→ zone), selected VAS (→ service variant), and shipping agent service code. The billing number is calculated as: EKP + procedure code + participation.
DHL assigns a separate participation for shipments with bulky goods, cash on delivery, insurance, etc. This must be configured as a separate contract line with Service Variant = With Services.
→ For more information: Setting up DHL Profiles
Shipper Address
Shipper address that appears on all DHL labels.
| Field | Description |
|---|---|
| Use Shipper Reference | When enabled, a reference address stored at DHL is used instead of manual entry |
| Shipper Reference | DHL shipper reference (only visible when Use Shipper Reference is active) |
| Shipper Name | Name of the shipper (line 1) |
| Shipper Name 2 | Additional shipper name (line 2) |
| Shipper Name 3 | Additional shipper name (line 3) |
| Shipper Street | Street of the shipper |
| Shipper House No. | House number of the shipper |
| Shipper Post Code | Postal code of the shipper |
| Shipper City | City of the shipper |
| Shipper Country Code | Country code of the shipper (ISO alpha-3, e.g. DEU) |
| Shipper Contact Name | Contact person at the shipper |
| Shipper Email | Email address of the shipper |
| Shipper Phone | Phone number of the shipper |
Shipper Reference
When using the shipper reference, the address fields are disabled. DHL will then use the address stored in the business customer portal.
Default Settings
Default values for label creation.
| Field | Description |
|---|---|
| Default Weight (g) | Default weight in grams when no weight is specified on the parcel |
| Require Routing Code | Rejects shipments whose German delivery address DHL cannot resolve into a routing code (default: on) — see below |
| Include Labels as | Type of label inclusion in the API response (URL or Base64) |
| Combine Labels | Combine shipment and return label into one PDF |
| Doc Format | Document format for shipping labels (PDF or ZPL2 for thermal printers). Switches the available print format. |
| Label Print Format | Print format for shipping labels. Values: A4, 100x70mm, 910-300-600 (105×205mm), 910-300-610 (105×208mm), 910-300-700, 910-300-700-oz, 910-300-710, 910-300-300 (105×148mm), 910-300-300-oz, 910-300-400 |
| Retoure Doc Format | Document format for return labels (PDF or ZPL2). Can differ from the shipping format — e.g. ZPL2 for the thermal printer at packing, PDF for the laser printer at receiving. |
| Retoure Label Print Format | Print format for return labels (separate selection) |
| Print DHL Logo | Print the DHL logo on shipping labels (default: enabled). Disable to save ink/toner on thermal printers. |
| Print DHL Logo (Return) | Print the DHL logo on return labels (default: enabled). |
ZPL2 and Print Format
When ZPL2 is selected as the document format, the print format automatically switches to 100×70mm (standard for thermal printers). A4 is not compatible with ZPL2.
Require Routing Code
From every German delivery address DHL builds a routing code — the sorting key the parcel travels by. If an address cannot be resolved, for instance because postcode and town do not match, there are two possibilities:
- Switched on (default): DHL creates no label. The shipment is rejected, and you correct the address before the parcel exists.
- Switched off: DHL creates the label anyway and only returns a warning. The parcel runs through the network without a sorting key — risking a misdelivery and the fees that come with it.
International shipments are unaffected. An address can be checked at any time with the Validate Shipment action on the sales order — no label, no charge.
Return Labels
| Field | Description |
|---|---|
| Include Return Label | Automatically create a return label with each shipment (via VAS dhlRetoure) |
Advanced
| Field | Description |
|---|---|
| Creation Software | Software identifier transmitted to DHL (for DHL partners only) |
Customs Defaults
Default values for customs declarations on international shipments.
| Field | Description |
|---|---|
| Default Shipper EORI | Default EORI number of the shipper for customs declarations |
| Default Export Type | Default export type: COMMERCIAL_GOODS, OTHER, PRESENT, COMMERCIAL_SAMPLE, DOCUMENT, RETURN_OF_GOODS |
| Default Endorsement | Default handling for undeliverable shipments: RETURN (return immediately) or ABANDON (abandon) |
DHL Retoure API
Settings for the separate DHL Returns API v1 (for standalone return labels, e.g. customer return QR codes).
| Field | Description |
|---|---|
| Retoure Enabled | Enables the DHL Returns API for standalone return labels |
| Retoure API Base URL | Base URL of the DHL Returns API. Sandbox: https://api-sandbox.dhl.com/parcel/de/shipping/returns/v1 |
| Retoure Receiver ID | Receiver ID for returns (e.g. deu for Germany) |
| Retoure GoGreen Plus | Enable carbon-neutral shipping for returns |
Tracking
Automatic shipment tracking through the DHL Track & Trace API. The detail fields only appear once Tracking Enabled is switched on.
| Field | Description |
|---|---|
| Tracking Enabled | Switches on automatic tracking and creates the matching job queue entry |
| Tracking Poll Interval (Min.) | Polling interval in minutes (default: 240) |
| Tracking Max Age Days | Shipments older than X days are no longer tracked (default: 30) |
| Tracking Calls Per Run | Upper limit of calls for a single background run (default: 250) |
| Tracking API Base URL | Base URL of the Track & Trace API (default: https://api-eu.dhl.com) |
| Tracking API Key (optional) | A key of its own for the Track & Trace API. Leave empty to use the key from the shipping credentials |
| Job Queue Status | State of the TRACKING job: Active, On Hold, Error or Not configured |
Raising Tracking Calls Per Run
The preset of 250 matches the development quota DHL grants at first. Once DHL has raised your quota for production, raise this value with it — otherwise it stays the real bottleneck. What is counted is calls, not shipments: a shipment in three cartons costs three calls.
→ In detail: Shipment tracking
License
| Field | Description |
|---|---|
| License Status | Current license status: Active (green), Demo (yellow), Unregistered / Expired (red) |
| Demo Expiry | Expiry date of the demo license (only shown in demo status) |
| Remaining Demo Days | Remaining demo days (only shown in demo status) |
| Licensed Since | Date of first licensing (only shown in active status) |
Status
Current status information for the DHL integration.
| Field | Description |
|---|---|
| Last Label Created | Date and time of the last label created |
| Labels Created Today | Number of labels created today (highlighted in green) |
| Last Error Message | Last error message from the DHL API (red when error) |
| Last Error DateTime | Timestamp of the last error |
Actions
| Action | Description |
|---|---|
| Test Connection | Tests the connection to the DHL API with the current credentials. Sends a test request to GET / and displays the result |
| Register Demo | Starts the free 30-day demo registration |
| Refresh License | Re-checks the license status from the license server |
Notes
API Key
The API key is created via the DHL Developer Portal. Activation by DHL is required for production use.
Warenpost (V62WP) discontinued
DHL discontinued Warenpost (V62WP) on 31 May 2026. The connector automatically migrates existing V62WP configurations to DHL Small Parcel (V62KP). Please configure new shipments exclusively with V62KP.
Singleton Page
This page has exactly one record. When opened for the first time, the record is created automatically.