Ellipse Gradient for Header

DHL Integration Guide

Connect DHL shipping, rating, pickup, tracking, and document services with enterprise applications through REST APIs, selected tracking notifications, and Martini workflows.

DHL integration options at a glance

DHL provides product- and region-specific REST APIs for shipment creation, rates and quotes, pickup booking, tracking, delivery status, address validation where available, and shipping documents. Selected DHL products also support push-style tracking notifications, while older DHL Express services may expose legacy SOAP or XML interfaces. Authentication varies by API and can include API keys, subscription keys, HTTP Basic Authentication with an API key and secret, or product-specific OAuth 2.0. Martini can consume the applicable DHL API, receive supported tracking notifications, transform shipment and tracking data, orchestrate retries and validation, and pass labels or customs documents to downstream systems.

Integration pointSupported by DHL?Common use casesHow Martini supports it
REST APIsYesDHL publishes current REST APIs for shipment creation, rating, pickup booking, tracking, delivery status, and shipping documents, depending on the business unit and product.Martini can consume the selected DHL REST API from workflows, apply product-specific authentication, map requests and responses, and expose normalized APIs to internal applications.
Webhooks / outbound callbacksLimitedSelected DHL products support push-style tracking notifications for selected shipment events; coverage varies by product, country, and account configuration.Martini can expose an API endpoint or receive webhook-style requests, acknowledge promptly, deduplicate events, and process them asynchronously through workflows.
SOAP APIsLegacyHistorical DHL Express integrations may use XML or SOAP-style services when a current REST alternative is unavailable or DHL explicitly requires the legacy interface.Martini can consume SOAP services and transform XML payloads, but new integrations should generally use the applicable DHL REST API.
File / attachment APIsLimitedShipment responses may include labels, invoices, waybills, or other shipping documents as encoded content or document references; DHL does not provide a confirmed general-purpose file repository API.Martini can decode, preserve, transform, store, or forward DHL documents while retaining their MIME type, file name, encoding, and document type.
AuthenticationYesDHL API products may require developer-portal credentials, API keys, subscription keys, HTTP Basic Authentication with an API key and secret, or product-specific OAuth 2.0.Martini can keep credentials and account identifiers in environment configuration or secrets and apply the authentication scheme required by the selected DHL API.
Scheduled synchronizationYesPolling is useful for tracking synchronization, reconciliation, and products where push-style tracking notifications are unavailable or incomplete.Martini can schedule workflows, maintain a checkpoint or date window, control request rates, and retry transient failures.
Bulk / asynchronous APIsNot confirmedNo general-purpose DHL bulk or asynchronous API was confirmed, although some requests may contain multiple packages or shipment items.Martini can implement controlled batching, scheduling, pagination, and rate management around the documented behavior of the selected DHL API without assuming a universal bulk endpoint.
Database / analytics accessNot confirmedNo direct DHL customer database or general-purpose analytics database access was confirmed.Martini can retrieve operational information through the applicable DHL APIs, tracking interfaces, reports, or customer-specific export facilities where available.

How DHL exposes data and business events

DHL REST APIs

REST is DHL's primary documented integration mechanism for current developer products. Depending on the DHL division and region, REST operations can create shipments, obtain rates, book pickups, retrieve tracking and delivery status, validate shipment data, and return labels or other shipping documents.

Martini implementation pattern

Martini implementation pattern: a workflow receives an internal order, fulfillment, rating, or pickup request, validates required fields, applies the product-specific DHL authentication scheme, calls the selected REST endpoint, maps the response, and persists DHL identifiers and documents. Reusable workflows can expose a normalized internal API while isolating DHL product variations.

Implementation sequence

Receive a shipment, rating, pickup, or tracking request
Validate addresses, packages, customs data, and required account fields
Apply the selected DHL API credentials from environment secrets
Call the applicable DHL REST endpoint
Map the DHL response to the internal canonical model
Persist the waybill, status, document, or quote result

DHL Tracking Notifications

Selected DHL products provide push-style tracking notifications for selected shipment events. Coverage depends on the DHL product, country, account, and configured event set, so notifications should not be assumed for every DHL object or status.

Martini implementation pattern

Martini implementation pattern: expose a controlled API endpoint for supported DHL notifications, acknowledge promptly, and hand the payload to an asynchronous workflow. The workflow validates and normalizes the event, deduplicates it against polling data where necessary, and updates downstream order, service, or warehouse systems.

Implementation sequence

Receive the DHL tracking notification
Validate the inbound request and capture the raw event
Acknowledge the notification promptly
Normalize the waybill, event code, timestamp, and location
Deduplicate the event against stored tracking history
Update downstream shipment or case systems

