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": "dhl-api-core",
    "rev": "62",
    "version": "5.0.20"
  }
}

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": "jLz4KVe2vRpYM1Lg2q",
  "label": {
    "b64": "TnZCIwtRklzHvTeIb0R2gzEmRZtsVlhktv597y3U"
  },
  "qrLabel": {
    "b64": "DMOujxceg9Ki4Zq19IR5fSUJkvycTmrUpiodpGRZ"
  },
  "qrLink": "https://limited-commodity.name",
  "routingCode": "FSIZsxJgK0LOEdnY9rPV7jcJD",
  "shipmentNo": "g1S6sPQUZLP5JfMUki",
  "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`	`aut`
`postalCode`	`77196-3983`
`receiverId`	`0b250b30-eb0e-4b3d-b678-0e2e322f69ee`
`billingNumber`	`9`
`maxResult`	`6886130`

Request Payload

Response Payload

[
  {
    "additionalEmailNote": "Innovative",
    "billingNumber": "3",
    "companyAddress": {
      "addressHouse": "242",
      "addressStreet": "Lake Street",
      "city": "Blandachester",
      "email": "Clifford_Blanda73@yahoo.com",
      "name1": "Norman Hand",
      "name2": "Courtney Kulas",
      "name3": "Johnnie Altenwerth",
      "phone": "+13582923942",
      "postalCode": "85535-3314",
      "state": "Delaware"
    },
    "companyManagement": "Mrs. Ellen Hintz",
    "companyName": "Beahan, Nolan and McKenzie",
    "contactEmail": "Wilton.Harber14@yahoo.com",
    "court": "North Janessa",
    "ekp": "4",
    "numberRange": "99999018187C",
    "receiverAddress": {
      "addressHouse": "1164",
      "addressStreet": "Wayne Radial",
      "city": "Percivalfield",
      "email": "Sunny10@gmail.com",
      "name1": "Dr. Keith Walter",
      "name2": "Joann Borer",
      "name3": "Mrs. Jacqueline Botsford",
      "phone": "+13504588155",
      "postalCode": "12704",
      "state": "North Dakota"
    },
    "receiverId": "c3f25558-322e-4d61-8fcc-892e36ec1223",
    "salesTaxIdentificationNumber": "7ABeT7sef0T",
    "shipperCountry": "fra"
  },
  {
    "additionalEmailNote": "Organized",
    "billingNumber": "7",
    "companyAddress": {
      "addressHouse": "9257",
      "addressStreet": "Elfrieda Flats",
      "city": "Port Tyraview",
      "email": "Florida67@hotmail.com",
      "name1": "Irene Haag",
      "name2": "Lawrence Miller",
      "name3": "Cedric O'Conner III",
      "phone": "+14034686249",
      "postalCode": "17503",
      "state": "Florida"
    },
    "companyManagement": "Terrence Cronin",
    "companyName": "Parisian LLC",
    "contactEmail": "Scotty_Reinger87@gmail.com",
    "court": "Janaeberg",
    "ekp": "3",
    "numberRange": "99999808145C",
    "receiverAddress": {
      "addressHouse": "596",
      "addressStreet": "Dickinson Locks",
      "city": "Port Alenacester",
      "email": "Hans_Hand13@gmail.com",
      "name1": "Paula Pollich",
      "name2": "Kim Rodriguez",
      "name3": "Mr. Ronnie Kirlin",
      "phone": "+14849331446",
      "postalCode": "68848-6321",
      "state": "Missouri"
    },
    "receiverId": "7f9eeaa3-2ec8-4536-afc7-799483c4f035",
    "salesTaxIdentificationNumber": "EEo32Rn5Z4v",
    "shipperCountry": "irl"
  },
  {
    "additionalEmailNote": "Focused",
    "billingNumber": "4",
    "companyAddress": {
      "addressHouse": "37505",
      "addressStreet": "Walsh Course",
      "city": "Fort Jovannyton",
      "email": "Evangeline.Reichert@hotmail.com",
      "name1": "Irene Fay",
      "name2": "Tami Vandervort",
      "name3": "Jim Gorczany",
      "phone": "+13734144607",
      "postalCode": "70596",
      "state": "Hawaii"
    },
    "companyManagement": "Cecelia Renner",
    "companyName": "Lehner and Sons",
    "contactEmail": "Heloise_Wisoky@yahoo.com",
    "court": "Lempiberg",
    "ekp": "2",
    "numberRange": "99999584014C",
    "receiverAddress": {
      "addressHouse": "986",
      "addressStreet": "Conn Shores",
      "city": "Huelsbury",
      "email": "Lloyd_Herzog74@hotmail.com",
      "name1": "Alex Corkery",
      "name2": "Mrs. Kristin Hudson",
      "name3": "Alberta Anderson",
      "phone": "+17972282421",
      "postalCode": "38495",
      "state": "Florida"
    },
    "receiverId": "eb0ff48e-4738-4916-97a6-9bc39e8f63c3",
    "salesTaxIdentificationNumber": "TjMrx7rl2WN",
    "shipperCountry": "ltu"
  },
  {
    "additionalEmailNote": "Sharable",
    "billingNumber": "9",
    "companyAddress": {
      "addressHouse": "54829",
      "addressStreet": "West Junctions",
      "city": "Rodgerfurt",
      "email": "Ed58@hotmail.com",
      "name1": "Shelley Harvey",
      "name2": "Brett Zboncak",
      "name3": "Beatrice Pagac",
      "phone": "+12646807748",
      "postalCode": "04284-6508",
      "state": "Louisiana"
    },
    "companyManagement": "Simon Walter",
    "companyName": "Reichel - Wisoky",
    "contactEmail": "Karl_Yundt86@hotmail.com",
    "court": "Moenville",
    "ekp": "7",
    "numberRange": "99999290177C",
    "receiverAddress": {
      "addressHouse": "3922",
      "addressStreet": "E 11th Street",
      "city": "Eden Prairie",
      "email": "Colten_Bernhard72@yahoo.com",
      "name1": "Karla Beer",
      "name2": "Leslie Rohan",
      "name3": "Scott Pagac",
      "phone": "+14018954873",
      "postalCode": "13576-8680",
      "state": "California"
    },
    "receiverId": "696abb70-53f3-4612-a84b-c00597a85ee1",
    "salesTaxIdentificationNumber": "67MPp07Bw3V",
    "shipperCountry": "che"
  },
  {
    "additionalEmailNote": "Customizable",
    "billingNumber": "6",
    "companyAddress": {
      "addressHouse": "8381",
      "addressStreet": "Yost Tunnel",
      "city": "O'Connellboro",
      "email": "Aliya57@gmail.com",
      "name1": "Jasmine Aufderhar",
      "name2": "Russell Schneider",
      "name3": "Cheryl Krajcik",
      "phone": "+12872876128",
      "postalCode": "11766-2419",
      "state": "New Jersey"
    },
    "companyManagement": "Edward Becker MD",
    "companyName": "Legros, Raynor and Stark",
    "contactEmail": "Jimmy_Blick-Heller@hotmail.com",
    "court": "North Don",
    "ekp": "1",
    "numberRange": "99999436221C",
    "receiverAddress": {
      "addressHouse": "1880",
      "addressStreet": "Balmoral Road",
      "city": "Johnson City",
      "email": "Julie73@hotmail.com",
      "name1": "Sandy Farrell",
      "name2": "Peter Bogan",
      "name3": "Deanna Franey",
      "phone": "+13433696027",
      "postalCode": "91115",
      "state": "Georgia"
    },
    "receiverId": "16e4803f-9407-4178-b62c-8bcb31cb4d49",
    "salesTaxIdentificationNumber": "nc5JXjnQBYv",
    "shipperCountry": "bel"
  },
  {
    "additionalEmailNote": "Ergonomic",
    "billingNumber": "5",
    "companyAddress": {
      "addressHouse": "38848",
      "addressStreet": "The Paddocks",
      "city": "Port Hal",
      "email": "Tianna_Flatley0@hotmail.com",
      "name1": "Lisa Auer",
      "name2": "Lorraine Reichert",
      "name3": "Roderick Ferry-Kuvalis",
      "phone": "+19875079454",
      "postalCode": "47128",
      "state": "Idaho"
    },
    "companyManagement": "Cesar Cartwright",
    "companyName": "Volkman - Ward",
    "contactEmail": "Meghan.Hirthe@yahoo.com",
    "court": "Huntersville",
    "ekp": "6",
    "numberRange": "99999890345C",
    "receiverAddress": {
      "addressHouse": "727",
      "addressStreet": "Pine Close",
      "city": "Lavinaside",
      "email": "Allison_Schowalter39@yahoo.com",
      "name1": "Homer Hyatt",
      "name2": "Jennifer Monahan",
      "name3": "Owen Wisoky",
      "phone": "+16902666934",
      "postalCode": "89138-7707",
      "state": "Massachusetts"
    },
    "receiverId": "1d84e640-0483-40cd-a606-58fbec93cfb3",
    "salesTaxIdentificationNumber": "ybtw2sAPtZF",
    "shipperCountry": "svn"
  },
  {
    "additionalEmailNote": "Extended",
    "billingNumber": "3",
    "companyAddress": {
      "addressHouse": "483",
      "addressStreet": "Schneider Street",
      "city": "South Amelia",
      "email": "Florence57@hotmail.com",
      "name1": "Ruben Koelpin",
      "name2": "Duane Farrell",
      "name3": "Mathew Kassulke",
      "phone": "+17585671654",
      "postalCode": "27543-9855",
      "state": "Iowa"
    },
    "companyManagement": "Constance Fadel",
    "companyName": "Conroy - Deckow",
    "contactEmail": "Piper91@gmail.com",
    "court": "O'Harafort",
    "ekp": "6",
    "numberRange": "99999650627C",
    "receiverAddress": {
      "addressHouse": "96782",
      "addressStreet": "Oak Road",
      "city": "Zitafurt",
      "email": "Wilhelmine69@hotmail.com",
      "name1": "Mr. Devin Spencer I",
      "name2": "Matt Bosco",
      "name3": "Martha Cronin",
      "phone": "+12097499877",
      "postalCode": "17121-7790",
      "state": "New York"
    },
    "receiverId": "21b094ba-d7fa-471c-be2b-ae6aa33227b9",
    "salesTaxIdentificationNumber": "7S7oLTCldcB",
    "shipperCountry": "lva"
  },
  {
    "additionalEmailNote": "Upgradable",
    "billingNumber": "8",
    "companyAddress": {
      "addressHouse": "27992",
      "addressStreet": "Sandy Lane",
      "city": "Midwest City",
      "email": "Augustine41@yahoo.com",
      "name1": "Kerry Jones",
      "name2": "Tim Barton",
      "name3": "Vicky Mayer",
      "phone": "+16063189043",
      "postalCode": "94641",
      "state": "West Virginia"
    },
    "companyManagement": "Robin Rutherford",
    "companyName": "Bernhard Inc",
    "contactEmail": "Gregory_Boyer@gmail.com",
    "court": "North Randal",
    "ekp": "9",
    "numberRange": "99999336952C",
    "receiverAddress": {
      "addressHouse": "600",
      "addressStreet": "Lauriane Curve",
      "city": "Peoria",
      "email": "Alyce96@hotmail.com",
      "name1": "Omar Rosenbaum",
      "name2": "Cary Medhurst",
      "name3": "Elmer Mayer",
      "phone": "+18083374993",
      "postalCode": "80201",
      "state": "Oklahoma"
    },
    "receiverId": "3c987e8a-ba4a-4ed8-9710-3f51a9f4416a",
    "salesTaxIdentificationNumber": "lXK50vLOKvk",
    "shipperCountry": "bel"
  },
  {
    "additionalEmailNote": "Networked",
    "billingNumber": "3",
    "companyAddress": {
      "addressHouse": "699",
      "addressStreet": "Pagac Ridges",
      "city": "Port Ismaeltown",
      "email": "Kattie_Harber30@hotmail.com",
      "name1": "Cindy Stiedemann",
      "name2": "Tasha Ondricka",
      "name3": "Mr. Clay Reichert",
      "phone": "+17706789061",
      "postalCode": "88597-5349",
      "state": "Arkansas"
    },
    "companyManagement": "Laurence Medhurst",
    "companyName": "Ondricka Inc",
    "contactEmail": "Davonte.Pagac@gmail.com",
    "court": "North Clarkborough",
    "ekp": "4",
    "numberRange": "99999708599C",
    "receiverAddress": {
      "addressHouse": "9506",
      "addressStreet": "The Lane",
      "city": "Flatleyborough",
      "email": "Bell.Kohler@yahoo.com",
      "name1": "Bertha Pouros",
      "name2": "Theresa Sipes",
      "name3": "Christy Walsh",
      "phone": "+15257954493",
      "postalCode": "59700",
      "state": "Illinois"
    },
    "receiverId": "4d521a16-0e70-41d8-be94-1eccd507fadb",
    "salesTaxIdentificationNumber": "iNbaxJSWacd",
    "shipperCountry": "rou"
  },
  {
    "additionalEmailNote": "Reactive",
    "billingNumber": "5",
    "companyAddress": {
      "addressHouse": "1128",
      "addressStreet": "Gerhold Parkway",
      "city": "Fort Adan",
      "email": "Rae.Wyman56@yahoo.com",
      "name1": "Kristin Bergstrom",
      "name2": "Mr. Dwayne Kerluke",
      "name3": "Leslie Medhurst",
      "phone": "+15712535027",
      "postalCode": "92581-4860",
      "state": "South Carolina"
    },
    "companyManagement": "Gerardo Kirlin",
    "companyName": "Hilpert LLC",
    "contactEmail": "Phyllis91@yahoo.com",
    "court": "Tremainebury",
    "ekp": "6",
    "numberRange": "99999076770C",
    "receiverAddress": {
      "addressHouse": "439",
      "addressStreet": "Wilkinson Crossroad",
      "city": "Kellibury",
      "email": "Elouise37@hotmail.com",
      "name1": "Mrs. Dana Daugherty V",
      "name2": "Gail Glover",
      "name3": "Hope Feil",
      "phone": "+19482264999",
      "postalCode": "42637",
      "state": "Alaska"
    },
    "receiverId": "e4b33f49-46df-44c4-9054-b0bd2406daad",
    "salesTaxIdentificationNumber": "XAlWJMBzByp",
    "shipperCountry": "nor"
  }
]

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