# DHL — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Track DHL shipments worldwide by entering a tracking number to retrieve real-time status updates, delivery location details, product information, and a complete history of all shipment events. Monitor packages from origin to destination with comprehensive tracking data.

**Category:** E-commerce | **Website:** [dhl.com/](https://dhl.com/) | **Docs:** [parse.bot/marketplace/3435cdb4-39be-40ab-b8b9-55f7e901a14a/dhl-com-api](https://parse.bot/marketplace/3435cdb4-39be-40ab-b8b9-55f7e901a14a/dhl-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/dhl/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Find service point

Find nearby DHL Express service points (drop-off/pickup locations) by address or postal code. Returns up to 10 results sorted by distance, including name, full address, geo-coordinates, distance, opening hours, and service capabilities for each point.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | Yes | Search address, postal code, or location name |
| `country_code` | string | No | Two-letter country code (ISO 3166-1 alpha-2) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/dhl/find-service-point \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"address":"<string>","country_code":"<string>"}'
```

### Get address suggestions

Returns address suggestions for a query string. Useful for validating and geocoding addresses before searching for service points. Returns up to 5 suggestions from Google geocoding service.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country_code` | string | No | Two-letter country code (ISO 3166-1 alpha-2) |
| `query` | string | Yes | Address search query (e.g. zip code, partial address, or city name) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/dhl/get-address-suggestions \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"country_code":"<string>","query":"<string>"}'
```

### Get estimated delivery

Extracts and returns the estimated or actual delivery date/time for a shipment. Returns null when no delivery estimate is available or the tracking number has no associated shipment.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `tracking_number` | string | Yes | DHL tracking number (alphanumeric, typically 10-34 characters) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/dhl/get-estimated-delivery \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"tracking_number":"<string>"}'
```

### Get service alerts

Retrieves current DHL Express service alerts, disruption notices, and important operational information including surcharges and regulatory changes. Returns an empty array when no active alerts exist.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/dhl/get-service-alerts \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get shipment events

Returns the full chronological list of tracking events for a shipment. Each event includes timestamp, location, and description. Returns an empty events array when the tracking number has no associated shipment.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `tracking_number` | string | Yes | DHL tracking number (alphanumeric, typically 10-34 characters) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/dhl/get-shipment-events \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"tracking_number":"<string>"}'
```

### Get shipment status

Returns the latest/current status of a shipment including the city of last known location and timestamp of the most recent status event. Returns status Not Found with null location and timestamp when the tracking number has no associated shipment.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `tracking_number` | string | Yes | DHL tracking number (alphanumeric, typically 10-34 characters) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/dhl/get-shipment-status \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"tracking_number":"<string>"}'
```

### List countries

Lists all available countries for DHL shipping services. Returns each country ISO code, whether postcodes are used, valid postcode format patterns, and the recommended format.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/dhl/list-countries \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Track shipment

Track a DHL shipment by tracking number. Returns the full shipment object including status, all tracking events, and delivery details when the shipment is found. Returns a not-found indicator with status Not Found when the tracking number has no associated shipment.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `tracking_number` | string | Yes | DHL tracking number (alphanumeric, typically 10-34 characters) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/dhl/track-shipment \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"tracking_number":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.