Best for:
- DHL Parcel Connect shipping & tracking
- DHL Parcel Return Connect shipping & tracking
- DHL Parcel Connect PLUS shipping & tracking
- Creating cross-border & direct injection shipments within Europe
- Large business customers of DHL eCommerce in Europe
- Sending shipments within Europe and from Europe (excl. DE) into Rest of World
This API Gateway is named eConnect API and is issued by DHL eCommerce . It is the one stop solution for large eCommerce customers in Europe to send shipment data, retrieve labels and access track and trace information. It offers the products DHL Parcel Connect, DHL Parcel Return Connect, DHL Parcel Connect PLUS and DHL Parcel International.
Users of the eConnect API can:
Send shipment data | Generate label | Location Finder | Track & Trace |
Create shipments automatically without manual effort, directly from their online shop, logistics software etc. | Retrieve compliant labels for their shipments in different formats | Request information from the "Unified Location Finder" to select from approx. 65 thousand Service Points and lockers for direct addressing of shipments | Access track and trace information on account or shipment level |
This page provides detailed information about the eConnect API content and its use. Click here to jump directly to the following topics:
- Access Token
- Send shipment data & generate labels
- Location Finder
- Track & trace
- Customs Data
- Overview and application of Use Cases
Scope
The eConnect API covers the essential DHL cross-border parcel products for shipments within Europe and beyond:
- DHL Parcel Connect: the best choice for cross-border eCommerce senders focusing on B2C. DHL Parcel Connect ships via the Connect network into 28 parcel destinations in Europe using a network-wide parcel product standard with harmonized features (e. g. label, dimensions, weights, etc.).
- Weight: Up to 31.5kg
- Dimension: Maximum 120 x 60 x 60cm
- Fast transit times: typically ranging between 1-3 days(depending on origin/destination country)
- For customers in all DHL Parcel Europe countries
- Delivery in all DHL Parcel Europe and partner countries
- End-to-End transparency through track & trace including pre-delivery notification
- Saturday and delivery on preferred day possible
- Direct delivery to Service Points
- Direct Injection options for customer-individual flows
- Additional services available (e.g. cash on delivery, bulky goods)
- DHL Parcel Return Connect: the product offers a comprehensive return solution from 28 DHL Parcel Connect destinations. Return senders can access one of the largest ServicePoints networks across Europe for return drop-off.
- DHL Parcel Connect PLUS: European B2B offering including multi-piece shipments and pallets.
- DHL Parcel International: Complementary offering to cover worldwide destinations outside the DHL Parcel Connect network via postal standard (incl. customs destinations) in addition.
Please see below an overview of our recommended products per country:
Country | Outbound Product | Return Product |
Austria | Parcel Connect | Return Connect |
Belgium | Parcel Connect | Return Connect |
Bulgaria | Parcel Connect | Return Connect |
Croatia | Parcel Connect | Return Connect |
Cyprus | Parcel Connect | Return Connect |
Czech Republic | Parcel Connect | Return Connect |
Denmark | Parcel Connect | Return Connect |
Estonia | Parcel Connect | Return Connect |
Finland | Parcel Connect | Return Connect |
France | Parcel Connect | Return Connect |
Germany | Parcel Connect | Return Connect |
Greece | Parcel Connect | Return Connect |
Hungary | Parcel Connect | Return Connect |
Ireland | Parcel Connect | Return Connect |
Italy | Parcel Connect | Return Connect |
Latvia | Parcel Connect | Return Connect |
Lithuania | Parcel Connect | Return Connect |
Luxembourg | Parcel Connect | Return Connect |
Netherlands | Parcel Connect | Return Connect |
Norway | Parcel International | Not available |
Poland | Parcel Connect | Return Connect |
Portugal | Parcel Connect | Return Connect |
Romania | Parcel Connect | Return Connect |
Slovakia | Parcel Connect | Return Connect |
Slovenia | Parcel Connect | Return Connect |
Spain | Parcel Connect | Return Connect |
Sweden | Parcel Connect | Return Connect |
United Kingdom | Parcel International | Not available |
Rest of World | Parcel International | Not available |
Feel free to check out our website for more detailed product information. For further information on the functionalities, please visit Use Cases.
In case you are a customer based in Germany, please check out our German portfolio at the DHL Entwicklerportal.
Example Use Cases
Example 1: user sends shipment data to DHL and receives a label in return
The eConnect API allows the user to send shipment data for Parcel Connect, Parcel Connect Return, Parcel Connect PLUS and Parcel International shipments to DHL. The data needs to be send in JSON format, following the "cPAN" request scheme according to the API documentation. If requested the API will return the respective label in the desired format (e.g. PDF) and resolution.
Example 2: user searches for shipment status via track & trace
The eConnect API offers a full track and trace functionality for the shipments of each user. It is possible to request the status information on singular shipment or account level.
Example 3: request ServicePoint location and directly address a shipment to a ServicePoint
The customer can address DHL Parcel Connect shipments to a DHL network location address, e.g. a ServicePoint or Locker, instead of a doorstep address. If the location data is not known , the user can search for available locations using the DHL Unified Location Finder API (http://developer.dhl.com/api-reference/location-finder). Retrieved location information needs to be integrated into the respective shipment data of the eConnect API.
Please visit our Use Case section for a full list of possible use cases.
Get Access
For onboarding, you need to follow this process guided by theDHL API team:
- Contact DHL to align use case and requirements
- Apply for access to sand box environment
- Implement your API solution (see use cases)
- Seek approval from DHL (for data and label)
- Retrieve access to production environment
To contact the DHL API team, please use this contact form.
Using the API
To get access to the API, you will receive a Client ID and a password ; please use the contact form to apply for these (including your company name, industry and contact details (incl. phone number and email address)).
The API provides OAuth 2.0 Access Token with various authorization scopes.
The "Get Access Token" API call provides an OAuth 2.0 Bearer token with authorization scope, assigned to your client id. It grants you an access to the CCC APIs.
The API operation is secured by HTTP Basic authentication, therefore you have to provide 'client_id' and 'client_secret' as an username and password, when calling the API. Credentials will be provided to you via secured channel.
Environments
The addressable API base URL/URI environments are:
Environment | Description |
https://api-sandbox.dhl.com | Sandbox environment |
https://api.dhl.com | Production environment |
The Sandbox environment can be used for testing freely. Only the production environment will trigger underlying processes, e.g. billing, operational procedures.
Information for integrators
The DHL Europe eCS API differentiates between customers and integrators. If you are an integrator, you may retrieve permission to operate the API on behalf of an assigned customer. For administrative reasons, shipments are always assigned to a dedicated customer. API users with status "integrator" cannot generate shipments themselves, unless they additionally have a customer account.
The customer/integrator configuration is performed by DHL, please contact via the contact form.
Rate Limits
Rate limits protect the DHL infrastructure from suspicious requests that exceed defined thresholds.
Should you exceed your rate limit you will receive a HTTP status code within the API response that will indicate this.
In addition to the rate limit a so called "spike arrest" protects our API Platform from potential outages caused by a very large volume of requests sent in a short time span (minutes or seconds). This will be indicated by a different HTTP status code.
This API offers various functionalities that all support you in managing your DHL eCommerce Solutions cross-border parcel shipments. This page gives an overview and introduction to the available functionalitites. A detailed developer's documentation is available in the "Reference Docs" section (see here).
Please note that all integrated API features need to be covered by the customer's DHL contract. The technical API integration of a feature alone is no sufficient precondition for feature usage on the production environment.
Shipment Data
- It is mandatory for the sender to send shipment data for each individual piece/parcel. Please see below explanations for details on the requested shipment parameter, in addition please check our use cases and the "reference docs" section on this website.
- Along with the recipient and sender address data, several additional shipment details need to be defined for each shipment:
- Product type: DHL Parcel Connect, DHL Parcel Return Connect, DHL Parcel Connect PLUS or DHL Parcel International
- Sender address data: Use these fields to define the shipper address on the label. The field "customerIdentfication" must contain the senders DHL customer number (e.g. EKP, local ID). Please note: For Connect return shipments the "customerIdentification" needs to be included as an attribute for the sender as well, not for the receiver.
- Recipient address data: Use these fields to insert the consignee address
- Product features: Depending on the selected product type, various product features are to be selected in the shipment data:
- Mandatory features
- Delivery type: The delivery type needs to be chosen i.e. default for doorstep, parcelshop, parcelstation or postOffice.
- Gross weight: It is mandatory to provide the gross weight in kg.
- Optional features
- Size: It is optional, but recommended, to delivery size information for shipments in meter.
- Cash on delivery (COD): When choosing "Cash-on-delivery", a shipment is handed over to the recipient against payment. Financial details are required in this case.
- Bulky: Shipments outside the standard dimensions or with any property that prevents automated sorting need to be marked as bulky by the customer. For details see product information (above).
- Additional insurance: Depending on your contract with DHL, the customer can order additional insurances
- Go Green: Depending on your agreement with DHL, the customer may ship Go Green shipments
- Mandatory features
Label
- The API can generate high-resolution labels based each individual shipment data and provide the label files within the API response.
- Labels are available for all covered products, i.e. DHL Parcel Connect, DHL Parcel Return Connect, DHL Parcel Connect PLUS and DHL Parcel International.
- All labels generated by the eConnect API come with an unique shipment identifier barcode (ASC MH10 format) which is assigned by the service. All these shipment identifiers have the same number-prefix JJD1499902... and a total length of 21 characters. They are unique for at least 13 months, before they are used again for another shipment.
- In certain cases it is possible to offer customer-individual shipment identifiers, please contact your DHL responsible if required.
- Currently the following products, formats, sizes and resolutions are available:
- 3 products: "DHL Parcel Connect", "DHL Parcel Return Connect" or"DHL Parcel International"
- 2 sizes: 15x10cm or 21x10cm
- 2 resolutions: 200 dpi or 300 dpi
- 3 formats: PDF, PNG or ZPL
- In case of generating DHL Parcel Return labels, it is recommended to additionally generate return instructions. Return instructions contain information in all local languages and shall help return senders (i.e. consumer) to correctly handle the return shipment. To receive our return instructions, please request them via our contact form.
- When creating shipments into customs areas please refer to below chapter "Customs Data".
- Please see below an example DHL Parcel Connect label for shipment delivered to a door-step address as well as the respective return label.
- Please note: below illustration contains max field lenghts for the addressing fields on the label. Additionally single fields might be changed for layout reasons due to character span/size during PDF creation.

Addressing to ServicePoints
- With DHL Parcel Connect it is possible, to directly address shipments to ServicePoints or Lockers in the destination country, instead of a doorstep address.
- The service is available for destinations: AT, BE, BG,CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, LT, LV, NL, PL, PT, RO, SE, SI, SK
- The service is not available for destinations: IE, IT, LU, NO
- The DHL Location Finder provides up-to-date address data of all available DHL and Partner locations, which can be used for direct addressing of shipments.
- It contains location information of ServicePoints, Postoffices and Lockers, including additional information such as opening hours, holiday closing times and services offered.
- The DHL Location Finder API offers to retrieve locations in an area near a specific address (within a radius of 25km).
- Please find more information on how to access and integrate the DHL Location Finder API here.
- After retrieving location address data via the DHL Location Finder API, the address data needs to be entered into the shipment data for the particular shipment on the eConnect API.
- Apply the below mapping table to correctly map the location data fields from the DHL Location Finder API to the shipment data fields of the DHL eCommerce Solutions API - needed for DHL Parcel Connect shipments directly addressed to a ServicePoint, PostOffice or Locker.
Overview of field mappings
Content | DHL Location Finder API | DHL eCommerce Solutions API | Example / Comment |
Name of Recipient | n.a. | CPAN/ addresses/ recipient/ name | e.g. Hans Schmitz |
Type of Location | locations/ location/ type | CPAN/ addresses/ recipient/ type | e.g. Servicepoint |
Postnummer (only for DE Packstation) | n.a. | CPAN/ addresses/ recipient/ customerIdentification | e.g. 1234567 (only needed for DE Packstation) |
Name of ServicePoint (not needed for Lockers) | locations/ name | CPAN/ addresses/ recipient/ additional name | e.g. B+B Tabakwaren |
Keyword of ServicePoint/ Locker | locations/ location/ keyword | CPAN/ addresses/ recipient/ street1 | e.g. Postfiliale |
ID of ServicePoint/ Locker | locations/ location/ keywordId | CPAN/ addresses/ recipient/ street1Nr | e.g. 443 |
Street name of the Servicepoint | locations/ place/ address/ streetAddress | CPAN/ addresses/ recipient/ street2 | e.g. Monckebergstr. 7 |
ZIP Code of the Servicepoint | locations/ place/ address/ postalCode | CPAN/ addresses/ recipient/ postcode | e.g. 20095 |
City of the ServicePoint | locations/ place/ address/ addressLocality | CPAN/ addresses/ recipient/ city | e.g. Hamburg |
Country of the ServicePoint | locations/ place/ address/ countryCode | CPAN/ addresses/ recipient/ country | e.g. DE |
Additional information & tipps for using both API's
- When requesting locations from the DHL Location Finder API, please make sure to only select locations offering the following "service types" in the Location Finder API:
- "parcel:pick-up" - these locations are available for any direct addressing of parcels
- "parcel: pick-up-unregistered" - these locations are available for any direct addressing of parcels
- "parcel: pick-up-registered" - these locations are available for direct addressing of parcels only, if a destination specific recipient-registration number is transmitted in the shipment data (e.g. for German Parcelstations a "Postnumber" is mandatory)
- When requesting locations from the DHL Location Finder API, please make sure to map the "type" of the selected location from the Location Finder API correctly to the DHL eCommerce Solutions API:
DHL Location Finder API <type> | DHL eCommerce Solutions API <type> |
---|---|
servicepoint | parcelshop |
locker | parcelstation |
postoffice | postOffice |
Track & Trace
- The eConnect API offers calls to request track & trace information for individual customers' shipments. Integrators can access information on their assigned customers' shipments as well.
- Available tracking options via API:
- Track & trace shipment details of a specific single shipment ID
- Track & trace all shipments of a given customer ID and injection date(s)
- Next to the API channel, customers shipments can be monitored as well via public websites, e.g.: www.dhl.com/tracking
- Senders can communicate track & trace information to their recipients via one link for all European destinations. The link gives direct access to tracking information: http://www.dhl.com/tracking?tracking-ID=#### and can be personalized with an individual shipping ID.
- The following Track & Trace statuses are available via the Track & Trace service on the eConnect API:
Category | Event | Event Text |
DataReceived | COLLECTION_DATA_RECEIVED | Pick-up data received by DHL Parcel |
DataReceived | DATA_RECEIVED_WITH_PREFIX_LABEL | Shipment not yet received or processed |
DataReceived | DEPART_SHIPPER_FACILITY | The shipment has departed the warehouse of the shipper |
DataReceived | NEW_COLLECTION_ATTEMPT | New pickup attempt by the courier |
DataReceived | PARCEL_WILL_BE_BROUGHT_IN_BY_RECEIVER | Ready for drop off by the sender |
DataReceived | PRENOTIFICATION_RECEIVED | Shipment not yet received or processed |
DataReceived | WILL_BE_TRANSFERRED_TO_THIRD_PARTY | will be transferred to third party |
Underway | ANNOUNCED_AT_PARCELSHOP | Announced at DHL ServicePoint |
Underway | ARRIVED_AT_DELIVERY_FACILITY | Arrived in your region |
Underway | ARRIVED_AT_INBOUND_GATEWAY | Arrived at inbound gateway |
Underway | ARRIVED_AT_ORIGIN_DEPOT | |
Underway | ARRIVED_AT_ORIGIN_GATEWAY | |
Underway | ARRIVED_AT_ORIGIN_HUB | |
Underway | ARRIVED_AT_TERMINAL | Arrived at terminal |
Underway | ARRIVED_FACILITY | Arrived at the international sorting center |
Underway | CLEARANCE_RELEASE | Released by customs |
Underway | COLLECTED | Shipment(s) has/have been picked up |
Underway | COLLECTED_AT_NEIGHBOUR | Picked up at neighbours by the courier |
Underway | COLLECTION_HANDED_OVER_TO_DD | Pickup order handed over to another courier |
Underway | COLLECTION_HANDED_OVER_TO_THIRD_PARTY | Pickup order handed over to another courier |
Underway | COLLECTION_IMPORT_EXPRESS | Pickup order received from Express |
Underway | COLLECTION_ORDER_SCANNED | Pickup order scanned by the courier |
Underway | COLLECTION_PLANNED_IN_ROUTE | Pickup planned in the route of the courier |
Underway | CONFIRMATION_OF_CLOSING_THE_SCAN-APPLICATION_AFTER_THE_SCAN_FOR_RETURN | Sorted to send to the sorting center |
Underway | DELIVERED_AT_SHIPPER | Delivered at the sender |
Underway | DEPART_ORIGIN_GATEWAY | |
Underway | DEPART_DESTINATION_GATEWAY | |
Underway | DEPART_FACILITY | Processed at the sorting center |
Underway | DEPARTURE | Departure from the sorting center |
Underway | DEPOT_SCAN | Scanned at the sorting center |
Underway | FACILITY_CHECK_OUT | Ready for departure from the international sorting center |
Underway | FORWARD_DESTINATION | Forwarded to the CityHub |
Underway | FORWARD_DESTINATION_TOO_LATE | Forwarded to the CityHub too late |
Underway | FORWARDED_TO_DIFFERENT_ADDRESS | Will be forwarded to another address |
Underway | GATEWAY_ARRIVED | Arrived at international sorting center in transit country |
Underway | GATEWAY_DEPARTED | Departed from international sorting center in transit country |
Underway | HANDOVER | Handed over to local carrier |
Underway | IN_CLEARANCE_PROCESS | In clearance at customs |
Underway | IN_ROUTE_THIRD_PARTY | On route to the CityHub |
Underway | ON_ROUTE_TO_SHIPPER | On route to the sender |
Underway | PARCEL_ARRIVED_AT_LOCAL_DEPOT | Arrived in your region |
Underway | PARCEL_COLLECTED | Picked up by the courier |
Underway | PARCEL_COLLECTED_AT_PARCELSHOP_BY_COURIER | Picked up at DHL ServicePoint by the courier |
Underway | PARCEL_COLLECTED_AT_SERVICEPOINT_BY_COURIER | Picked up at DHL ServicePoint by the courier |
Underway | PARCEL_NO_DATA | No data |
Underway | PARCEL_PICKED_UP_AT_ACCESSPOINT | |
Underway | PARCEL_PICKED_UP_AT_PARCELSHOP | Picked up at DHL ServicePoint by the courier |
Underway | PARCEL_PICKED_UP_AT_PARCELSTATION | |
Underway | PARCEL_READY_FOR_RETURN_TO_HUB | Ready to send to the sorting center |
Underway | PARCEL_RECEIVED | Dropped off by the sender |
Underway | PARCEL_RESORTED_AT_HUB | Resorted at the sorting center |
Underway | PARCEL_SCANNED_AT_RETURN_HUB | Returned to sender |
Underway | PARCEL_SCANNED_FOR_COLLECTION_AT_ACCESSPOINT_BY_COURIER | |
Underway | PARCEL_SCANNED_FOR_COLLECTION_AT_PARCELSHOP_BY_COURIER | Pickup order scanned at DHL ServicePoint by the courier |
Underway | PARCEL_SCANNED_FOR_COLLECTION_AT_PARCELSTATION_BY_COURIER | |
Underway | PARCEL_SCANNED_FOR_COLLECTION_AT_SERVICEPOINT_BY_COURIER | |
Underway | PARCEL_SCANNED_FOR_RETURN_TO_HUB | Scanned for return to sorting center |
Underway | PARCEL_SORTED_AT_GATEWAY | |
Underway | PARCEL_SORTED_AT_HUB | Processed at the sorting center |
Underway | PASSED_GATEWAY | Departure from the international sorting center |
Underway | PICKED_UP | Picked up by the courier |
Underway | PROCESSED_AT_LOCATION | Processed at the sorting center |
Underway | PROCESSED_AT_ORIGIN | Processed at the sorting center |
Underway | RECORD_OF_TRANSIT | On route to the international sorting center |
Underway | REWEIGH | Weighed and measured at the sorting center |
Underway | SCAN_OK_GATEWAY | Departure from the international sorting center |
Underway | SCHEDULED_FOR_MOVEMENT | Delivery instruction changed to delivery at another day or time |
Underway | SERVICE_CHANGED | Service changed |
Underway | SHIPMENT_ACCEPTANCE | Dropped off at DHL by the sender |
Underway | SHIPMENT_ACCEPTANCE_DEPOT | |
Underway | SHIPMENT_ACCEPTANCE_PARCELSHOP | Dropped off at DHL ServicePoint |
Underway | SHIPMENT_ACCEPTANCE_PARCELSTATION | Dropped off at DHL ServicePoint |
Underway | SHIPMENT_INSPECTION_RELEASED | Delay resolved |
Underway | SORTED_AT_DESTINATION_DEPOT | |
Underway | SORTED_AT_DESTINATION_GATEWAY | |
Underway | SORTED_AT_DESTINATION_HUB | |
Underway | SORTED_AT_ORIGIN_DEPOT | |
Underway | SORTED_AT_ORIGIN_GATEWAY | |
Underway | SORTED_AT_ORIGIN_HUB | |
Underway | SPONTANEOUS_RETURN | Unannounced return given to the courier |
Underway | UNLOAD_VEHICLE | Vehicle is being unloaded |
InDelivery | AGREED_DELIVERY | Delivery according to agreement |
InDelivery | AWAITING_RECEIVER_COLLECTION | Ready for collection at DHL ServicePoint |
InDelivery | COLLECTION_ORDER_HANDED_OVER_TO_DRIVER | Pickup order handed over to the courier |
InDelivery | COLLECTION_ORDER_OUT_FOR_DELIVERY | Courier on route for pickup order |
InDelivery | DELIVERED_AT_ACCESSPOINT | Delivered at DHL ServicePoint |
InDelivery | DELIVERED_AT_DEPOT | |
InDelivery | DELIVERED_AT_PARCELSTATION | Delivered at DHL ServicePoint, your shipment is ready for collection |
InDelivery | DELIVERED_AT_PREFERED_NEIGHBOURS | Delivered at preferred neighbours |
InDelivery | LOAD_VEHICLE | Out for delivery with the courier |
InDelivery | NOTIFICATION_FOR_PARCELSHOP_COLLECTION_HAS_BEEN_SENT | Your package is ready to be picked up. |
InDelivery | ON_HOLD_FOR_COLLECTION | Ready for collection at the sorting center by the recipient |
InDelivery | OUT_FOR_DELIVERY | Out for delivery with the courier |
InDelivery | PARCEL_HELD_FOR_COLLECTION_AT_LOCAL_DEPOT | Ready for collection by the recipient |
InDelivery | REDELIVER | New delivery attempt on the next delivery day |
InDelivery | REDELIVER_AT_PARCELSHOP | New delivery attempt at DHL ServicePoint on the next delivery day |
InDelivery | REDELIVER_DIFFERENT_ADDRESS | New delivery attempt on another address the next delivery day |
InDelivery | REDELIVER_SAME_ADDRESS | New delivery attempt on the same address next delivery day |
Delivered | BROKER_RELEASED | Cleared by the broker and released at customs |
Delivered | COLLECTED_AT_ACCESSPOINT | Collected at DHL ServicePoint by the recipient |
Delivered | COLLECTED_AT_PARCELSHOP | Collected at DHL ServicePoint by the recipient |
Delivered | COLLECTED_AT_PARCELSTATION | Collected at DHL ServicePoint by the recipient |
Delivered | DELIVERED | Delivered |
Delivered | DELIVERED_AT_NEIGHBOURS | Delivered at the neighbours |
Delivered | DELIVERED_AT_SAFEPLACE | Delivered at the preferred location |
Delivered | DELIVERED_DAMAGED | Delivered with damage |
Delivered | DELIVERED_IN_MAILBOX | Delivered in mailbox |
Delivered | DELIVERED_NOT_IN_TIME | Delivered |
Delivered | FORWARD_THIRD_PARTY | Forwarded to local carrier |
Delivered | MONEY_TRANSFERED_TO_SENDER | |
Delivered | SHIPMENT_COLLECTED | Collected by the recipient |
Intervention | INTERVENTION | Delivery instruction changed |
Intervention | INTERVENTION_DELIVERY_ADDRESS_CHANGED_INTO_PARCELSTATION | |
Intervention | INTERVENTION_PROCESSED_FOR_DELIVERY_AT_SAFEPLACE | We deliver your shipment at your preferred location |
Intervention | INTERVENTION_RECEIVER_REQUESTS_DELIVERY_AT_ACCESSPOINT | |
Intervention | INTERVENTION_RECEIVER_REQUESTS_DELIVERY_AT_ANOTHER_TIME/DATE | We deliver your shipment at your preferred day and/or time |
Intervention | INTERVENTION_RECEIVER_REQUESTS_DELIVERY_AT_DIFFERENT_ADDRESS | Request by the recipient for delivery to a different address |
Intervention | INTERVENTION_RECEIVER_REQUESTS_DELIVERY_AT_NEIGHBOURS | We deliver your shipment at your neigbours |
Intervention | INTERVENTION_RECEIVER_REQUESTS_DELIVERY_AT_PARCELSHOP | We deliver your shipment at a DHL ServicePoint |
Intervention | INTERVENTION_RECEIVER_REQUESTS_DELIVERY_AT_PARCELSTATION | |
Intervention | INTERVENTION_RECEIVER_REQUESTS_DELIVERY_AT_PREFERRED_NEIGHBOURS | |
Intervention | INTERVENTION_RECEIVER_REQUESTS_DELIVERY_AT_SAFEPLACE | Preferred location communicated to DHL |
Intervention | INTERVENTION_SYSTEM_REQUESTS_DELIVERY_AT_PARCELSHOP | We deliver your shipment at a DHL ServicePoint |
Exception | COD_AMOUNT_CHANGED | Cash on delivery amount changed on request of the sender |
Exception | DELIVERY_DATE_CHANGED_BY_DEPOT_MANAGER | Delivery postponed, delivery date changed |
Exception | DELIVERY_DATE_CHANGED_BY_DEPOT_MANAGER_REASON_CLOSED | Delivery postponed, delivery date changed |
Exception | FORWARDED_TO_DIFFERENT_PARCELSHOP | |
Exception | PARCEL_FOUND_AT_PARCELSHOP | Pickup at DHL ServicePoint possible again |
Exception | PARCEL_INFORMATION_REMOVED_FROM_PARCELSHOP_APPLICATION | Removed from the application of DHL ServicePoint |
Exception | PARCEL_OUT_OF_TIME_FOR_DROP_OFF | Period expired for drop off at DHL ServicePoint by the sender |
Exception | PICTURE_TAKEN_OF_PARCEL | Photo taken of parcel |
Exception | RELABELED | Relabeled |
Exception | RETURN_ORDER_CANCELLED | Return order cancelled at DHL ServicePoint |
Exception | UNJUSTIFIED_SPONTANEOUS_RETURN | Unjustified return given to the courier |
Information | NOTIFICATION_DELIVERED_AT_AGREED_PLACE | |
Information | NOTIFICATION_NOT_HOME_TO_PARCELSHOP | We missed you. We deliver your shipment at a DHL ServicePoint. |
Problem | ACCESSPOINT_FULL_REDELIVER | |
Problem | ADDRESS_CORRECTED_BY_DEPOT_MANAGER | Address details corrected |
Problem | ADDRESS_UNKNOWN | Incorrect address details, the shipment will return to the sender |
Problem | ARRIVED_DAMAGED | Arrived at the CityHub with damage |
Problem | AWAITING_PAYMENT_RECEIVER_NOTIFIED | |
Problem | BACKLOG_COLLECTION_CANCELLED | Shipment(s) not picked up due to backlog, pick-up order cancelled |
Problem | BACKLOG_NOT_COLLECTED | No pick-up due to DHL backlog, new pick-up attempt next delivery day |
Problem | BACKLOG_NOT_DELIVERED | Delivery interrupted, delivery date changed |
Problem | BAD_ADDRESS | Incorrect address details, we will contact the sender for new deliver instructions |
Problem | BAD_ADDRESS_INTERNATIONAL | Incorrect address details, please contact the sender |
Problem | BAD_ADDRESS_NOT_COLLECTED | Incorrect pick-up address, pick-up order cancelled |
Problem | BONDED_LOCATION | Stored in the customs area |
Problem | CALAMITY_SYSTEM_INTERVENTION_DELIVERY_AT_PARCELSHOP | We deliver your shipment at a DHL ServicePoint |
Problem | CLEARANCE_DELAY | Delayed during clearance at customs |
Problem | CLOSED | Recipient is closed |
Problem | CLOSED_AWAITING_COLLECTION | Recipient is closed, ready for collection by the recipient at the sorting center on the next business day |
Problem | CLOSED_ON_ARRIVAL | Recipient is not present |
Problem | CLOSED_SHIPMENT | Delivery (partially) interrupted, please contact the sender |
Problem | COLLECTION_ADDRESS_CLOSED | Pick-up address closed |
Problem | COLLECTION_ORDER_REFUSED | Pickup order refused by the courier |
Problem | CS_ACTION_REQUIRED | Sender will contact DHL |
Problem | DAMAGE_RETURN | Return to sender because of damage |
Problem | DELIVERY_DATA_INCORRECT | Incorrect data for delivery |
Problem | DELIVERY_DATA_INCORRECT_RETURN | Incorrect address details, the shipment will return to the sender |
Problem | DESTROYED | Disposed of shipment as requested by the sender |
Problem | FAILED_TO_DELIVER_REDELIVER | Delivery delayed, new delivery attempt on next delivery day |
Problem | FORCE_MAJEURE | Delivery interrupted, delivery date changed |
Problem | FOUND_AT_DEPOT | Found at the CityHub |
Problem | FOUND_DURING_INVENTORY | Found during stocktaking |
Problem | HELD_FOR_PAYMENT | Awaiting payment |
Problem | HELD_IN_STORAGE | Held in storage |
Problem | HELD_IN_STORAGE_BACKLOG | In storage for later delivery |
Problem | HELD_IN_STORAGE_CLOSED | Held in storage, receiver location closed |
Problem | HELD_IN_STORAGE_DAMAGED | Held in storage due to damage |
Problem | HELD_IN_STORAGE_HOLIDAY | In storage because of holiday |
Problem | HELD_IN_STORAGE_INCOMPLETE | In storage because of incomplete |
Problem | HELD_IN_STORAGE_REFUSED | In storage because of refusal |
Problem | ID_CHECK_UNSUCCESSFUL | |
Problem | INCORRECT/UNKNOWN_PIN | Pincode incorrect or unknown |
Problem | INSUFFICIENT_DOCUMENTATION | |
Problem | INVALID_SHIPMENT_SPECIFICATION | |
Problem | INVALID_SHIPMENT_SPECIFICATION_RETURN | |
Problem | INVENTORY | Inventory |
Problem | MIS_ROUTED | Sorted incorrectly delayed because of resorting |
Problem | MISCODE | Address details incorrect because of postal code |
Problem | MISROUTED_RETURN_TO_SHIPPER | |
Problem | MISSED_DELIVERY_CYCLE | Missed delivery route |
Problem | MISSING_AFTER_ROUTE | Delivery interrupted |
Problem | MISSORT | Sorted incorrectly delayed because of resorting |
Problem | NO_MONEY_REDELIVER | No payment, new delivery attempt on the next delivery day |
Problem | NO_MONEY_RETURN | No payment, return to sender |
Problem | NOT_ARRIVED | Not arrived at the CityHub |
Problem | NOT_HOME | We missed you |
Problem | NOT_HOME_NEW_DELIVERY | We missed you, new attempt on the next delivery day |
Problem | NOT_HOME_RETURN_TO_SHIPPER | We missed you, the shipment will return to the sender |
Problem | NOT_HOME_SYSTEM_INTERVENTION_DELIVERY_AT_PARCELSHOP | We missed you. We deliver your shipment at a DHL ServicePoint. |
Problem | NOT_HOME_TO_PARCELSHOP | We missed you |
Problem | NOTHING_COLLECTED | Nothing picked up by the courier |
Problem | NOTHING_PICKED_UP | No shipment(s) picked up |
Problem | NOTHING_PICKED_UP_GOODS_ALREADY_COLLECTED | Nothing was picked up, shipment(s) already picked up previously |
Problem | NOTHING_PICKED_UP_GOODS_ARE_NOT_READY_YET | Nothing was picked up, no shipment(s) prepared |
Problem | NOTIFICATION_FOR_PARCELSHOP_COLLECTION_HAS_FAILED | Failed to send notification for collection at DHL ServicePoint by the recipient |
Problem | ON_HOLD | Temporarily in storage |
Problem | ON_HOLD_ANNOUNCED | In storage |
Problem | PALLET_MATERIAL_NOT_AVAILABLE | No empty pallet material available at pick-up address |
Problem | PALLET_MATERIAL_NOT_AVAILABLE_AT_PICKUP | No empty pallet material available at pick-up address |
Problem | PALLET_NOT_EMPTY | Euro-pallets at pick-up address still in use |
Problem | PALLET_NOT_EMPTY_AT_PICKUP | Euro-pallets at pick-up address still in use |
Problem | PARCEL_ALREADY_RETURNED | Already returned to the sender |
Problem | PARCEL_MISSING | Delivery interrupted, the parcel is delayed for one or two days |
Problem | PARCEL_MISSING_AT_PARCELSHOP | Collection at DHL ServicePoint by recipient not possible at this moment, please contact the sender |
Problem | PARCEL_MISSING_AT_PARCELSHOP_NOTICED_AT_STOCK_CHECK | Pickup at DHL ServicePoint not possible at this moment, please contact the sender |
Problem | PARCEL_MISSING_AT_PARCELSHOP_NOTICED_BY_COURIER | Pickup at DHL ServicePoint by the courier not possible at this moment, please contact the sender |
Problem | PARCEL_MISSING_AT_PARCELSHOP_NOTICED_BY_CUSTOMER | Collection at DHL ServicePoint by recipient not possible at this moment, please contact the sender |
Problem | PARCEL_NOT_BROUGHT_IN | Not dropped off by the sender |
Problem | PARCEL_NOT_COLLECTED_AT_PARCELSHOP | Not collected at DHL ServicePoint |
Problem | PARCEL_NOT_SORTED_AT_HUB_NO_INFO | Received in sorting center, awaiting the data |
Problem | PARCEL_RELABELED_FOR_RETURN_TO_SHIPPER | Relabeled for return to sender |
Problem | PARCELSHOP_FULL_REDELIVER | DHL ServicePoint full, new delivery attempt on the next delivery day |
Problem | PARCELSTATION_DELIVERY_UNSUCCESFULL_RETURN | |
Problem | PARCELSTATION_NOT_AVAILABLE_REDELIVER_TO_PARCELSHOP | |
Problem | PARTIAL_DELIVERY | Partially delivered |
Problem | PIECE_MISSING | Delivery (partially) interrupted the parcel is delayed for one day |
Problem | PO_BOX | It's not possible to deliver to a post office box the shipment will return to the sender |
Problem | POSTAL_CODE_INCORRECT | Incorrect address details, the shipment will return to the sender |
Problem | RECEIVER_CLOSED_ANNOUNCED | Recipient closed |
Problem | RECEIVER_CLOSED_COLLECTION_CANCELLED | Pick-up address is closed, pick-up order cancelled |
Problem | RECEIVER_CLOSED_COLLECTION_RESCHEDULED | Pick-up address closed, new pick-up attempt next delivery day |
Problem | RECEIVER_CLOSED_ON_HOLIDAY | Recipient is closed because of holiday |
Problem | RECEIVER_CLOSED_ON_HOLIDAY_COLLECTION_CANCELLED | Pickup address is closed because of holiday pickup order cancelled |
Problem | RECEIVER_CLOSED_ON_HOLIDAY_COLLECTION_RESCHEDULED | Pick-up address closed due to holiday |
Problem | RECEIVER_CLOSED_ON_HOLIDAY_PICKUP_CANCELLED | Pick-up address closed due to holiday, pick-up order cancelled |
Problem | RECEIVER_CLOSED_PASSED_TO_DEPOT | Recipient is closed will be forwarded to sorting center |
Problem | RECEIVER_CLOSED_PASSED_TO_PARCELSHOP | Recipient is closed will be forwarded to DHL ServicePoint |
Problem | RECEIVER_MOVED_OR_UNKNOWN | Recipient moved or unknown, please contact the sender |
Problem | RECEIVER_MOVED_OR_UNKNOWN_NOT_COLLECTED | Pick-up address unknown |
Problem | RECEIVER_ON_HOLIDAY_ANNOUNCED | Recipient closed because of holiday |
Problem | REFUSED | Delivery interrupted |
Problem | REFUSED_2ND_KIB | Not collected at the sorting center by the recipient return to sender |
Problem | REFUSED_AT_PARCELSHOP | Refused at DHL ServicePoint by the recipient |
Problem | REFUSED_BY_RECEIVER | Refused by the recipient |
Problem | REFUSED_DAMAGED | Refused because of damage |
Problem | REFUSED_INCOMPLETE | Refused because of incomplete |
Problem | REFUSED_INVENTORY | Refused because of inventory |
Problem | REFUSED_NO_MONEY | Refused because of no money |
Problem | REFUSED_NO_RECAP | Refused because of missing delivery note |
Problem | REFUSED_NOT_COLLECTED | Not collected by the recipient return to sender |
Problem | REFUSED_NOT_ORDERED | Refused by the recipient because of not ordered |
Problem | REFUSED_NOT_ORDERED_CORONA | Refused: not ordered OR Closed due to Coronavirus |
Problem | REFUSED_NOT_SIGNED | Refused, receiver refuses to sign |
Problem | REFUSED_OTHER_REASON | Not delivered because of other reason |
Problem | REFUSED_REQUESTS_WAYBILL | Refused, receiver requests waybill |
Problem | REFUSED_RETURN | |
Problem | REFUSED_RETURN_TO_DD | Refused and return to sorting center |
Problem | REFUSED_TOO_LATE | Refused because of delivery too late |
Problem | REFUSED_WILL_NOT_PAY | Not delivered because of no payment by the recipient |
Problem | REPACKED_DELIVERY_DAMAGED | Repackaged due to damage |
Problem | RETURNED_NOT_COLLECTED | Not collected, return to the shipper |
Problem | RETURNED_TO_SHIPPER | Returned to the sender |
Problem | SAFEPLACE_DELIVERY_FAILED | Your shipment couldn't be delivered at your preferred location |
Problem | SHIPMENT_INSPECTION_ON_HOLD | Shipment delayed due to screening |
Problem | SHIPMENT_INSPECTION_REJECTED | Shipment blocked, please contact the sender |
Problem | SHIPMENT_STOPPED | Impounded by customs |
Problem | SHIPMENT_TOO_LARGE_FOR_ACCESSPOINT | |
Problem | SHIPMENT_TOO_LARGE_FOR_PARCELSHOP | |
Problem | SHIPMENT_TOO_LARGE_FOR_PARCELSTATION | |
Problem | STORAGE_PERIOD_ENDED_AT_ACCESSPOINT | Not collected at DHL ServicePoint by the recipient return to sender |
Problem | STORAGE_PERIOD_ENDED_AT_PARCELSHOP | Not collected at DHL ServicePoint by the recipient return to sender |
Problem | STORAGE_PERIOD_ENDED_AT_PARCELSTATION | |
Problem | TRACE_INITIATED | Customer service of DHL initiates action |
Problem | TRACE_TERMINATED | Customer service of DHL terminates action |
Problem | TRANSPORT_DELAY | Delayed during transport |
Problem | UNCONTROLLABLE_CLEARANCE_DELAY | Uncontrollable delay at customs |
Customs data
- With the product "DHL Parcel International" the eConnect API supports shipments to countries liable to customs.
- The customs functionality of this eConnect API is not applicable for "DHL Parcel Connect". The product "DHL Parcel Connet" cannot be send into customs destinations via this eConnect API (as of May 2022).
- For "DHL Parcel International" into customs destinations, it is mandatory send customs data per each shipment (i.e. cCustoms request) in addition to the shipment data (i.e. cPAN request).
- The cCustoms call requires information about the content of the parcel (including its value and purpose). It will forward the electronic information to the customs entities and return a CN23 document to the user on request.
- The CN23 document is returned together with the shipment label (see explanations on "Label" above). It is issued in PDF format for printout and attachment to the parcel.
- Overview of use cases:
- If you create a shipment to a non-customs destination, you don't need to send a "cCustoms" request. If you still send customs data, these will be ignored by the eConnect API.
- If you create a shipment to a customs destination or region, the "cCustoms" request containing the customs data is mandatory. If you don't send it, your shipments will be rejected and you will not receive a shipment label.
- If either one of CPAN and/or cCustoms is inconsistent, your shipments will be rejected too.
Use Case Overview
Below you can find an overview of the different use cases, that are available via the eConnect API. In the next section you can find a short description for each use case. For request/response examples please see Reference Docs section.
Business Process | eConnect API functionalities/requests | |||||
No. | Use Case | Access | Shipment data (cPAN) | Location finder | T&T | Customs data (cCustoms) |
1 | Create DHL Parcel Connect shipment delivered to a doorstep address | yes | yes | no | optional | no |
2 | Create DHL Parcel Connect shipment delivered to a Service Point (Option to include location finder) | yes | yes | optional | optional | no |
3 | Create DHL Parcel Connect shipment delivered to a locker/Parcelstation in Germany | yes | yes | optional | optional | no |
4 | Create a DHL Parcel Return Connect shipment | yes | yes | no | optional | no |
5 | Create DHL Parcel International shipment (EU destination) | yes | yes | no | optional | no |
6 | Parcel International shipment including customs | yes | yes | no | optional | yes |
7 | Track and trace your shipments | yes | no | no | yes | no |
Use Case 1: DHL Parcel Connect shipment delivered to door
Business Process
This request enables users to inject their shipment data for doorstep deliveries for DHL Parcel Connect shipments. If requested, the API will return the respective label in the desired format and resolution.
Key success factors:
- The recipient address must be the correct door address of the recipient
- It is recommended to include e-mail and/or phone number in the recipient data to enable recipient services (e.g. re-routing to ServicePoints
Request/Response Examples
For examples and Try-Out functionality see Reference Docs section under "sendCPAN".
Use Case Label
Depending on how the request was specified, the response may optionally contain a shipping label in the specified format.
Use Case 2: DHL Parcel Connect shipment delivered to Service Point (Option to include location finder - see below)
Business Process
This request enables users to inject their shipment data for ServicePoint deliveries for DHL Parcel Connect shipments. The sender needs to know the desired ServicePoint address. If requested, the API will return the respective label in the desired format (e.g. PDF or ZPL) and resolution.
Key success factors:
- It is mandatory for ServicePoint shipments to include the following parameters in the address: name of recipient, name of service point, keyword, servicepointID, street, housenumber, ZIP code, city, country
- When sending the shipment data to the eConnect API, the location information needs to be integrated into the respective shipment data (cPAN), by using the mapping table shown here.
- Only for directly addressed shipments to German ServicePoints (aka „Postfiliale" - See Use Case 4) the attributes which contain the street and house number of the shops are optional.
- It is recommended to include phone numbers for SMS notification to create higher pick up rates
- Shipments to LU: Please not that there is an exception for shipments to LU as address data needs to be entered differently. In case you want to send shipments to lockers in LU, please reach out to us for further instructions
Optional: In case the desired location data of the ServicePoint is not known already, you have the option to search for a location address by accessing the DHL Location Finder API. Ideally the eCommerce/webshop user interface lets the recipient choose the preferred ServicePoint during check-out.
Use Case Label
Depending on how the request was specified, the response may contain label in the specified format (e.g. pdf) and resolution.
Use Case 3: DHL Parcel Connect shipment delivered to locker/Parcelstation in Germany
Business Process
This request enables the user to inject their shipment data for shipments delivered to lockers/Parcelstations in Germany. To make use of DHL lockers in Germany, customers need to provide an identification number for each recipient (i.e. "PostNummer"), as German recipients need to be registered to receive locker shipments. The PostNummer needs to be inserted into the "customerIdentification" field of the recipient data in the shipment data request. If requested, the API will return the respective label in the desired format and resolution.
Key success factors:
- The attributes which contain the street and house number of the shops are optional.
- It is recommended to include phone numbers for SMS notification to create higher pick up rates at the locker.
- Shipments to Luxembourg: Please note that there is an exception for shipments going to LU as address data needs to be entered differently. In case you want to send shipments to lockers in LU, please reach out to us for further instructions.
Use Case Label
Depending on how the request was specified, the response may contain label in the specified format (e.g. pdf) and resolution.

Use Case 4: DHL Parcel Return Connect shipment
The following request enables the user to send shipment data for a DHL Parcel Return Connect Shipment. If requested, the API will return the respective label in the desired format (PDF or ZPL).
Key success factors:
- The Return product needs to be dropped-off by the customer in a local ServicePoint or PostOffice in the country of residency.
- DHL Return Connect offers a public website to search for drop-off locations all accross Europe: https://finder.dhlparcel.com/
- Make sure to inform your recipients (i.e. consumers) about where they can search for possible drop off points for returns in their region, e.g. by distributing this link (https://finder.dhlparcel.com/)
- It is recommended to additionally generate return instructions. Return instructions contain handling information to help return senders (i.e. consumers) to correctly handle the return shipment. The instructions are issued by DHL in all local European languages and can be requested via our contact form (add link).
Request Example
POST /ccc/send-cpan?generateLabel=true&labelFormat=pdf HTTP/1.1
Host: api-sandbox.dhl.com
Content-Type: application/json
Authorization: Bearer AJx0yDAMVnBlcBsSeTwuPpkytYz78fzgUG20aBrTyMBPeP347pVDrz
{
"dataElement": {
"parcelOriginOrganization": "GB",
"parcelDestinationOrganization": "DE",
"general": {
"product": "ParcelEurope.return.network"
},
"cPAN": {
"addresses": {
"sender": {
"type": "default",
"firstName": "John",
"name": "Doe",
"additionalName": "Rain Inc.",
"mobileNr": "+441234567890",
"email": "john.doe@example.com",
"street1": "Ossulston St.",
"street1Nr": "174",
"postcode": "NW1 1DN",
"city": "London",
"country": "GB",
"referenceNr": "REF45678901234567890123456789012345",
"customerIdentification": "YOUR_ID_HERE"
"customerAccountNr1": "YOUR_ID_HERE"
},
"recipient": {
"type": "doorstep",
"firstName": "",
"name": "c/o DHL Parcel Europe",
"additionalName": "Good Weather GmbH",
"street1": "Robert-Bosch-Str.",
"street1Nr": "750",
"postcode": "93055",
"city": "Regensburg",
"country": "DE"
}
},
"features": {
"physical": {
"grossWeight": "1.0"
}
}
}
}
}
Response Example
Depending on how the request was specified, the response may contain label in the specified format (e.g. pdf) or not (see example below). The response will also contain a status code as well as a status message both indicating whether the request could be processed successfully or not (see examples below).

Success Response
HTTP/1.1 200
Content-Type: application/json;charset=UTF-8
shipmentId: JVGL003101234567801234
{
"response":{
"status":"200",
"timestamp":"2017-03-21T06:29:55",
"customerId":"AAAA",
"sessionId":"f10953e8-2e73-41f4-ab4e-818ea4ac76ad",
"statusCode":"OK",
"statusMessage":"cPAN has been processed successfully"
}
}
Error Response
HTTP/1.1 400
Content-Type: application/json;charset=UTF-8
shipmentId: JVGL003101234567801234
{
"error":{
"status":"400",
"timestamp":"2017-03-21T06:29:55",
"sessionId":"f10953e8-2e73-41f4-ab4e-818ea4ac76ad",
"statusCode":"ERROR",
"statusMessage":"Unexpected input provided"
}
}
Use Case 5: DHL Parcel International shipment
This request enables the user to inject their shipment data for DHL Parcel International shipments. If requested, the API will return the respective label in the desired format (PDF or ZPL).
Key success factors:
- Please note: If "customsDocCount" in your response is 1 or more, you need to additionally send a "cCustoms" request as this lane requires custom clearance (Please see Use Case 6).
Request Example
POST /ccc/send-cpan?generateLabel=true&labelFormat=pdf HTTP/1.1
Host: api-sandbox.dhl.com
Content-Type: application/json
Authorization: Bearer 47gbtqPg5cEOfmv2FXGWNe4lFyHrwM3jZfurBGGCCdex7SRXXbAYrV
{
"dataElement": {
"parcelOriginOrganization": "NL",
"parcelDestinationOrganization": "US",
"general": {
"product": "ParcelEurope.parcelinternational"
},
"cPAN": {
"addresses": {
"sender": {
"type": "default",
"firstName": "",
"name": "Good Weather GmbH",
"street1": "Beulingstraat",
"street1Nr": "17a",
"postcode": "1017 BA",
"city": "Amsterdam",
"country": "NL",
"referenceNr": "REF45678901234567890123456789012345",
"customerIdentification": "6266404794",
"customerAccountNr1": "YOUR_ID_HERE"
},
"recipient": {
"type": "doorstep",
"firstName": "John",
"name": "Doe",
"additionalName": "Rain Inc.",
"mobileNr": "+1234567890",
"email": "john.doe@example.com",
"street1": "Long Street",
"street1Nr": "16",
"postcode": "NJ 07305",
"city": "New York City",
"country": "US"
}
},
"features": {
"physical": {
"grossWeight": "1.0"
},
"undeliverableInstruction": "Return"
}
}
}
}
Response Example
Depending on how the request was specified, the response may contain label in the specified format (e.g. pdf) or not (see example below). The response will also contain a status code as well as a status message both indicating whether the request could be processed successfully or not (see examples below).

Success Response
HTTP/1.1 200
Content-Type: application/json;charset=UTF-8
shipmentId: JVGL003101234567801234
{
"response":{
"status":"200",
"timestamp":"2017-03-21T06:29:55",
"customerId":"AAAA",
"sessionId":"f10953e8-2e73-41f4-ab4e-818ea4ac76ad",
"statusCode":"OK",
"statusMessage":"cPAN has been processed successfully"
}
}
Error Response
HTTP/1.1 400
Content-Type: application/json;charset=UTF-8
shipmentId: JVGL003101234567801234
{
"error":{
"status":"400",
"timestamp":"2017-03-21T06:29:55",
"sessionId":"f10953e8-2e73-41f4-ab4e-818ea4ac76ad",
"statusCode":"ERROR",
"statusMessage":"Unexpected input provided"
}
}
Use Case 6: DHL Parcel International shipment including customs
Note that the customs functionality of this eConnect API is not available for the product "DHL Parcel Connect". Customs shipments are only available for the "DHL Parcel International" product.
This use case / request enables the user to inject their shipment data for DHL Parcel International shipments, if custom clearance is required. In this case, it is mandatory send a "cCustoms" request after sending the cPAN (See Use Case 6 for a cPAN example). The cCustoms call requires information about the content of the parcel (including its value and purpose). It will forward the electronic information to the customs entities and on demand return a CN23 document as PDF for printout and attachment to the parcel.
Key success factors:
- Always send cCustoms if you send to a customs destination or region as it is mandatory. If not provided, the shipment will be rejected.
- Make sure that both cPAN and cCustoms are correct; otherwise the system will reject the shipment.
- CPAN request needs to be send before cCustoms and the parcelIdentifier is mandatory here
- When sending in your cPAN, "customsDocCount" in the response informs you about the amount of CN23 printouts required for that specific shipment.
Request Example
POST ccc/send-cCustoms?generateCustomsDocument=true HTTP/1.1
Host: api-sandbox.dhl.com
Content-Type: application/json
Authorization: Bearer AJx0yDAMVnBlcBsSeTwuPpkytYz78fzgUG20aBrTyMBPeP347pVDrz
{
"dataElement": {
"version": "0200",
"parcelOriginOrganization": "NL",
"parcelDestinationOrganization": "US",
"general": {
"parcelIdentifier": "CY657904000DE",
"timestamp": "2020-12-04T14:13:58.798000",
"product": "ParcelEurope.parcelinternational",
"routingCode": "2LJP5300002+71000000",
"customerIdentification": "5012345678"
},
"cCustoms": {
"CustomsIDs": {
"sender": [{
"idType": "VAT",
"identifier": "789012"
}]
},
"shippingFee": {
"currency": "EUR",
"value": "5.50"
},
"goodsDescription": {
"general": {
"goodsClassification": "ProductSample",
"currency": "EUR"
},
"item": [{
"description": "Tea, green",
"customsTariffNumber": "902100",
"originCountry": "NL",
"quantity": "2",
"netWeight": "0.100",
"value": "8.00"
},
{
"description": "Sneakers",
"customsTariffNumber": "640411",
"originCountry": "NL",
"quantity": "1",
"netWeight": "0.400",
"value": "49.99"
}
]
},
"customsDocuments": {
"document": [{
"docType": "Invoice",
"identifier": "Inv-2020-12345"
}]
},
"comment": "Some additional information for customs authorities"
}
}
}
Response Example
Depending on how the request was specified, the response may contain a CN23 document in the specified format (e.g. pdf) or not . The response will also contain a status code as well as a status message both indicating whether the request could be processed successfully or not (see examples below).
Success Responses
Scenario 1: without CN23
HTTP/1.1 200
Content-Type: application/json;charset=UTF-8
{
"response":{
"status":"200",
"timestamp":"2020-08-06T10:31:55",
"customerId":"EKPTest001",
"sessionId":"f10953e8-2e73-41f4-ab4e-818ea4ac76ad",
"statusCode":"OK",
"statusMessage":"cCustoms has been processed successfully"
}
}
Scenario 2: with CN23
HTTP/1.1 200
Content-Type: application/pdf;charset=UTF-8
CN23 document as PDF.
Error Responses
HTTP/1.1 200
Content-Type: application/json;charset=UTF-8
{
"error":{
"status":"400",
"timestamp":"2020-08-06T10:32:55",
"sessionId":"a10953e8-2e73-41f4-ab4e-818ea4ac76ad",
"statusCode":"ERROR",
"statusMessage":"Unexpected input provided"
}
}
Use Case 7: Track and trace your shipment
The API offers a full track and trace functionality for the shipments of each user. It is possible to request the status information on singular shipment or account level.
GET /ccc/track-trace?shipmentId=JVGL00000000600337158749 HTTP/1.1
Host: api-sandbox.dhl.com
Content-Type: application/json
Authorization: Bearer AJx0yDAMVnBlcBsSeTwuPpkytYz78fzgUG20aBrTyMBPeP347pVDrz
{
"barcode": "JVGL00000000600337158749",
"barcodes": ["JVGL00000000600337158749"],
"date": "2018-09-21T08:07:02.000Z",
"events": [
{
"parcelId": "2644d961-2a6e-45a7-86ba-1dc808841bc6",
"category": "DATA_RECEIVED",
"leg": {
"accountId": "00000000",
"network": "MDP"
},
"localTimestamp": "2018-09-21T09:52:45.018+02:00",
"status": "PRENOTIFICATION_RECEIVED",
"timestamp": "2018-09-21T07:52:45.018Z",
"type": "LEG_EVENT"
},
{
"category": "UNDERWAY",
"facility": "Ottendorf-Okrilla-01458",
"localTimestamp": "2018-09-21T09:54:59.000+02:00",
"leg": {"network": "CDEx"},
"status": "PICKED_UP",
"timestamp": "2018-09-21T07:54:59.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "Frankfurt-60327",
"localTimestamp": "2018-09-21T09:56:02.000+02:00",
"leg": {"network": "CDEx"},
"status": "GATEWAY_DEPARTED",
"timestamp": "2018-09-21T07:56:02.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "Liége-4000",
"localTimestamp": "2018-09-21T09:56:51.000+02:00",
"leg": {"network": "CDEx"},
"status": "GATEWAY_ARRIVED",
"timestamp": "2018-09-21T07:56:51.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "Turnhout-2300",
"localTimestamp": "2018-09-21T09:58:07.000+02:00",
"leg": {"network": "CDEx"},
"status": "GATEWAY_DEPARTED",
"timestamp": "2018-09-21T07:58:07.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "Roermond-6043JR",
"localTimestamp": "2018-09-21T10:02:16.000+02:00",
"leg": {"network": "CDEx"},
"status": "ARRIVED_AT_INBOUND_GATEWAY",
"timestamp": "2018-09-21T08:02:16.000Z",
"type": "PIECE_EVENT"
},
{
"category": "DATA_RECEIVED",
"localTimestamp": "2018-09-21T10:03:04.000+02:00",
"leg": {"network": "ECOMMERCE"},
"status": "PRENOTIFICATION_RECEIVED",
"timestamp": "2018-09-21T08:03:04.000Z",
"type": "PIECE_EVENT"
},
{
"category": "LEG",
"leg": {
"accountId": "49538108",
"network": "ECOMMERCE"
},
"localTimestamp": "2018-09-21T10:04:03.000+02:00",
"status": "LEG_CREATED",
"timestamp": "2018-09-21T08:04:03.000Z",
"type": "LEG_EVENT"
},
{
"category": "DELIVERED",
"facility": "Luyksgestel-5575AE",
"localTimestamp": "2018-09-21T10:07:02.000+02:00",
"leg": {"network": "CDEx"},
"status": "DELIVERED",
"timestamp": "2018-09-21T08:07:02.000Z",
"type": "PIECE_EVENT"
}
],
"type": "SHIPMENT",
"deliveredAt": "2018-09-21T10:07:02.000+02:00"
}
DHL eCommerce Solutions Europe is always here to help you out.
Please use the contact forms according to your need:
Testing / Getting started
Should we conduct all testing against the sandbox API or are we also able to test towards the production API?
First we kindly ask you to do all testing against the Sandbox, until you have finalized your flow with working requests/replies. Then we will do an approval of label & request data. After that you will receive PROD credentials for real-life shipment tests (e.g. with a couple of customer shipments).
Note: usually a limited amount of test shipments against the production environment remain without consequence, if there are no scan events performed by DHL and no additional services are requested (e.g. pickup-requests).
Do you have any Postman collections of the different requests that you could share with us?
Unfortunately we do not share those at the moment, they are only used internally by our developer team.
Sending shipments
Which information is mandatory to enter to be able to book a shipment?
Please see our request spec for details on each field.
Do you have package volume and weight validations on your side through the API, or do we need to have all the validations on our side?
We have a validation service for several aspects of the shipment, but that is currently inactive for self-labeling customers. Only active for API-label customers.
Which package types should be available?
The allowed packaging types per product and shipment can be obtained from the product information (see overview section) and need to be obeyed. On the API-call there is no package-type field, so from IT-integration perspective the type of packaging does not have relevance.
Is it possible to ask for status files through customer ID or shipment ID?
This is unfortunately not possible as we do not offer FTP transmission and the API does not push statuses. Track and trace is currently offered via API calls on shipment or customer level only, no status files are provided.
Label
How do we request the label through the API, do you have any examples?
This is part of the GET request, it is defined here.
Is it possible to send in a parcel ID/parcelIdentifier while also requesting a label, so that the label would contain the customers own parcel ID?
This is not supported at the moment. Either you use our API-generated label, which will come with a dedicated number range starting with "JVGL..." or you create the label yourself, applying a different number range.
Do you have any restrictions on which kinds of parcel ID's you are accepting?
The following options exist for identifiers:
- ASC MH10 in symbology Code 128 barcode, max. 35digits (alphanumeric characters)
- GS1 (former EAN), starting with an FNC1 character in symbology Code GS1 128, 20digits (numerical)
It is permitted that the routing barcode is shown in one license plate barcode format (i.e. ASC MH10) while the identifier is shown in another license plate barcode format (i.e. GS1)
Service Points
When we request available service points from the API, does the receiving address need to look exactly like in your specification?
The minimum requirement is to provide a correct zip code and city.
How should the service point be sent in the EDI to you?
It is essential to map the retrieved service point addressing information to the correct API fields. Please see our example CPAN for this use case here.
Is it possible to search by ServicepointID via the API?
This search option is not available at the moment.
Integrators
Are the EDI credentials unique to the integrator or to the customer?
Generally the credentials are customer-unique. Only in case the service is cloud-based (and not installed on customers premises), we can issue a central pair of credentials to you, so that it is integrator-unique.
Specifics for the use of DHL eCommerce Solutions Europe API
To register for the use of and/or access to DHL eCommerce Solutions' Europe API and the underlying API Services (create shipment, generate label, track & trace, parcel shop finder) - hereinafter referred to as DHL eCommerce Solutions Europe API - you and/or the entity you are authorized to represent (hereinafter "You"/"Your") need to have an account with and/or have entered into a Customer Services Agreement with one of DHL eCommerce Solutions' legal entities. If You engage an external developer or other IT services provider to represent You and to develop Your Application according to the General Developer Portal Terms of Use and these special API terms & conditions (also referred to as "Legal Terms"), You are liable for the acts or omissions of such third party in connection with the access to and/or usage of the DHL eCommerce Solutions Europe API.
These Legal Terms and the General Developer Portal Terms of Use govern your usage of and/or access to the DHL eCommerce Solutions Europe API including the API Services and, unless otherwise stated herein, do not replace and/or modify any other DHL eCommerce Solutions terms and conditions of Carriage, Customer Services Agreements and/or any other agreements, contracts or SOWs with DHL eCommerce Solutions or any of its affiliates, which govern services or products provided to you (separately, each an "Agreement"). Notwithstanding the foregoing, you expressly acknowledge and agree that solely with respect to your use of and access to the DHL eCommerce Solutions Europe API these Legal Terms and the General Developer Portal Terms of Use shall have preference over the terms and conditions in an Agreement, unless any terms and conditions in an Agreement specifically address the use of/access to the DHL eCommerce Solutions Europe API by You, in which case the specific terms and conditions of the Agreement shall prevail with respect to Your use of/access to the DHL eCommerce Solutions Europe API.
You shall use the services and/or data that You receive via the DHL eCommerce Solutions Europe API only for the legitimate contractual purposes and only in connection with DHL eCommerce Solutions' carriage services.
The following prerequisites and/or restrictions apply for the usage of data or information received via the DHL eCommerce Solutions Europe API:
Parcel shop finder
Data requested and received via this API, such as addresses of DHL Service Point locations, location types, services at location, is hereinafter referred to as "Location Data".
Such Location Data is provided to You and/or the entity you are authorized to represent (hereinafter "You"/"Your") via the DHL eCommerce Solutions Europe API under the following prerequisites and/or restrictions:
- You shall only publish, display and/or otherwise use the Location Data in connection with location data of other logistics/transportation services providers (e.g. show DPDHL´s locations together with locations of other transportation and/or logistics services providers on a website - a comparison portal for example - or any other (electronic) channel and/or medium), provided that You
- always show and/or display all DPDHL locations, that are available at the according address and that have been provided to You via the DHL eCommerce Solutions Europe (i.e. without dismissing single locations), and
- do not specifically select and/or recommend single locations thus contradicting DPDHL´s business interests.
- You shall not store and/or modify Location Data in any form; it is especially prohibited to analyze and/or derive data/information for competitive purposes from the Location Data without our prior written consent.
Label
The API Service "label" provides You with the possibility to create and download labels for singular shipments. Please note that the creating and/or downloading of a label does not constitute the contract of carriage. Such contract will be concluded once the labeled package is handed over or picked up and accordingly accepted by DHL eCommerce Solutions
Track & Trace
Data requested and received via this API, such as transport status, estimated delivery date, is hereinafter referred to as "Tracking Data".
Tracking Data is Confidential Information in the meaning of section "Communication" of the General Developer Portal Terms of Use. Other than set forth below You must not reveal and/or provide third parties with the Tracking Data and/or analyze, modify such data in any form and/or derive data/information especially for competitive purposes from it without DHL eCommerce Solutions' prior written consent.
Tracking Data is provided to You and/or the entity you are authorized to represent (hereinafter "You"/"Your") under the prerequisite, that You retrieved the according tracking number in compliance with the applicable law, especially in the field of data protection and competition law and that You use the Tracking Data solely for Your own or Your customers' legitimate tracking purposes.
You shall not combine Tracking Data with advertisement or present it in a way that it could be regarded as advertisement.
Unless otherwise agreed, You shall delete the Tracking Data 90 days after the delivery (of the shipment) to the recipient is completed. DHL eCommerce Solutions shall not be required to provide Tracking Data to You that is older than 90 days from the delivery date.
The use and submission of Tracking Data - including submission to any of Your subcontractors - shall always be in compliance with applicable laws and regulations, including - without limitation - data protection laws and competition/antitrust law.
If You are neither the shipper/sender nor the recipient of packages the Tracking Data refers to,
- You shall ensure, that you are duly authorized to act on behalf of the sender and/or the recipient;
- You shall make the sender and/or the recipient aware of the restrictions set out in this User Guide just as the General Developer Portal Terms of Use;
- You shall make the sender aware of the necessity to inform the recipient transparently about the processing of his/her personal data according to applicable data protection laws;
- You shall inform the sender and/or recipient transparently that the use of Your Application may result in the disclosure of data being subject to postal secrecy and data protection laws to third parties (including You).
April 2023
- First mile handling options for outbound shipments out of Italy and France
- Labelless Return Connect option for Polish senders of returns
- Provision of improved error messages on eConnect API to smoothen onboarding and error handling
- Increased robustness in handling of timestamp formats in API requests
October 2022
- Contents of the developer Portal have been improved.
- The eConnect API features the new DHL Parcel Connect PLUS product.
- The eConnect API features the postal return product "DHL Parcel Return International" for EU origins plus UK in selected customer scenarios.
- For trusted API partners, the eConnect API now offers a feature to send parcel-related events to DHL. Contact your DHL representative for details.
- For shipment labels, created via the eConnect API, it is now possible for customers to provide customer-individual Identcode Ranges ("customRange"). Enabling API-generated labels with customer barcodes for shipment identification.
January 2022
- The eConnect developer portal now offers "Try Out" functionality in the "Reference Docs" section. All available endpoints can be tested by developers with dummy data to provide easy access and accelerate API onboardings.
December 2021
- The cPAN request parameters related to the "direct injection" functionality are now deprecated. It is no longer necessary to transmit any "direct injection" parameters in cPAN requests. The configuration of direct injection setups for individual customers is done via the eConnect backend.
October 2021
- New Label selection available: eConnect API users can choose between 3 formats (pdf, zpl, png), 2 resolutions (200, 300 dpi) and 2 label sizes (10x15cm, 10x21cm) for eConnect labels.
- Simplification of shipment data (cPAN) to improve user experience for eConnect API developers; reduction of complexity
June 2021
- eConnect Portal now features Track & Trace UI for customers using the eConnect API
- New Code examples for most common programming languages added, see "Reference Docs" / "Send CPAN"
November 2020
- Improved documentation, including
- Overview of the different products and countries covered by the API
- Comprehensive description on how to use the API and its functionalities
- Description of various use cases (incl. example cPAN and example label)
- For DHL Parcel International, the cPAN fields Street2 and StreetNr2 will now be displayed on the label.
October 2020
- Initial release