4 Labels and Shipments

4.1 Intro

The Shipments and Labels endpoints make it possible to create and retrieve your own labels.

These endpoints are secured, therefore the use of an authorization header with ‘Bearer’ as prefix and your token is required.

Preconditions

  • Business account for the test environment and or on MY DHL Portal.

    A business account is handed out by the sales department. You can place a request for an account as a business by email to: CIM eCommerce BNL.

  • Authentication token. See documentation on the Authentication and authorization endpoint.

4.2 Services

4.2.1 Create shipment

The Create shipment endpoint constructs a shipment.

In order to create a shipment, a unique identifier is needed as input for the shipment request. The format for this identifier is the Universally Unique Identifier (UUID). The use of UUIDs keeps our API idempotent. It ensures in this case that a shipment is created uniquely and just once, without needing to do any expensive and complicated synchronized bookkeeping.

Most programming languages and platforms have a built-in UUID generator that you can use for this purpose.A brief explanation on the other input data is given in the table below.

Be aware that the use of an authorization token in the header of the HTTP request is mandatory.

Field Type Mandatory Description
shipmentId string Y Use a UUID Generator
orderReference string N Your own reference for the shipment, can be used to retrieve the label, e.g. your order number.
receiver   Y Name and address
name     Requires at least firstName, lastName or companyName
firstName string N  
lastName string N  
companyName string N  
additionalName string N  
address     Depending on country, use designated endpoint to check input address
countryCode string Y  
postalCode string   Mandatory and format is checked based on country code
city string Y  
street string Y  
number string N  
isBusiness boolean N Defaults to true
addition string N  
email string N Mandatory for shipment to consumers
phoneNumber string N  
vatNumber string N  
eoriNumber string N  
onBehalfOf   N Name and address. See Ad 1.
name     Requires at least firstName, lastName or companyName
firstName string    
lastName string    
companyName string    
additionalName string    
address     Depending on country, use designated endpoint for address
countryCode string Y  
postalCode string   Mandatory and format is checked based on country code
city string Y  
street string Y  
number string N  
isBusiness boolean N Defaults to true
addition string N  
email string N  
phoneNumber string N  
vatNumber string N  
eoriNumber string N  
shipper   Y Name and address
name     Requires at least firstName, lastName or companyName
firstName string N  
lastName string N  
companyName string N  
additionalName string N  
address     Depending on country, use designated endpoint to check input address
countryCode string Y  
postalCode string   Mandatory and format is checked based on country code
city string Y  
street string Y  
number string N  
isBusiness boolean N Defaults to true
addition string N  
email string N  
phoneNumber string N  
vatNumber string N  
eoriNumber string N  
accountId string Y As provided by DHL. May only be empty for C2C customers
options array Y Provide empty array ([]) for no options
key string Y See Capabilities endpoint in API docs and Ad 2.
input   N See Ad 2.
returnLabel boolean N See Ad 3.
pieces   Y See Ad 4.
parcelType string Y See ParcelTypes endpoint in API docs
quantity integer N Number of parcels of this parcel type
weight number N Actual piece weight in kilograms. Maximum weight depends on the parcel type. Weight icons will be printed on the label based on the specified weight, or the parcelType’s default weight (whichever is higher).
dimensions   N Actual dimensions of the parcel, in centimeters
length number N Length in centimeters
width number N Width in centimeters
height number N Height in centimeters
customsDeclaration   N Customs details when sending to a customs destination
currency string N Currency of the invoice, ISO (EUR, CHF, NOK, GBP, USD)
invoiceNumber string N  
remarks string N Supplementary information, such as consignment remarks
invoiceType string N Type of invoice, e.g. commercial
exportType string N Permanent, Repair, Return, Temporary
exportReason string N Other, SaleOfGoods, ReturnedGoods, Gift, CommercialSample, Documents
incoTerms string N CFR, CIF, CIP, CPT, DAP, DAT, DDP, DDU, DDX, EXW, FCA, FOB; DDX means ‘DDP VAT Excl.’ EXW not applicable for UK exports. For Parcel Connect only DDU applicable to UK.
incoTermsCity string N Named place of delivery/destination/port
senderInboundVatNumber string N Sender VAT number for inbound country. Only applicable for shipments to GB. Mandatory for Parcel Connect shipments to GB
attachmentIds [string] N Specify uploaded custom attachments
defermentAccountVat String N Deferment Account VAT
defermentAccountDuties String N Deferment Account for Duties (if a separate account exits)
vatReverseCharge boolean N  
shippingFee     Additional shipping fee
currency string Y  
value string Y  
importerOfRecord   N Importer of the customs shipment
email string N  
phoneNumber string N  
vatNumber string N  
eoriNumber string N  
name     Requires at least firstName, lastName or companyName
firstName string N  
lastName string N  
companyName string N  
additionalName string N  
address     Depending on country, use designated endpoint to check input address
countryCode string Y  
postalCode string   Mandatory and format is checked based on country code
city string Y  
street string Y  
number string N  
isBusiness boolean N Defaults to true
addition string N  
customsGoods   Y Customs goods in this declaration, at least one is required
code string Y HS-code of the goods, see Harmonized commodity description and coding System, to classify globally traded products. Always 8 or 10 positions.
description string Y Description of the goods
origin string Y Country of origin, ISO 3166-1 alpha-2 country code
quantity string Y Number of the products of this line
value string Y Total value of the goods of this line
weight string Y Net weight of the products of this line

