Migrating DHL SOAP v3 to Parcel DE API V2

Migrating DHL SOAP v3 to Parcel DE API V2

If you're still calling the SOAP v3 Business Customer Shipping API for DHL Parcel DE, it's dead. DHL confirmed it directly: "the legacy version 3 of the SOAP Business Customer Shipping API will no longer be supported as of May 31, 2026. After this date, no shipments can be created and no shipping labels can be generated via this interface." Today is July 21, 2026. That means every integration engineer reading this is either finishing the DHL Parcel DE Shipping API migration or firefighting a broken production pipeline that stopped issuing labels seven weeks ago. This guide covers both cases: the clean migration path and what to do if you're already past the DHL SOAP API shutdown.

Why this migration couldn't wait

DHL didn't spring this on anyone. The GKV SOAP v2 predecessor was killed off in May 2025, and DHL flagged the v3 sunset a year in advance, noting "we will also discontinue the development of version v3 of the Geschäftskundenversand SOAP API. This version will be decommissioned May 31, 2026." The final reminder emails went out in the weeks before the deadline, and the production DNS switch for api-eu.dhl.com was scheduled between "22-29 June, 2026". If you were relying on the old endpoint still quietly working past the announced date, that grace period is now gone too.

The Returns side got the same treatment on the same date. DHL's own notice states: "the legacy version of the Returns API (under cig.dhl.de) will no longer be supported as of May 31, 2026. After this date, no returns can be created and no return labels can be generated via this interface. If you have integrated the mentioned API directly into your system, we recommend that you transition to the new DHL Parcel DE Returns API (under api-eu.dhl.com) as soon as possible." Two separate legacy interfaces, one deadline, one migration project if you're doing this properly.

There's a second, smaller wave coming that teams routinely miss because it doesn't break anything immediately: "the specifications and the Common Label Specification have been updated, as the GoGreen service will be discontinued as of August 31, 2026... Customers should note the following changes regarding the shipping label: GoGreen logo: Removal by August 31, 2026, at the latest." If your label templates or request payloads hard-code GoGreen logo flags, budget a small follow-up ticket for late August.

Before you start: what you need

Don't open the DHL API Developer Portal cold. Get these lined up first:

