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 | Reference | Topics | |---|---| | [Access and operations](references/access-and-operations.md) | Product scope, authentication, environments, quotas, compatibility, migration, and usage restrictions | | [Discovery and locations](references/discovery-and-locations.md) | Product Finder, Location Finder searches and filters, service identifiers, response fields, and shipment addressing | | [Shipment, labels, and manifests](references/shipment-labels-and-manifests.md) | Shipment inputs, pickup, labels, closeout, returns, lifecycle, and Parcel Germany response behavior | | [Customs, rating, and dangerous goods](references/customs-rating-and-dangerous-goods.md) | International rules, rates, landed cost, customs codes, invoice data, and dangerous goods | | [Tracking and documents](references/tracking-and-documents.md) | Tracking fields, image types, invoice upload, piece-to-label linkage, and document retrieval | ## 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](references/discovery-and-locations.md). ### 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 | Product | Supported integration scope | |---|---| | eCommerce Americas v4 | Discovery, duty and tax calculation, labels, manifests, tracking, and returns for domestic and international packages originating in the United States or Canada | | Location Finder v1 | GET-only lookup by address, coordinates, location ID, or `keywordId` | | MyDHL API | DHL Express product/rating, shipment, pickup, tracking, invoice, image, reference-data, and service-point operations for an active DHL Express customer account | | Parcel Germany Shipping v2 | Labels and export documents for goods shipments originating in Germany for eligible Post & Parcel Germany business customers | 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](references/access-and-operations.md). ## 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.