DHL eCommerce Europe
v 1.1.30
Division: DHL eCommerce

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
Region: Europe
Used for: Shipping, Tracking
Overview

eConnect

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:

Scope

The eConnect API covers the essential DHL cross-border parcel products for shipments within Europe and beyond:![Parcel Connect Coverage](images\Parcel Connect Coverage_0.png)

  • 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.

User Guide

Get Access

For onboarding, you need to follow this process guided by theDHL API team:

  1. Contact DHL to align use case and requirements
  2. Apply for access to sand box environment
  3. Implement your API solution (see use cases)
  4. Seek approval from DHL (for data and label)
  5. 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.

Functionalities

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

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.

Label Example Connect

Label Example Return Connect

  • 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.
    ![label incl field length](images\Use Case 1_1.png)

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.

Mapping

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 Cases

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 3](images\Use Case 4.png)

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).

![Use Case 4](images\Use Case 5.png)

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).

![Label 6](images\Use Case 6_1.png)

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"
}
Support & FAQ

Support

To get access to the eConnect API and solve any business-related matters, please access our business customer service available here

In case of technical questions related to the eConnect API and it's associated services please contact our technical support.

 

FAQ

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.

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.

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)

 

FAQ on 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 API 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.

Legal Terms

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).
May 2024
17.May.2024
  • API shipping labels are now available in native zpl format if requested by the user via GET parameter.
  • As an alternative option to printed labels, the product "Return Connect" now offers QR code return labels out of Poland, Bulgaria, Sweden and Spain
December 2023
11.Dec.2023
  • The send CPAN function was enhanced to support Return consolidation in DHL facilities based on customer configuration.
  • Adjustment of password credential reset process to a fully automized solution. API users will get new credentials automatically every year.
October 2023
17.Oct.2023
  • A new endpoint is available to book courier pickups for business customer addresses in Italy and France (beta version).
August 2023
17.Aug.2023
  • A new endpoint is available to Reprint shipment labels, that have been produced in the past, e.g. if labels are lost or damaged.
  • The API Status has been integrated into the status.dhl.com platform, enabling API users to subscribe to alerts in case of availability issues with the eConnect API.
  • A new option is offered, to automatically send emails to shipment recipients, whenever a shipment is created via the eConnect API.
April 2023
03.May.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
10.Oct.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
31.Jan.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
21.Dec.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
29.Oct.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
10.Jun.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
04.Nov.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
09.Oct.2020
  • Initial release