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
From the Sales Return Order
The usual route when a customer asks for a return and you record it as a sales return order:
- Open the sales return order.
- On the Home tab, choose Create Return Label.
The shipper is the customer: its sell-to address is used. When the return order names a Ship-to Code of the customer, that alternative address of the customer is used instead. The ship-to fields of the return order itself are ignored - on return orders Business Central fills them with your own location or company address, the receiver of the return. The weight follows from the Return Qty. to Receive of the item lines. Which carrier takes the return is decided by the Shipping Agent Code of the return order. Without one, or when its provider cannot create return labels, the provider in the Default Shipment Provider Code field of the merchantCENTRAL setup is used, otherwise the only enabled provider that supports return labels. When several providers are still possible, you choose one from a list.
The label keeps the number of the sales return order. It appears in the Return Labels FactBox of the return order, and DHL receives the return order number as the shipment reference, so it shows in the DHL business customer portal as well. When the return receipt is posted, the tracking number is kept as Return Tracking No. on the posted return receipt.
Second label
If the return order already has a return label, merchantCENTRAL asks before creating a second one: every label is a shipment of its own that DHL charges for.
When the Return Is Delivered
Tracking follows return labels like any other shipment. What happens once DHL reports the return parcel as delivered to you is set in the merchantCENTRAL Setup, FastTab Shipment Label Defaults, field On Return Delivered:
| Value | Effect |
|---|---|
| No Action | Only the delivery status of the label changes. This is the default. |
| Notify | The sales return order shows Return Delivered At, and the dashboard counts "returns delivered, not yet received" until goods are received on the return order. |
| Create Warehouse Receipt | As Notify, and the warehouse receipt of the return order is created where its location requires one. The return order has to be released for that. |
A job queue entry, created when you switch the setting on, does the work. Whatever could not be handled is listed in Delivered Returns and can be retried there.
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 |