Ad 1. An ‘on behalf of’ shipment

For destinations offering the ‘SSN’ shipment option (e.g. Benelux) it is possible to do a shipment on behalf of someone else. This is done by an extra information block called ‘onBehalfOf’. It has the same structure as the ‘shipper’ block.

"onBehalfOf": {
  "name": {
    "firstName": "Mr",
    "lastName": "Onbehalfof",
    "companyName": "DHL eCommerce",
    "additionalName": "Benelux"
  },
  "address": {
    "countryCode": "NL",
    "postalCode": "3542AD",
    "city": "Onbehalf",
    "street": "Onbehalfweg",
    "number": "2",
    "isBusiness": false
  },
  "email": "[email protected]",
  "phoneNumber": "0031612345678"
}

In addition to the onBehalfOn block the shipping option undisclosed sender (SSN) is required:

{
  "key": "SSN"
}

It is possible to do an onBehalfOf shipment outside the Benelux, but the original sender will not be anonymous in the Track & Trace info (DHL).

In the case of an onBehalfOf shipment outside the Benelux it also necessary to use the onBehalfOf json block, but the shipping option undisclosed sender should be left out of the request.

Ad 2. Adding shipment options

Some shipments options require specifying extra information. For example, in the case of a cash on delivery, the amount should be specified or in case of a reference, some text is needed as input. Whether additional information is necessary for the shipping option is determined by the ‘input type’ listed with the shipment option (See Shipment Options or Capabilities endpoint).

For example shipment option ‘REFERENCE’ will be returned like:

{
  "key": "REFERENCE",
  "description": "Reference",
  "rank": 5,
  "code": 0,
  "inputType": "text",
  "inputMax": "15"
}

When the extra information is required the field “input” can be used to specify this.

For example, in case of a delivery to a parcel shop, the parcel shop is identified by it’s id through the input field.

{
  "key": "PS",
  "input": "8004-NL-272403"
}

In case a parcel is to be delivered at a postbox of German PackStation, the syntax is first the id of the parcel station delimited by ‘|’ and then the postnummer of the recipient:

{
  "key": "PS",
  "input": "8003-4125530|12345"
}

In case of cash on delivery, the amount that needs to be paid by the recipient serves as input.

{
  "key": "COD_CASH",
  "input": 5
}

Ad 3. Create return label

A label is either a ‘normal’, so an initial label or a return label. By setting the value of the ‘returnLabel’ attribute to ‘true’, the endpoint will create a return label; a return label is marked as a RETURN label. Note that there must be a return product available (a setting for your account).

return label

When creating a return label, make sure the receiver and shipper information are set correctly. If a customer returns a package, the customer’s address becomes the shipper’s address and the company’s address becomes the receiver’s address.

To have a return label created automatically with the original label, supply the ADD_RETURN_LABEL shipment option to the shipment. Note that option is only supported on the ‘Create Shipment’ endpoint.

Ad 4. Mono/multi collo (pieces)

The create shipment service will produce one shipment per request, but it can contain more than one piece or package.

If a shipment contains for example two packages, a single piece can be specified with quantity 2 in case the packages are of an identical type, or both packages can be specified using two pieces.

See given examples of the created labels for quantity greater than 1.

multiple labels

Multi colli is only possible if the shipment is not a single piece product (mono collo). In general shipments meant for consumers are mono collo products, but not necessarily.

In the capabilities service you can determine if the product is a mono collo. See example of an excerpt from the capability service below, the attribute monoColloProduct is either true or false.

