DHL Label API Virtual Sandbox

Create domestic and international shipping labels for DHL eCommerce services.

The DHL Label API enables developers to generate shipping labels for domestic and international shipments. It supports various product IDs including Ground Advantage, Bounded Printed Matter, and Parcel Select. The API handles complex requirements like APO/FPO/DPO customs documentation and provides integrated shipping labels with customs forms.

Use this hosted sandbox to simulate DHL Label API APIs without authentication, API keys, or extra dependencies. Point your code or SDK to the Beeceptor base URL, preferably through an environment variable or feature flag, and switch back to the production API when ready. This keeps your integration code consistent across local development, QA, demos, and production.

Use cases:

Use this sandbox to validate shipping label request payloads, verify mandatory field requirements for different product IDs, test customs declaration structures for international and APO/FPO/DPO shipments, and handle label generation responses before integrating with DHL production systems.

DHL Label API virtual sandbox is up and running!

Use this sandbox URL as the API base in your code to simulate DHL Label API responses instantly.

`https://dhl-label-api.mock.beeceptor.com`

Label(3 operations)

POST

/shipping/v4/label

Use this request to create a single label for any US Domestic or International Product. Here's the minimum information you need to generate a label: - Your pickup Account number - Distribution Center - Ordered Product ID - Consignee Address - Return Address - Unique Package Id - Weight and Weight U

Query Parameter Name	Example
`format`*	`PDF`

Header Name	Example
`User-Agent`	`"esse labore minim aute"`

Request Payload

{
  "pickup": "5234567",
  "distributionCenter": "USRDU1",
  "orderedProductId": "GND",
  "consigneeAddress": {
    "name": "John Doe",
    "companyName": "Doe Inc.",
    "address1": "5923 Peachtree Industrial Blvd",
    "address2": "Suite 100",
    "city": "Norcross",
    "state": "GA",
    "country": "US",
    "postalCode": "30024",
    "email": "2@y.com",
    "phone": "44423440348",
    "deliveryInstructions": "Enter your instructions",
    "isBusiness": false,
    "idNumber": "S85795ED4",
    "idType": 1,
    "taxId": "90000230082958130",
    "taxIdType": 1
  },
  "returnAddress": {
    "name": "Dave Bloggs",
    "companyName": "Joe Inc.",
    "address1": "4552 OLD DIXIE HWY",
    "address2": "Near Pixar road",
    "address3": "Pixar",
    "city": "Baltimore",
    "state": "MD",
    "country": "US",
    "postalCode": "30024",
    "email": "2@y.com",
    "phone": "44423440348"
  },
  "packageDetail": {
    "packageId": "V4-TET-100397983738",
    "packageDescription": "test package desc",
    "packageReference": "test",
    "orderSource": "www.shopify.com",
    "contentCategory": "01",
    "weight": {
      "value": 10,
      "unitOfMeasure": "OZ"
    },
    "service": "DELCON",
    "serviceEndorsement": "1",
    "billingReference1": "test bill ref 1",
    "billingReference2": "test bill ref 2",
    "customLabelText1": "sampletext1",
    "customLabelText2": "sampletext2",
    "shippingCost": {
      "currency": "USD",
      "freight": 4,
      "declaredValue": 50,
      "insuredValue": 50,
      "tax": 10
    }
  }
}

Response Payload

{
  "timestamp": "2026-01-10T21:53:16.735Z",
  "pickup": "5234567",
  "distributionCenter": "USRDU1",
  "labels": [
    {
      "createdOn": "2026-01-10T21:51:34.000Z",
      "packageId": "V4-TEST-1581371343739",
      "dhlPackageId": "3387191106122423",
      "trackingId": "420300249374869903500011991305",
      "labelData": "iVBORw0KGgoAAAANSUhEUgAAAywAAATCAQAAAAB3HF9MAAAV...",
      "encodeType": "BASE64",
      "format": "PNG",
      "link": "https://api-sandbox.dhlecs.com/shipping/v4/label/pickup-identifier-example?packageId=V4-TEST-1586965592482",
      "labelDetail": {
        "serviceLevel": "GRD",
        "outboundSortCode": "62",
        "sortingSetupVersion": "1",
        "inboundSortCode": "n59",
        "serviceEndorsement": "1",
        "intendedReceivingFacility": "USRDU1",
        "mailBanner": "USPS PARCEL SELECT",
        "customsDetailsProvided": false
      }
    }
  ],
  "orderedProductId": "GND"
}