• An app in the DHL API Developer Portal with a client_id/client_secret pair, added to both the "DHL Parcel DE Shipping" and "DHL Parcel DE Returns" products.
• Your Post & DHL Business Customer Portal login — the REST API still ties back to a business customer account and billing numbers, same as SOAP did.
• Sandbox test credentials for the transition period: DHL documents Basic Auth as "Basic Auth (Username: 'user-valid', Password: 'SandboxPasswort2023!') for authentication and additionally provide your API key (take it from the firstly generated APP) as request header information ('dhl-api-key')", though this is explicitly a bridge, not a destination — more on that below.
• Your current SOAP v3 mapping documented: product codes (V01PAK, V54EPAK, and the retired V62WP if you're still on Warenpost instead of DHL Kleinpaket), service flags like printOnlyIfCodable, and any GoGreen billing numbers.
• A decision on scope. If DHL is one carrier among several — GLS, DPD, UPS — in your stack, consider whether this migration belongs in a dedicated carrier-adapter layer rather than woven through order management code. Platforms like Cargoson, EasyPost, or nShift let you isolate a single carrier's breaking change instead of touching every calling service.

The migration steps

1. Inventory your SOAP v3 exposure. Grep your codebase, config, and access logs for the old WSDL endpoint and any calls to cig.dhl.de. List every product code and service flag actually in use — you'll need this list when you rebuild the equivalent REST payload, and it's the fastest way to catch dead code paths nobody remembers writing.
2. Confirm your app has both new products enabled. In the developer portal, verify "DHL Parcel DE Shipping" and "DHL Parcel DE Returns" are both attached to your app, not just Shipping. Teams migrating shipment creation often forget Returns runs on a separate product grant with its own sandbox toggle.
3. Get an OAuth2 token in sandbox. DHL's REST API defaults to OAuth2 with Basic Auth offered only as a fallback: "Introduction of the authentication method OAuth2 parallel to the current Basic Auth. Later API versions will no longer support Basic Auth." Request a token using the ROPC flow against the sandbox authentication endpoint documented in the Authentication API reference, passing your sandbox username and password as grant_type=password parameters.
4. Re-point your base URL to the naming convention DHL uses across all REST products — pattern is api-eu.dhl.com/parcel/de/shipping/v2/ for orders and manifests. Don't assume the old SOAP endpoint host resolves anywhere useful anymore; the DNS cutover already happened.
5. Rebuild shipment creation against POST /orders. This single call replaces createShipmentOrder from the SOAP interface and returns labels, tracking numbers, and documentation in one response. Before you wire it into production logic, DHL's own advice is blunt: "PLEASE use the validation switch available for POST /orders. It will tell you if you are missing required elements, mistyped an attribute name and more." Treat every 400 from validation mode as a blocking error to fix, not a warning to log and ignore.
6. Migrate Returns separately, on its own timeline. The new Returns API isn't a drop-in replacement for the old Retoure endpoints; it changes structure and adds a locations lookup. DHL lists the concrete improvements: "Secure authentication method (OAuth2). Harmonization of request and response structures to optimize usage. Retrieve available return locations for your account through the new service /locations. Response for international returns, including international shipping numbers." Pull your drop-off location logic from /locations rather than a hard-coded list, and switch return-label auth to OAuth2 alongside the shipping side rather than leaving one flow on Basic Auth indefinitely.
7. Update label parameters ahead of the GoGreen cutover. Confirm nothing in your integration depends on the retiring logo flag, and start capturing the new UUID field DHL added to responses: "The response now additionally includes the shipment UUID. The UUID is a unique identifier of a shipment and can be used for clear identification within maintenance processes in the Shipping API." Store it — support tickets referencing the old shipment number alone are about to get harder to resolve quickly.
8. Run a parallel diff in sandbox. Fire the same logical shipment (same weight, same product, same customs data) at the new /orders endpoint and compare the resulting label PDF, tracking number format, and any error payload structure against your last known-good SOAP output. Small differences in error schema are common; DHL notes "for some technical errors, the structure of the error message deviates from the structure described in the YAML" as a known open issue, so don't hard-code exact error-body parsing against the OpenAPI spec without a fallback.
9. Cut over production behind a feature flag, watching two things closely: error rate on /orders calls, and OAuth2 token refresh timing. ROPC tokens expire; if your refresh logic fires late, you'll see a burst of 401s that looks like a DHL outage but is actually your own token lifecycle bug.

How you know it worked

Three checks, in order of speed:

• Your OAuth2 token request returns a bearer token and expires_in without error. A quick getVersion-style connectivity check against the base path confirms the endpoint is live: DHL describes it as helping you check connectivity and confirm the running version, with "this helps you as a quick connectivity check and also tells you the current version number. Part of the response is like 'version': 'v2.0.2'."
• A production call to POST /orders returns 200 with a tracking number, label document, and the new shipment UUID populated.
• Zero calls to the old SOAP endpoint or cig.dhl.de appear in your logs 24-48 hours after cutover. If you still see traffic there, something in your stack — a cron job, a retry queue, a forgotten microservice — didn't get the memo.

Failure mode: mixed goods categories on Europaket

One error trips up nearly every team moving international or mixed-cargo shipments to the REST API. DHL's own troubleshooting notes call it out directly: "Likely you are getting the error message when sending an Europaket V54EPAK with more than one goods categories per packet. This product allows only a single goods category (defined by the attribute 'hsCode')." The SOAP interface tolerated looser customs grouping in practice; the REST validation is stricter. The fix isn't a retry — it's a data model change: split any shipment carrying mixed HS codes into separate orders before calling /orders, one goods category per Europaket shipment. Retrying the same payload with backoff will just burn your rate limit for a request that will never succeed.

More generally: don't apply retry-with-backoff logic to anything the validation switch flags as a 400. Reserve retry logic for 5xx responses and timeouts. A malformed hsCode or an unknown service combination isn't transient — DHL's guidance on unknown-service errors is explicit that "the error message when requesting a service which is either not known (check with validate=true please) or your account number + billing number information is not enabled for the service... reach out to your DHL contact to check that." That's a configuration fix, not a network blip.

If you missed the deadline

If it's already past May 31, 2026 and your production labels stopped generating, you don't have a slow-migration problem anymore — you have an outage. Don't try to file a support ticket asking DHL to re-enable SOAP v3; the shutdown was announced roughly a year ahead of time and DHL's messaging was consistent that no exceptions would be made. Your fastest path is the same nine steps above, compressed: get OAuth2 working in sandbox same day, validate your highest-volume product code and service combination first (usually standard domestic parcel, V01PAK), get that one path into production behind a flag within 24-48 hours to stop the bleeding, then backfill Returns and edge-case products afterward. If you're running a third-party platform rather than a direct integration — JTL, Xentral, a shop plugin — your first move is checking whether your vendor already shipped REST support; several, including plentymarkets and Adobe Commerce's DHL extension, moved their underlying SDK to the new sdk-api-parcel-de REST wrapper well ahead of the deadline.

Where this fits in a multi-carrier stack

DHL isn't the only carrier forcing this kind of cutover this year. UPS moved first: "UPS was the first to phase out its legacy APIs in 2025... Mid 2023: UPS rolled out a major update to its API infrastructure, transitioning from old access keys to a more secure OAuth 2.0 model. Summer 2025: UPS sunset its legacy access key authorization for all APIs." FedEx and USPS are running parallel timelines through 2026, per ShipperHQ's tracking of carrier API changes. If you're maintaining direct adapters for DHL, DB Schenker, GLS, and UPS simultaneously, each carrier's OAuth2/REST cutover is its own project with its own deadline, its own quirks, and its own version of the Europaket error above waiting to surprise you. That's the real argument for consolidating carrier connections behind a multi-carrier layer — Cargoson, EasyPost, Sendcloud, or ShipStation all absorb this category of carrier-side breaking change into a maintained connector rather than requiring your team to run N separate migration projects on N separate deadlines. Whether that trade-off is worth it depends on how many direct carrier integrations you're carrying and how much engineering time you want spending on OAuth2 token lifecycles instead of your own product.

Either way, start a deprecation changelog now if you don't have one — DHL, UPS, FedEx, USPS. This is a recurring maintenance category, not a one-off you get to forget about after this migration ships.