{
  "rank": 2,
  "fromCountryCode": "NL",
  "toCountryCode": "NL",
  "product": {
    "key": "DFY-SDD",
    "label": "DFY",
    "code": "00",
    "menuCode": "07",
    "businessProduct": true,
    "monoColloProduct": true,
    "softwareCharacteristic": "B2X",
    "returnProduct": false
  },
  "parcelType": {
    "key": "MEDIUM",
    "minWeightKg": 20,
    "maxWeightKg": 31,
    "dimensions": {
      "maxLengthCm": 80,
      "maxWidthCm": 50,
      "maxHeightCm": 35
    }
  },
  "options": [
    {
      "key": "DOOR",
      "description": "Delivery to the address of the recipient",
      "rank": 2,
      "code": 0,
      "exclusions": [
        {

Ad 5. Customs

When sending to a customs destination, a customsDeclaration should be specified in the shipment request so that we can send the commercial invoice of a customs declaration.

"customsDeclaration" : {
  "currency": "GBP",
  "invoiceNumber": "123.A01",
  "type": "COMMERCIAL",
  "exportReason": "SaleOfGoods",
  "products": [
    {
      "code": "85365019",
      "description": "Air flow switch",
      "origin": "NL",
      "quantity": 1,
      "value": 745,
      "weight": 0.8
    },
    {
      "code": "90269000",
      "description": "Adaptor",
      "origin": "DE",
      "quantity": 2,
      "value": 12.5,
      "weight": 0.3
    },
    {
      "code": "85444290",
      "description": "Cable connector",
      "origin": "PL",
      "quantity": 3,
      "value": 62.5,
      "weight": 0.35
    }
  ],
  "incoTerms": "CFR",
  "importerOfRecord": {
    "name": {
      "firstName": "Mr",
      "lastName": "Importer",
      "companyName": "DHL eCommerce",
      "additionalName": "Britain"
    },
    "address": {
      "countryCode": "GB",
      "postalCode": "E11 1AB",
      "city": "London",
      "street": "Store Road",
      "number": "1",
      "isBusiness": true
    },
    "email": "[email protected]",
    "phoneNumber": "0031612345678",
    "vatNumber": "GB123456789",
    "eori": "GB123456789"
  }
}

Depending on input details, a CN23 form or invoice is generated as well.

When a customsDeclaration is provided, the generated customsDeclarationId is included in the response. This can be used to retrieve the declaration and generated documents through Get customs declaration by id.

Generated documents can also be retrieved through Get customs forms by shipment id

Multiple custom attachments can be included, but the combined size of all attachments is limited to 2.5 MB for Benelux.

4.2.2 Create label

*Deprecated, please use Create shipment to create a shipment and retrieve labels using the shipment response information or the get multiple labels endpoint. While this endpoint will be supported, new features will be added only to the Create shipment

The Create label endpoint constructs one label at a time, which can be either a standard label or a return label.

In order to create a label, a unique identifier is needed as input for the label request. The format for this identifier is the Universally Unique Identifier (UUID). The use of UUIDs keeps our API idempotent. It ensures in this case that a label is created uniquely and just once, without needing to do any expensive and complicated synchronized bookkeeping.

Most programming languages and platforms have a built-in UUID generator that you can use for this purpose.A brief explanation on the other input data is given in the table below.

Be aware that the use of an authorization token in the header of the HTTP request is mandatory.

Field Type Mandatory Description
labelId string Y Use a UUID Generator
labelFormat string N Determines label binary representation included in the JSON response. Defaults to ‘pdf’.
orderReference string N Your own reference for the label(s), e.g. your order number.
parcelTypeKey string Y See ParcelTypes endpoint in API docs
receiver   Y Name and address
name     Requires at least firstName, lastName or companyName
firstName string N  
lastName string N  
companyName string N  
additionalName string N  
address     Depending on country, use designated endpoint to check input address
countryCode string Y  
postalCode string   Mandatory and format is checked based on country code
city string Y  
street string Y  
number string N  
isBusiness boolean N Defaults to true
addition string N  
email string N  
phoneNumber string N  
onBehalfOf   N Name and address. See Ad 1.
name     Requires at least firstName, lastName or companyName
firstName string    
lastName string    
companyName string    
additionalName string    
address     Depending on country, use designated endpoint for address
countryCode string Y  
postalCode string   Mandatory and format is checked based on country code
city string Y  
street string Y  
number string N  
isBusiness boolean N Defaults to true
addition string N  
email string N  
phoneNumber string N  
shipper   Y Name and address
name     Requires at least firstName, lastName or companyName
firstName string N  
lastName string N  
companyName string N  
additionalName string N  
address     Depending on country, use designated endpoint to check input address
countryCode string Y  
postalCode string   Mandatory and format is checked based on country code
city string Y  
street string Y  
number string N  
isBusiness boolean N Defaults to true
addition string N  
email string N  
phoneNumber string N  
accountId string Y  
options array    
key string Y See Capabilities endpoint in API docs and Ad 2.
input   N See Ad 2.
returnLabel boolean N See Ad 3.
pieceNumber integer N See Ad 6.
quantity integer N  
automaticPrintDialog boolean N If true, PDF labels will include a flag that opens the print dialog in supported software (Acrobat reader).

Ad 6. Multi collo (pieces)

The create label service will produce just one label per request, but if the shipment contains more than one piece or package it is possible to specify this on the label through ‘pieceNumber’ and ‘quantity’ request attributes.

If a shipment contains for example two packages, the label service needs to be called twice. The information set for first call to label service would be pieceNumber 1, quantity 2. For the second label this information is set to pieceNumber 2, quantity 2.

See given examples of the created labels.

multiple labels

Multi colli is only possible if the shipment is not a single piece product (mono collo). In general shipments meant for consumers are mono collo products, but not necessarily.

In the capabilities service you can determine if the product is a mono collo. See example of an excerpt from the capability service below, the attribute monoColloProduct is either true or false.

Multi colli shipments will get a shipment tracker code assigned (in addition to the individual piece tracker codes). When this tracker code is generated by the label service, the shipmentTrackerCode field will be present in the response. However, in certain cases the shipment tracker code will be generated later in the logistical workflow, and therefore the shipment tracker code is not known by the label service API.

{
  "rank": 2,
  "fromCountryCode": "NL",
  "toCountryCode": "NL",
  "product": {
    "key": "DFY-SDD",
    "label": "DFY",
    "code": "00",
    "menuCode": "07",
    "businessProduct": true,
    "monoColloProduct": true,
    "softwareCharacteristic": "B2X",
    "returnProduct": false
  },
  "parcelType": {
    "key": "MEDIUM",
    "minWeightKg": 20,
    "maxWeightKg": 31,
    "dimensions": {
      "maxLengthCm": 80,
      "maxWidthCm": 50,
      "maxHeightCm": 35
    }
  },
  "options": [
    {
      "key": "DOOR",
      "description": "Delivery to the address of the recipient",
      "rank": 2,
      "code": 0,
      "exclusions": [
        {

4.2.3 Get label id by tracking code or order reference

The Find labels endpoint by tracker code or order reference is used to retrieve label information.

The endpoint will return, among other identifying information (but not the label), the registered label id to use with the get label by id endpoint.

The use of the authorization token in the header of http request is mandatory.

4.2.4 Get label by id

With the label id, as fetched with the endpoint Get label id by tracking code or order reference, a specific label can be retrieved through Get label endpoint by id.

The Get label endpoint by id result depends on the content of the Accept header.

Accept Result
application/json Detailed label information, including organization id
application/pdf PDF document with the specified label(s)
application/zpl ZPL document with the specified label(s)

4.2.5 Get multiple labels

The Get multiple labels endpoint is used to retrieve multiple labels in a single document, based on the content of the Accept header.

Accept Result
application/pdf PDF document with the specified label(s)
application/zpl ZPL document with the specified label(s)

All documents are sent using chunked transfer encoding.

4.2.5.1 Specify labels to include

The request body specifies the labels to include:

Field Type Mandatory Description
labelIds array N Include all labels with the specified ids
shipmentIds array N Include all labels for the shipments with the specified ids
trackerCodes array N Include all labels with the specified tracker codes
shipmentTrackerCodes array N Include all labels for the shipments with the specified tracker codes

Any combination of fields can be used to retrieve labels. If no labels are specified, the request fails and no document is returned.

The use of the authorization token in the header of http request is mandatory.

4.2.5.2 Ordering

Generally, labels are rendered in the following order:

  1. Field order as described above, so first all labels requested by labelIds are included, then all labels requested by shipmentIds, etc.
  2. Specified order in the array for the requested field, so first the label in the first position, then the label in the second position, etc.
  3. Piece number in case of multiple labels for a single element, so first piece number one for a shipment, then piece number two, etc.

In some cases, labels for a single request can have various sizes demanding different paper layouts. In that case we aim to preserve paper by grouping labels with the same layout. The order of labels within each group is preserved. This behaviour can be disabled by setting the ordering field to original.

4.2.5.3 Non-existing labels

When requesting multiple labels, a non-existing label can be specified. By default any request with a non-existing label fails and no document is returned. In some cases, it might be convenient to silently skip any non-existing labels by setting the missingLabelPolicy field to skip.

In case all specified labels do not exist, the request fails regardless of the specified option.

4.2.5.4 PDF specific rendering options

When getting multiple labels as PDF, additional options can be specified.

Field Type Mandatory Description
autoPrintDialog boolean N Automatically show print dialog when PDF is opened using a PDF reader that supports that option.
pageSize string N Render every label in their original size on a single page, or arrange labels on a larger page (a4).
pageOptions object N Additional options when arranging labels.
pageLayout string N Physical page layout affects how labels are arranged in landscape mode. Ignored for A4 sized labels (always 1 per page) and A6 labels (always 4 per page in portrait mode).
mixedLayoutPolicy string N Can be specified to ensure a certain label arrangement always matches the physical page layout.
firstPageOffset string N Rendering option that allows to continue printing on re-used paper.

4.3 API Usage

Description URL
Create shipment endpoint https://api-gw.dhlparcel.nl/shipments
Endpoint to get label information by tracking code https://api-gw.dhlparcel.nl/labels?trackerCodeFilter=”your_tracking_code”
Endpoint to get label information by order reference https://api-gw.dhlparcel.nl/labels?orderReferenceFilter=”your_order_reference”
Endpoint to get the label of a specific package https://api-gw.dhlparcel.nl/labels/your_labelId

4.3.1 Create shipment

Request examples

Curl 
curl -X POST "https://api-gw.dhlparcel.nl/shipments" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJhNzAxN2EzZi1jMGYzLTQ3ZTAtOGQzNC1mMmZhMDFjYTlkY2EiLCJzdWIiOiI2YmZjNzU2MS00YjQxLTRjYjctYTFjMy1kYzMxZmFmODYwZGIiLCJvcmdhbml6YXRpb25JZCI6ImE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMTg2NzUwNywiZXhwIjoxNTExODY4NDA4LCJyb2xlcyI6WyJsYWJlbC1zZXJ2aWNlLkIyWCIsInBpY2t1cC1zZXJ2aWNlLkIyWCJdLCJhY2NvdW50cyI6WyIwODUwMDAwMSJdfQ.Qs79I-LW0ES4mO8hObOiZXvuuipBQ_-eJ7pd-10rrSQ" \
     -H "Content-Type: application/json" \
     -i \
     -d "{
     		\"shipmentId\": \"331708e4-e876-4f9a-94f3-c74bd482988b\",
     		\"orderReference\":\"myReference\",
     		\"receiver\": {
     			\"name\": {
     				\"firstName\": \"John\",
     				\"lastName\": \"Doe\",
     				\"companyName\": \"ACME Corp.\",
     				\"additionalName\": \"Benelux\"
     			},
     			\"address\": {
     				\"countryCode\": \"NL\",
     				\"postalCode\": \"3542AD\",
     				\"city\":\"Utrecht\",
     				\"street\": \"Reactorweg\",
     				\"number\": \"25\",
     				\"isBusiness\": true,
     				\"addition\": \"A\"
     			},
     			\"email\": \"[email protected]\",
     			\"phoneNumber\":\"0031612345678\"
     		},
     		\"shipper\": {
     			\"name\": {
     				\"firstName\": \"John\",
     				\"lastName\":\"Doe\",
     				\"companyName\": \"ACME Corp.\",
     				\"additionalName\": \"Benelux\"
     			},
     			\"address\": {
     				\"countryCode\": \"NL\",
     				\"postalCode\": \"3542AD\",
     				\"city\": \"Utrecht\",
     				\"street\": \"Reactorweg\",
     				\"number\": \"25\",
     				\"isBusiness\": true,
     				\"addition\": \"A\"
     			},
     			\"email\": \"[email protected]\",
     			\"phoneNumber\":\"0031612345678\"
     		},
     		\"accountId\": \"01234567\",
     		\"options\": [
     			{ \"key\": \"DOOR\" }
     		],
     		\"returnLabel\": false,
     		\"pieces\": [
     			{
	     			\"parcelType\": \"SMALL\",
	     			\"quantity\": 1,
	     			\"weight\": 1.5
     			}
     		]
     	}"
PHP 
<?php
// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://api-gw.dhlparcel.nl/shipments');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');


// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1 );

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Content-Type: application/json; charset=utf-8",
"Authorization: Bearer
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJkYWFkNzU3ZC03NGY4LTQ5YzktOWI4OC1kMzEyN2
Q2ZDczMDAiLCJzdWIiOiI5MWQ5NGZiZC0xODk2LTQyMTctODlkNy0wM2M4ZTY4Y2YwYTAiLCJvcmdhbml6YXRpb
25JZCI6ImE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMTg2NzczMSwiZXhw
IjoxNTExODY4NjMyLCJyb2xlcyI6WyJsYWJlbC1zZXJ2aWNlLkIyWCIsInBpY2t1cC1zZXJ2aWNlLkIyWCJdLCJ
hY2NvdW50cyI6WyI3NDY1NjE3MCIsIjEyMzQ1Njk4IiwiNDU5MDAxMDAiLCI0MDA0NDU4OSIsIjg3NjU0MzIxIi
wiMzMzMzMzMzMiLCIwNTkyMDUxNyIsIjA4NTAwMDAxIiwiMTIzNDU2NzgiLCIwNTk1Nzg0MCJdfQ.KywXOWovoS
Vf1WJ-CWAJ9j4rUXuMp-f0q2c2PKkOZno",
"Accept: application/pdf",
]
);
// Create body
$json_array = [
"accountId" => "01234567",
"labelId" => "85146e8f-c5c6-40a5-9a1b-25548d607cd7",
"receiver" => [
"email" => "[email protected]",
"phoneNumber" => "0031612345678",
"name" => [
"firstName" => "Slab",
"companyName" => "Lechio",
"lastName" => "Krampus"
],
"address" => [
"countryCode" => "NL",
"number" => "74",
"isBusiness" => true,
"street" => "Baan",
"city" => "Rotterdam",
"postalCode" => "3011CD"
]
],
"shipper" => [
"email" => "[email protected]",
"phoneNumber" => "0031612345678",
"name" => [
"firstName" => "Jan",
"lastName" => "Jansen"
],
"address" => [
"street" => "Reactorweg",
"city" => "Utrecht",
"number" => "25",
"postalCode" => "3542AD",
"isBusiness" => true,
"addition" => "A",
"countryCode" => "NL"
]
],
"options" => [
[
"key" => "DOOR"
],
[
"key" => "COD_CASH",
"input" => "5"
]
],
"returnLabel" => false,
"pieces" => [
[
"parcelType" => "SMALL",
"quantity" => 1
]
]
];
$body = json_encode($json_array);

// Set body
curl_setopt($ch, CURLOPT_POST, 1 );
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
die('Error: "'. curl_error($ch). '" - Code: '. curl_errno($ch));
} else {
echo "Response HTTP Status Code : ". curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo "\nResponse HTTP Body : ". $resp;
}

