SendLabel API Migration

Migrating from DHL native APIs to the SendLabel API

Estimate the migration effort first, then decide between a low-change DHL compat migration or a direct move to the unified SendLabel API.

Back to help center Open API docs Open API access page

Migration summary

- If the client only creates single shipments and downloads labels, the migration is usually limited to domain, auth and a small payload mapping review.

- If the client depends on native DHL error parsing, multi-shipment requests, account-wide manifests or separate product lines, the effort increases noticeably.

- The safest path is usually to adopt SendLabel's DHL compatibility routes first and move to unified endpoints later.

Recommended migration path

- Phase 1: switch base URL, authentication headers and key routes to SendLabel.

- Phase 2: stabilize `orders / labels / senders` first so the core flow works end to end.

- Phase 3: add idempotency, error handling and reconciliation alignment, then decide whether to move to the unified API.

Common endpoint mapping

From

DHL orders

SendLabel `/api/compat/dhl-parcel-de/orders`

DHL labels

SendLabel `/api/compat/dhl-parcel-de/labels`

DHL senders

SendLabel `/api/compat/dhl-parcel-de/v1/senders`

DHL default sender

SendLabel `/api/compat/dhl-parcel-de/v1/senders/default`

DHL manifests

SendLabel `/api/compat/dhl-parcel-de/manifests`

New unified flow

SendLabel `/api/v1/shipments/import`

Migration comparison table

Use this table as a practical checklist for engineers estimating the migration work.

Topic	DHL native	SendLabel API	What the client changes
Authentication	Use DHL API credentials and DHL-native auth headers.	Switch to a SendLabel API key, usually via `Authorization: Bearer <API_KEY>`.	You must change request headers and secret management.
Base URL	Call DHL official domains.	Call the SendLabel domain instead.	Replace the base URL and keep it configurable.
Endpoint paths	Use DHL-native orders / labels / senders / manifests routes.	Prefer SendLabel DHL compatibility routes, or move directly to `/api/v1/shipments/import` for new projects.	At minimum, remap the endpoint paths.
Shipment payload	Field names, nesting and enums follow DHL-native structures.	Compatibility routes stay close to DHL, but SendLabel still normalizes input.	Usually only a small field review is needed; deep DHL-specific assumptions may need a mapping layer.
Multiple shipments per request	Client programs may submit multiple shipments in one request.	Current DHL compat `orders` is best for one-shipment mirroring; use the unified import endpoint for batch flows.	If the current client depends on multi-shipment requests, split calls or move to the unified API.
Label return format	The client may expect DHL-native label return behavior.	API clients typically consume `labelBase64`, and can still download labels later via the label endpoint.	If the client assumes a raw PDF stream, add a decode or follow-up download step.
Sender management	Use sender records managed in DHL directly.	Use SendLabel sender records, with compat sender routes to reduce migration cost.	You usually need to sync or recreate sender data and adjust default sender handling.
Manifest semantics	Some clients treat manifests as account-wide DHL artifacts.	SendLabel currently exposes manifests more from the customer/system scope.	If the client expects account-wide manifest aggregation, re-check the business expectation.
Address validation	Clients may pass raw addresses directly to DHL.	SendLabel normalizes, splits and validates addresses before shipment creation.	Address issues may surface earlier; forward validation feedback to ERP/WMS users.
Error handling	The code may depend on raw DHL error codes and payload fields.	Compatibility errors now use a dual-track structure: DHL-style fields remain where possible and a normalized `sendlabelError` block is added for standard parsing.	If the client hardcodes DHL-native error fields, it should be updated; prefer `sendlabelError` first and keep legacy-field fallback only for compatibility.
Idempotency and retries	Many clients simply retry after timeouts.	Use `Idempotency-Key` explicitly so SendLabel can handle duplicate requests safely.	Strongly recommended: add idempotency keys to the ERP/WMS request model.
Billing and invoicing	Billing may have been handled directly between the client and DHL.	After switching, shipments enter SendLabel's balance, credit-line and batched invoicing model.	The client must align with the new reconciliation and invoice cycle, especially weekly or threshold-triggered billing.
Pickup / Postnumber / Tracking	Some clients assume these capabilities are included in shipping by default.	These remain separate product-line capabilities and should not be assumed to be part of core shipping by default.	If the client relies on these APIs, confirm enablement and testing separately.

