<!-- BusyBot node reference — https://busybot.net/tools/dhl/ -->

> Node: DHL (`dhl`) · Action · v1
> Category: Utility · Credentials: DHL API (`dhlApi`)
> Updated: 2026-08-16

# DHL

> Track DHL shipments by tracking number

## Overview

DHL is a global logistics company providing shipping and tracking services. This tool queries the DHL Unified Tracking API to retrieve tracking details for shipments by their tracking number. It returns shipment status, origin/destination, tracking events, and delivery details. Optionally accepts a recipient postal code for more detailed information.

**Category:** Utility  
**Tool Name:** `dhl`  
**Version:** 1

**Appearance:** Icon: `lucide-Truck` | Color: `#FFCC00`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **DHL API** credentials.
See the [Credentials Guide](https://busybot.net/credentials/dhl-api/) for setup instructions.

### Operations

| Operation | Value | Description |
|-----------|-------|-------------|
| Get Tracking Details | `get` | The operation to perform. |

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Tracking Number | `string` | Yes | — | The DHL tracking number of the shipment to look up. Supports expressions like {{ $json.trackingNumber }}. |
| Options | `collection` | No | `{}` | Additional options for the tracking request. |
| — Recipient's Postal Code | `string` | No | — | DHL will return more detailed information on the shipment when you provide the recipient's postal code. It acts as a verification step. Supports expressions. |
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

Each shipment the API returns becomes its own output item: the shipment object is merged into the incoming item JSON at the top level, so the upstream fields stay addressable alongside the tracking data. Binary data is forwarded. One input item can therefore produce several output items when a tracking number resolves to more than one shipment.

Merged shipment data covers the shipment's status, origin and destination, and its tracking events, along with the delivery details DHL exposes for that shipment. Supplying the recipient's postal code makes DHL return a more detailed record.

When the tracking number matches nothing, one item is emitted carrying the original JSON plus:

```json
{
  "_trackingNumber": "1234567890",
  "_shipments": []
}
```

Check `_shipments` before treating a result as a real shipment — an empty array is the "not found" signal, not an error.

## Usage Examples

- Get tracking details for a DHL shipment
- Check the delivery status of a DHL package
- Look up DHL tracking events for a parcel

## Example Configuration

Track a single package by a tracking number carried on the item:

```json
{
  "type": "dhl",
  "parameters": {
    "operation": "get",
    "trackingNumber": "{{ $json.trackingNumber }}"
  }
}
```

Ask for the detailed record by verifying with the recipient's postal code:

```json
{
  "type": "dhl",
  "parameters": {
    "operation": "get",
    "trackingNumber": "{{ $json.trackingNumber }}",
    "options": {
      "recipientPostalCode": "{{ $json.shipTo.postalCode }}"
    }
  }
}
```

Track a batch of numbers with a higher concurrency:

```json
{
  "type": "dhl",
  "parameters": {
    "operation": "get",
    "trackingNumber": "{{ $json.awb }}",
    "maxConcurrency": 20
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Track DHL shipments by tracking number using the DHL Unified Tracking API.

### Important Notes

- **Parameter structure.** `options` is a collection — its fields nest under the `options` key. Do not place `recipientPostalCode` at the top level of the parameters object.
- **Required fields.** `trackingNumber` is required for every tracking request.
- **One operation.** `get` is the only operation available; the tool always reads tracking data and never writes to DHL.
- **Fan-out.** Because each shipment leaves as its own item, downstream nodes see one item per shipment rather than one per input item.