Create one or more shipments and their documents. (This is the primary call of the API.)
This request is used to create one or more shipments and return corresponding shipment tracking numbers, labels, and documentation. Up to 30 shipments can be created in a single call.
Request
The selected products and corresponding billing numbers, as well as the desired services and package details are required to create a shipment. Each shipment can have a dedicated shipper address. The example request body contains sample values for most services.
Response
The request will return shipment tracking numbers and the applicable labels for each shipment. If multiple shipments have been included, an HTTP 207 response (multistatus) is returned and holds detailed status for each shipment. Other standard HTTP response codes (401, 500, 400, 200, 429) are possible, too. Labels can be either provided as part of the response (base64 encoded for PDF, text for ZPL) or via URL link for view and download. Note that the format settings per query parameters apply to the shipping label. It may also apply to other labels included, depending on the configuration of your account. Label paper for return shipments can be specified separately since a different printer may be used here. If requesting labels to be provided as URL for separate download, the URLs can be shared.
Validation
It is recommended to validate the request first prior to shipment creation by setting the validate query parameter to true. Especially, during development and test, it is recommended to perform this validation. This functionality supports both
- JSON schema validation (against this API description). During development and test, it is recommended to do this validation. JSON schema is available for local validation
- Dry run against the DHL backend
If this succeeds, actual shipment creation will also succeed.
Request
- Base URLhttps://api-eu.dhl.com/parcel/de/shipping/v2
- Auth
- API key in header dhl-api-key
- or HTTP basic
- or OAuth 2PasswordToken URL: /parcel/de/account/auth/ropc/v1/token
Query parameters
If provided and set to true, the input document will be:
- validated against JSON schema (/orders/ endpoint) at the API layer. In case of errors, HTTP 400 and details will be returned.
- validated against the DHL backend.
In that case, no state changes are happening, no data is stored, shipments neither deleted nor created, no labels being returned. The call will return a status (200, 400) for each shipment element.
Legacy name printOnlyIfCodable. If set to true, labels will only be created if an address is encodable. This is only relevant for German consignee addresses. If set to false or left out, addresses, that are not encodable will be printed even though you receive a warning.
Legacy name labelResponseType. Shipping labels and further shipment documents can be:
- include: included as base64 encoded data in the response (default)
- URL: provided as URL reference.
Defines the printable document format to be used for label and manifest documents.
Defines the print medium for the shipping label. The different option vary from standard paper sizes DIN A4 and DIN A5 to specific label print formats.
Specific laser print formats using DIN A5 blanks are:
- 910-300-600(-oz) (105 x 205mm)
- 910-300-300(-oz) (105 x 148mm)
Specific laser print formats not using a DIN A5 blank:
- 910-300-610 (105 x 208mm)
- 100x70mm
Specific thermal print formats:
- 910-300-600 (103 x 199mm)
- 910-300-400 (103 x 150mm)
- 100x70mm
Please use the different formats as follows. If you do not set the parameter the settings of DHL costumer portal account will be used as default.
Defines the print medium for the return shipping label. This parameter is only usable, if you do not use combined printing. The different option vary from standard paper sizes DIN A4 and DIN A5 to specific label print formats.
Specific laser print formats using DIN A5 blanks are:
- 910-300-600(-oz) (105 x 205mm)
- 910-300-300(-oz) (105 x 148mm)
Specific laser print formats not using a DIN A5 blank:
- 910-300-610 (105 x 208mm)
- 100x70mm
Specific thermal print formats:
- 910-300-600 (103 x 199mm)
- 910-300-400 (103 x 150mm)
- 100x70mm
Please use the different formats as follows. If you do not set the parameter the settings of DHL costumer portal account will be used as default.
If set, label and return label for one shipment will be printed as single PDF document with possibly multiple pages. Else, those two labels come as separate documents. The option does not affect customs documents and COD labels.
Headers
Control the APIs response language via locale abbreviation. English (en-US) and german (de-DE) are supported. If not specified, the default is english.
Request body
Example request
{
"shipments": [
{
"product": "V01PAK",
"billingNumber": "33333333330101 or 333333333362aa",
"shipper": {
"name1": "Blumen Krause",
"name2": "To the attention of Erna.",
"name3": "Backdrawer all the way back.",
"addressStreet": "Hauptstrasse",
"addressHouse": "1a",
"postalCode": "53113",
"city": "Berlin",
"contactName": "Konrad Kontaktmann",
"email": "mustermann@example.com"
},
"consignee": {
"name1": "Blumen Krause",
"name2": "To the attention of Erna.",
"name3": "Backdrawer all the way back.",
"dispatchingInformation": "PO Box, bpack 24/7",
"addressStreet": "Hauptstrasse",
"addressHouse": "1a",
"additionalAddressInformation1": "3. Etage",
"additionalAddressInformation2": "Apartment 12",
"postalCode": "53113",
"city": "Berlin",
"state": "NRW",
"contactName": "Konrad Kontaktmann",
"phone": "+49 170 1234567",
"email": "mustermann@example.com"
},
"details": {
"dim": {
"uom": "cm",
"height": 10,
"length": 20,
"width": 15
},
"weight": {
"uom": "g",
"value": 500
}
},
"services": {
"preferredNeighbour": "Please ring at Meier next door",
"preferredLocation": "Please leave in carport",
"visualCheckOfAge": "A18",
"namedPersonOnly": true,
"identCheck": {
"firstName": "Max",
"lastName": "Mustermann",
"minimumAge": "A18"
},
"signedForByRecipient": true,
"endorsement": "RETURN",
"noNeighbourDelivery": true,
"bulkyGoods": true,
"cashOnDelivery": {
"bankAccount": {
"accountHolder": "John D. Rockefeller",
"bankName": "The Iron Bank, Braavos",
"iban": "DE02100100100006820101",
"bic": "DEUTDEFFXXX"
}
},
"individualSenderRequirement": "ZZ",
"premium": true,
"closestDropPoint": true,
"parcelOutletRouting": "max.mustermann@example.com",
"goGreenPlus": true,
"dhlRetoure": {
"returnAddress": {
"name1": "Blumen Krause",
"name2": "To the attention of Erna.",
"name3": "Backdrawer all the way back.",
"dispatchingInformation": "PO Box, bpack 24/7",
"addressStreet": "Hauptstrasse",
"addressHouse": "1a",
"additionalAddressInformation1": "3. Etage",
"additionalAddressInformation2": "Apartment 12",
"postalCode": "53113",
"city": "Berlin",
"state": "NRW",
"contactName": "Konrad Kontaktmann",
"phone": "+49 170 1234567",
"email": "mustermann@example.com"
},
"goGreenPlus": true
},
"postalDeliveryDutyPaid": true
},
"customs": {
"exportDescription": "Detailed description for OTHER goods.",
"MRN": "abcd1234567890",
"shipperCustomsRef": "DE73282932000074",
"consigneeCustomsRef": "GB73282932000074",
"items": [
{
"itemDescription": "T-Shirt",
"hscode": "61099090",
"countryOfOrigin": "DE",
"packagedQuantity": 3
},
{
"itemDescription": "Book",
"hscode": "49019900",
"packagedQuantity": 1
}
]
}
}
]
}Response
Success response for requests with a single shipment.
Example response
{
"status": {
"title": "ok",
"statusCode": 200,
"status": 200,
"detail": "The Webservice call ran successfully."
},
"items": [
{
"shipmentNo": 340434310428091700,
"routingCode": "40327653113+99000943058020",
"sstatus": {
"title": "OK",
"status": 200
},
"label": {
"url": "https://api-dev.dhl.com/parcel/de/shipping/v1-feature-order-endpoint/labels?token=x5xzrHE7ctmqPqk33k%2BKkBwbvIfYP4elMQsBFM%2BJOdiT2bmoaXXzris%2Ftz9jBtdVFLY5cCENit0Jnd9aXuxoNEXhP9PQ8tAVdPeXD26RZ6JZqF5NCJlrihrAv1%2FAOzuDPqWJLRVaRq461BpT4bcbzChAAHVg%2FHUaQAkeIkaZ8NqfcxWEQzK1AYJWczpy6sv6",
"format": "PDF"
}
}
]
}Changes
No recorded changes to this operation across all 1 revision of this API.