DHL Parcel DE Private Shipping (Post & Parcel Germany)

v 1.0.0

Division: Post & Parcel Germany, Parcel

Best for:

Developers who need an API to create DHL private customer shipments.
The submission of structurally simple to highly complex shipments to DHL, including domestic and international shipments with customs handling.
Access to labels or QR codes for handover at DHL drop-off locations.

Region: Germany

Used for: Shipping

Overview

The API allows partners to create private customer shipments by integrating DHL shipping capabilities into their own products and software.

Using the API, partners can populate a DHL Online Franking shopping cart and retrieve the services of a paid shopping cart. Payment itself is completed through the DHL Online Franking frontend.

Not suitable for:

Marketplace operators who want to manage fulfillment, including shipment payment, entirely via the API.

Typical Integration Flow

Register in the DHL Developer Portal and create an app.
Retrieve the available shipping products from the Product Catalog and cache them locally.
Create a shopping cart containing the desired shipment data and services.
Redirect the user to the entryUrl of the preconfigured DHL Online Franking cart.
The user completes payment in the DHL Online Franking frontend.
Receive a GET callback via notifyUrl after successful payment.
Call /shopping-carts/{shoppingCartId} to load the paid shopping cart, confirm its status, and inspect its items and services.
Use the returned PAKID values to access labels and QR codes through the corresponding label endpoints.

Core Concepts

partner The business customer or integrator consuming the service.

partner system The software used by the partner to communicate with the API.

product catalog The list of DHL shipping products and services available to the partner. The catalog depends on the product set assigned during onboarding and should be cached locally for better performance.

shopping cart The main business object of the API. It contains products, services, sender and receiver data, and all related purchase information.

entryUrl The frontend URL returned by DHL. It opens a preconfigured DHL Online Franking cart so the user can complete payment.

notifyUrl The partner endpoint that DHL calls after successful payment to signal successful payment.

Access and Technical Preconditions

Registration and App Setup

To access the services, registration in the DHL Developer Portal is required. Partners can register here.

You must also create an app in the Developer Portal. The corresponding instructions are available here.

After creating an app, you can obtain the API key for authentication and configure your notifyUrl.

Transport and Interface

The service is available only via HTTPS.
HTTP requests are ignored.
The API is exposed as a REST interface and can be used from common programming languages and HTTP-capable tools.

Character Set and Input Restrictions

DHL Online Franking supports only the ISO-8859-1 (Latin-1) character set.
Requests using other character sets are rejected.
The following characters are not allowed: ?*^!#%$:{}[]

Authentication

Web Service Authentication

Your application must authenticate in both test and production environments.

Pass the API Key of your DHL Developer Account in every request:

dhl-api-key: API Key

Keep private and personal data secure.

Frontend Authentication

To access the shopping cart provided via the entryUrl, use the following credentials:

Important: These Basic Auth credentials are required only for accessing the DHL Online Franking Sandbox frontend via entryUrl.

User: sbx_dev
Password: Lop6-tends0-4Avail-Abrade-2Weeks-4immovable

For the DHL Online Franking production frontend, no Basic Auth is required.

AI-Supported Integration

The DHL AI API Assistant can be used to support the integration.

It is an MCP server designed for AI-assisted integration scenarios, for example with tools such as GitHub Copilot.

For VS Code, a dedicated extension is available in the Downloads section.

More information about the MCP server can be found here.

Main Use Cases

1. Retrieve and Cache Product Information

The products resource provides the available product portfolio for the partner. It also supports search and filtering.

Because the amount of data is large, this endpoint should not be called for every transaction. The partner or partner system should cache the returned product data locally and refresh it only periodically, typically once per day.

In practice, the Product Catalog should be handled through a separate synchronization process rather than as part of the checkout flow.

The returned product set defines which products and services can later be added to the shopping cart.

2. Create a Shopping Cart

The most common purchase flow uses the ShoppingCart pre-paid endpoint.

In this model:

The partner system creates and submits a shopping cart to the web service.
DHL returns an entryUrl inside the shopping cart response under download.

This step is performed by the partner system. At this stage, the shopping cart is prepared, but payment has not yet been completed.

3. Complete Payment in DHL Online Franking

After the shopping cart has been created, the user completes payment independently in the DHL Online Franking website.

In this step:

The user opens the entryUrl returned by DHL.
The user completes payment in DHL Online Franking.
After successful payment, DHL triggers the configured notifyUrl as a simple GET request.
The callback signals successful payment only. Shopping cart contents are not transmitted.
Once the callback has been received, the follow-up processes can start.

This model is suitable when shipment purchase and payment are intentionally completed in the DHL Online Franking frontend rather than directly in the partner system.

4. Load a Paid Shopping Cart

The endpoint /shopping-carts/{shoppingCartId} is used to load a created and paid shopping cart, including its items and services.

This endpoint is especially relevant after a notifyUrl callback has been received. The callback signals that payment was successful, and the shopping cart can then be loaded through this endpoint to inspect the completed purchase.

The response allows the partner system to:

Check the current shopping cart status.
Inspect the purchased items and services.
Read shipment-related identifiers such as PAKID.
Use these identifiers to access labels or QR codes through the corresponding label access endpoints.

Typical post-payment flow:

Receive the GET payment notification through notifyUrl.
Read the shoppingCartId from the callback.
Call /shopping-carts/{shoppingCartId}.
Inspect the returned shopping cart and item data.
Extract the PAKID values from the returned items.
Use the PAKID to retrieve labels or QR codes.

This makes the endpoint the central lookup step between payment confirmation and document retrieval.

5. Use the Notify URL Securely

To secure communication, the notifyUrl should contain a one-time, non-guessable token.

Example:

https://merchant.example.com/notify/{token}

The endpoint must be registered through a service ticket before use. You can create a ticket in the DHL Developer Portal here.

Requirements for {token}:

It must be generated cryptographically at random.
A minimum entropy of 128 bits is recommended, for example UUIDv4 or at least 16 random bytes encoded as hex or Base64.
It must be unique per shopping cart.
Processing must be idempotent.
The token must be invalidated after the transaction has been completed.

Technical requirements for the notifyUrl endpoint:

Only HTTPS is accepted, with TLS 1.2 or higher.
The endpoint must be able to handle the query parameters appended by DHL.
Only GET must be accepted.
Return HTTP 200 after successful processing.
Return HTTP 4xx or 5xx if processing fails.
The endpoint must tolerate retries and traffic peaks.

Notify URL Request

After successful payment by the customer, DHL calls the configured notifyUrl as a simple GET request.

The callback is used only to signal successful payment. No additional content is transmitted in the request body.

The request has the following characteristics:

Method: GET
Trigger: Successful payment in DHL Online Franking
Callback purpose: Signal successful payment
Path parameter: {token}
Query parameter: dhlPartner=DEUANON
Query parameter: shoppingCartId=XXXXXXXXXXXX
Request body: none

Example request:

GET https://merchant.example.com/notify/{token}?dhlPartner=DEUANON&shoppingCartId=XXXXXXXXXXXX HTTP/1.1

The dhlPartner=DEUANON parameter is a static part of the callback request.

The partner is fully responsible for secure data processing and for compliance with legal and data protection requirements. DHL reserves the right to deactivate the notifyUrl in the event of non-compliance.

6. Book a Pickup

Pickup booking is optional during shopping cart creation. It is also possible to book a pickup without any other product.

Address Types

Different address types can be used with the web service, including direct delivery to pickup locations such as Parcel Shops and Packstations.

The address type is mainly determined by the values used in fields such as street, streetNumber, and name2.

Choosing the Correct Address Type

Use German Street Address when shipping to a regular postal address in Germany.

Use Parcel Shop when shipping to a DHL Parcel Shop and the receiver is identified by name plus Postnummer.

