DHL Returns
Guide for creating DHL return labels via the DHL Returns API v1.
Overview
DHL return labels are created via a separate API (DHL Returns v1) — not through the regular Shipping API. The process therefore differs from standard label creation:
- Return labels receive their own shipment number (independent of the outbound label)
- The "shipper" for returns is the customer (who sends the item back)
- The "receiver" is your company (configured via Receiver ID)
- Optionally a QR code is generated (for paperless returns at DHL locations)
Creating a Return Label
Automatically During Label Creation
If the option Include Return Label is enabled in the DHL Setup, a return label is automatically created with every outbound shipping label.
Manually from the Shipment Label List
- Open the Shipment Labels list
- Select an existing shipment label
- Click Create Return Label
Manually via the Label Dialog
- Open the Label Dialog (Create Label)
- Enable the Include Return Label toggle
- Create the label as usual
Settings
DHL Setup — Return Configuration
| Field | Description |
|---|---|
| Include Return Label | Automatically create a return label with every outbound label |
| Retoure Receiver ID | DHL receiver ID for returns. If empty, the ISO-3 country code of the shipper is used. |
| Retoure Doc Format | Document format for return labels (PDF or ZPL2) |
| Retoure Label Print Format | Print format for return labels (can differ from outbound format) |
| Print DHL Logo (Return) | Print DHL logo on return labels |
Separate Formats
Outbound and return labels can use different formats. Typical scenario: ZPL2 on a thermal printer for fast packing, PDF on a laser printer for return slips included in the package.
API Response
On successful creation, the DHL Returns API provides:
| Field | Description |
|---|---|
| Shipment No. | Unique shipment number of the return label |
| Label (Base64) | The return label as PDF/ZPL (Base64-encoded) |
| QR Label (Base64) | QR code label for paperless returns |
| QR Link | URL to the QR code (to send to customers via email) |
| Routing Code | DHL routing code for internal forwarding |
QR Code Return (Paperless)
DHL offers paperless returns via QR codes:
- The customer receives the QR link (e.g., via email)
- At a DHL location (retail outlet, Packstation) the QR code is scanned
- The label is printed on-site — the customer doesn't need their own printer
The QR link can be retrieved from the merchantCENTRAL Activity Log or directly from the Shipment Label record.
International Returns
For international return shipments, customs data can be specified. The customs information from the original label is automatically transferred to the return request (if available).
Error Handling
| Error | Cause | Solution |
|---|---|---|
| HTTP 400 Receiver ID invalid | Invalid or missing Receiver ID | Check Receiver ID in setup or configure correct ISO-3 country code of shipper |
| HTTP 401 | Authentication failed | Check API Key (Returns API uses the same key as Shipping) |
| Weight must be positive | Weight not specified | Set weight on label or configure default weight in setup |