Implementation-ready endpoint comparison

This section is intended for engineers. Each row shows the recommended target route, header changes, request/response differences, and how much code usually needs to change.

Original DHL endpoint	Recommended SendLabel endpoint	Auth/header change	Request change	Response change	Code change level
POST DHL orders	POST /api/compat/dhl-parcel-de/orders	Replace DHL-native auth headers with SendLabel API key auth.	The payload shape stays broadly similar, but the current mirror supports only one shipment per request; multi-shipment clients must split calls or move to the unified API.	The response includes SendLabel compatibility metadata and local order semantics, so avoid parsing only DHL-native fields.	Medium
GET DHL labels	GET /api/compat/dhl-parcel-de/labels	Also switch to SendLabel API key auth.	Use `shipment`, `shipmentNumber`, `trackingNumber`, or `orderId` as lookup parameters.	This mirror returns a PDF stream; if the client later moves to the unified API, it may switch to `labelBase64`.	Low
GET/POST DHL manifests	GET/POST /api/compat/dhl-parcel-de/manifests	Switch to SendLabel API key auth.	Date- or shipment-based lookup still works, but the scope is customer-specific rather than account-wide.	The returned manifest document and sheet mapping remain usable, but confirm whether account-wide aggregation is still required.	Medium
GET/POST DHL senders	GET/POST /api/compat/dhl-parcel-de/v1/senders	Switch to SendLabel API key auth.	Existing sender records need to be migrated from DHL account storage into SendLabel sender records.	Responses are backed by SendLabel sender records, so do not assume keys match DHL-native sender identifiers.	Medium
POST DHL default sender	POST /api/compat/dhl-parcel-de/v1/senders/default	Switch to SendLabel API key auth.	The default sender becomes a SendLabel-side default, not the DHL account default.	The response reflects the SendLabel-side default sender selection.	Low
POST DHL batch shipment creation	POST /api/v1/shipments/import	Switch to SendLabel API key auth and require `Idempotency-Key`.	You must move from DHL-native payloads to the SendLabel unified structure, including `carrier`, `shipments[]`, address, and parcel fields.	Responses follow the unified import result model with `results[]`, execution mode, and possibly `labelBase64` or local order IDs.	High

Header examples

Getting the headers right is usually enough for the first integration round. These examples show the minimum change from DHL-native requests to SendLabel compat or unified calls.

DHL native header example

The original client usually calls DHL directly and sends DHL-native auth headers.

POST /orders HTTP/1.1
Host: api-eu.dhl.com
Content-Type: application/json
DHL-API-Key: <DHL_API_KEY>
DHL-API-Secret: <DHL_API_SECRET>

{ ... }

SendLabel compat header example

For the low-change path, switch the domain and auth to SendLabel first and keep the payload as close as possible.

POST /api/compat/dhl-parcel-de/orders HTTP/1.1
Host: api.sendlabel.example
Authorization: Bearer <SENDLABEL_API_KEY>
Content-Type: application/json
Idempotency-Key: erp-order-20260623-10001

{ ... }

SendLabel unified header example

If the client accepts a larger refactor, the unified API uses the same auth style but a different payload model.

POST /api/v1/shipments/import HTTP/1.1
Host: api.sendlabel.example
Authorization: Bearer <SENDLABEL_API_KEY>
Content-Type: application/json
Idempotency-Key: erp-order-20260623-10001

{ ... }

Before / after request examples

This section is ready to share with customer engineers. Start with compat for a low-change migration, then move to unified import if UPS and DHL should share one model later.

Example 1: DHL native single-shipment request

This is a typical starting point: submit one shipment using the DHL-native payload style.

