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": "96",
    "version": "1.19.17"
  }
}

Orders

POST

/orders

Creates a return label by given information.

Query Parameter Name	Example
`labelType`	`BOTH`

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": "gSXfaFEuhVTxscKVF5",
  "label": {
    "b64": "09gmYwcuLaUBa1mAk6t1i1mvqhr5qz5C83PBh95W"
  },
  "qrLabel": {
    "b64": "CtacIRYQ5lLTtMDTy8SyIk5Dawth7gwjlYabmAKG"
  },
  "qrLink": "https://noxious-heartbeat.info",
  "routingCode": "VTWZhaE4674k9LcZVGZvwfbbO",
  "shipmentNo": "X6g0e4IHZ9F4k7utYM",
  "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`	`irl`
`postalCode`	`02528-2484`
`receiverId`	`84c6110b-5111-4cbc-bcce-a4a35b0cbcd1`
`billingNumber`	`0`
`maxResult`	`23663825`

Request Payload

Response Payload

[
  {
    "additionalEmailNote": "Business-focused",
    "billingNumber": "5",
    "companyAddress": {
      "addressHouse": "69276",
      "addressStreet": "Swift Ville",
      "city": "New Katrine",
      "email": "Jarrell.Ondricka35@yahoo.com",
      "name1": "Cecil Hartmann",
      "name2": "Mrs. Miriam Sipes",
      "name3": "Walter Jerde",
      "phone": "+16156857009",
      "postalCode": "97411-5152",
      "state": "Maryland"
    },
    "companyManagement": "Alex Weimann",
    "companyName": "Reinger - Johnson",
    "contactEmail": "Katelyn_Crist@hotmail.com",
    "court": "Rogahnstad",
    "ekp": "2",
    "numberRange": "99999494317C",
    "receiverAddress": {
      "addressHouse": "653",
      "addressStreet": "Gleichner Keys",
      "city": "South Noemie",
      "email": "Malcolm.Crona14@gmail.com",
      "name1": "Mr. Tommie Fritsch",
      "name2": "Charlotte Wilderman",
      "name3": "Gwen Nicolas",
      "phone": "+17944905181",
      "postalCode": "85446",
      "state": "Rhode Island"
    },
    "receiverId": "36381eee-f697-4dfb-8134-82c18e6784d6",
    "salesTaxIdentificationNumber": "ShAMRViPYci",
    "shipperCountry": "gbr"
  },
  {
    "additionalEmailNote": "Monitored",
    "billingNumber": "9",
    "companyAddress": {
      "addressHouse": "1182",
      "addressStreet": "Noe Ways",
      "city": "Fort Macieview",
      "email": "Alanis.Leffler5@gmail.com",
      "name1": "Lena Gibson",
      "name2": "Nichole Lubowitz",
      "name3": "Leland Gulgowski",
      "phone": "+18883144612",
      "postalCode": "86767",
      "state": "West Virginia"
    },
    "companyManagement": "Lance Bechtelar",
    "companyName": "Boyle Group",
    "contactEmail": "Bulah_Jakubowski@hotmail.com",
    "court": "Port Kobyburgh",
    "ekp": "9",
    "numberRange": "99999547669C",
    "receiverAddress": {
      "addressHouse": "42292",
      "addressStreet": "E Walnut Street",
      "city": "South Odellbury",
      "email": "Larissa.Dicki@hotmail.com",
      "name1": "Ms. Antonia Quigley",
      "name2": "Rudy O'Keefe",
      "name3": "Alberta Altenwerth",
      "phone": "+18584511805",
      "postalCode": "69593",
      "state": "Maryland"
    },
    "receiverId": "9c11a0a3-ec13-4580-aff0-30a893765664",
    "salesTaxIdentificationNumber": "uXWQL0FlhbG",
    "shipperCountry": "pol"
  },
  {
    "additionalEmailNote": "Persevering",
    "billingNumber": "6",
    "companyAddress": {
      "addressHouse": "92090",
      "addressStreet": "Watson Key",
      "city": "Fabiolacester",
      "email": "Rhianna66@yahoo.com",
      "name1": "Bessie Murray",
      "name2": "Dr. Leon Hoeger",
      "name3": "Mae Kohler",
      "phone": "+13358214738",
      "postalCode": "06893",
      "state": "Oregon"
    },
    "companyManagement": "Earnest Tillman-Schumm",
    "companyName": "Ullrich and Sons",
    "contactEmail": "Margot_Kuphal67@hotmail.com",
    "court": "Salvatorestead",
    "ekp": "5",
    "numberRange": "99999634267C",
    "receiverAddress": {
      "addressHouse": "247",
      "addressStreet": "Johnston Landing",
      "city": "Fort Alexane",
      "email": "Rosalia.Feil79@hotmail.com",
      "name1": "Paulette Aufderhar I",
      "name2": "Samuel McLaughlin DVM",
      "name3": "Luz Hayes DVM",
      "phone": "+17826021708",
      "postalCode": "38818",
      "state": "Illinois"
    },
    "receiverId": "2cb10a07-927f-4ab1-bc81-f9698182943d",
    "salesTaxIdentificationNumber": "9nLBorg1EHX",
    "shipperCountry": "est"
  },
  {
    "additionalEmailNote": "Customizable",
    "billingNumber": "9",
    "companyAddress": {
      "addressHouse": "970",
      "addressStreet": "Jaron Street",
      "city": "Rosemaryworth",
      "email": "Calista_Schaden@gmail.com",
      "name1": "Julia Gottlieb III",
      "name2": "Jerald Weimann II",
      "name3": "Kelvin Feest",
      "phone": "+17318559921",
      "postalCode": "12531",
      "state": "Maine"
    },
    "companyManagement": "Kara Wiza",
    "companyName": "Terry, Jast and Hamill",
    "contactEmail": "Catherine_Considine@yahoo.com",
    "court": "Hartmannfield",
    "ekp": "1",
    "numberRange": "99999894978C",
    "receiverAddress": {
      "addressHouse": "5887",
      "addressStreet": "Rusty Lakes",
      "city": "Lake Benny",
      "email": "Abe_Lakin@hotmail.com",
      "name1": "Dana Ledner",
      "name2": "Mr. Isaac Kuhn",
      "name3": "Lee Beer",
      "phone": "+13736581951",
      "postalCode": "10267",
      "state": "Oklahoma"
    },
    "receiverId": "2077ab7a-b1e2-4ad2-8944-1c0426fed9f0",
    "salesTaxIdentificationNumber": "y2tGGnBIZxF",
    "shipperCountry": "bgr"
  },
  {
    "additionalEmailNote": "Digitized",
    "billingNumber": "4",
    "companyAddress": {
      "addressHouse": "51915",
      "addressStreet": "Claud Views",
      "city": "North Carmelo",
      "email": "Kylee69@hotmail.com",
      "name1": "Kristi Kertzmann",
      "name2": "Lester Collier",
      "name3": "Kenny Reilly",
      "phone": "+18802343640",
      "postalCode": "76617-4592",
      "state": "Minnesota"
    },
    "companyManagement": "Kerry Gislason",
    "companyName": "Weissnat, Denesik and Rogahn",
    "contactEmail": "Mustafa37@hotmail.com",
    "court": "North Margot",
    "ekp": "7",
    "numberRange": "99999004672C",
    "receiverAddress": {
      "addressHouse": "1911",
      "addressStreet": "Anderson Hill",
      "city": "Walshside",
      "email": "Dixie10@hotmail.com",
      "name1": "Denise Frami",
      "name2": "Mr. Dominick Langworth",
      "name3": "Doris Pfannerstill",
      "phone": "+18698293609",
      "postalCode": "34253-1085",
      "state": "Utah"
    },
    "receiverId": "967ab3f5-69d3-46a3-89b1-2c338aeb9356",
    "salesTaxIdentificationNumber": "Ynn8UPEr2IY",
    "shipperCountry": "nld"
  },
  {
    "additionalEmailNote": "Future-proofed",
    "billingNumber": "2",
    "companyAddress": {
      "addressHouse": "39219",
      "addressStreet": "S Jefferson Street",
      "city": "Lillieborough",
      "email": "Enrique_VonRueden@gmail.com",
      "name1": "Rosemarie Mante",
      "name2": "Alberta Schmitt",
      "name3": "Leona Dickens",
      "phone": "+18873470837",
      "postalCode": "45606",
      "state": "South Carolina"
    },
    "companyManagement": "Patti Bernier",
    "companyName": "O'Conner and Sons",
    "contactEmail": "Jayce_OHara51@gmail.com",
    "court": "West Christopherhaven",
    "ekp": "4",
    "numberRange": "99999524979C",
    "receiverAddress": {
      "addressHouse": "60800",
      "addressStreet": "Hahn Union",
      "city": "Carolebury",
      "email": "Levi.Rempel@hotmail.com",
      "name1": "Archie Cummerata",
      "name2": "Francisco Torphy",
      "name3": "Peter Windler",
      "phone": "+17078768039",
      "postalCode": "08563",
      "state": "Connecticut"
    },
    "receiverId": "d4eb069a-473b-4bb0-a7f2-d4238d50dc89",
    "salesTaxIdentificationNumber": "RH82JDk6iH9",
    "shipperCountry": "irl"
  },
  {
    "additionalEmailNote": "Grass-roots",
    "billingNumber": "1",
    "companyAddress": {
      "addressHouse": "21637",
      "addressStreet": "Ryan Burgs",
      "city": "Rolfsontown",
      "email": "Angie.Jones@yahoo.com",
      "name1": "Pedro Jacobs",
      "name2": "Dolores Flatley",
      "name3": "Herman Lockman II",
      "phone": "+16998817201",
      "postalCode": "48186",
      "state": "Nevada"
    },
    "companyManagement": "Mrs. Darla Ebert",
    "companyName": "Bauch, Moen and McLaughlin",
    "contactEmail": "Dominique.Wisoky55@yahoo.com",
    "court": "Fredaton",
    "ekp": "7",
    "numberRange": "99999087952C",
    "receiverAddress": {
      "addressHouse": "9033",
      "addressStreet": "Hermiston Hill",
      "city": "Clevelandport",
      "email": "Walker_Bode@hotmail.com",
      "name1": "Gloria Dare",
      "name2": "Terence Huels",
      "name3": "Eric Shanahan",
      "phone": "+16175917815",
      "postalCode": "05870",
      "state": "Colorado"
    },
    "receiverId": "ed4bdea0-c47b-4412-9f20-fe3ec7b2cfe7",
    "salesTaxIdentificationNumber": "4GiZELAWSkN",
    "shipperCountry": "lva"
  },
  {
    "additionalEmailNote": "Universal",
    "billingNumber": "9",
    "companyAddress": {
      "addressHouse": "756",
      "addressStreet": "Osinski Ridges",
      "city": "Giovannyburgh",
      "email": "Carmella.Casper28@yahoo.com",
      "name1": "Roderick Schamberger",
      "name2": "Seth Collier",
      "name3": "Martin Abernathy DVM",
      "phone": "+17184016530",
      "postalCode": "67188",
      "state": "Massachusetts"
    },
    "companyManagement": "Jan Satterfield",
    "companyName": "Howell, Glover and Ondricka",
    "contactEmail": "Curtis65@hotmail.com",
    "court": "South Keeganworth",
    "ekp": "4",
    "numberRange": "99999217471C",
    "receiverAddress": {
      "addressHouse": "21250",
      "addressStreet": "Mireya Streets",
      "city": "Lake Lilianborough",
      "email": "Amely_Hackett@gmail.com",
      "name1": "Clifford Brekke",
      "name2": "Dr. Alison Roob",
      "name3": "Oliver Baumbach",
      "phone": "+19939449055",
      "postalCode": "56444",
      "state": "Louisiana"
    },
    "receiverId": "cb6533f2-ed79-4707-a7e7-c7ceecd6650c",
    "salesTaxIdentificationNumber": "mihXckUrgEQ",
    "shipperCountry": "grc"
  },
  {
    "additionalEmailNote": "Monitored",
    "billingNumber": "0",
    "companyAddress": {
      "addressHouse": "11763",
      "addressStreet": "Kshlerin Court",
      "city": "Port Ovaberg",
      "email": "Russ74@gmail.com",
      "name1": "Cecil Langworth",
      "name2": "Victoria Howell-Lind",
      "name3": "Leland Reinger",
      "phone": "+18264537922",
      "postalCode": "38954-9899",
      "state": "Iowa"
    },
    "companyManagement": "Cornelius Runte",
    "companyName": "Ortiz, McCullough and Hagenes",
    "contactEmail": "Gudrun37@hotmail.com",
    "court": "West Waino",
    "ekp": "3",
    "numberRange": "99999522638C",
    "receiverAddress": {
      "addressHouse": "58563",
      "addressStreet": "Schamberger Keys",
      "city": "East Domingoview",
      "email": "Modesto56@gmail.com",
      "name1": "Sandra Lowe",
      "name2": "Nichole Funk-Lynch",
      "name3": "Simon Ullrich",
      "phone": "+19696346625",
      "postalCode": "42600",
      "state": "Missouri"
    },
    "receiverId": "dcb61822-5b09-4e93-9226-bebff870ddc4",
    "salesTaxIdentificationNumber": "Mk4LfaEsEkx",
    "shipperCountry": "che"
  },
  {
    "additionalEmailNote": "Reactive",
    "billingNumber": "2",
    "companyAddress": {
      "addressHouse": "21330",
      "addressStreet": "Hermiston Road",
      "city": "West Jorgeberg",
      "email": "Schuyler_Schaefer31@hotmail.com",
      "name1": "Dr. Neil Kozey-Gleichner",
      "name2": "Lloyd Goodwin",
      "name3": "Willis Cummings",
      "phone": "+16523990640",
      "postalCode": "93743-0200",
      "state": "Montana"
    },
    "companyManagement": "Erik Walker",
    "companyName": "Williamson and Sons",
    "contactEmail": "Watson_Langworth84@hotmail.com",
    "court": "South Neva",
    "ekp": "2",
    "numberRange": "99999042420C",
    "receiverAddress": {
      "addressHouse": "459",
      "addressStreet": "Rosie Circle",
      "city": "Fort Angel",
      "email": "Foster_Beatty9@yahoo.com",
      "name1": "Nathan Hahn",
      "name2": "Miss Brandi Sauer",
      "name3": "Mamie Fadel",
      "phone": "+15766031321",
      "postalCode": "67960-9837",
      "state": "Wisconsin"
    },
    "receiverId": "5a33b55f-440a-407e-8848-8abd089778fc",
    "salesTaxIdentificationNumber": "L90MPlK5TWf",
    "shipperCountry": "bgr"
  }
]

{
  "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