Dhl Shipping Knowledge Patch

DHL Shipping API compatibility

Load this skill when implementing, migrating, or reviewing integrations with DHL eCommerce Americas v4, DHL Location Finder, MyDHL API, or Parcel Germany Shipping v2. Identify the product first: their authentication, environments, account rules, resources, service identifiers, and data-use terms differ.

Reference index

Breaking changes, retirements, and deadlines

Retired Location Search Europe

Location Search Europe is decommissioned. Migrate to Unified Location Finder v1 and apply the documented response mappings. Several legacy fields have no Unified equivalent; see Discovery and locations.

Parcel Germany transport and schema changes

• Parcel Germany REST v2 remains active. GKV SOAP 1.x and 2.x are retired, and GKV SOAP 3.x reached its stated sunset on May 31, 2026.
• OAuth 2 uses the separately assigned Post & Parcel Germany Authentication API. Basic Auth with dhl-api-key remains a v2 alternative but is slated for removal in a future major version.
• officeOfOrigin is deprecated. Follow the corrected GET /labels, GET /manifests, shippingConditions, and product schemas.
• DHL Kleinpaket replaced Warenpost on January 1, 2025. Kleinpaket now requires Consignee.ContactAddress.country as an ISO 3166-1 alpha-3 code.

MyDHL cutoff-field migration

Versioned Shipment and Rates responses expose pickupCutoffSameDayOutboundProcessing through x-version as the replacement for GMTCutoffTime. Consumers should migrate field handling rather than treating the two names as unrelated cutoff values.

GoGreen label deadlines

• Remove the GoGreen logo by August 31, 2026, when GoGreen ends.
• Remove the existing GoGreen Plus logo by September 27, 2026.
• The new GoGreen Plus claim is optional. The service remains available for national outbound and return shipments.

Choose the correct API

MyDHL Service Point should not be substituted for another DHL division's location API. Its contract is specific to MyDHL.

Authentication and environment quick reference

eCommerce Americas

• Test at https://api-sandbox.dhlecs.com; use https://api.dhlecs.com in production.
• Labels and manifests do not cross environments. Verify production pickup access, products, capacity, account data, distribution centers, and allowed content categories separately.
• Network allowlists and TLS policy should be checked against the inbound/outbound IPs and supported TLS cipher versions published effective August 18, 2026.

Location Finder

• Call https://api.dhl.com/location-finder/v1 with an approved app key in DHL-API-Key.
• New access starts at 500 calls per day. Exhaustion returns HTTP 429; an app upgrade request is required for a higher limit.

MyDHL API

• Use pre-emptive HTTP Basic authentication with issued credentials.
• Test at https://express.api.dhl.com/mydhlapi/test; production is https://express.api.dhl.com/mydhlapi.
• Test credentials allow 500 service invocations per day.

Parcel Germany Shipping v2

• Obtain an OAuth 2 access token by sending the portal username/password and app key/secret to the Post & Parcel Germany Authentication API, then use Authorization: Bearer ....
• A production integration should use a non-interactive system user. Its portal password expires after 365 days; a personal user's expires after 90 days.
• A new API key may not work until 00:00 CEST.
• Test at https://api-sandbox.dhl.com/parcel/de/shipping/v2/; production is https://api-eu.dhl.com/parcel/de/shipping/v2/ and requires approval after successful sandbox use.

Compatibility and failure handling

eCommerce Americas clients

Within an API version, tolerate new optional request/query fields, added response fields, property reordering, new methods, and new resources. Use product codes, error codes, and event IDs as integration keys instead of mutable names or descriptions.

Error details are linked at https://api.dhlecs.com/docs/errors/<error-code>. Handle both independent 429 cases with queue-and-retry behavior: per-resource parallel-request Spike Arrest and account-specific weekly cross-resource Quota Violation.

MyDHL validation flow

Use Product for lightweight one-piece capability lookup. Rating adds account rates, value-added services, and estimated delivery. DHL recommends rating before shipment creation so only eligible products and services are submitted.

Requests undergo schema/cardinality validation and then business-rule validation; findings appear in the operation result message. JSON must not begin with a byte-order mark.

Parcel Germany request and warning behavior

• POST /orders and other array operations return entries in request order; even one request entry receives a one-entry response array.
• Use validate=true to validate fields and business rules without creating a shipment.
• Warning responses do not invalidate an accompanying label. Use mustEncode=true if label creation must require an encodable street.
• Omit a missing consignee phone or email, or send null; do not send whitespace.

High-value shipment rules

eCommerce Americas

• PLX is DHL Parcel International Expedited and does not support dangerous goods.
• Domestic-label customsDetails is only for APO, FPO, DPO, and non-continental US destinations; it should be omitted elsewhere.
• Use Manifest products to close out packages by selected product.
• Put optional deliveryInstructions in consigneeAddress.

MyDHL API

• Since version 3.3.0, pickup validation and Rates pickup capabilities use the shipper account number's cutoff, not only the origin or a generic schedule.
• A standardized packaging type code lets Rating and Shipment populate dimensions. addPiece works only before pickup or a recorded scan.
• Package dimensions must be positive and greater than 0.001.
• Validate shipment data without creating a label when needed.

Parcel Germany Shipping v2

• One physical parcel is one shipment; multipackage shipments are unsupported.
• The 14-character billingNumber combines the ten-digit EKP, two-character procedure/product, and participation. Support multiple billing numbers or participations.
• Created shipments can be canceled and recreated only until manifested. Manifested shipments cannot be changed.
• International parcels must be manifested before handoff.
• Do not scale labels; thermal formats assume 203 dpi.

High-value discovery rules

• Location Finder repeats of serviceType are AND conditions. parcel:pick-up-all and parcel:drop-off-all are query-only family meta-services and are not returned as service values.
• Use providerType=parcel to exclude Express locations.
• A syntactically valid but uncovered country can return 200 with no locations; an invalid country code returns 400.
• Direct shipment addressing is not for DHL Express and requires a location with a designated Postfiliale number in keywordId. Supply the recipient's email for pickup notification.
• Location Data must not be stored or modified. Its display and analysis terms are detailed in Access and operations.

High-value customs and document rules

• For eCommerce Americas PLT dangerous-goods categories 01–06 and 40, allow Canada and Mexico and reject other destinations.
• MyDHL declarable non-document shipments require exportDeclaration. Monetary, weight, duty, tax, and additional-charge values must be positive.
• Parcel Germany customs data is per parcel outside the applicable customs union. UK BT postcodes are treated as Northern Ireland/EU and need no customs data.
• MyDHL protected tracking data is masked and requires authorization.
• A MyDHL Customs Entry Document image requires the requester to be the Exporter of Record.

Use the indexed references for the complete field, code, eligibility, rendering, retention, and lifecycle rules.