DHL SOAP and XML Services

DHL has historical XML and SOAP-style services, particularly for older DHL Express integrations. These interfaces are legacy or product-specific and should generally be replaced with the applicable REST API for new implementations when available.

Martini implementation pattern

Martini implementation pattern: when a DHL product requires a legacy SOAP or XML service, a workflow consumes the service with the documented configuration, transforms XML into the internal model, and isolates the legacy contract behind a reusable integration component. Version and error handling should remain specific to the DHL service.

Implementation sequence

Confirm that the selected DHL product requires the legacy service
Configure the documented SOAP endpoint and credentials
Build the XML request from validated internal data
Invoke the DHL SOAP operation
Parse and map the XML response
Persist the result and route service faults for review

DHL Shipping Documents

DHL shipment APIs may return labels, invoices, waybills, or other shipping documents as encoded response content or document references. This capability is part of shipment processing rather than a confirmed general-purpose DHL file repository.

Martini implementation pattern

Martini implementation pattern: the workflow extracts document content from the DHL response, preserves its encoding and MIME type, and forwards or stores it through a supported file, database, or application endpoint. Document handling is kept separate from ordinary text mappings to avoid corrupting binary content.

Implementation sequence

Receive the DHL shipment response
Identify each returned document and its encoding
Decode or retrieve the document content
Preserve the file name, MIME type, and document type
Store or forward the document to the target application
Record the document reference with the shipment

Common DHL integration patterns

Pattern 1: Create shipments and return DHL documents

When to use this pattern

Use this pattern when an order, ERP, or commerce application needs to create a DHL shipment and receive a waybill, label, or other shipping document. Validation and idempotency are important because retrying after a timeout can create a duplicate shipment.

Integration direction
Shopify
Martini
DHL
Example Mapping
DHL FieldCanonical FieldTarget Field
orderReferencefulfillment.referencecustomerReference
recipient.addressshipment.recipientAddressreceiver.address
packages[].weightshipment.packages[].weightpackages[].weight
customs.items[]shipment.customsItems[]customs.declaredItems
Martini implementation pattern

Martini receives the fulfillment request, validates address, package, and customs information, and checks for an existing waybill using the internal order reference. It maps the request to the applicable DHL shipment schema, calls the REST API, stores the response and documents, and returns a normalized result. Transient failures are retried, while ambiguous timeouts are held for reconciliation rather than blindly resubmitted.

Martini capabilities used
  • workflows
  • API consumption
  • data mapping
  • business rules
  • secrets management
  • error handling

Pattern 2: Synchronize DHL tracking events

When to use this pattern

Use this pattern to keep order, warehouse, customer service, or case systems aligned with shipment milestones and delivery exceptions. It supports either selected DHL push notifications or scheduled polling when notifications are unavailable or incomplete.

Integration direction
DHL
Martini
Salesforce
Example Mapping
DHL FieldCanonical FieldTarget Field
waybillNumbershipment.externalIdshipment.trackingNumber
trackingEvent.codeshipment.statusshipment.status
trackingEvent.timestampshipment.statusAtshipment.lastStatusTime
trackingEvent.descriptionshipment.statusDetailcase.description
Martini implementation pattern

Martini receives supported DHL notifications or schedules tracking retrieval for active waybills. The workflow normalizes event codes, timestamps, locations, and descriptions, deduplicates events received through both push and polling paths, applies rules for delivered and exception states, and updates the target system with retry handling.

Martini capabilities used
  • workflow triggers
  • scheduled workflows
  • API consumption
  • data mapping
  • deduplication rules
  • error handling

Pattern 3: Calculate DHL rates and service options

When to use this pattern

Use this pattern when a storefront or order application needs DHL prices and service levels before fulfillment. The workflow can normalize product-specific rate responses into a stable model for checkout or order selection.

Integration direction
Adobe Commerce
Martini
DHL
Example Mapping
DHL FieldCanonical FieldTarget Field
originshipment.originshipper.address
destinationshipment.destinationreceiver.address
package.weightshipment.totalWeightpackages[].weight
service.priceshippingOption.amountshippingMethods[].price
Martini implementation pattern

Martini receives origin, destination, package, and service requirements, validates the input, calls the selected DHL rating API, and maps returned service codes, prices, currencies, and delivery estimates into a canonical response. Business rules can filter unavailable services, and transient DHL responses can be retried without duplicating a shipment.

Martini capabilities used
  • API exposure
  • API consumption
  • data mapping
  • validation
  • business rules
  • retry handling