// Close request to clear up some resources
curl_close($ch);
PHP cURL - WordPress 
<?php
// Create JSON body
$json = json_encode( array(
'accountId' => '01234567',
'labelId' => '1e877014-fa2f-424c-95e7- 2 e2e8a05af44',
'receiver' => array(
'email' => '[email protected]',
'phoneNumber' => '0031612345678',
'name' => array(
'firstName' => 'Slab',
'companyName' => 'Lechio',
'lastName' => 'Krampus'
),,
'address' => array(
'countryCode' => 'NL',
'number' => '74',
'isBusiness' => true,
'street' => 'Baan',
'city' => 'Rotterdam',
'postalCode' => '3011CD'
),
),,
'shipper' => array(
'email' => '[email protected]',
'phoneNumber' => '0031612345678',
'name' => array(
'firstName' => 'Jan',
'lastName' => 'Jansen'
),,
'address' => array(
'street' => 'Reactorweg',
'city' => 'Utrecht',
'number' => '25',
'postalCode' => '3542AD',
'isBusiness' => true,
'addition' => 'A',
'countryCode' => 'NL'
),
),,
'options' => array(
array(
'key' => 'DOOR'
),,
array(
'key' => 'COD_CASH',
'input' => '5'
),
),,
'pieces' => array(
'parcelType' => 'SMALL',
'quantity' => 1 ,
),,
'returnLabel' => false
) );