Use Packstation when shipping to a DHL Packstation and the receiver is identified by name plus Postnummer.

Use Province-Based Address for countries where a province or state is relevant, for example in international shipping.

German Street Address

Use this type for regular sender and receiver addresses in Germany.

Required fields:

Field	Type	Required	Notes
`name2`	string	yes	First and last name
`street`	string	yes	Street name
`streetNumber`	string	yes	Street number
`plz`	string	yes	5-digit postal code
`city`	string	yes	City
`country`	string	yes	Usually `DEU`
`email`	string	yes	Sender email address

Optional fields:

Field	Type	Notes
`name1`	string	Title
`name3`	string	Address addition
`addressAddition1`	string	Extra address information
`addressAddition2`	string	Extra address information
`province`	string	Province, if applicable
`phone`	string	Phone number

Example:

"address": {
  "receiver": {
    "name1": "Mrs.",
    "name2": "Selma Sender",
    "street": "Sträßchensweg",
    "streetNumber": "1-5",
    "plz": "53113",
    "city": "Bonn",
    "country": "DEU",
    "email": "noreply@dhl.com"
  }
}

Parcel Shop (Paketshop)

Use this type when shipping to a DHL Parcel Shop.

Required fields:

Field	Type	Required	Fixed or Special Value
`name1`	string	yes	Receiver's first and last name
`name2`	string	yes	Postnummer
`street`	string	yes	Must be `Postfiliale`
`streetNumber`	string	yes	Parcel Shop number
`plz`	string	yes	Postal code
`city`	string	yes	City
`country`	string	yes	Usually `DEU`
`email`	string	yes	Sender email address

Optional fields:

Field	Type	Notes
`addressAddition1`	string	Extra address information
`addressAddition2`	string	Extra address information
`phone`	string	Phone number

Example:

"address": {
  "receiver": {
    "name1": "Selma Sender",
    "name2": "12341887",
    "street": "Postfiliale",
    "streetNumber": "506",
    "plz": "53119",
    "city": "Bonn",
    "country": "DEU"
  }
}

Packstation

Use this type when shipping to a DHL Packstation.

Required fields:

Field	Type	Required	Fixed or Special Value
`name1`	string	yes	Receiver's first and last name
`name2`	string	yes	Postnummer
`street`	string	yes	Must be `Packstation`
`streetNumber`	string	yes	Packstation number
`plz`	string	yes	Postal code
`city`	string	yes	City
`country`	string	yes	Usually `DEU`
`email`	string	yes	Sender email address

Optional fields:

Field	Type	Notes
`addressAddition1`	string	Extra address information
`addressAddition2`	string	Extra address information
`province`	string	Province, if applicable
`phone`	string	Phone number

Example:

"address": {
  "receiver": {
    "name1": "Selma Sender",
    "name2": "12341887",
    "street": "Packstation",
    "streetNumber": "150",
    "plz": "53113",
    "city": "Bonn",
    "country": "DEU"
  }
}

Province-Based Address

Use this type when the destination country requires a province or state.

Typical fields:

Field	Required	Notes
`name2`	yes	First and last name
`street`	yes	Street name
`streetNumber`	yes	Street number
`plz`	yes	Postal code
`city`	yes	City
`country`	yes	Country code
`province`	no	Province or state
`email`	no	Email address
`name1`	no	Title
`name3`	no	Address addition
`phone`	no	Phone number

Example:

"address": {
  "receiver": {
    "name2": "Selma Sender",
    "street": "Dyer Ave",
    "streetNumber": "100",
    "plz": "10001",
    "city": "New York",
    "province": "NY",
    "country": "USA",
    "email": "noreply@dhl.com"
  }
}

Sender Address

The sender address must use the German Street Address type.

Error Format

For 4xx and 5xx responses, the API returns application/problem+json when the request uses application/json.

Example:

{
  "code": "vls.gpm.address.plzRequired",
  "detail": "Please enter a postal code.",
  "property": "item._0.address.receiver.plz"
}

