> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spojit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DHL Express

> Rates, tracking, shipments, and pickup management via the MyDHL API.

The DHL Express connector lets your workflows quote rates, create shipments and labels, track parcels, and manage pickups through the [MyDHL API](https://developer.dhl.com/api-reference/dhl-express-mydhl-api).

<Note>
  For the full API reference, see the [DHL Express MyDHL API documentation](https://developer.dhl.com/api-reference/dhl-express-mydhl-api).
</Note>

<Snippet file="connection-note.mdx" />

## Connection setup

<Steps>
  <Step title="Register on the DHL Developer Portal">
    Sign up at [developer.dhl.com](https://developer.dhl.com), create an app, and subscribe it to the MyDHL API. Copy the **API username** and **API password** issued for your app.
  </Step>

  <Step title="Add the connection in Spojit">
    Go to **Connections** in Spojit, click **Add Connection**, select **DHL Express**, and enter:

    * **DHL API Username**: Your MyDHL API username
    * **DHL API Password**: Your MyDHL API password
    * **Environment**: `production` (default) or `sandbox` for testing
  </Step>
</Steps>

<Info>
  Sandbox uses a separate base URL (`/mydhlapi/test`) and separate credentials. Production credentials will not work in sandbox and vice versa.
</Info>

## Tools

### Rates

<AccordionGroup>
  <Accordion title="get-rates: Get shipping rates">
    Retrieve available DHL Express products and rates between an origin and destination.

    <ParamField body="originPostalCode" type="string" required>Origin postal/zip code.</ParamField>
    <ParamField body="originCountryCode" type="string" required>Origin country code (ISO 3166-1 alpha-2, e.g. `US`).</ParamField>
    <ParamField body="originCityName" type="string">Origin city name.</ParamField>
    <ParamField body="destinationPostalCode" type="string" required>Destination postal/zip code.</ParamField>
    <ParamField body="destinationCountryCode" type="string" required>Destination country code (ISO 3166-1 alpha-2).</ParamField>
    <ParamField body="destinationCityName" type="string">Destination city name.</ParamField>
    <ParamField body="weight" type="number" required>Package weight in kilograms.</ParamField>
    <ParamField body="length" type="number">Package length in centimetres.</ParamField>
    <ParamField body="width" type="number">Package width in centimetres.</ParamField>
    <ParamField body="height" type="number">Package height in centimetres.</ParamField>
    <ParamField body="plannedShippingDate" type="string" required>Planned shipping date (`YYYY-MM-DD`).</ParamField>
    <ParamField body="isCustomsDeclarable" type="boolean" required>Whether the shipment is customs-declarable.</ParamField>
    <ParamField body="unitOfMeasurement" type="string" default="metric">`metric` or `imperial`.</ParamField>

    **Example request:**

    ```json theme={null}
    {
      "originPostalCode": "10001",
      "originCountryCode": "US",
      "originCityName": "New York",
      "destinationPostalCode": "SW1A 1AA",
      "destinationCountryCode": "GB",
      "destinationCityName": "London",
      "weight": 2.5,
      "length": 30,
      "width": 20,
      "height": 15,
      "plannedShippingDate": "2026-06-01",
      "isCustomsDeclarable": true,
      "unitOfMeasurement": "metric"
    }
    ```

    **Example response:**

    ```json theme={null}
    {
      "products": [
        {
          "productName": "EXPRESS WORLDWIDE",
          "productCode": "P",
          "localProductCode": "P",
          "weight": {
            "volumetric": 1.8,
            "provided": 2.5,
            "unitOfMeasurement": "metric"
          },
          "totalPrice": [
            {
              "currencyType": "BILLC",
              "priceCurrency": "USD",
              "price": 142.5
            }
          ],
          "deliveryCapabilities": {
            "deliveryTypeCode": "QDDC",
            "estimatedDeliveryDateAndTime": "2026-06-03T12:00:00",
            "totalTransitDays": "2"
          }
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

### Shipments

<AccordionGroup>
  <Accordion title="create-shipment: Create a shipment and label">
    Submit a `ShipmentRequest` to the MyDHL API. The `payload` argument is passed through unchanged as the request body.

    <ParamField body="payload" type="object" required>
      MyDHL API ShipmentRequest. Typically includes `plannedShippingDateAndTime`, `productCode`, `customerDetails` (`shipperDetails`, `receiverDetails`), `content` (`packages`, `isCustomsDeclarable`, `declaredValue`, `description`), and `accounts`.
    </ParamField>

    **Example request:**

    ```json theme={null}
    {
      "payload": {
        "plannedShippingDateAndTime": "2026-06-01T13:00:00 GMT+00:00",
        "pickup": { "isRequested": false },
        "productCode": "P",
        "accounts": [{ "typeCode": "shipper", "number": "123456789" }],
        "customerDetails": {
          "shipperDetails": {
            "postalAddress": {
              "postalCode": "10001",
              "cityName": "New York",
              "countryCode": "US",
              "addressLine1": "350 5th Ave"
            },
            "contactInformation": {
              "phone": "+12125551212",
              "companyName": "Acme Corp",
              "fullName": "Jane Doe"
            }
          },
          "receiverDetails": {
            "postalAddress": {
              "postalCode": "SW1A 1AA",
              "cityName": "London",
              "countryCode": "GB",
              "addressLine1": "10 Downing Street"
            },
            "contactInformation": {
              "phone": "+442079460000",
              "companyName": "Receiver Ltd",
              "fullName": "John Smith"
            }
          }
        },
        "content": {
          "packages": [
            {
              "weight": 2.5,
              "dimensions": { "length": 30, "width": 20, "height": 15 }
            }
          ],
          "isCustomsDeclarable": true,
          "declaredValue": 100,
          "declaredValueCurrency": "USD",
          "description": "Sample documents",
          "incoterm": "DAP",
          "unitOfMeasurement": "metric"
        }
      }
    }
    ```

    **Example response:**

    ```json theme={null}
    {
      "shipmentTrackingNumber": "1234567890",
      "trackingUrl": "https://www.dhl.com/en/express/tracking.html?AWB=1234567890",
      "packages": [
        {
          "referenceNumber": 1,
          "trackingNumber": "JD0140048500001234"
        }
      ],
      "documents": [
        {
          "imageFormat": "PDF",
          "content": "JVBERi0xLjQKJeLjz9MKMiAwIG9iago8PC...",
          "typeCode": "label"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="track-shipment: Track a shipment by tracking number">
    <ParamField body="trackingNumber" type="string" required>DHL Express tracking / waybill number.</ParamField>
    <ParamField body="pieceTrackingNumber" type="string">Optional individual piece tracking number.</ParamField>
    <ParamField body="levelOfDetail" type="string" default="all">`all`, `shipment`, or `piece`.</ParamField>

    **Example request:**

    ```json theme={null}
    {
      "trackingNumber": "1234567890"
    }
    ```

    **Example response:**

    ```json theme={null}
    {
      "shipments": [
        {
          "shipmentTrackingNumber": "1234567890",
          "status": "delivered",
          "shipmentTimestamp": "2026-06-01T13:25:00",
          "productCode": "P",
          "description": "EXPRESS WORLDWIDE",
          "shipperDetails": {
            "postalAddress": { "cityName": "New York", "countryCode": "US" }
          },
          "receiverDetails": {
            "postalAddress": { "cityName": "London", "countryCode": "GB" }
          },
          "events": [
            {
              "date": "2026-06-03",
              "time": "11:42:00",
              "typeCode": "OK",
              "description": "Delivered",
              "serviceArea": [{ "code": "LHR", "description": "London - UK" }]
            },
            {
              "date": "2026-06-01",
              "time": "13:25:00",
              "typeCode": "PU",
              "description": "Shipment picked up",
              "serviceArea": [{ "code": "JFK", "description": "New York - USA" }]
            }
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="cancel-shipment: Cancel a booked shipment's pickup">
    <ParamField body="trackingNumber" type="string" required>DHL Express tracking / waybill number.</ParamField>
    <ParamField body="requestorName" type="string" required>Name of the person requesting cancellation.</ParamField>
    <ParamField body="reason" type="string" required>Reason for the cancellation.</ParamField>

    **Example request:**

    ```json theme={null}
    {
      "trackingNumber": "1234567890",
      "requestorName": "Jane Doe",
      "reason": "Customer cancelled order"
    }
    ```

    **Example response:**

    ```json theme={null}
    {
      "status": "cancelled",
      "trackingNumber": "1234567890",
      "cancelPickupReason": "Customer cancelled order"
    }
    ```
  </Accordion>
</AccordionGroup>

### Pickups

<AccordionGroup>
  <Accordion title="create-pickup: Schedule a pickup">
    Submit a `PickupRequest` to the MyDHL API. The `payload` is passed through unchanged.

    <ParamField body="payload" type="object" required>
      MyDHL API PickupRequest. Typically includes `plannedPickupDateAndTime`, `customerDetails` (`shipperDetails`), `shipmentDetails` (packages, productCode), and `accounts`.
    </ParamField>

    **Example request:**

    ```json theme={null}
    {
      "payload": {
        "plannedPickupDateAndTime": "2026-06-01T13:00:00 GMT+00:00",
        "closeTime": "18:00",
        "location": "reception",
        "accounts": [{ "typeCode": "shipper", "number": "123456789" }],
        "customerDetails": {
          "shipperDetails": {
            "postalAddress": {
              "postalCode": "10001",
              "cityName": "New York",
              "countryCode": "US",
              "addressLine1": "350 5th Ave"
            },
            "contactInformation": {
              "phone": "+12125551212",
              "companyName": "Acme Corp",
              "fullName": "Jane Doe"
            }
          }
        },
        "shipmentDetails": [
          {
            "productCode": "P",
            "isCustomsDeclarable": true,
            "packages": [
              { "weight": 2.5, "dimensions": { "length": 30, "width": 20, "height": 15 } }
            ],
            "unitOfMeasurement": "metric"
          }
        ]
      }
    }
    ```

    **Example response:**

    ```json theme={null}
    {
      "dispatchConfirmationNumbers": ["DXB-001-12345"],
      "readyByTime": "13:00",
      "nextPickupDate": "2026-06-01"
    }
    ```
  </Accordion>

  <Accordion title="cancel-pickup: Cancel a scheduled pickup">
    <ParamField body="dispatchConfirmationNumber" type="string" required>Dispatch confirmation number returned from `create-pickup`.</ParamField>
    <ParamField body="requestorName" type="string" required>Name of the person requesting cancellation.</ParamField>
    <ParamField body="reason" type="string" required>Reason for the cancellation.</ParamField>

    **Example request:**

    ```json theme={null}
    {
      "dispatchConfirmationNumber": "DXB-001-12345",
      "requestorName": "Jane Doe",
      "reason": "Schedule change"
    }
    ```

    **Example response:**

    ```json theme={null}
    {
      "status": "cancelled",
      "dispatchConfirmationNumber": "DXB-001-12345"
    }
    ```
  </Accordion>
</AccordionGroup>

### Advanced

<AccordionGroup>
  <Accordion title="raw-api-request: Make an arbitrary MyDHL API request">
    Send a request to any MyDHL API endpoint not covered by the curated tools, for example address validation, products listing, label image retrieval, or paperless trade document upload.

    <ParamField body="method" type="string" required>`GET`, `POST`, `PATCH`, or `DELETE`.</ParamField>
    <ParamField body="path" type="string" required>API path (e.g. `/address-validate` or `/shipments/1234567890/proof-of-delivery`).</ParamField>
    <ParamField body="query" type="object">Optional query parameters object.</ParamField>
    <ParamField body="body" type="object">Request body for `POST`/`PATCH`.</ParamField>

    **Example request:**

    ```json theme={null}
    {
      "method": "GET",
      "path": "/address-validate",
      "query": {
        "type": "delivery",
        "countryCode": "GB",
        "postalCode": "SW1A 1AA",
        "cityName": "London",
        "strictValidation": true
      }
    }
    ```

    **Example response:**

    ```json theme={null}
    {
      "address": [
        {
          "countryCode": "GB",
          "postalCode": "SW1A 1AA",
          "cityName": "London",
          "serviceArea": { "code": "LHR", "description": "London - UK" }
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>