Download the PHP package ecommerce-utilities/dhl-api without Composer

DHL-API

Use at your own risk - parents are responsible for their children!

Composer

composer require ecommerce-utilities/dhl-api *

Shipment Tracking Unified Push

The push API uses the API key from the DHL Developer Portal. It does not use the OAuth token for the DHL business customer portal.

The validation message sent to the webhook contains the subscription ID and its hook secret. Use both to activate the subscription:

Batch subscriptions and daily quota

DHL documents 1 to 10 tracking numbers per subscription request in SubscriptionShipmentIds.shipmentIDs of its Unified Push OpenAPI specification v1.2.5 (checked 2026-09-26). The maximum is stated in the property's description, not as a machine-readable maxItems constraint. The library exposes this limit as DHLPushSubscriptionService::MAX_SHIPMENT_IDS_PER_REQUEST.

createShipmentSubscription() still sends exactly one request and returns one subscription response. More than ten IDs, missing required input or invalid IDs now raise DHLRequestValidationException (a DHLApiException) locally, before any API call. For larger lists, iterate the new batch method:

The generator sends requests only while it is iterated, with ten IDs per request except for a smaller final batch. It validates the complete input before the first request, preserves ID order and leading zeros, and makes no requests for an empty list. Errors stop iteration without retrying; already yielded results remain available to the caller. Persist each result inside the loop rather than collecting all results with iterator_to_array(). An interrupted/failed HTTP request may already have created a subscription: reconcile it before retrying and never replay the complete list blindly.

Each batch still requires its own activation call. For N shipments, budget at least 2 * ceil(N / 10) outgoing API calls (creation plus activation). A quota of 500 calls/day therefore allows at most 2,500 new shipments/day with full batches, before additional lookups, deletions or retries. At 8,000 shipments/day, at least 1,600 calls are needed. Incoming webhook messages do not consume this outgoing-call quota. See the DHL access form and activation workflow.

The batch method does not collect numbers across separate calls, enforce the daily quota or activate subscriptions automatically. Consumers such as ShopOffice must aggregate pending shipments, map all batch members to the shared subscription ID, activate each subscription only once, and reserve quota for activation and retries. For durable queues that must reserve a batch before the HTTP request, use array_chunk($trackingNumbers, DHLPushSubscriptionService::MAX_SHIPMENT_IDS_PER_REQUEST) and call createShipmentSubscription() for each reserved batch.

Example:

Shipment labels via REST API

Supported outbound shipment features:

• Postal recipient addresses
• DHL Packstation addresses
• DHL Postfiliale addresses
• Cash on delivery (DHLCashOnDeliveryService)
• Named person only (DHLNamedPersonOnly)

DHLOAuthCredentials now contains the business customer portal login, the developer portal API key/secret, the environment flag, and optionally the receiverId for returns use cases. The current setup flow is:

1. Create DHLOAuthCredentials
2. Create DHLHttpClient
3. Create DHLOAuthTokenProvider
4. Inject those dependencies into DHLRetoureService or DHLShipmentService

For DHL Returns in sandbox, use the sandbox user plus receiverId = 'deu'. The developer portal appName is not part of the OAuth token request.