{
  "invalidParams": [
    {
      "name": "packageId",
      "reason": "packageId, dhlPackageId, or dhlTrackingNumber is required as query param"
    },
    {
      "name": "packageId",
      "reason": "packageId, dhlPackageId, or dhlTrackingNumber is required as query param"
    },
    {
      "name": "packageId",
      "reason": "packageId, dhlPackageId, or dhlTrackingNumber is required as query param"
    }
  ],
  "title": "Missing Query Param",
  "type": "https://api-sandbox.dhlecs.com/docs/errors/400.0000001"
}

{
  "title": "No credentials provided",
  "type": "https://api-sandbox.dhlecs.com/docs/errors/401.0000008"
}

{
  "title": "HTTP method not allowed",
  "type": "https://api-sandbox.dhlecs.com/docs/errors/405.0000001"
}

{
  "title": "Internal gateway server error",
  "type": "https://api-sandbox.dhlecs.com/docs/errors/500.0000002"
}

GET

/shipping/v4/label/{pickup}

Use this request to retrieve an existing label that was generated in the last 7 days. You can retrieve a label using either packageId or dhlPackageId. You cannot GET a label if it has been voided. The response is exactly the same as the Create Label response. Request Description AUTHORIZATION Be

Query Parameter Name	Example
`packageId`	`V4-TEST-1586965592482`
`dhlPackageId`	`minim repreh`

Header Name	Example
`User-Agent`	`"ad culpa cillum"`

Request Payload

Response Payload

{
  "distributionCenter": "USLAX1",
  "labels": [
    {
      "createdOn": "2025-12-15T15:38:07.0Z",
      "dhlPackageId": "6101211207915799",
      "encodeType": "PLAIN",
      "format": "ZPL",
      "labelData": "^XA\n^CI28\n^PW812\n^FO1,1^GB200,200,4,B^FS\n...",
      "labelDetail": {
        "customsDetailsProvided": true,
        "inboundSortCode": "Y54",
        "intendedReceivingFacility": "ATL",
        "mailBanner": "USPS PARCEL SELECT",
        "outboundSortCode": "61",
        "serviceEndorsement": "1",
        "serviceLevel": "GRD",
        "sortingSetupVersion": "7"
      },
      "link": "https://api.dhlecs.com/shipping/v4/label/5326755?packageId=511TESTPACK1",
      "packageId": "511TESTPACK1",
      "trackingId": "420300249261210000000954273699"
    },
    {
      "createdOn": "2025-12-15T15:38:07.0Z",
      "dhlPackageId": "6101211207915799",
      "encodeType": "PLAIN",
      "format": "ZPL",
      "labelData": "^XA\n^CI28\n^PW812\n^FO1,1^GB200,200,4,B^FS\n...",
      "labelDetail": {
        "customsDetailsProvided": true,
        "inboundSortCode": "Y54",
        "intendedReceivingFacility": "ATL",
        "mailBanner": "USPS PARCEL SELECT",
        "outboundSortCode": "61",
        "serviceEndorsement": "1",
        "serviceLevel": "GRD",
        "sortingSetupVersion": "7"
      },
      "link": "https://api.dhlecs.com/shipping/v4/label/5326755?packageId=511TESTPACK1",
      "packageId": "511TESTPACK1",
      "trackingId": "420300249261210000000954273699"
    },
    {
      "createdOn": "2025-12-15T15:38:07.0Z",
      "dhlPackageId": "6101211207915799",
      "encodeType": "PLAIN",
      "format": "ZPL",
      "labelData": "^XA\n^CI28\n^PW812\n^FO1,1^GB200,200,4,B^FS\n...",
      "labelDetail": {
        "customsDetailsProvided": true,
        "inboundSortCode": "Y54",
        "intendedReceivingFacility": "ATL",
        "mailBanner": "USPS PARCEL SELECT",
        "outboundSortCode": "61",
        "serviceEndorsement": "1",
        "serviceLevel": "GRD",
        "sortingSetupVersion": "7"
      },
      "link": "https://api.dhlecs.com/shipping/v4/label/5326755?packageId=511TESTPACK1",
      "packageId": "511TESTPACK1",
      "trackingId": "420300249261210000000954273699"
    },
    {
      "createdOn": "2025-12-15T15:38:07.0Z",
      "dhlPackageId": "6101211207915799",
      "encodeType": "PLAIN",
      "format": "ZPL",
      "labelData": "^XA\n^CI28\n^PW812\n^FO1,1^GB200,200,4,B^FS\n...",
      "labelDetail": {
        "customsDetailsProvided": true,
        "inboundSortCode": "Y54",
        "intendedReceivingFacility": "ATL",
        "mailBanner": "USPS PARCEL SELECT",
        "outboundSortCode": "61",
        "serviceEndorsement": "1",
        "serviceLevel": "GRD",
        "sortingSetupVersion": "7"
      },
      "link": "https://api.dhlecs.com/shipping/v4/label/5326755?packageId=511TESTPACK1",
      "packageId": "511TESTPACK1",
      "trackingId": "420300249261210000000954273699"
    },
    {
      "createdOn": "2025-12-15T15:38:07.0Z",
      "dhlPackageId": "6101211207915799",
      "encodeType": "PLAIN",
      "format": "ZPL",
      "labelData": "^XA\n^CI28\n^PW812\n^FO1,1^GB200,200,4,B^FS\n...",
      "labelDetail": {
        "customsDetailsProvided": true,
        "inboundSortCode": "Y54",
        "intendedReceivingFacility": "ATL",
        "mailBanner": "USPS PARCEL SELECT",
        "outboundSortCode": "61",
        "serviceEndorsement": "1",
        "serviceLevel": "GRD",
        "sortingSetupVersion": "7"
      },
      "link": "https://api.dhlecs.com/shipping/v4/label/5326755?packageId=511TESTPACK1",
      "packageId": "511TESTPACK1",
      "trackingId": "420300249261210000000954273699"
    }
  ],
  "orderedProductId": "GND",
  "pickup": "5326755",
  "timestamp": "2025-12-15T15:38:07.0Z"
}

