DHL Parcel DE Returns Virtual Sandbox

Virtual API for generating DHL return labels and querying receiver locations.

The DHL Parcel DE Returns API allows business customers to programmatically create return labels on demand and determine receiver locations. This service supports standard RESTful interactions for order processing and location lookups, providing a reliable interface for integrating return logistics into e-commerce platforms.

Use this hosted sandbox to simulate DHL Parcel DE Returns 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 return label generation workflows, test payload structures for order creation, verify receiver location lookup responses, and handle authentication flows including API keys and OAuth2 tokens before integrating with DHL production systems.

DHL Parcel DE Returns virtual sandbox is up and running!

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

`https://dhl-parcel-returns.mock.beeceptor.com`

General

GET

/

Returns the current version of the API as major.minor.patch. Supports content negotiation (json and html) and does __not__ require authentication. This can be used as healthcheck or to identify which version of the API is being used.

Request Payload

Response Payload

{
  "amp": {
    "env": "prod",
    "name": "pp-parcel-returns",
    "rev": "62",
    "version": "3.8.17"
  }
}

Orders

POST

/orders

Creates a return label by given information.

Query Parameter Name	Example
`labelType`	`QR_LABEL`

Request Payload

{
  "receiverId": "deu",
  "customerReference": "Kundenreferenz",
  "shipmentReference": "Sendungsreferenz",
  "shipper": {
    "name1": "Absender Retoure Zeile 1",
    "name2": "Absender Retoure Zeile 2",
    "name3": "Absender Retoure Zeile 3",
    "addressStreet": "Charles-de-Gaulle Str.",
    "addressHouse": 20,
    "postalCode": 53113,
    "city": "Bonn",
    "email": "Max.Mustermann@dhl.local",
    "phone": "+49 123456789"
  },
  "itemWeight": {
    "uom": "kg",
    "value": 1
  },
  "itemValue": {
    "currency": "EUR",
    "value": 10
  }
}

Response Payload

{
  "internationalShipmentNo": "EgbfB7cvNraikFaRir",
  "label": {
    "b64": "IhkHdjsXluQrkKYtqymElvg0Qywy05aZJ4r2tob9"
  },
  "qrLabel": {
    "b64": "i5iFVg1eYGi6rxAHYhW3PSFOfyrLdoUE3efBM7oE"
  },
  "qrLink": "https://homely-provider.biz",
  "routingCode": "gKyzMY4rc2pbYqaiSV73OFD9N",
  "shipmentNo": "MgdwsZFNZc7Z5YrQQy",
  "sstatus": {
    "detail": "Created",
    "status": 201,
    "title": "Created"
  }
}

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Bad Request - The request could not be understood by the server due to malformed syntax."
}

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Unauthorized - The client could not be authenticated since the request lacks the required HTTP headers or the credentials are just wrong."
}

{
  "title": "Forbidden",
  "status": 403,
  "detail": "Forbidden - The client has successfully been authenticated but could not be authorized for the particular request."
}

{
  "title": "Unprocessable",
  "status": 422,
  "detail": "Unprocessable Entity - unable to process the content type of the request entity."
}

{
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Too Many Requests - You have exceeded the maximum number of requests per time unit."
}

Locations

GET

/locations

The response should be a list of Receiver, each containing the following information

Query Parameter Name	Example
`countryCode`	`cze`
`postalCode`	`99739`
`receiverId`	`7ef697c4-8458-4d32-91f4-9b9e487f601c`
`billingNumber`	`4`
`maxResult`	`56993907`

Request Payload

Response Payload