The code shown above is a business error code, not the HTTP status code.

Common HTTP Status Codes

400 Bad Request The request is syntactically or semantically invalid. The request should only be repeated after correction.

401 Unauthorized Authentication failed because the provided credentials are invalid.

403 Forbidden Authentication succeeded, but the caller does not have sufficient permissions for the requested resource.

Legal Terms

GTC

GENERAL TERMS AND CONDITIONS FOR THE USE OF DHL Parcel DE Private Shipping (DHL Online Franking)

1 Scope of application/basis of agreement

(1) These General Terms and Conditions (GT&C) apply to agreements concluded with
Deutsche Post AG, Charles-de-Gaulle Straße 20, 53113 Bonn (hereinafter referred to as
“Deutsche Post”) for using the DHL Parcel DE Private Shippingg application. The customer can use this
application to purchase addressed parcel labels for the available selection of products
(hereinafter referred to as “DHL Shipping Labels”), which can be printed on their own printer,
or to purchase pre-paid individual coupons (hereinafter referred to as "Coupons"), which can
be used to purchase DHL Shipping Labels.

(2) The DHL Shipping Labels entitle the person specified on them as the sender to obtain the
stated transport service (DHL Päckchen (small packets), DHL Paket, DHL ExpressEasy
shipments and pick-up) to the recipient specified on the DHL Shipping Label, in accordance
with the general conditions* and prices for the respective transport service of Deutsche Post
and its associated companies, which can be viewed at the relevant locations of Deutsche Post.
The agreement concerning the respective transport service is not concluded until the
shipment is posted or handed over at or to Deutsche Post or its associated handling company
as set out in the relevant general conditions.

*AGB Brief National (GT&C for the Domestic Mail Service) or AGB Brief International (GT&C for
the International Mail Service) for small packages; AGB Paket/Express National (GT&C for the
Domestic Parcel/Express Service) for national parcels and Express shipments or AGB Paket
International (GT&C for the International Parcel Service) for international parcels and ATB
ExpressEasy International (TT&C for the International ExpressEasy Service) for international
ExpressEasy shipments.

(3) The Coupons entitle the customer to order the DHL Shipping Labels specified on the
coupons in the franking application.

2 Conclusion of the agreement

By ordering, the customer submits a binding offer for the conclusion of an agreement. The
agreement concerning the ordered DHL Shipping Label, the requested pickup or the Coupon
takes effect vis-à-vis the parties, if Deutsche Post accepts the offer. Acceptance occurs by
sending an order confirmation by e-mail. In this e-mail the respective ordered products are
usually made available, too.

3 Right of Withdrawal

3a Right of Withdrawal for DHL Parcel DE Private Shipping

(1) Right of Withdrawal

You have the right to withdraw from your order of DHL Shipping Labels or Coupons within
fourteen (14) days without giving any reason.

The withdrawal period will expire fourteen (14) days from the day you acquire, or a third
party other than the carrier indicated by you acquires, possession of (i.e. print out or
receive in your e-mail inbox) the DHL Shipping Labels or Coupons.

To exercise your right of withdrawal, you must inform us (Deutsche Post AG; DHL Online
Frankierung; Charles-de-Gaulle Str. 20; 53113 Bonn) of your decision to withdraw from
this contract by means of a clear declaration (e.g. online at dhl.de/widerruf, by e-mail to
widerruf@dhl.com, by telephone at 0228 4333112 or by letter sent by post). To do so,
you can submit a clear declaration electronically on our website dhl.de/widerruf or use the
model withdrawal form, which is, however, not mandatory.

To meet the withdrawal deadline, it is sufficient for you to send your communication
concerning your exercise of the right of withdrawal before the withdrawal period has
expired.

(2) Effects of withdrawal