{
  "invalidParams": [
    {
      "name": "packageId",
      "reason": "packageId V4-TEST-1742404129495 not found"
    }
  ],
  "title": "Query parameter value could not be found or is invalid",
  "type": "https://api-sandbox.dhlecs.com/docs/errors/400.0000002"
}

{
  "title": "No credentials provided",
  "type": "https://api-sandbox.dhlecs.com/docs/errors/401.0000008"
}

{
  "title": "Internal gateway server error",
  "type": "https://api-sandbox.dhlecs.com/docs/errors/500.0000002"
}

DELETE

/shipping/v4/label/{pickup}

Use this request to void an existing label that was generated in the last 45 days. You can void a Domestic existing label using one of the following package identifiers: - `packageId` - `dhlPackageId` The response will return a 200 once the label has been voided correctly. There are a few reason

Query Parameter Name	Example
`packageId`*	`V4-TEST-1586965592482`
`dhlPackageId`	`eiusm`

Header Name	Example
`User-Agent`	`"ut"`

Request Payload

Response Payload

Missing schema or example in the OpenAPI spec.
Update the definition and recreate the mock server.

{
  "invalidParams": [
    {
      "name": "packageId",
      "reason": "packageId, dhlPackageId, or dhlTrackingNumber is required as query param"
    },
    {
      "name": "packageId",
      "reason": "packageId, dhlPackageId, or dhlTrackingNumber is required as query param"
    },
    {
      "name": "packageId",
      "reason": "packageId, dhlPackageId, or dhlTrackingNumber is required as query param"
    }
  ],
  "title": "Missing Query Param",
  "type": "https://api-sandbox.dhlecs.com/docs/errors/400.0000001"
}

{
  "title": "No credentials provided",
  "type": "https://api-sandbox.dhlecs.com/docs/errors/401.0000008"
}

Service Homepage: developer.dhl.com/api-reference/label-dhl-ecommerce-americas#reference-docs-section

dhlshippinglogisticsecommercelabels