↑↓ selectEnter openEsc close

    1. Elbuz
    2. Delivery services in Elbuz

    DHL API in Elbuz: DHL Paket waybills, Packstation, cash on delivery and statuses

    6 min readUpdated

    Elbuz connects to the DHL API under your DHL Paket contract in Germany and creates waybills from the order card. Parcels go to an address, Packstation or Postfiliale; statuses update every 10 minutes.

    When you need this:

    • Your store in Germany ships with DHL Paket — a waybill from the order, no Geschäftskundenportal.
    • The customer asks for a Packstation or Postfiliale — number and Postnummer go in one field.
    • Payment on delivery — Nachnahme within Germany in euros, paid to your IBAN.
    • Parcels abroad — DHL Paket International, Europaket or Warenpost International, per your Abrechnungsnummer.

    Where to start: get an API key on developer.dhl.com → enter the credentials in Elbuz.

    What DHL Paket does in Elbuz

    • Connection — Geschäftskundenportal sign-in, an API key, the Abrechnungsnummer and the DHL sandbox.
    • Waybill from the order — within Germany and abroad, to an address, a Packstation or a Postfiliale.
    • Cash on delivery (Nachnahme) — the amount from the order, transferred to your IBAN.
    • Label — a PDF at any time by the waybill number.
    • Parcel statuses — every 10 minutes; order statuses change according to your code table.

    How to connect the DHL Paket API

    What to get from DHL

    WhatWhere to get it
    API keyOn developer.dhl.com, the “Get Access” button creates an app with Parcel DE Shipping and issues an API Key and an API Secret. You don't need to request OAuth2 sign-in (Authentication API) separately — DHL enables it together with Shipping. For statuses, add Shipment Tracking – Unified to the same app: DHL reviews the request, usually in 2–5 business days
    Login and passwordA Geschäftskundenportal user. DHL recommends a separate system user (System user) from the “Benutzer verwalten” section: it can't sign in to the interface, and its password is valid for 365 days
    Abrechnungsnummer14 characters: EKP (10 digits) + procedure (2) + participation (2). For DHL Paket within Germany the procedure is 01; abroad — 53 (DHL Paket International), 54 (Europaket) or 66 (Warenpost International). Procedures come with your DHL contract: if the one you need is missing, contact your DHL sales representative. The numbers are in the contract and in the portal: “Versenden → Einstellungen → Nutzergruppen”

    The DHL portal and API are free. DHL opens production access manually, after checking your integration in the sandbox.

    What to enter in Elbuz

    Where: External services and integrations → Delivery → “DHL Paket (Deutschland)”.

    FieldWhat to enter
    “Active”On — otherwise the DHL waybill won't open
    “User”, “Password”Geschäftskundenportal login and password
    “Token”The API Key of the developer.dhl.com app
    “App API Secret (developer.dhl.com)”The API Secret of the same app. With it, Elbuz signs in to DHL via OAuth2. Empty — the old sign-in with login and password: it still works, but DHL will remove it in the next API version
    “Billing number: within Germany (14 characters)”The number with procedure 01
    “Billing number: international (14 characters)”The number with procedure 53, 54 or 66 — it defines the product; without it, waybills abroad aren't created
    “User profile (Gruppenprofil)”The user's group profile in the portal; STANDARD_GRUPPENPROFIL by default
    “IBAN for cash on delivery”, “Account holder for cash on delivery”The account DHL transfers Nachnahme to
    “Sandbox environment”Turn it on to test without a contract (sandbox)
    “Sender” blockCompany, contact person, country as an ISO code (empty — DE), postcode, city, street, house number, phone, email
    DHL Paket connection form with credentials, DHL Paket settings and sender block
    1User and Password
    2Token
    3App API Secret
    4Billing numbers
    5IBAN and account holder
    6Sandbox environment
    7Sender block
    1. User and Password — your Geschäftskundenportal sign-in.
    2. Token — the API Key from developer.dhl.com.
    3. App API Secret — the secret of the same developer.dhl.com app.
    4. Billing numbers — 14-character numbers for domestic and international shipments.
    5. IBAN and account holder — bank details for cash on delivery.
    6. Sandbox environment — switches requests to the DHL test environment.
    7. Sender block — the company and address the parcels ship from.

    The form saves itself as soon as you change a field. After saving, “Password” and “Token” show dots, and an empty field doesn't erase the key. Elbuz doesn't check the credentials on save — the first waybill will show any error.

    DHL sandbox

    You can test the integration without a contract. Turn on “Sandbox environment” and enter the test data from the DHL reference:

    • “User” — user-valid, “Password” — SandboxPasswort2023!;
    • “Token” — your API Key, “App API Secret” — your API Secret;
    • Abrechnungsnummer within Germany — 33333333330101, international — 33333333335301.

    Waybills go to the DHL sandbox, and nothing is actually shipped. Before going live, turn the switch off and enter your own credentials.

    How to create a DHL Paket waybill from an order

    The general procedure for all carriers is in how to create a waybill from an order.

    Where: an order card with the “DHL Paket (Deutschland)” delivery method → “Delivery” section → “Create waybill”.

    What the form fills in and what to check

    FieldSourceWhat to check
    Last name, First name, Phone, E-MailOrderName, city and postcode are required
    Postcode, City, Street, House, ApartmentThe order's delivery address: the whole address goes into “Street”, “House” and “Apartment” stay emptyStreet — up to 50 characters, house with apartment — up to 10; Elbuz trims anything longer
    Country (ISO code: DE, FR, IT, ES…)The order's delivery countryNot recognized — the sender's country
    Pickup point codeThe point from the orderFor a Packstation — “station number/Postnummer”, for a Postfiliale — “Postfiliale number/Postnummer” (Packstation and Postfiliale)
    Total weight, kgWeight of the order's productsNo weight in the products either — 1 kg is sent; DHL Paket — up to 31.5 kg
    Length, Width, Height, cmEmptySent only if all three are filled in
    Return delivery (recipient)“Money” if the order is unpaid and paid on deliveryWithin Germany only (Nachnahme)
    Waybill creation form for DHL Paket with recipient, address and shipment options
    1Pickup point code
    2Country
    3Total weight
    4Return delivery
    5Create waybill
    1. Pickup point code — a Packstation or pickup point code; empty for home delivery.
    2. Country — two-letter ISO code of the destination.
    3. Total weight — parcel weight in kilograms.
    4. Return delivery — the recipient's return option.
    5. Create waybill — sends the request to DHL (not pressed in the shot).

    Which DHL product Elbuz picks

    Sender and recipient in Germany — DHL Paket (V01PAK) with the “within Germany” Abrechnungsnummer. Otherwise the product comes from the procedure in the “international” number (characters 11 and 12): DHL itself matches the product against these digits.

    ProcedureProductWhat for
    53DHL Paket International (V53WPAK)Parcels to consumers worldwide
    54DHL Europaket (V54EPAK)Business customers only (B2B), mostly EU countries
    66Warenpost International (V66WPI)Small items via postal networks

    With another procedure in the “international” number, the waybill isn't created (troubleshooting). Outside the EU customs union (CH, GB, NO, UA) DHL requires customs data that Elbuz doesn't send: create such waybills in the Geschäftskundenportal.

    Recipient countries: AT, BE, BG, CH, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IT, LT, LU, LV, MT, NL, NO, PL, PT, RO, SE, SI, SK, UA. For others the app replies “DHL: unsupported country”.

    Parcel dimensions according to the DHL reference — from 15×11×1 to 120×60×60 cm.

    Packstation and Postfiliale

    In “Pickup point code”, enter the station number and the recipient's Postnummer separated by a slash, for example 118/12345678. The station number is three digits, the Postnummer is 6–10 digits from the customer's DHL account. With a pickup point code the street isn't needed, but the station's postcode and city are required.

    For a Postfiliale, enter Postfiliale 518/12345678: the post office number is 401 to 999. You can leave out the Postnummer (Postfiliale 518) if the order has the customer's e-mail: DHL will notify them when the parcel arrives.

    Orders from an Elbuz CMS store arrive with the code ready. In an older order where only the number was saved, complete the code once.

    The app won't send any other format (troubleshooting). Packstation and Postfiliale are available in Germany only.

    What happens after “Create waybill”

    1. Elbuz checks the data before it reaches DHL. If the Abrechnungsnummer of the needed type or the sender address is missing, you get a message with the reason, and no waybill is created.
    2. DHL creates the shipment. The parcel number goes into “Delivery service: number”, and “Waybill created, No.‹number›” appears.
    3. The order number goes into the waybill as the reference; if it's shorter than 8 characters, it's padded with zeros on the left, because DHL accepts 8 or more.
    4. If DHL refuses, the window shows its text — in German, with the name of the field it rejected.

    The waybill is created at once and charged under your DHL contract. You can't cancel it from Elbuz — only in DHL and only before the daily closing (Tagesabschluss): 17:45 by default or the time set in the portal. After canceling, clear “Delivery service: number” in the order to create a new one.

    DHL cash on delivery (Nachnahme)

    In the waybill form, choose “Return delivery (recipient)” → “Money” and check the amount. An unpaid order paid on delivery already has “Money” and the order amount. DHL receives the amount in euros, with the order number as the payment reference.

    DHL accepts Nachnahme only in euros. Elbuz won't send an order with “Money” in another currency: “DHL accepts cash on delivery only in euros (EUR), but the order currency is UAH…”. Change the order currency to EUR or choose “Not required”.

    • Within Germany only: for abroad — “DHL: cash on delivery is available only inside Germany”.
    • Without an IBAN and account holder in the connection — “DHL: IBAN and account holder for cash on delivery are required (API settings)”.

    Under DHL's terms, Nachnahme costs €7.49 excluding VAT on top of the parcel price, the amount is up to €3,500, and the money usually arrives in 1–2 business days.

    How to print a DHL label

    Where: order card → “View waybill” → print icon; or “Shipments” → row → “Print waybill”.

    The label is a PDF in a new tab. Elbuz fetches it from DHL by the parcel number every time, so you can reprint it whenever you need.

    You can't call a DHL courier from Elbuz: the DHL waybill has no “Courier pickup” block.

    How Elbuz tracks DHL parcels

    Every 10 minutes Elbuz asks DHL about parcels with the same API key — up to 100 waybills per run. It tracks orders from the last 60 days and orders in the checked statuses until the parcel reaches the “Delivered” state. The DHL status code and text are shown in the order and in “Shipments”; the “Track on carrier site” button opens the dhl.de page with the number.

    A starter Shipment Tracking key allows 250 requests a day and no more than one every 5 seconds. When the limit runs out, Elbuz stops the run and checks the remaining parcels next time — statuses update slowly. If you ship more than a few parcels a day, click “Request Upgrade” on the API page.

    How to change order statuses by DHL codes

    The app doesn't know DHL codes by itself: while the table is empty, the parcel has the “Unknown” state in “Shipments”, and order statuses don't change.

    1. In the DHL connection, in the “Order statuses for which to check the parcel status with the delivery service” block, check the statuses in which an order waits for delivery, for example “Shipped”.
    2. In the “Notification settings” block, open “Delivery statuses” (and “Order statuses”, “Payment statuses” if needed).
    3. The DHL codes from the table below are already in the “Code (name) on site (API)” column; add your own comma-separated.
    DHL codes for the “Delivery statuses” window
    Your delivery statusDHL codeState in “Shipments”
    Awaiting senderpre-transitCreated
    On the waytransitIn transit
    DelivereddeliveredDelivered, polling stops

    Without the delivered code next to “Delivered” in “Delivery statuses”, the parcel won't reach the “Delivered” state, and Elbuz keeps asking about it after handover, taking up space in the limit of 100 waybills per run.

    Delivery statuses window with DHL status codes next to status names
    1Code column
    2Delivered
    3Empty code
    1. Code (name) on site (API) — the status code DHL returns.
    2. Delivered — matched to the delivered code.
    3. Refused — left empty because DHL does not report this status separately.

    DHL has two more codes: failure — a delivery failure — and unknown. Leave them out of the table: such a parcel gets the “Unknown” state, and you'll notice it. How the three status tables work is explained in the article on automatic order status changes.

    Scenarios

    Test before signing a contract

    Get a key on developer.dhl.com, enter the DHL test data and turn on “Sandbox environment”. Create a waybill for one of your orders and print the label. Once the contract is signed, enter your own credentials and turn the switch off.

    The customer wants a Packstation or Postfiliale

    In the waybill form, enter a “Pickup point code” like 118/12345678 or Postfiliale 518/12345678, plus the postcode and city of the station or post office. You can leave the street as it is — DHL won't receive it.

    An order to Austria

    Check that “Country” = AT in the form and that the “international” Abrechnungsnummer is filled in. The product comes from this number; with procedure 53 it's DHL Paket International. “Return delivery” — “Not required”.

    What to do when something goes wrong

    Common problems
    What you seeWhyWhat to do
    “The delivery service is not connected: fill in its API settings (System settings → Other settings → External services and integrations).” Neither the password nor the key is entered, or “Active” is off Fill in the credentials and turn on “Active” (what to enter)
    “DHL: portal login, password and API key are required (API settings)” One of the three fields — “User”, “Password”, “Token” — is empty Fill in all three
    “DHL: billing number (14 characters) is required for domestic shipments (API settings)” (or international) The Abrechnungsnummer of the needed type is empty or incomplete Enter 14 characters without spaces (Abrechnungsnummer)
    “DHL OAuth: Unauthorized API Authentication failed: Invalid client identifier” The API Key in “Token” and the API Secret come from different apps, or the app has no access to this environment Copy both keys from the same app on developer.dhl.com; for production, keep the sandbox switch off
    “DHL: international billing number must be for procedure 53…” The “international” field holds a number of another product, for example with procedure 01 Enter a number with procedure 53, 54 or 66 (product)
    “DHL: pickup point code must be «station number/Postnummer»…” “Pickup point code” has a different format, for example only the station number without the Postnummer Enter 118/12345678 or Postfiliale 518/12345678 (Packstation and Postfiliale)
    “DHL: a Postfiliale needs the Postnummer…” The Postfiliale code has no Postnummer, and the order has no customer e-mail Add the Postnummer: Postfiliale 518/12345678, or add an e-mail to the order
    “DHL: cash on delivery is available only inside Germany” “Money” on a parcel going abroad Choose “Not required”
    “DHL accepts cash on delivery only in euros (EUR), but the order currency is …” An order with “Money” isn't in euros Change the order currency to EUR or choose “Not required” (Nachnahme)
    “DHL: unsupported country” The recipient's or sender's country isn't on Elbuz's DHL list Check the code in “Country” (list of countries)
    DHL statuses update slowly The starter Shipment Tracking key limit Ask DHL to raise the limit (key limit)
    A DHL parcel in “Shipments” with the “Unknown” state The DHL code isn't in the “Delivery statuses” window Add the code (DHL codes)

    FAQ

    How much does the DHL integration cost in Elbuz?

    Elbuz charges nothing for DHL waybills, labels and statuses, and the DHL API is free. You pay DHL for parcels and Nachnahme under your contract.

    Can I connect DHL without a DHL Paket contract?

    Only the sandbox: an API key and the DHL test user. Real waybills need a contract, a Geschäftskundenportal sign-in and an Abrechnungsnummer (sandbox).

    Is the API Secret required?

    No, without it Elbuz signs in to DHL with login and password, as before. But DHL will remove that sign-in in the next API version, so add the API Secret in advance — no separate request to DHL is needed (what to enter).

    Can I collect cash on delivery in hryvnias or złoty?

    No, DHL accepts Nachnahme only in euros. The order must be in EUR (Nachnahme).

    Can I call a DHL courier from Elbuz?

    No, courier pickup isn't connected for DHL Paket. Book a pickup with DHL.

    How do I cancel a DHL waybill?

    Only in DHL, before the daily closing (Tagesabschluss). Then clear “Delivery service: number” in the order (after creation).

    Can I ship DHL to a post office (Postfiliale)?

    Yes, enter Postfiliale 518/12345678 in “Pickup point code”. Without the Postnummer, the order needs the customer's e-mail (Packstation and Postfiliale).

    How is DHL Paket different from DHL in Poland?

    They're different services with different accounts: DHL Paket is for contracts with DHL in Germany, and DHL Parcel Polska is a separate entry, DHL Parcel (Poland, DHL24).

    Where it is and who has access

    Menu
    Account → System settings → “Other settings” → “External services and integrations” → Delivery → DHL Paket (Deutschland)
    Other entry points
    Directories → Documents → Shipments → “Delivery services”; order card → “Delivery” section
    Access right
    connection — “API & access tokens”; waybill — the “Delivery waybill creation” window
    Prepare
    a DHL Paket contract, a Geschäftskundenportal user, an API key from developer.dhl.com
    1. Get an API keydeveloper.dhl.com
    2. Enter the credentials, Abrechnungsnummer and senderExternal services and integrations → DHL Paket
    3. Enter the DHL status codesSame place, “Notification settings”
    4. Create a waybill and print the labelOrder card, “Delivery” section

    Related topics

    Was this article helpful?

    Missing a feature? Tell us.

    We will add it for free if other users need it too.

    If only you need it, we will agree on it separately.

    Article contents

    Suggest an improvement

    Try Elbuz free