{
  "profile": "STANDARD_GRUPPENPROFIL",
  "shipments": [
    {
      "product": "V01PAK",
      "billingNumber": "22222222220101",
      "refNo": "ERP-10001",
      "shipper": {
        "name1": "ACME GmbH",
        "addressStreet": "Musterstrasse",
        "addressHouse": "12",
        "postalCode": "53113",
        "city": "Bonn",
        "country": "DE"
      },
      "consignee": {
        "name1": "Max Mustermann",
        "addressStreet": "Hauptstrasse",
        "addressHouse": "8",
        "postalCode": "10115",
        "city": "Berlin",
        "country": "DE"
      },
      "details": {
        "weight": {
          "uom": "kg",
          "value": 1.2
        }
      }
    }
  ]
}

Example 2: minimal-change SendLabel compat request

For a low-change migration, keep the shipment structure close to DHL, switch the target route to SendLabel compat, and send one shipment per request.

{
  "profile": "STANDARD_GRUPPENPROFIL",
  "shipments": [
    {
      "product": "V01PAK",
      "billingNumber": "22222222220101",
      "refNo": "ERP-10001",
      "shipper": {
        "name1": "ACME GmbH",
        "addressStreet": "Musterstrasse",
        "addressHouse": "12",
        "postalCode": "53113",
        "city": "Bonn",
        "country": "DE"
      },
      "consignee": {
        "name1": "Max Mustermann",
        "addressStreet": "Hauptstrasse",
        "addressHouse": "8",
        "postalCode": "10115",
        "city": "Berlin",
        "country": "DE"
      },
      "details": {
        "weight": {
          "uom": "kg",
          "value": 1.2
        }
      }
    }
  ]
}

Example 3: refactored SendLabel unified request

If the client wants one structure for DHL, UPS, and other carriers, it is better to move to the unified import payload.

{
  "carrier": "dhl",
  "service": "parcel_de",
  "shipments": [
    {
      "shipper": {
        "name": "ACME GmbH",
        "address1": "Musterstrasse 12",
        "postalCode": "53113",
        "city": "Bonn",
        "countryCode": "DE"
      },
      "recipient": {
        "name": "Max Mustermann",
        "address1": "Hauptstrasse 8",
        "postalCode": "10115",
        "city": "Berlin",
        "countryCode": "DE"
      },
      "parcel": {
        "weightKg": 1.2
      },
      "references": {
        "customerReference": "ERP-10001"
      },
      "options": {
        "labelFormat": "pdf"
      }
    }
  ]
}

Example 4: key fields in the unified response

The unified response is no longer a DHL-native payload. ERP/WMS clients usually need to read the local orderId, tracking, and labelBase64 fields.

{
  "results": [
    {
      "ok": true,
      "carrier": "dhl",
      "orderId": "ord_123456",
      "trackingNumber": "00340434161234567890",
      "labelBase64": "<base64-pdf>",
      "executionMode": "sync"
    }
  ]
}

curl examples

These commands are useful for the first technical handshake. Validate auth, routes, and label download first, then update the production client code.

curl example 1: compat single-shipment creation

Best for a low-change migration. Keep the DHL-like payload shape and only switch the target route and authentication.

curl -X POST "https://api.sendlabel.example/api/compat/dhl-parcel-de/orders" \
  -H "Authorization: Bearer <SENDLABEL_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-order-20260623-10001" \
  --data @dhl-compat-order.json

curl example 2: unified import

Best for customers who want one request model for DHL, UPS, and other carriers.

curl -X POST "https://api.sendlabel.example/api/v1/shipments/import" \
  -H "Authorization: Bearer <SENDLABEL_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-order-20260623-10001" \
  --data @sendlabel-unified-order.json

curl example 3: download label by tracking number

If the client still prefers a PDF download step, keep using the compat label endpoint with a tracking number.

curl -L "https://api.sendlabel.example/api/compat/dhl-parcel-de/labels?trackingNumber=00340434161234567890" \
  -H "Authorization: Bearer <SENDLABEL_API_KEY>" \
  --output label.pdf

