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": "dev",
    "name": "pp-parcel-returns",
    "rev": "69",
    "version": "2.18.7"
  }
}

Orders

POST

/orders

Creates a return label by given information.

Query Parameter Name	Example
`labelType`	`SHIPMENT_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": "SSSiERdiglVz7qhY9E",
  "label": {
    "b64": "gtgbWYPSvzbHTWDeXulP1b6Pg0cOWDNXsuaw2K42"
  },
  "qrLabel": {
    "b64": "sFoN7h6IH5wOn67lcyimjq0FLEal0DwMej1d8cGF"
  },
  "qrLink": "https://beloved-curl.biz",
  "routingCode": "Z3atC443Mqtx5ORCdSogt2Vs7",
  "shipmentNo": "als8w9xI5Hr5hrTqIq",
  "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`	`svk`
`postalCode`	`19220-8550`
`receiverId`	`b0186078-837c-4495-af86-7f8bb393777d`
`billingNumber`	`8`
`maxResult`	`26305803`

Request Payload

Response Payload

[
  {
    "additionalEmailNote": "Business-focused",
    "billingNumber": "0",
    "companyAddress": {
      "addressHouse": "735",
      "addressStreet": "Ivah Bridge",
      "city": "Lake Troy",
      "email": "Cedrick73@gmail.com",
      "name1": "Guillermo Effertz",
      "name2": "Wesley Runte",
      "name3": "Ryan Erdman Jr.",
      "phone": "+16478305425",
      "postalCode": "54324",
      "state": "Rhode Island"
    },
    "companyManagement": "Cheryl Smith",
    "companyName": "Torphy Inc",
    "contactEmail": "Mose14@gmail.com",
    "court": "South Brianne",
    "ekp": "7",
    "numberRange": "99999399375C",
    "receiverAddress": {
      "addressHouse": "542",
      "addressStreet": "Belle Circles",
      "city": "Port Oda",
      "email": "Ova.Johnston@hotmail.com",
      "name1": "Ms. Darla Swift",
      "name2": "Ted D'Amore",
      "name3": "Dr. Alberto Corkery",
      "phone": "+13379694551",
      "postalCode": "91004-9305",
      "state": "West Virginia"
    },
    "receiverId": "86e12520-6e82-4371-a705-6cf54b843ee4",
    "salesTaxIdentificationNumber": "dWsb10tiSO8",
    "shipperCountry": "cze"
  },
  {
    "additionalEmailNote": "Triple-buffered",
    "billingNumber": "9",
    "companyAddress": {
      "addressHouse": "144",
      "addressStreet": "Rippin Dam",
      "city": "West Aryanna",
      "email": "Stephanie_Lehner31@gmail.com",
      "name1": "Edith Homenick",
      "name2": "Andrew Brekke",
      "name3": "Whitney Dare",
      "phone": "+17419382330",
      "postalCode": "08894",
      "state": "Iowa"
    },
    "companyManagement": "Debbie Beahan",
    "companyName": "Tromp - Pfeffer",
    "contactEmail": "Jasmin_Kuhlman77@gmail.com",
    "court": "Lake Jennyferberg",
    "ekp": "3",
    "numberRange": "99999032364C",
    "receiverAddress": {
      "addressHouse": "2085",
      "addressStreet": "Bethany Flats",
      "city": "North Christophe",
      "email": "Franz22@hotmail.com",
      "name1": "Dr. Grady Rutherford",
      "name2": "Regina Jakubowski",
      "name3": "Grady Weissnat I",
      "phone": "+19518161976",
      "postalCode": "23610",
      "state": "North Dakota"
    },
    "receiverId": "255fab1d-a102-4e08-ae7f-8242ddab002a",
    "salesTaxIdentificationNumber": "KaGiTGQSPCy",
    "shipperCountry": "nor"
  },
  {
    "additionalEmailNote": "Monitored",
    "billingNumber": "3",
    "companyAddress": {
      "addressHouse": "652",
      "addressStreet": "Jeffry Route",
      "city": "Oleland",
      "email": "Murphy.Gutmann85@gmail.com",
      "name1": "Loretta Mertz",
      "name2": "Gordon Gerhold II",
      "name3": "Mr. Steve Kling",
      "phone": "+14429533450",
      "postalCode": "73121-1738",
      "state": "California"
    },
    "companyManagement": "Sheila Lockman",
    "companyName": "Purdy - Orn",
    "contactEmail": "Micheal_Cruickshank@yahoo.com",
    "court": "South Destanyland",
    "ekp": "9",
    "numberRange": "99999176175C",
    "receiverAddress": {
      "addressHouse": "4261",
      "addressStreet": "Francesca Shore",
      "city": "Lake Judge",
      "email": "Giovanni_Wolff83@hotmail.com",
      "name1": "Dr. Karl Fay",
      "name2": "Tom Schmitt",
      "name3": "Christy Little",
      "phone": "+14188312985",
      "postalCode": "31277",
      "state": "North Carolina"
    },
    "receiverId": "b66375f1-f95a-40c8-bb13-97a9d65c3adf",
    "salesTaxIdentificationNumber": "019O4oAj9yo",
    "shipperCountry": "mlt"
  },
  {
    "additionalEmailNote": "Smart",
    "billingNumber": "0",
    "companyAddress": {
      "addressHouse": "437",
      "addressStreet": "The Maltings",
      "city": "Hilpertmouth",
      "email": "Sincere_Cremin22@gmail.com",
      "name1": "Percy Volkman",
      "name2": "Jasmine McLaughlin",
      "name3": "Janie Bernhard",
      "phone": "+18783092202",
      "postalCode": "68886",
      "state": "Indiana"
    },
    "companyManagement": "Annie Hackett",
    "companyName": "Spencer - Smith",
    "contactEmail": "Melissa45@yahoo.com",
    "court": "Noblesville",
    "ekp": "6",
    "numberRange": "99999855474C",
    "receiverAddress": {
      "addressHouse": "908",
      "addressStreet": "Erling Points",
      "city": "Bradlyboro",
      "email": "Candelario56@yahoo.com",
      "name1": "Dr. Travis Anderson",
      "name2": "Luke Gusikowski",
      "name3": "Malcolm Runolfsson",
      "phone": "+13575371680",
      "postalCode": "98788-3465",
      "state": "Iowa"
    },
    "receiverId": "cc0621d5-2609-4d63-a01d-a11e2b3273ad",
    "salesTaxIdentificationNumber": "XjE47VOBGZy",
    "shipperCountry": "rou"
  },
  {
    "additionalEmailNote": "Persevering",
    "billingNumber": "0",
    "companyAddress": {
      "addressHouse": "28662",
      "addressStreet": "Reilly Loop",
      "city": "Stratford",
      "email": "Arthur.Towne@hotmail.com",
      "name1": "Esther Hickle",
      "name2": "Lena Johnson",
      "name3": "Geoffrey Pouros",
      "phone": "+17092984533",
      "postalCode": "63811",
      "state": "Vermont"
    },
    "companyManagement": "Darrel Miller II",
    "companyName": "Cormier, Feest and Marks",
    "contactEmail": "Yasmine.McCullough@gmail.com",
    "court": "Fort Cyrus",
    "ekp": "2",
    "numberRange": "99999737392C",
    "receiverAddress": {
      "addressHouse": "9288",
      "addressStreet": "Hudson View",
      "city": "Maximilliantown",
      "email": "Filomena.Denesik@hotmail.com",
      "name1": "Salvatore Leffler",
      "name2": "Henry Bauch",
      "name3": "Bernadette Moen",
      "phone": "+16419771760",
      "postalCode": "20175",
      "state": "Idaho"
    },
    "receiverId": "ef2a6a06-ce14-48ba-a5d6-a8fe7e1871e6",
    "salesTaxIdentificationNumber": "Zsn7K2erPee",
    "shipperCountry": "deu"
  },
  {
    "additionalEmailNote": "Universal",
    "billingNumber": "5",
    "companyAddress": {
      "addressHouse": "43152",
      "addressStreet": "Dandre Trafficway",
      "city": "North Ada",
      "email": "Anna85@gmail.com",
      "name1": "Carrie Pfannerstill",
      "name2": "Nathaniel Ferry",
      "name3": "Ginger Stoltenberg",
      "phone": "+14843612685",
      "postalCode": "59959",
      "state": "Delaware"
    },
    "companyManagement": "Marie Daniel",
    "companyName": "Farrell - Rohan",
    "contactEmail": "Liza80@gmail.com",
    "court": "North Lea",
    "ekp": "6",
    "numberRange": "99999614745C",
    "receiverAddress": {
      "addressHouse": "88824",
      "addressStreet": "Lubowitz Square",
      "city": "Memphis",
      "email": "Madelynn.Lueilwitz87@hotmail.com",
      "name1": "Rita Borer",
      "name2": "Darla Johns-Satterfield",
      "name3": "Rose Wuckert",
      "phone": "+13423755231",
      "postalCode": "16284",
      "state": "Connecticut"
    },
    "receiverId": "2cbefe15-35fc-4738-ab7c-642be03c73ae",
    "salesTaxIdentificationNumber": "IVfeVhl5OVk",
    "shipperCountry": "lux"
  },
  {
    "additionalEmailNote": "Stand-alone",
    "billingNumber": "1",
    "companyAddress": {
      "addressHouse": "3806",
      "addressStreet": "Beach Road",
      "city": "Lake Robb",
      "email": "Pierre26@hotmail.com",
      "name1": "Ramona Gerhold",
      "name2": "Gail Schroeder",
      "name3": "Glenda Langosh",
      "phone": "+14423384507",
      "postalCode": "00604",
      "state": "Kansas"
    },
    "companyManagement": "Jennie Erdman",
    "companyName": "Harris, Nolan and Borer",
    "contactEmail": "Oran.Walsh@hotmail.com",
    "court": "New Hester",
    "ekp": "9",
    "numberRange": "99999899522C",
    "receiverAddress": {
      "addressHouse": "1602",
      "addressStreet": "Sycamore Street",
      "city": "Royberg",
      "email": "Lesly25@gmail.com",
      "name1": "Shannon Mante",
      "name2": "Diana Paucek",
      "name3": "Phil Wunsch",
      "phone": "+12984367702",
      "postalCode": "74145-2371",
      "state": "Connecticut"
    },
    "receiverId": "ac035998-a377-4ee6-a2ad-7e9545a52096",
    "salesTaxIdentificationNumber": "OOIJZcS2ILp",
    "shipperCountry": "bel"
  },
  {
    "additionalEmailNote": "Decentralized",
    "billingNumber": "0",
    "companyAddress": {
      "addressHouse": "1034",
      "addressStreet": "Bertram Camp",
      "city": "Norwalk",
      "email": "Leo.Johns@hotmail.com",
      "name1": "Alan Legros",
      "name2": "Blanca Stehr",
      "name3": "Ethel Keeling",
      "phone": "+14505363533",
      "postalCode": "79396-0958",
      "state": "Vermont"
    },
    "companyManagement": "Mabel Luettgen",
    "companyName": "Crooks - Cremin",
    "contactEmail": "Nedra56@yahoo.com",
    "court": "Fort Sadiefield",
    "ekp": "9",
    "numberRange": "99999741108C",
    "receiverAddress": {
      "addressHouse": "44829",
      "addressStreet": "Deckow Avenue",
      "city": "Earlland",
      "email": "Jarrod_Lynch45@yahoo.com",
      "name1": "Lora Lowe",
      "name2": "Sherri Stracke",
      "name3": "Everett Flatley Sr.",
      "phone": "+12067509544",
      "postalCode": "19121",
      "state": "Idaho"
    },
    "receiverId": "6212c992-1542-4e33-9a7a-1f3183048c57",
    "salesTaxIdentificationNumber": "mQQOqpBu36y",
    "shipperCountry": "lva"
  },
  {
    "additionalEmailNote": "Optimized",
    "billingNumber": "0",
    "companyAddress": {
      "addressHouse": "740",
      "addressStreet": "St John's Road",
      "city": "Lake Filiberto",
      "email": "Ubaldo1@gmail.com",
      "name1": "Wade Rippin",
      "name2": "Eula Moore V",
      "name3": "Katherine Bartell",
      "phone": "+19989935185",
      "postalCode": "69466",
      "state": "Rhode Island"
    },
    "companyManagement": "Carla Schuster",
    "companyName": "Renner, Renner and Vandervort",
    "contactEmail": "Doris_Gerhold@gmail.com",
    "court": "Wiltonport",
    "ekp": "2",
    "numberRange": "99999264943C",
    "receiverAddress": {
      "addressHouse": "355",
      "addressStreet": "3rd Street",
      "city": "Presleyport",
      "email": "Ferne_Cronin36@gmail.com",
      "name1": "Mercedes Dare",
      "name2": "Frances Heller",
      "name3": "Gladys Friesen",
      "phone": "+13868639459",
      "postalCode": "89937-6951",
      "state": "Texas"
    },
    "receiverId": "b748184b-3f18-426b-adc3-276920a91204",
    "salesTaxIdentificationNumber": "8gfQ0iYqvrN",
    "shipperCountry": "swe"
  },
  {
    "additionalEmailNote": "Configurable",
    "billingNumber": "2",
    "companyAddress": {
      "addressHouse": "221",
      "addressStreet": "Albert Road",
      "city": "Port Vallieville",
      "email": "Joaquin_Rogahn43@hotmail.com",
      "name1": "Mrs. Kimberly Kuhlman",
      "name2": "Rosie Lockman IV",
      "name3": "Mr. Jesse Konopelski MD",
      "phone": "+13302226422",
      "postalCode": "20212",
      "state": "Tennessee"
    },
    "companyManagement": "Jennie Mertz",
    "companyName": "Ernser, Zboncak and Walker",
    "contactEmail": "Madaline.Jakubowski@yahoo.com",
    "court": "South Leopold",
    "ekp": "6",
    "numberRange": "99999778763C",
    "receiverAddress": {
      "addressHouse": "15073",
      "addressStreet": "E 10th Street",
      "city": "New Paulaberg",
      "email": "Elna69@hotmail.com",
      "name1": "Sue Flatley",
      "name2": "Linda McKenzie",
      "name3": "Katherine Howell",
      "phone": "+13789465393",
      "postalCode": "35537",
      "state": "Montana"
    },
    "receiverId": "072cb127-238c-4f85-abf7-14063fa787a5",
    "salesTaxIdentificationNumber": "l1DKgodiUfw",
    "shipperCountry": "svn"
  }
]

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