[
  {
    "additionalEmailNote": "Persistent",
    "billingNumber": "0",
    "companyAddress": {
      "addressHouse": "829",
      "addressStreet": "Derwent Close",
      "city": "South Eliseo",
      "email": "Anita84@hotmail.com",
      "name1": "Terry Kessler",
      "name2": "Jean Carroll",
      "name3": "Christie Larson",
      "phone": "+12737769814",
      "postalCode": "45836-7274",
      "state": "Florida"
    },
    "companyManagement": "Katie Dach",
    "companyName": "Franecki LLC",
    "contactEmail": "Bridget.Buckridge84@hotmail.com",
    "court": "Port Kirkburgh",
    "ekp": "2",
    "numberRange": "99999593208C",
    "receiverAddress": {
      "addressHouse": "4827",
      "addressStreet": "E 8th Street",
      "city": "Rafaelville",
      "email": "Kip.Thiel@gmail.com",
      "name1": "Bradley Wisozk",
      "name2": "Geoffrey Buckridge",
      "name3": "Bradford Kub",
      "phone": "+13553889615",
      "postalCode": "94306",
      "state": "Louisiana"
    },
    "receiverId": "b209db3c-279b-4416-a1f8-56b6e66fdacb",
    "salesTaxIdentificationNumber": "ZxyOjwwSc6w",
    "shipperCountry": "dnk"
  },
  {
    "additionalEmailNote": "Optimized",
    "billingNumber": "8",
    "companyAddress": {
      "addressHouse": "55504",
      "addressStreet": "Sauer Lodge",
      "city": "Elmhurst",
      "email": "Jakob73@yahoo.com",
      "name1": "Miss Renee Friesen Sr.",
      "name2": "Dennis Torp DVM",
      "name3": "Steven Goldner",
      "phone": "+17234755699",
      "postalCode": "11290",
      "state": "Michigan"
    },
    "companyManagement": "Delbert Torphy",
    "companyName": "Breitenberg, O'Keefe and Leuschke",
    "contactEmail": "Rosa_Murphy@yahoo.com",
    "court": "Gissellefort",
    "ekp": "3",
    "numberRange": "99999583514C",
    "receiverAddress": {
      "addressHouse": "2904",
      "addressStreet": "Cole Rapid",
      "city": "North Faustinochester",
      "email": "Ransom22@hotmail.com",
      "name1": "Cory Rodriguez",
      "name2": "Kristopher Welch",
      "name3": "Blake Blick",
      "phone": "+13642860333",
      "postalCode": "22714-2735",
      "state": "Colorado"
    },
    "receiverId": "1a4107e2-bd9e-4cd3-af68-ec46c07ee9b0",
    "salesTaxIdentificationNumber": "41I9Jxp3R7u",
    "shipperCountry": "prt"
  },
  {
    "additionalEmailNote": "Stand-alone",
    "billingNumber": "9",
    "companyAddress": {
      "addressHouse": "9173",
      "addressStreet": "Samanta Gardens",
      "city": "Deltona",
      "email": "Marguerite.Dicki75@gmail.com",
      "name1": "Sylvia Monahan",
      "name2": "Clifton Wolff V",
      "name3": "Reginald Balistreri",
      "phone": "+12877239042",
      "postalCode": "24494",
      "state": "Wyoming"
    },
    "companyManagement": "Omar Boyle DDS",
    "companyName": "Cruickshank - Swaniawski",
    "contactEmail": "Andrew_Strosin19@hotmail.com",
    "court": "East Creolaburgh",
    "ekp": "9",
    "numberRange": "99999787553C",
    "receiverAddress": {
      "addressHouse": "68680",
      "addressStreet": "Pouros Track",
      "city": "Stillwater",
      "email": "Reanna20@yahoo.com",
      "name1": "Lori Kihn",
      "name2": "Leah Torp",
      "name3": "Dr. John Tromp-O'Connell",
      "phone": "+17478782456",
      "postalCode": "44421-0268",
      "state": "South Carolina"
    },
    "receiverId": "3d6b41de-e421-488b-a0bc-446ea48f46fb",
    "salesTaxIdentificationNumber": "cokYQ14afXZ",
    "shipperCountry": "nor"
  },
  {
    "additionalEmailNote": "Front-line",
    "billingNumber": "7",
    "companyAddress": {
      "addressHouse": "456",
      "addressStreet": "Cole Harbor",
      "city": "Raoulmouth",
      "email": "Emerald91@hotmail.com",
      "name1": "Carla Connelly IV",
      "name2": "Otis Bode",
      "name3": "Kathleen Harber",
      "phone": "+19727691766",
      "postalCode": "96559",
      "state": "Florida"
    },
    "companyManagement": "Wilson Lueilwitz",
    "companyName": "Kiehn LLC",
    "contactEmail": "Carter63@yahoo.com",
    "court": "Madelineport",
    "ekp": "8",
    "numberRange": "99999107132C",
    "receiverAddress": {
      "addressHouse": "8918",
      "addressStreet": "Deckow Turnpike",
      "city": "West Janaefield",
      "email": "Adrienne82@gmail.com",
      "name1": "Dr. Ricardo Roberts",
      "name2": "Christopher Ruecker",
      "name3": "Carroll Tillman-Runolfsdottir",
      "phone": "+15817969645",
      "postalCode": "78414",
      "state": "South Carolina"
    },
    "receiverId": "de95a599-48dd-4297-b34d-023e512d7b51",
    "salesTaxIdentificationNumber": "552bFP96dOe",
    "shipperCountry": "hun"
  },
  {
    "additionalEmailNote": "Self-enabling",
    "billingNumber": "7",
    "companyAddress": {
      "addressHouse": "8432",
      "addressStreet": "Prospect Place",
      "city": "Joshuachester",
      "email": "Emmie.Heaney47@hotmail.com",
      "name1": "Melody Gutkowski",
      "name2": "Sherry Harvey-Dach",
      "name3": "Clara Cormier",
      "phone": "+19252025601",
      "postalCode": "42568",
      "state": "Texas"
    },
    "companyManagement": "Dr. Thomas Hegmann",
    "companyName": "Grady - Zboncak",
    "contactEmail": "Bobbie_Ankunding@hotmail.com",
    "court": "New Arloberg",
    "ekp": "0",
    "numberRange": "99999342870C",
    "receiverAddress": {
      "addressHouse": "37509",
      "addressStreet": "Mohr Terrace",
      "city": "Port Thelma",
      "email": "Lottie.Volkman83@hotmail.com",
      "name1": "Cary Raynor",
      "name2": "Jan Runolfsdottir",
      "name3": "Leah Padberg",
      "phone": "+15536597116",
      "postalCode": "88718-0955",
      "state": "Wyoming"
    },
    "receiverId": "14331310-2e26-4312-85e8-58846da3f035",
    "salesTaxIdentificationNumber": "OYk9ELHcKxh",
    "shipperCountry": "gbr"
  },
  {
    "additionalEmailNote": "Reverse-engineered",
    "billingNumber": "0",
    "companyAddress": {
      "addressHouse": "9034",
      "addressStreet": "3rd Avenue",
      "city": "Lake Lexiworth",
      "email": "Velda7@yahoo.com",
      "name1": "Dr. Glen Boehm",
      "name2": "Harvey Purdy III",
      "name3": "Denise Yost II",
      "phone": "+19852136638",
      "postalCode": "37284-7749",
      "state": "Alabama"
    },
    "companyManagement": "Sean Powlowski",
    "companyName": "Jakubowski - Stokes",
    "contactEmail": "Joelle.Pollich@gmail.com",
    "court": "East Koreystead",
    "ekp": "2",
    "numberRange": "99999266562C",
    "receiverAddress": {
      "addressHouse": "65196",
      "addressStreet": "Coty Union",
      "city": "Fernestad",
      "email": "Andres22@hotmail.com",
      "name1": "Frances Deckow II",
      "name2": "Ken Brekke Jr.",
      "name3": "Carl Parker",
      "phone": "+14486998260",
      "postalCode": "62798",
      "state": "Oregon"
    },
    "receiverId": "51e1b159-4215-4296-a7b2-3f77cbf9b149",
    "salesTaxIdentificationNumber": "3SbT2y6bOIw",
    "shipperCountry": "irl"
  },
  {
    "additionalEmailNote": "Streamlined",
    "billingNumber": "7",
    "companyAddress": {
      "addressHouse": "83546",
      "addressStreet": "Jarrell Mission",
      "city": "Lake Cyril",
      "email": "Quinten.Kshlerin@gmail.com",
      "name1": "Angela Dietrich-Kub",
      "name2": "Beulah Windler",
      "name3": "Dr. Luke Mayert",
      "phone": "+16597769440",
      "postalCode": "58735-8076",
      "state": "North Carolina"
    },
    "companyManagement": "Gilberto Collins",
    "companyName": "Lubowitz - O'Hara",
    "contactEmail": "Jacquelyn_Beier@gmail.com",
    "court": "Carriebury",
    "ekp": "7",
    "numberRange": "99999385449C",
    "receiverAddress": {
      "addressHouse": "618",
      "addressStreet": "Verda Alley",
      "city": "West Alison",
      "email": "Boyd.Grady@yahoo.com",
      "name1": "Carolyn Shields",
      "name2": "Ronald Dickens",
      "name3": "Gregory Rohan",
      "phone": "+19399284856",
      "postalCode": "72444-2566",
      "state": "Utah"
    },
    "receiverId": "b0358c24-dc35-4d6d-a5e7-c67bdfb79ea7",
    "salesTaxIdentificationNumber": "ZnDDDD10loo",
    "shipperCountry": "nor"
  },
  {
    "additionalEmailNote": "User-friendly",
    "billingNumber": "4",
    "companyAddress": {
      "addressHouse": "564",
      "addressStreet": "Cordell Run",
      "city": "North Yazminview",
      "email": "Christian_Russel@hotmail.com",
      "name1": "Vanessa Jacobson",
      "name2": "Dr. Linda Johnson Jr.",
      "name3": "Jimmy Kassulke",
      "phone": "+16225548161",
      "postalCode": "94713-5350",
      "state": "Iowa"
    },
    "companyManagement": "Angelica Rice",
    "companyName": "Huel Group",
    "contactEmail": "Peyton38@yahoo.com",
    "court": "Emilefort",
    "ekp": "9",
    "numberRange": "99999621637C",
    "receiverAddress": {
      "addressHouse": "5285",
      "addressStreet": "Pleasant Street",
      "city": "Camarillo",
      "email": "Erwin.Beatty@gmail.com",
      "name1": "Roberto Yost",
      "name2": "Mamie Tremblay",
      "name3": "Noah Streich Sr.",
      "phone": "+17812936364",
      "postalCode": "91422-7537",
      "state": "Kansas"
    },
    "receiverId": "a41a2baf-b3d9-456f-9418-5f9527180691",
    "salesTaxIdentificationNumber": "eVt7vrhhlMa",
    "shipperCountry": "pol"
  },
  {
    "additionalEmailNote": "Implemented",
    "billingNumber": "8",
    "companyAddress": {
      "addressHouse": "8923",
      "addressStreet": "Zieme Unions",
      "city": "South Rickychester",
      "email": "Dale26@yahoo.com",
      "name1": "Yvonne Wunsch-Bins",
      "name2": "Mathew Mills",
      "name3": "Pablo Funk",
      "phone": "+18128733241",
      "postalCode": "17568-1484",
      "state": "Utah"
    },
    "companyManagement": "Mattie Sporer PhD",
    "companyName": "Zieme, Predovic and Sawayn",
    "contactEmail": "Gregorio.Boyle@gmail.com",
    "court": "Lake Bettyehaven",
    "ekp": "9",
    "numberRange": "99999016608C",
    "receiverAddress": {
      "addressHouse": "182",
      "addressStreet": "Morissette Lodge",
      "city": "Shawnberg",
      "email": "Lonnie.Tillman46@hotmail.com",
      "name1": "Mrs. Edna Altenwerth",
      "name2": "Meghan Koepp V",
      "name3": "Miriam Crist",
      "phone": "+13437988537",
      "postalCode": "15716-9003",
      "state": "Texas"
    },
    "receiverId": "a13c8a88-62c3-4482-8cf7-5973e876f8f1",
    "salesTaxIdentificationNumber": "ZBu0oJuArYM",
    "shipperCountry": "cyp"
  },
  {
    "additionalEmailNote": "Business-focused",
    "billingNumber": "3",
    "companyAddress": {
      "addressHouse": "64600",
      "addressStreet": "McKenzie Pike",
      "city": "Hintzborough",
      "email": "Graham.Smith49@hotmail.com",
      "name1": "Mr. Dustin Harvey",
      "name2": "Mrs. Crystal Stroman DDS",
      "name3": "Elena Towne",
      "phone": "+15334520958",
      "postalCode": "48112-4587",
      "state": "South Dakota"
    },
    "companyManagement": "Chelsea Vandervort Sr.",
    "companyName": "Hermann Inc",
    "contactEmail": "Dawn.Breitenberg@hotmail.com",
    "court": "Lawrence",
    "ekp": "6",
    "numberRange": "99999055045C",
    "receiverAddress": {
      "addressHouse": "921",
      "addressStreet": "E Grand Avenue",
      "city": "Rosalynmouth",
      "email": "Rhiannon.Raynor@hotmail.com",
      "name1": "Dr. Benny Block",
      "name2": "Floyd Hand",
      "name3": "Abel McClure IV",
      "phone": "+19715494400",
      "postalCode": "78184",
      "state": "New Mexico"
    },
    "receiverId": "d71c149c-f496-42fa-ba20-54706888b8c9",
    "salesTaxIdentificationNumber": "V5qNIE9hVVI",
    "shipperCountry": "pol"
  }
]

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Bad Request - The request could not be understood by the server due to malformed syntax."
}

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Unauthorized - The client could not be authenticated since the request lacks the required HTTP headers or the credentials are just wrong."
}

{
  "title": "Forbidden",
  "status": 403,
  "detail": "Forbidden - The client has successfully been authenticated but could not be authorized for the particular request."
}

{
  "title": "Unprocessable",
  "status": 422,
  "detail": "Unprocessable Entity - unable to process the content type of the request entity."
}

{
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Too Many Requests - You have exceeded the maximum number of requests per time unit."
}

Service Homepage: developer.dhl.com/api-reference/dhl-parcel-de-returns-post-parcel-germany#reference-docs-section

dhllogisticsshippingreturnsparcel