// {@see https://codex.wordpress.org/HTTP_API}
$response = wp_remote_post( 'https://api-gw.dhlparcel.nl/shipments', array(
'headers' => array(
'Content-Type' => 'application/json; charset=utf-8',
'Authorization' => 'Bearer
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJkYWFkNzU3ZC03NGY4LTQ5YzktOWI4OC1kMzEyN2
Q2ZDczMDAiLCJzdWIiOiI5MWQ5NGZiZC0xODk2LTQyMTctODlkNy0wM2M4ZTY4Y2YwYTAiLCJvcmdhbml6YXRpb
25JZCI6ImE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMTg2NzczMSwiZXhw
IjoxNTExODY4NjMyLCJyb2xlcyI6WyJsYWJlbC1zZXJ2aWNlLkIyWCIsInBpY2t1cC1zZXJ2aWNlLkIyWCJdLCJ
hY2NvdW50cyI6WyI3NDY1NjE3MCIsIjEyMzQ1Njk4IiwiNDU5MDAxMDAiLCI0MDA0NDU4OSIsIjg3NjU0MzIxIi
wiMzMzMzMzMzMiLCIwNTkyMDUxNyIsIjA4NTAwMDAxIiwiMTIzNDU2NzgiLCIwNTk1Nzg0MCJdfQ.KywXOWovoS
Vf1WJ-CWAJ9j4rUXuMp-f0q2c2PKkOZno',
'Accept' => 'application/pdf',
),
'body' => $json,
) );