If you withdraw from this agreement, we shall reimburse to you all payments that we have
received from you without undue delay and in any event no later than fourteen (14) days
from the day on which we are informed about your decision to withdraw from this
agreement. We will carry out such reimbursement using the same means of payment as
you used for the initial transaction unless you have expressly agreed otherwise; in any
event, you will not incur any fees as a result of such reimbursement. We may withhold
reimbursement until we have received the goods back or you have submitted evidence
that they have been sent back, whichever comes first.

You shall send back or hand over the DHL Shipping Labels or Coupons to Deutsche Post
AG; DHL Online Frankierung; Charles-de-Gaulle Str. 20; 53113 Bonn, or to permanently
delete them from your e-mail inbox, or, in the case of printed DHL Shipping Labels, to
destroy them, without delay and in any event no later than fourteen (14) days from the
day on which you communicate your withdrawal from this agreement to us. The observed
deadline is met, if you send the goods or permanently delete them or destroy them before
the period of fourteen (14) days has expired.

You will have to bear the direct cost of returning the DHL Shipping Labels.
You are only liable for any diminished value of the DHL Shipping Label or Coupon resulting
from the handling other than what is necessary to establish the nature, characteristics and
functioning of the DHL Shipping Label or Coupon.

3b Right of Withdrawal for the pickup service

(1) Right of withdrawal

You have the right to withdraw from this agreement within fourteen (14) days without
giving any reason.

The withdrawal period will expire fourteen (14) days from the day of the conclusion of the
agreement.

To meet the withdrawal deadline, it is sufficient for you to send your communication
concerning your exercise of the right of withdrawal before the withdrawal period has
expired.

(2) Effects of withdrawal

If you requested to begin the performance of services during the withdrawal period, you
shall pay us an amount which is in proportion to what has been provided until you have
communicated us your withdrawal from this contract, in comparison with the full
coverage of the contract.

4 Rights and obligations of Deutsche Post

(1) Besides its legal claims against the customer, Deutsche Post reserves the right to block
online access to the DHL Parcel DE Private Shipping application and/or acceptance of the shipment if the
customer uses the service contrary to the agreement.

(2) Deutsche Post can, in particular, refuse the use of e-mail addresses in the DHL Parcel DE Private Shipping
application if the system is unable to identify the customer (“10 minute mail”), if there is any
other doubt regarding the identifiability of the customer, or if there is a suspicion of misuse.

5 Customer’s rights and obligations

(1) The customer must keep available sufficient printing consumables in order that the
customer's printer can create print-outs with a minimum resolution of 300 dpi.

(2) After their printing, no changes may be made to the DHL Shipping Label. In particular, the
sender or recipient details may neither be deleted nor changed, for example.

(3) DHL Shipping Labels may not be combined with other postage types, e.g. postage stamps
(prohibition of hybrid franking). The use of additional DHL Shipping Labels for services (e.g.
bulky goods shipments) is permitted, but only in the event of posting and booking in Deutsche
Post or Deutsche Postbank retail outlets or agencies.

(4) The customer may only use the purchased DHL Shipping Labels for a transport order
between the sender and recipient printed on the DHL Shipping Label. The customer may only
use Coupons in order to purchase the specified number and value of the DHL Shipping Labels.
Resale is not permitted in either case.

(5) The customer undertakes to provide a permanent and customisable e-mail address for the
purchase via the DHL Parcel DE Private Shipping application, for which a deliverable postal address is
verifiably stored that clearly identifies the customer as the buyer.

(6) If the customer provides the recipient's e-mail address and/or telephone number when
placing the order, the customer guarantees that the customer is entitled on a legal basis (e.g.
by consent) to pass the e-mail address to Deutsche Post and its other associated companies
handling the transport services as set out in (1) – currently DHL Paket GmbH and DHL Express
Germany GmbH – for the purpose of communicating with the recipient concerning delivery of
the shipment in question and in order to meet statutory obligations (e.g. notification of
customs authorities).

(7) The customer may download the purchased DHL Shipping Labels or the purchased
Coupons within a period of 30 days of the conclusion of the agreement, quoting the shopping
cart ID. After this period the DHL Shipping Label or the Coupons can be sent to be customer by
e-mail on request.

