canonical: https://jentic.com/apis/api-gw.dhlparcel.nl/dhlparcel

# Api Gw Dhlparcel Nl DHL eCommerce API

DHL eCommerce API for the Netherlands and Belgium provides programmatic access to label generation, shipment tracking, delivery option lookup, and parcel-shop locator queries. The 6 endpoints cover the end-to-end parcel flow from picking a delivery option to printing the label and tracking the resulting consignment. Authentication is by JWT bearer token, obtained from the /authenticate/api-key endpoint by exchanging a long-lived API key. The base host is api-gw.dhlparcel.nl.

## For AI agents

Generate DHL parcel labels, track shipments, look up delivery options, and find parcel-shop locations across the Netherlands and Belgium.

## Scope

Does not handle customs paperwork, returns processing, or non-DHL carriers - use for DHL eCommerce NL and BE label generation, tracking, and parcel-shop lookup only.

## Capabilities

- Exchange a long-lived DHL API key for a short-lived JWT via /authenticate/api-key
- Create parcel labels with /labels for shipments going through the DHL eCommerce network
- Track a parcel by its tracking reference with /track-trace and surface the latest status
- Look up the delivery options available for a recipient address via /shipment-options
- Find nearby parcel shops and lockers for drop-off or pickup with /parcel-shop-locations

## Use cases

### E-Commerce Order Fulfilment

When an order is paid, an e-commerce backend exchanges its DHL API key for a JWT, calls /shipment-options for the recipient address, then calls /labels with the chosen option to receive a printable label and tracking code. The tracking code is returned to the customer immediately and the label is queued for warehouse printing. This covers Netherlands and Belgium domestic and outbound flows.

Example prompt: Call /authenticate/api-key with the API key, call /shipment-options for the recipient postcode, then call /labels with the chosen optionId to receive the label PDF and tracking reference

### Customer Tracking Page

Build a branded order-tracking page that takes the customer's order id, looks up the stored DHL tracking reference, and calls /track-trace to surface the current status. The endpoint returns the parcel state and event history without redirecting the customer to dhl.com. This keeps the tracking experience inside the merchant's own brand.

Example prompt: Call /track-trace with the parcel's tracking reference and render the latest event description, timestamp, and final status in the merchant's tracking page

### Parcel-Shop Drop-Off Selector

Offer the customer a list of nearby DHL parcel shops at checkout by calling /parcel-shop-locations with the delivery postcode. The response includes the shop address, opening hours, and distance, which can be presented in a map widget so the customer can choose a drop-off or pickup point. This converts higher than home delivery for some product categories.

Example prompt: Call /parcel-shop-locations with postal code 1011AB and radius 2km, then return the three closest shops with their addresses and opening hours

### Agent Integration via Jentic

An AI agent built on Jentic can search for the DHL eCommerce label, tracking, and shop-locator operations by intent and execute them without holding the long-lived API key in agent context. Jentic's your Jentic One instance holds the credential and the JWT exchange is handled in the call layer, so the agent's instructions stay focused on the shipping logic rather than the auth dance.

Example prompt: Use Jentic search for 'create a dhl ecommerce shipping label', load the /labels operation, execute it with the recipient address and the chosen shipment option, and return the tracking reference

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /authenticate/api-key | Exchange an API key for a JWT bearer token |
| POST | /labels | Create a parcel label and tracking reference |
| GET | /track-trace | Get the status and event history for a parcel |
| GET | /shipment-options | Look up delivery options for a recipient address |
| GET | /parcel-shop-locations | Find nearby parcel shops and lockers |

## Key resources

- **Authentication** — Exchange an API key for a short-lived JWT bearer token via /authenticate/api-key
- **Labels** — Generate parcel labels for DHL eCommerce shipments via /labels
- **Track and Trace** — Look up parcel status by tracking reference via /track-trace
- **Shipment Options** — Discover the delivery options available for a recipient address via /shipment-options
- **Parcel Shops** — Find nearby parcel shops and lockers via /parcel-shop-locations

## Why Jentic

- **Setup:** Wiring the DHL eCommerce API by hand means exchanging your long-lived API key for a bearer token through the authenticate route, then mapping the label, tracking, and parcel-shop endpoints yourself. Through Jentic you install once, import DHL eCommerce from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** DHL eCommerce addresses work through request bodies and query parameters rather than resource ids in the URL path, so you limit the agent to the operations it needs, such as tracking a parcel or looking up parcel-shop locations. Label generation is a separate operation that is only available if you include it in the allowed set.
- **Credential handling:** Your DHL API key is stored once, encrypted, by your own Jentic One instance, which performs the token exchange and injects the bearer token at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a DHL eCommerce shipping label' or 'track a DHL parcel', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **DHL Shipment Tracking Unified API** — Cross-DHL global tracking surface across DHL Express, eCommerce, and others
- **DHL Tracking API** — DHL's general tracking API for shipments worldwide
- **FedEx API** — FedEx label generation and tracking for international parcels
- **AfterShip** — Multi-carrier tracking aggregation across hundreds of providers

## FAQ

### What authentication does the DHL eCommerce API use?

Authentication is HTTP bearer with a JWT. The JWT is obtained by POSTing your long-lived DHL API key to /authenticate/api-key. When the API is called through Jentic, the long-lived key is held in your Jentic One instance and the JWT exchange happens in the call layer, so the agent never sees the raw key.

### Can I create shipping labels with this API?

Yes. POST /labels with the sender, recipient, and chosen shipment option to receive a printable label PDF and a tracking reference. Use /shipment-options first to discover the valid options for the recipient address.

### What are the rate limits for the DHL eCommerce API?

The OpenAPI spec does not declare explicit rate limits. Treat the API as standard HTTPS with JWT bearer auth, respect any 429 responses with exponential backoff, and check your DHL account dashboard for the contractual ceiling.

### How do I track a parcel through Jentic?

Install the Jentic SDK with pip install jentic, search for 'track a dhl parcel', load the GET /track-trace operation, and execute it with the parcel's tracking reference. Run it through Jentic One, the self-hosted execution layer to get a Jentic agent key.

### Does this API cover Belgium as well as the Netherlands?

Yes. The api-gw.dhlparcel.nl host serves DHL eCommerce flows for the Netherlands and Belgium. Use /shipment-options with the recipient postal code and country to confirm the available delivery options for a given address.

### Can I find nearby DHL parcel shops at checkout?

Yes. GET /parcel-shop-locations returns DHL parcel shops and lockers near a postal code with their address, opening hours, and distance. Render them in a checkout map widget to let the customer choose a drop-off or pickup point.

### Can I limit what my agent is allowed to do with the DHL eCommerce API?

Yes. Because you run Jentic One yourself, your own rules decide which DHL eCommerce operations and credentials the agent may use, so you can allow only what a given agent needs, such as GET /track-trace to check a parcel or GET /parcel-shop-locations to find drop-off points. Since DHL eCommerce takes addresses through request bodies and query parameters rather than resource ids in the URL path, you scope at the operation level rather than per record. Label creation via POST /labels is a separate operation that runs only if you include it in the allowed set, so an agent built for tracking cannot generate shipments. The stored API key stays under your control and the agent only ever calls the operations you have permitted.