Pattern 4: Book pickups and reconcile operations

When to use this pattern

Use this pattern when a warehouse or ERP needs to book DHL collections and later reconcile pickup or shipment status. It separates the initial booking from ongoing operational synchronization.

Integration direction
SAP S/4HANA
Martini
DHL
Example Mapping
DHL FieldCanonical FieldTarget Field
pickup.datepickup.requestedDaterequestedPickupDate
pickup.locationpickup.locationpickupAddress
shipmentReferences[]pickup.shipmentReferences[]shipments[]
pickup.confirmationpickup.externalConfirmationpickupConfirmation
Martini implementation pattern

Martini validates the pickup location, date, shipment references, and account scope, invokes the DHL pickup operation, stores the confirmation, and returns it to the source system. A scheduled reconciliation workflow retrieves applicable status information, applies operational rules, and routes rejected or ambiguous bookings for review.

Martini capabilities used
  • workflows
  • API consumption
  • scheduling
  • data mapping
  • business rules
  • monitoring and error handling

Applications commonly integrated with DHL

DHL commonly participates in fulfillment, delivery, tracking, and logistics workflows across commerce and enterprise applications. Martini can mediate between these applications and the applicable DHL product, while keeping DHL-specific authentication, mappings, retries, and regional variations isolated from business systems.

Application Scenario Direction Martini Pattern
SAP S/4HANA Create outbound shipments, obtain rates, transmit delivery and customs information, and synchronize tracking results with enterprise logistics processes. SAP S/4HANA → Martini → DHL Expose or consume an order and fulfillment workflow, validate shipment and customs data, map SAP delivery structures to the selected DHL REST API, persist the waybill, and return tracking and document information to SAP. Apply retry and duplicate-prevention rules around shipment creation.
NetSuite Connect sales orders and item fulfillments with DHL shipment creation, labels, tracking numbers, rates, and delivery updates. NetSuite → Martini → DHL Receive fulfillment data from NetSuite, transform packages and recipient details into the DHL shipment schema, store the returned waybill and documents, and synchronize tracking exceptions or delivery milestones back to the fulfillment record.
Salesforce Make shipment milestones and delivery exceptions available to sales, service, and customer-success teams. DHL → Martini → Salesforce Poll DHL tracking data or receive supported tracking notifications, normalize event codes and timestamps, associate events with Salesforce orders or cases, and route delivery exceptions through a controlled workflow.
Shopify Calculate DHL shipping services, create shipments after fulfillment, and return tracking numbers and shipping documents to online orders. Shopify → Martini → DHL Use a Martini API or workflow to receive order and fulfillment information, call the relevant DHL rating or shipment endpoint, transform the response for Shopify, and persist identifiers to support later tracking synchronization.
Adobe Commerce Connect orders and fulfillment processes with DHL rating, shipment creation, label generation, and tracking. Adobe Commerce → Martini → DHL Orchestrate rating and shipment workflows from Adobe Commerce, validate package and address data, handle encoded DHL documents as binary content, and update the commerce order with the waybill and status events.
ServiceNow Synchronize delivery exceptions, shipment milestones, or logistics-related cases with service management workflows. DHL → Martini → ServiceNow Receive or retrieve DHL tracking events, apply business rules for exception and delivery states, map the normalized event to ServiceNow cases or records, and use retry-aware API workflows for downstream updates.
Oracle Fusion Cloud Applications Transmit fulfillment and order data to DHL and return shipment, delivery, and tracking information to Oracle applications. Oracle Fusion Cloud Applications → Martini → DHL Use Martini to map Oracle fulfillment structures into the selected DHL request model, orchestrate shipment or pickup calls, preserve DHL identifiers, and synchronize subsequent tracking and document responses.
WooCommerce Create DHL shipments and return labels and tracking details for online orders. WooCommerce → Martini → DHL Accept WooCommerce fulfillment data through an API workflow, call DHL shipment services, transform labels and tracking identifiers into WooCommerce-compatible updates, and retry transient failures without duplicating shipments.

How to build a DHL integration in Martini

Objective

Identify the DHL business unit, product, country, account, and required operations before configuring the integration. Store the selected API key, subscription key, API secret, account identifier, or other product-specific credentials outside workflow logic.

Instructions in Martini

  • Confirm the applicable DHL API product and environment
  • Configure the documented authentication scheme for that product
  • Store credentials and account identifiers in Martini secrets or environment configuration
  • Restrict access to exposed Martini APIs and workflow resources

Objective

Select an event-driven or scheduled entry point based on the DHL capability and business process. Use an internal API for shipment and rating requests, supported DHL notifications for selected tracking events, or scheduling for polling and reconciliation.