if (! is_wp_error( $response ) ) {
// The request went through successfully, check the response code against
// what we're expecting
if ( 200 == wp_remote_retrieve_response_code( $response ) ) {
// Do something with the response
// $body = wp_remote_retrieve_body( $response );
// $headers = wp_remote_retrieve_headers( $response );
} else {
// The response code was not what we were expecting, record the message
$error_message = wp_remote_retrieve_response_message( $response );


}
} else {
// There was an error making the request
$error_message = $response->get_error_message();
}

Responses

Success (code 201) 
{
  "shipmentId": "15916857-2a31-4238-a45b-e7ba32e0e320",
  "shipmentTrackerCode": "0123456789",
  "pieces": [
    {
      "labelId": "061091e9-f6cf-453e-951d-5a276303d060",
      "trackerCode": "JVGL08500001813590386271",
      "parcelType": "SMALL",
      "pieceNumber": 1,
      "weight": 1
    }
  ],
}

4.3.2 Create Label

Request examples

Curl 
curl -X POST "https://api-gw.dhlparcel.nl/labels" -H "Accept: application/json" -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJhNzAxN2EzZi1jMGYzLTQ3ZTAtOGQzNC1mMmZhMDFjYTlkY2EiLCJzdWIiOiI2YmZjNzU2MS00YjQxLTRjYjctYTFjMy1kYzMxZmFmODYwZGIiLCJvcmdhbml6YXRpb25JZCI6ImE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMTg2NzUwNywiZXhwIjoxNTExODY4NDA4LCJyb2xlcyI6WyJsYWJlbC1zZXJ2aWNlLkIyWCIsInBpY2t1cC1zZXJ2aWNlLkIyWCJdLCJhY2NvdW50cyI6WyIwODUwMDAwMSJdfQ.Qs79I-LW0ES4mO8hObOiZXvuuipBQ_-eJ7pd-10rrSQ" -H "Content-Type: application/json" -d "{ \"labelId\": \"331708e4-e876-4f9a-94f3-c74bd482988b\",\"labelFormat\": \"pdf\", \"orderReference\":\"myReference\",\"parcelTypeKey\": \"SMALL\", \"receiver\": { \"name\": { \"firstName\": \"John\",\"lastName\": \"Doe\", \"companyName\": \"ACME Corp.\", \"additionalName\": \"Benelux\"}, \"address\": { \"countryCode\": \"NL\", \"postalCode\": \"3542AD\", \"city\":\"Utrecht\", \"street\": \"Reactorweg\", \"number\": \"25\", \"isBusiness\": true,\"addition\": \"A\" }, \"email\": \"[email protected]\", \"phoneNumber\":\"0031612345678\" }, \"shipper\": { \"name\": { \"firstName\": \"John\", \"lastName\":\"Doe\", \"companyName\": \"ACME Corp.\", \"additionalName\": \"Benelux\" },\"address\": { \"countryCode\": \"NL\", \"postalCode\": \"3542AD\", \"city\":\"Utrecht\", \"street\": \"Reactorweg\", \"number\": \"25\", \"isBusiness\": true,\"addition\": \"A\" }, \"email\": \"[email protected]\", \"phoneNumber\":\"0031612345678\" }, \"accountId\": \"01234567\", \"options\": [ { \"key\": \"DOOR\" }], \"returnLabel\": false,\"pieceNumber\": 1, \"quantity\": 1,\"automaticPrintDialog\": true}"
PHP 
<?php
// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://api-gw.dhlparcel.nl/labels');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');


// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1 );

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Content-Type: application/json; charset=utf-8",
"Authorization: Bearer
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJkYWFkNzU3ZC03NGY4LTQ5YzktOWI4OC1kMzEyN2
Q2ZDczMDAiLCJzdWIiOiI5MWQ5NGZiZC0xODk2LTQyMTctODlkNy0wM2M4ZTY4Y2YwYTAiLCJvcmdhbml6YXRpb
25JZCI6ImE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMTg2NzczMSwiZXhw
IjoxNTExODY4NjMyLCJyb2xlcyI6WyJsYWJlbC1zZXJ2aWNlLkIyWCIsInBpY2t1cC1zZXJ2aWNlLkIyWCJdLCJ
hY2NvdW50cyI6WyI3NDY1NjE3MCIsIjEyMzQ1Njk4IiwiNDU5MDAxMDAiLCI0MDA0NDU4OSIsIjg3NjU0MzIxIi
wiMzMzMzMzMzMiLCIwNTkyMDUxNyIsIjA4NTAwMDAxIiwiMTIzNDU2NzgiLCIwNTk1Nzg0MCJdfQ.KywXOWovoS
Vf1WJ-CWAJ9j4rUXuMp-f0q2c2PKkOZno",
"Accept: application/pdf",
]
);
// Create body
$json_array = [
"accountId" => "01234567",
"labelId" => "85146e8f-c5c6-40a5-9a1b-25548d607cd7",
"receiver" => [
"email" => "[email protected]",
"phoneNumber" => "0031612345678",
"name" => [
"firstName" => "Slab",
"companyName" => "Lechio",
"lastName" => "Krampus"
],
"address" => [
"countryCode" => "NL",
"number" => "74",
"isBusiness" => true,
"street" => "Baan",
"city" => "Rotterdam",
"postalCode" => "3011CD"
]
],
"shipper" => [
"email" => "[email protected]",
"phoneNumber" => "0031612345678",
"name" => [
"firstName" => "Jan",
"lastName" => "Jansen"
],
"address" => [
"street" => "Reactorweg",
"city" => "Utrecht",
"number" => "25",
"postalCode" => "3542AD",
"isBusiness" => true,
"addition" => "A",
"countryCode" => "NL"
]
],
"parcelTypeKey" => "SMALL",
"pieceNumber" => 1 ,
"quantity" => 1 ,
"automaticPrintDialog" => false,


"options" => [
[
"key" => "DOOR"
],
[
"key" => "COD_CASH",
"input" => "5"
]
],
"returnLabel" => false
];
$body = json_encode($json_array);

