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), 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) and shipping agent service code. The billing number is calculated as: EKP + procedure code + participation.
→ 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 |
| 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.
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 |
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 is discontinuing Warenpost (V62WP) on 31 May 2026. Existing shipments using V62WP are automatically migrated to DHL Small Parcel (V62KP). Please configure new shipments directly with V62KP.
Singleton Page
This page has exactly one record. When opened for the first time, the record is created automatically.