Instructions in Martini

  • Expose a Martini API for internal shipment, rating, or pickup requests
  • Configure a webhook-style endpoint when the selected DHL product supports tracking notifications
  • Use a scheduler for tracking polling and reconciliation
  • Define correlation identifiers such as order references and waybills

Objective

Receive or retrieve DHL data using the applicable REST API, supported notification, or legacy SOAP/XML service. Capture raw responses and correlation information needed for diagnostics and reconciliation.

Instructions in Martini

  • Call the selected DHL REST endpoint with validated parameters
  • Retrieve tracking updates using notifications or documented polling behavior
  • Use SOAP/XML only when the DHL product requires a legacy interface
  • Capture response codes, correlation data, and raw event context safely

Objective

Use a Martini workflow to coordinate validation, DHL calls, transformations, downstream updates, and exceptional paths. Keep product-specific DHL logic reusable and separate from target application logic.

Instructions in Martini

  • Sequence validation, API calls, mappings, and target writes
  • Branch for validation failures, authentication failures, rate limits, and transient service errors
  • Apply controlled delays and backoff for retryable responses
  • Persist checkpoints, waybills, document references, and processing state

Objective

Convert between internal shipment, package, tracking, rate, pickup, customs, and document models and the schema of the selected DHL API. Preserve product-specific fields where downstream processes depend on them.

Instructions in Martini

  • Map recipient, sender, package, customs, service, and reference fields
  • Normalize DHL service codes, tracking statuses, timestamps, and locations
  • Handle JSON or XML according to the selected DHL interface
  • Keep labels and other encoded documents as binary content with correct metadata

Objective

Apply operational rules before and after DHL calls, including address and customs validation, service filtering, duplicate prevention, event deduplication, and status routing.

Instructions in Martini

  • Validate required address, package, customs, and account fields
  • Check stable order or fulfillment references before creating shipments
  • Filter or route DHL service options according to business requirements
  • Deduplicate tracking events using waybill and event attributes
  • Separate recoverable errors from requests requiring business correction

Common DHL data objects used in integrations

ObjectTypical UseCommon target systemsMartini handling
ShipmentRepresents a shipment request, shipment record, or shipping transaction created or retrieved through a DHL service.SAP S/4HANA, NetSuite, Oracle Fusion Cloud Applications, Shopify, Adobe CommerceMartini validates shipment inputs, maps them to the product-specific DHL schema, stores identifiers, and synchronizes responses and status changes.
PackageRepresents a physical parcel, piece, or package within a shipment, including dimensions, weight, and package-level details where supported.SAP S/4HANA, NetSuite, Shopify, Adobe CommerceMartini transforms package arrays, applies validation and business rules, and preserves package relationships when building DHL requests.
Tracking eventRepresents a scan, movement, exception, delivery, or status event associated with a shipment.Salesforce, ServiceNow, SAP S/4HANA, NetSuite, ShopifyMartini receives supported push notifications or polls tracking APIs, normalizes event codes and timestamps, deduplicates events, and routes them to target workflows.
Rate or quoteRepresents a transportation price and service-level response for origin, destination, package, and service requirements.Shopify, Adobe Commerce, NetSuite, SAP S/4HANAMartini maps commerce or order inputs to DHL rating requests, normalizes service and price results, and returns usable options to the ordering application.
PickupRepresents a request or booking for DHL to collect one or more shipments.SAP S/4HANA, Oracle Fusion Cloud Applications, warehouse applications, NetSuiteMartini validates pickup requirements, invokes the applicable DHL operation, persists confirmation details, and reconciles later status updates.
WaybillRepresents a shipment identifier used for tracking and operational processing.NetSuite, SAP S/4HANA, Shopify, Adobe Commerce, SalesforceMartini persists the waybill against the internal fulfillment reference and uses it as the key for tracking synchronization and duplicate prevention.

Authentication and security considerations

Product-specific authentication

DHL authentication varies by business unit, API product, country, and account. Integrations may use API keys, subscription keys, HTTP Basic Authentication with an API key and secret, or product-specific OAuth 2.0. Configure the scheme documented for the selected DHL API rather than assuming one method applies across DHL services.

Secrets and account scope

Store DHL credentials, account identifiers, and subscription values in Martini secrets or environment configuration. Access may be constrained by the DHL customer account, subscribed API products, geography, and permitted operations such as shipment creation, rating, pickup booking, or tracking.

Inbound protection

Restrict Martini endpoints used for DHL tracking notifications and validate the request using the authentication or signature mechanism provided by the selected DHL product. Avoid logging credentials or full customs payloads containing sensitive information.