// Set body
curl_setopt($ch, CURLOPT_POST, 1 );
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
die('Error: "'. curl_error($ch). '" - Code: '. curl_errno($ch));
} else {
echo "Response HTTP Status Code : ". curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo "\nResponse HTTP Body : ". $resp;
}

// Close request to clear up some resources
curl_close($ch);
PHP cURL - WordPress 
<?php
// Create JSON body
$json = json_encode( array(
'accountId' => '01234567',
'labelId' => '1e877014-fa2f-424c-95e7- 2 e2e8a05af44',
'receiver' => array(
'email' => '[email protected]',
'phoneNumber' => '0031612345678',
'name' => array(
'firstName' => 'Slab',
'companyName' => 'Lechio',
'lastName' => 'Krampus'
),,
'address' => array(
'countryCode' => 'NL',
'number' => '74',
'isBusiness' => true,
'street' => 'Baan',
'city' => 'Rotterdam',
'postalCode' => '3011CD'
),
),,
'shipper' => array(


'email' => '[email protected]',
'phoneNumber' => '0031612345678',
'name' => array(
'firstName' => 'Jan',
'lastName' => 'Jansen'
),,
'address' => array(
'street' => 'Reactorweg',
'city' => 'Utrecht',
'number' => '25',
'postalCode' => '3542AD',
'isBusiness' => true,
'addition' => 'A',
'countryCode' => 'NL'
),
),,
'parcelTypeKey' => 'SMALL',
'pieceNumber' => 1 ,
'quantity' => 1 ,
'automaticPrintDialog' => false,
'options' => array(
array(
'key' => 'DOOR'
),,
array(
'key' => 'COD_CASH',
'input' => '5'
),
),,
'returnLabel' => false
) );

// {@see https://codex.wordpress.org/HTTP_API}
$response = wp_remote_post( 'https://api-gw.dhlparcel.nl/labels', array(
'headers' => array(
'Content-Type' => 'application/json; charset=utf-8',
'Authorization' => 'Bearer
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJkYWFkNzU3ZC03NGY4LTQ5YzktOWI4OC1kMzEyN2
Q2ZDczMDAiLCJzdWIiOiI5MWQ5NGZiZC0xODk2LTQyMTctODlkNy0wM2M4ZTY4Y2YwYTAiLCJvcmdhbml6YXRpb
25JZCI6ImE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMTg2NzczMSwiZXhw
IjoxNTExODY4NjMyLCJyb2xlcyI6WyJsYWJlbC1zZXJ2aWNlLkIyWCIsInBpY2t1cC1zZXJ2aWNlLkIyWCJdLCJ
hY2NvdW50cyI6WyI3NDY1NjE3MCIsIjEyMzQ1Njk4IiwiNDU5MDAxMDAiLCI0MDA0NDU4OSIsIjg3NjU0MzIxIi
wiMzMzMzMzMzMiLCIwNTkyMDUxNyIsIjA4NTAwMDAxIiwiMTIzNDU2NzgiLCIwNTk1Nzg0MCJdfQ.KywXOWovoS
Vf1WJ-CWAJ9j4rUXuMp-f0q2c2PKkOZno',
'Accept' => 'application/pdf',
),
'body' => $json,
) );

if (! is_wp_error( $response ) ) {
// The request went through successfully, check the response code against
// what we're expecting
if ( 200 == wp_remote_retrieve_response_code( $response ) ) {
// Do something with the response
// $body = wp_remote_retrieve_body( $response );
// $headers = wp_remote_retrieve_headers( $response );
} else {
// The response code was not what we were expecting, record the message
$error_message = wp_remote_retrieve_response_message( $response );


}
} else {
// There was an error making the request
$error_message = $response->get_error_message();
}

Responses

