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:

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:

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:

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:

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

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

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:

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:

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.

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:

• Business Questions
• Technical Questions

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