Operational considerations for DHL integrations

Rate limits and retries

Respect the limits associated with the selected DHL API. Use controlled scheduling, retry delays, and backoff for transient responses such as 429, 502, 503, and 504, while separating validation and authentication failures from recoverable service errors.

Pagination and checkpoints

Tracking or shipment searches may use cursors, pages, offsets, or date windows. Store the last successful checkpoint and design incremental retrieval so the same data is not repeatedly processed.

Idempotency and event ordering

Persist internal fulfillment references and DHL waybills before processing retries. Deduplicate tracking events using the waybill, event code, timestamp, location, and DHL event identifier where available. Support duplicate, delayed, and out-of-order notifications.

Documents and schemas

Preserve the MIME type, file name, encoding, and document type for labels, invoices, waybills, and customs documents. Keep DHL-specific mappings versioned because service codes, tracking events, document structures, and required customs fields can vary by product.

Testing and monitoring

Test shipment creation, rating, pickup, tracking, document handling, validation failures, rate limits, and ambiguous timeouts in the applicable DHL environment. Monitor workflow logs, response codes, correlation data, and reconciliation queues without exposing secrets.

Why use Martini instead of scripts or point-to-point integrations?

Reusable orchestration

Scripts often combine DHL authentication, request construction, response parsing, retries, and downstream updates in code that is difficult to reuse. Martini centralizes this orchestration in workflows and reusable integration assets.

Separation of contracts

Martini can expose normalized APIs to internal applications while isolating DHL product, regional, and schema variations behind mappings and business rules. This reduces the need for every application to understand DHL-specific request formats.

Operational reliability

Workflows can coordinate scheduled polling and supported notifications, checkpoints, deduplication, retry paths, document handling, and monitoring. This provides a maintainable foundation for shipment, tracking, rating, and pickup processes compared with multiple point-to-point implementations.

Frequently asked questions

How can DHL be integrated with enterprise systems?

DHL can be integrated through product- and region-specific REST APIs for shipment creation, rates, pickups, tracking, delivery status, and shipping documents. Selected DHL products also support tracking push notifications, while older services may expose SOAP or XML interfaces. Authentication varies by API and may use API keys, subscription keys, HTTP Basic Authentication, or product-specific OAuth 2.0.

Can Martini integrate with DHL?

Yes. Martini can consume the applicable DHL REST APIs, receive supported tracking notifications, and orchestrate shipment, rating, pickup, tracking, document, and downstream synchronization workflows. A legacy DHL SOAP or XML service can also be consumed when required by a specific product.

Do I need a connector to integrate DHL with Martini?

No. A dedicated DHL connector is not required. Martini can integrate with DHL using the vendor's native REST APIs, supported tracking notifications, legacy SOAP or XML services where necessary, product-specific authentication, and workflow-based mappings and orchestration.

Is there any extra Lonti cost to integrate DHL with Martini?

Lonti does not charge an additional per-connector or per-vendor fee to integrate DHL. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from DHL, cloud infrastructure, or other third-party systems depending on subscriptions, usage, and deployment model.

Which DHL integration methods should a new implementation use?

REST should generally be the primary method for current DHL integrations, but the correct API depends on the DHL division, country, account, and required operation. Selected products may support tracking notifications, while SOAP and XML services should be treated as legacy or product-specific. DHL's documented authentication scheme should be confirmed for each API.

Can Martini receive DHL tracking events?

Martini can receive webhook-style HTTP requests where the selected DHL product supports tracking push notifications. Coverage is limited to selected products and events, so a robust design can combine supported notifications with scheduled tracking polling, deduplication, and out-of-order event handling.

How does synchronization and duplicate handling work with DHL?

Martini can synchronize tracking through DHL notifications or scheduled API retrieval, using waybill numbers and stored checkpoints or date windows. Shipment creation and pickup workflows should use stable order or fulfillment references, persist successful DHL identifiers, and distinguish ambiguous timeouts from confirmed failures before retrying.

Can Martini expose an API façade for DHL?

Yes. Martini can expose an internal API that presents a normalized shipment, rating, pickup, or tracking contract to enterprise applications while encapsulating DHL-specific endpoints, credentials, request schemas, response mappings, regional differences, retries, and error handling.

Related Martini documentation

DHL APIs

Events

Workflows

Security

Operations

Connect DHL with your enterprise systems

Use Martini to orchestrate DHL shipping, rating, pickup, tracking, and document workflows across your commerce, ERP, warehouse, and customer service applications.

EXPLORE MARTINI
BOOK A DEMO