(8) Purchased Coupons and DHL Shipping Labels are valid for three years starting at the end
of the year in which the Coupons or the DHL Shipping Labels were purchased. Campaign
coupons, for example from the bonus programme, have the individually stated period of
validity.

(9) If the customer has booked the pickup of a shipment, the pickup will be carried out at the
specified address by a deliverer of Deutsche Post or of its associated handling company as set
out in the relevant general conditions, and the shipment will either be handed over personally
by the customer or be taken from a specified storage location. This storage location should
generally be on the customer’s premises, in a dry place, protected from the weather, out of
sight of third parties, and with unhindered access for the delivery staff. The shipment must be
available at the specified storage location no later than 8:00 on the pickup date. Shipments to
be picked up must be sufficiently franked, packed, addressed, and labelled with the correct
Identcode.

6 Prices

(1) The applicable prices are those specified for the individual products in the DHL Parcel DE Private Shipping application at the time of ordering.

(2) Payment is made using one of the payment methods offered in the DHL Parcel DE Private Shipping application.

7 Liability

(1) Customer`s claim for damages for any given reason or claims for compensation for futile
efforts are excluded, unless they are caused by gross negligence or intent or a negligent
breach of essential contractual obligations (cardinal obligations); in the latter case, the extent
of liability will be limited to typically foreseeable loss or damage. Cardinal obligations are
obligations whose fulfilment is vital to the proper performance of the agreement and which
the contractual partner may normally expect to be honoured and/or obligations whose breach
would compromise the achievement of the purpose of the agreement

(2) The foregoing limitation of liability does not apply in the case of injury to life, limb, or
health; in the case of liability under the German Product Liability Act [Produkthaftungsgesetz];
or where Deutsche Post has, exceptionally, granted a guarantee.

8 Data protection

(1) The customer’s personal data will only be collected, processed or used if the customer has
given consent or if the EU General Data Protection Regulation (EU GDPR), the German Federal
Data Protection Act [Bundesdatenschutzgesetz, BDSG], the German Postal Act [Postgesetz,
PostG], or another statutory provision orders and permits it.

(2) If the customer uses DHL Parcel DE Private Shipping via Internet exchanges and sales platforms of
third parties (e.g. eBay, Amazon), not only will the customer’s contractual partner (seller or
buyer) be able to view the address and shipment data, but this data will also be available to
and stored by the operator of the website. In these cases, the use and storage of data is
therefore not entirely under the control of Deutsche Post. It is possible that data entered could
be further processed and stored on servers outside the European Union. Alternatively, if
customers do not agree to this, they will still be able to access and use DHL Parcel DE Private Shipping
directly via Deutsche Post’s own solution (website), using the link
http://www.dhl.de/onlinefrankierung.

9 Non-assignment clause and offsetting ban

(1) The customer may neither assign nor pledge claims against Deutsche Post with the
exception of monetary claims.

(2) Offsetting and retention in relation to claims of Deutsche Post are only permissible with
payable counterclaims which are undisputed, legally enforceable or ready for decision, or are
due to defects in the performance on which they are based.

10 Other provisions

(1) German law is applicable to all legal relationships of the contractual parties, to the
exclusion of the UN Convention on the International Sale of Goods.

(2) Bonn is the exclusive place of jurisdiction for legal disputes involving merchants, legal
persons under public law, or special funds subject to public law resulting from agreements
based on these GT&C.

(3) General duty to inform pursuant to Section 36 of the German Consumer Dispute
Settlement Act [Verbraucherstreitbeilegungsgesetz, VSBG]: Deutsche Post AG will not
participate in any dispute resolution process, as defined in the VSBG, concerning the products
and services covered by the agreement.

Version: 10.05.2022

Extension for Visual Studio Code to install DHL MCP Server ZIP - 34.47 KB

1.0.0

02.Sep.2024

Initial release of the redesigned DHL Private Customer Shipping EasyAPI