Success (code 201) 
{
  "labelId": "331708e4-e876-4f9a-94f3-c74bd482988b",
  "labelType": "B2X_Generic_A4_Third",
  "trackerCode": "JVGL01234567889003262926",
  "routingCode": "2LNL3542AD+04000000",
  "userId": "a86628b8-a4bd-436b-8d92-cd735223c9e5",
  "orderReference": "myReference",
  "pdf": "<pdf-label>"
}

4.3.3 Get Label (trackerCodeFilter)

Request examples

Curl 
curl -X GET "https://api-gw.dhlparcel.nl/labels?trackerCodeFilter=JVGL08500001813590386271" -H "Accept:application/json" -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJhNzAxN2EzZi1jMGYzLTQ3ZTAtOGQzNC1mMmZhMDFjYTlkY2EiLCJzdWIiOiI2YmZjNzU2MS00YjQxLTRjYjctYTFjMy1kYzMxZmFmODYwZGIiLCJvcmdhbml6YXRpb25JZCI6ImE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMTg2NzUwNywiZXhwIjoxNTExODY4NDA4LCJyb2xlcyI6WyJsYWJlbC1zZXJ2aWNlLkIyWCIsInBpY2t1cC1zZXJ2aWNlLkIyWCJdLCJhY2NvdW50cyI6WyIwODUwMDAwMSJdfQ.Qs79I-LW0ES4mO8hObOiZXvuuipBQ_-eJ7pd-10rrSQ"

Responses

Success (code 200) 
[
  {
    "labelId": "ecda3006-b605-413f-b3b1-e0dca32e987e",
    "orderReference": "393d649c-fdf4-4e16-b329-40c36e8cff48",
    "labelType": "B2X_Generic_A4_Third",
    "trackerCode": "JVGL08500001813590386271",
    "routingCode": "2LIC12342+04000001",
    "userId": "6bfc7561-4b41-4cb7-a1c3-dc31faf860db",
    "organizationId": "a40933de-bd17- 4944 - b7e9-23fc7ee9c835"
  }
]

4.3.4 Get pdf label specific shipment

Request examples

Curl 
curl -X GET "https://api-gw.dhlparcel.nl/labels/ecda3006-b605-413f-b3b1-e0dca32e987e" -H "Accept: application/json" -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJhNzAxN2EzZi1jMGYzLTQ3ZTAtOGQzNC1mMmZhMDFjYTlkY2EiLCJzdWIiOiI2YmZjNzU2MS00YjQxLTRjYjctYTFjMy1kYzMxZmFmODYwZGIiLCJvcmdhbml6YXRpb25JZCI6ImE0MDkzM2RlLWJkMTctNDk0NC1iN2U5LTIzZmM3ZWU5YzgzNSIsIm5iZiI6MTUxMTg2NzUwNywiZXhwIjoxNTExODY4NDA4LCJyb2xlcyI6WyJsYWJlbC1zZXJ2aWNlLkIyWCIsInBpY2t1cC1zZXJ2aWNlLkIyWCJdLCJhY2NvdW50cyI6WyIwODUwMDAwMSJdfQ.Qs79I-LW0ES4mO8hObOiZXvuuipBQ_-eJ7pd-10rrSQ"

Responses

Success (code 200): 
{
  "labelId": "ecda3006-b605-413f-b3b1-e0dca32e987e",
  "labelType": "B2X_Generic_A4_Third",
  "trackerCode": "JVGL08500001813590386271",
  "routingCode": "2LIC12342+04000001",
  "userId": "6bfc7561-4b41-4cb7-a1c3-dc31faf860db",
  "organizationId": "a40933de-bd17- 4944 - b7e9-23fc7ee9c835",
  "orderReference": "393d649c-fdf4-4e16-b329-40c36e8cff48",
  "pdf": "<base64-encoded pdf-label>"
}

4.3.5 Create printless label

A printless label is not printed by the customer, but will be printed by DHL based on a QR-code at a DHL ServicePoint. By default, printless labels can be used for your B2C returns from NL.

printless label

By setting the value of the ‘returnLabel’ attribute to ‘true’ and adding the PRINTLESS option to a Create shipment request, the endpoint will create a printless QR code for the return shipment.

{
  "options": [
    {
      "key": "PRINTLESS"
     }
   ]
}

By default, shipment notifications including the generated QR code will be sent for return shipments. Triggering notifications can be disabled using the option input.

{
  "options": [
    {
      "key": "PRINTLESS",
        "input": {
          "notification": false
       }
     }
   ]
}

The response includes the printless codes, which can be used to generate customs QR codes.

{
    "shipmentId": "545d5455-c313-46fc-9546-9be146d5a056",
    "product": "DFY-B2C",
    "pieces": [
        {
            "printlessCode": "MDP5KLWYM4R",
            "parcelType": "MEDIUM",
            "pieceNumber": 1,
            "labelType": "PRINTLESS_QR"
        }
    ]
}

4.4 Testing

These test cases with positive outcomes are merely suggestions and it is not an extensive test set, e.g. test with negative outcome should also be taken into scope. Please extend with test cases which are suitable for your line of business or wishes.

Suggested Test Cases Expected Result
Create a shipment A shipment is created and the identifying information is returned. Get label id by tracking code or order reference and the label identification is returned.
Create a label A label is created and the identifying information and pdf of the label is returned. Get label id by tracking code or order reference and the label identification is returned.
Get pdf label by id The pdf of the label is returned.