Example file guide

If engineers start with the curl commands on this page, this table explains what each example file is for and which endpoint it belongs to.

File name	Purpose	Applies to
dhl-compat-order.json	Used by the compat single-shipment example and keeps the DHL-like field structure.	POST /api/compat/dhl-parcel-de/orders
sendlabel-unified-order.json	Used by the unified import example and fits customers who want one UPS/DHL model.	POST /api/v1/shipments/import
label.pdf	Output file name for the compat label download example, useful for quick manual checks.	GET /api/compat/dhl-parcel-de/labels

Field mapping quick reference

This table is useful when engineers estimate the migration effort. It shows common DHL fields, how they look in compat mode, and what they usually become in unified mode.

Common DHL field	SendLabel compat	SendLabel unified	Notes
shipments[0].product	shipments[0].product	service	Compat can keep this nearly unchanged; unified switches to SendLabel service identifiers.
shipments[0].billingNumber	shipments[0].billingNumber	not passed by customer in most cases	Usually preserved in compat; unified usually does not require the client to pass a DHL billing number directly.
shipments[0].refNo	shipments[0].refNo	shipments[0].references.customerReference	Keep the customer reference, but the field path changes in unified mode.
shipments[0].shipper.name1	shipments[0].shipper.name1	shipments[0].shipper.name	Compat keeps the original shape; unified normalizes this into a generic name field.
shipments[0].shipper.addressStreet + addressHouse	shipments[0].shipper.addressStreet + addressHouse	shipments[0].shipper.address1	Unified prefers a single-line address; clients that split street and house number should merge them in a mapping layer.
shipments[0].consignee.*	shipments[0].consignee.*	shipments[0].recipient.*	The receiver object is renamed to `recipient` in unified mode.
shipments[0].details.weight.value	shipments[0].details.weight.value	shipments[0].parcel.weightKg	The weight field moves from a DHL-style nested structure into the direct parcel model.
label response document	PDF stream from labels endpoint	results[0].labelBase64	If ERP/WMS wants to avoid a separate download call, unified is better because it can return the base64 label directly.
native DHL error fields	compat response + SendLabel wrapper	unified import result/errors	Do not hardcode only DHL-native error parsing anymore; add one adaptation layer.

Success response comparison

These examples remind engineers that after migration they should not keep parsing only DHL-native success fields.

Success example 1: DHL-native style

Legacy clients often parse DHL-native shipment numbers, label documents, and status fields directly.

{
  "shipments": [
    {
      "shipmentNo": "00340434161234567890",
      "shipmentLabel": {
        "format": "PDF",
        "data": "<base64-pdf>"
      },
      "status": {
        "statusCode": 2000,
        "statusText": "OK"
      }
    }
  ]
}

Success example 2: SendLabel compat

Compat stays close to DHL semantics, but the response may also include SendLabel compatibility metadata and local order semantics.

{
  "orderId": "ord_123456",
  "trackingNumber": "00340434161234567890",
  "labelBase64": "<base64-pdf>",
  "Compatibility": {
    "provider": "DHL",
    "route": "/api/compat/dhl-parcel-de/orders"
  }
}

Success example 3: SendLabel unified

Unified no longer centers the DHL-native response and instead uses one result model for DHL, UPS, and other carriers.

{
  "results": [
    {
      "ok": true,
      "carrier": "dhl",
      "service": "parcel_de",
      "orderId": "ord_123456",
      "trackingNumber": "00340434161234567890",
      "labelBase64": "<base64-pdf>",
      "executionMode": "sync"
    }
  ]
}

Pre-cutover checklist

- Confirm whether the client starts with `DHL compat` or moves directly to the unified import API.

- Issue a test key and require `Idempotency-Key` in all non-trivial requests.

- Review sender setup, label format, address fields, reference length and error handling branches.

- If the client also depends on Pickup / Postnumber / Tracking, validate those separately.

- Run both dry run and live test before go-live, then confirm billing and invoice expectations.