2 Capabilities

2.1 Intro

The Capabilities endpoint lists the available shipment options (and their exclusions) given a certain country, parcel type and whether the recipient of the parcel is a business or a consumer.

The purpose of the endpoint is twofold: it offers all available options to choose from for a given situation, and can then validate the interdependency of all variables for a shipment, serving as a validation tool for your shipment request.

Per situation you should think of what is possible in terms of the kind of shipment, if it is a business-to-business or business-to-consumer shipment, does your account allow you to create return shipments or a same day delivery.

The Create Label endpoint makes use of the capabilities endpoint, thereby checking the validity of a shipment the same way.

Preconditions

No preconditions are applicable.

2.2 Services

2.2.1 Capabilities

In order to get the correct capabilities for your shipment, in addition to the sender type (mandatory), at least the top three fields in the table below should be given in order to get the applicable set of options for a specific shipment. Without these parameters, the request will result in a too broad dataset to be useful for a single shipment.

In certain cases, it is better to not supply the ‘parcelType’ and ‘shipmentOptions’ fields. The input fields work like a filter, returning only valid product combinations; when provided with an impossible combination of options, the endpoint will not return an error message, but simply return an empty list.

For example, when Saturday delivery (‘S’) is present and toBusiness is set to true, the call will be successful, but the response will not contain possible shipment options. In fact that means that there are none, since these options are incompatible with each other.

Parcel types can be cross-referenced through the Parcel type endpoint. This is useful since available parcel types can differ per country. The same applies for the Shipments options endpoint, where options differ per origin/destination country pair.

Field	Description
fromCountry	Country code of origin
toCountry	Country code of destination
toBusiness	Does it concern a delivery to a business? True or false
parcelType	Check Parcel type API. A parcel type is available or valid depending on the ‘senderType’ and the values of ‘toBusiness’ and ‘fromCountry’. See Ad 1.
shipment options	Check Shipment options API. Depending on the values of ‘senderType’, ‘parcelType’, ‘fromCountry’ and ‘toBusiness’ options are available. Some options are excluded based on the chosen option(s). See Ad 2.

As a result of a ‘successful’ call the API will return all possible parcel types, shipment options with its exclusions.

Ad 1. For example parcel Type “PALLET” is known in the Netherlands, but not in Spain. In order to get the right parcel types from the sender’s point of view (country code), the Parcel type endpoint should be used.

This is just one example why the input needs to be cross-referenced with the Parcel types (or with the Shipment options) endpoint. As already mentioned, the input in itself will not be validated through the Capabilities endpoint. Providing non-existent or incompatible options will just yield an empty list.

[{
  "key": "SMALL",
  "minWeightKg": 0,
  "maxWeightKg": 5,
  "dimensions": {
    "maxLengthCm": 25,
    "maxWidthCm": 20,
    "maxHeightCm": 5
  }
},{
  "key": "MEDIUM",
  "minWeightKg": 5,
  "maxWeightKg": 15,
  "dimensions": {
    "maxLengthCm": 60,
    "maxWidthCm": 50,
    "maxHeightCm": 25
  }
},{
  "key": "LARGE",
  "minWeightKg": 16,
  "maxWeightKg": 31,
  "dimensions": {
    "maxLengthCm": 120,
    "maxWidthCm": 60,
    "maxHeightCm": 60
  }
},{
  "key": "BULKY",
  "minWeightKg": 0,
  "maxWeightKg": 31,
  "dimensions": {
    "maxLengthCm": 200,
    "maxWidthCm": 120,
    "maxHeightCm": 80
  }
}]

Ad 2. The option “PS”, meaning delivery to a DHL Servicepoint, and the option “DOOR”, delivery at the door, of course do not go together. If chosen together in the Capabilities endpoint the response code is 200, but the result will be an empty array.

In the snippet of the Shipment options endpoint below you can see that “DOOR” is listed as an exclusion to the shipment option “PS”, indicating their incompatibility.

{
  "key": "PS",
  "description": "Delivery to the specified DHL Parcelshop or DHL Parcelstation",
  "rank": 1,
  "code": 21,
  "inputType": "text",
  "exclusions": [
    {
      "key": "EVE",
      "rank": 13,
      "code": 14
    },
    {
      "key": "S",
      "rank": 11,
      "code": 15
    },
    {
      "key": "NBB",
      "rank": 14,
      "code": 36
    },
    {
      "key": "HANDT",
      "rank": 12,
      "code": 56
    },
    {
      "key": "DOOR",
      "rank": 2,
      "code": 0
    },
    {
      "key": "COD_CASH",
      "rank": 17,
      "code": 0,
      "inputType": "number"
    },
    {
      "key": "COD_CHECK",
      "rank": 18,
      "code": 0,
      "inputType": "number"
    },
    {
      "key": "EXP",
      "rank": 15,
      "code": 1
    },
    {
      "key": "H",
      "rank": 4,
      "code": 21
    },
    {
      "key": "BOUW",
      "rank": 19,
      "code": 0
    },
    {
      "key": "EXW",
      "rank": 20,
      "code": 0
    },
    {
      "key": "SSN",
      "rank": 16,
      "code": 0,
      "inputType": "address"
    },
    {
      "key": "RECAP",
      "rank": 21,
      "code": 0,
      "inputType": "text"
    },
    {
      "key": "BP",
      "rank": 3,
      "code": 91
    },
    {
      "key": "SDD",
      "rank": 7,
      "code": 6
    },
    {
      "key": "NO_TT",
      "rank": 22,
      "code": 0
    }
  ]
}

If, for example, a “SMALL” parcel type is chosen and the delivery of the parcel is to a business (toBusiness = true) and the chosen option is “PS”, again the response will be successful, but there is no result.

It might be better to not have shipment option(s) and or parcel types as input. The endpoint will then return all parcel types and options available based on the base input (toBusiness, fromCountry and toCountry).

Then, in your application, show a list of returned options the end-user can choose from and validate each option against its exclusions.

If no shipment option is entered as input for the endpoint, like in the last example (toBusiness = true, fromCountry=NL and toCountry=NL) , the shipment option “PS” will only show up in the result of certain parcel types.

[
  {
    "rank": 2,
    "fromCountryCode": "NL",
    "toCountryCode": "NL",
    "product": {
      "key": "EPL",
      "label": "EUROPLUS",
      "code": "04",
      "menuCode": "01",
      "businessProduct": true,
      "monoColloProduct": false,
      "softwareCharacteristic": "B2X",
      "returnProduct": false
    },
    "parcelType": {
      "key": "SMALL",
      "minWeightKg": 0,
      "maxWeightKg": 20,
      "dimensions": {
        "maxLengthCm": 80,
        "maxWidthCm": 50,
        "maxHeightCm": 35
      }
    },
    "options": [
      {
        "key": "DOOR",
        "description": "Delivery to the address of the recipient",
        "rank": 2,
        "code": 0,
        "exclusions": [
          {
            "key": "PS",
            "rank": 1,
            "code": 21,
            "inputType": "text"
          },
          {
            "key": "BP",
            "rank": 3,
            "code": 91
          },
          {
            "key": "NO_TT",
            "rank": 22,
            "code": 0
          }
        ]
      },
      {
        "key": "H",
        "description": "Hold for collection",
        "rank": 4,
        "code": 21,
        "exclusions": [
          {
            "key": "PS",
            "rank": 1,
            "code": 21,
            "inputType": "text"
          },
          {
            "key": "EVE",
            "rank": 13,
            "code": 14
          },
          {
            "key": "EA",
            "rank": 9,
            "code": 58
          },
          {
            "key": "EXP",
            "rank": 15,
            "code": 1
          },
          {
            "key": "BOUW",
            "rank": 19,
            "code": 0
          },
          {
            "key": "BP",
            "rank": 3,
            "code": 91
          },
          {
            "key": "DOOR",
            "rank": 2,
            "code": 0
          }
        ]
      },
      {
        "key": "REFERENCE",
        "description": "Reference",
        "rank": 5,
        "code": 0,
        "inputType": "text",
        "inputMax": "15"
      },
      {
        "key": "PERS_NOTE",
        "description": "E-mail to receiver",
        "rank": 6,
        "code": 0,
        "inputType": "text"
      },
      {
        "key": "ADD_RETURN_LABEL",
        "description": "Print extra label for return shipment",
        "rank": 8,
        "code": 0
      },
      {
        "key": "INS",
        "description": "All risks insurance",
        "rank": 10,
        "code": 0,
        "inputType": "number"
      },
      {
        "key": "S",
        "description": "Saturday delivery",
        "rank": 11,
        "code": 15,
        "exclusions": [
          {
            "key": "PS",
            "rank": 1,
            "code": 21,
            "inputType": "text"
          },
          {
            "key": "EVE",
            "rank": 13,
            "code": 14
          },
          {
            "key": "EXP",
            "rank": 15,
            "code": 1
          },
          {
            "key": "BP",
            "rank": 3,
            "code": 91
          }
        ]
      },
      {
        "key": "EXP",
        "description": "Expresser",
        "rank": 15,
        "code": 1,
        "exclusions": [
          {
            "key": "PS",
            "rank": 1,
            "code": 21,
            "inputType": "text"
          },
          {
            "key": "EVE",
            "rank": 13,
            "code": 14
          },
          {
            "key": "EA",
            "rank": 9,
            "code": 58
          },
          {
            "key": "S",
            "rank": 11,
            "code": 15
          },
          {
            "key": "H",
            "rank": 4,
            "code": 21
          },
          {
            "key": "BP",
            "rank": 3,
            "code": 91
          }
        ]
      },
      {
        "key": "SSN",
        "description": "Undisclosed sender",
        "rank": 16,
        "code": 0,
        "inputType": "address",
        "exclusions": [
          {
            "key": "PS",
            "rank": 1,
            "code": 21,
            "inputType": "text"
          },
          {
            "key": "EVE",
            "rank": 13,
            "code": 14
          },
          {
            "key": "EA",
            "rank": 9,
            "code": 58
          },
          {
            "key": "BP",
            "rank": 3,
            "code": 91
          }
        ]
      },
      {
        "key": "COD_CASH",
        "description": "Cash on delivery. Payment method cash.",
        "rank": 17,
        "code": 0,
        "inputType": "number",
        "exclusions": [
          {
            "key": "COD_CHECK",
            "rank": 18,
            "code": 0,
            "inputType": "number"
          },
          {
            "key": "PS",
            "rank": 1,
            "code": 21,
            "inputType": "text"
          },
          {
            "key": "EVE",
            "rank": 13,
            "code": 14
          },
          {
            "key": "EA",
            "rank": 9,
            "code": 58
          },
          {
            "key": "BP",
            "rank": 3,
            "code": 91
          }
        ]
      },
      {
        "key": "BOUW",
        "description": "Delivery to construction site",
        "rank": 19,
        "code": 0,
        "exclusions": [
          {
            "key": "PS",
            "rank": 1,
            "code": 21,
            "inputType": "text"
          },
          {
            "key": "EVE",
            "rank": 13,
            "code": 14
          },
          {
            "key": "EA",
            "rank": 9,
            "code": 58
          },
          {
            "key": "H",
            "rank": 4,
            "code": 21
          },
          {
            "key": "BP",
            "rank": 3,
            "code": 91
          }
        ]
      },
      {
        "key": "EXW",
        "description": "Ex Works",
        "rank": 20,
        "code": 0,
        "exclusions": [
          {
            "key": "PS",
            "rank": 1,
            "code": 21,
            "inputType": "text"
          },
          {
            "key": "EVE",
            "rank": 13,
            "code": 14
          },
          {
            "key": "EA",
            "rank": 9,
            "code": 8
          },
          {
            "key": "BP",
            "rank": 3,
            "code": 91
          }
        ]
      },
      {
        "key": "REFERENCE2",
        "description": "Reference",
        "rank": 22,
        "code": 0,
        "inputType": "text",
        "inputMax": "70"
      }
    ]
  }
]

2.3 API Usage

Description	Production
Retrieve capabilities	https://api-gw.dhlparcel.nl/capabilities/business?

2.3.1 Retrieve capabilities

Request examples

Curl

curl -X GET "https://api-gw.dhlparcel.nl/capabilities/business?fromCountry=NL&toCountry=NL&toBusiness=false&parcelType=SMALL&option=PS" -H "Accept: application/json"

PHP - WordPress

<?php
// {@see https://codex.wordpress.org/HTTP_API}
$response = wp_remote_get( 'https://api-gw.dhlparcel.nl/capabilities/business?fromCountry=NL&toCountry=NL&toBusiness=false&parcelType=SMALL&option=PS', array(
'headers' => array(
'Accept' => 'application/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();
}

PHP cURL - WordPress

<?php
// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://api-gw.dhlparcel.nl/capabilities/business?fromCountry=NL&toCountry=NL&toBusiness=false&parcelType=SMALL&option=PS');

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

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

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Accept: application/json",
]
);


// 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);

Responses

Success (code 200):

[
  {
    "rank": 2,
    "fromCountryCode": "NL",
    "toCountryCode": "NL",
    "product": {
      "key": "EPL",
      "label": "EUROPLUS",
      "code": "04",
      "menuCode": "01",
      "businessProduct": true,
      "monoColloProduct": false,
      "softwareCharacteristic": "B2X",
      "returnProduct": false
    },
    "parcelType": {
      "key": "PALLET",
      "minWeightKg": 50,
      "maxWeightKg": 1000,
      "dimensions": {
        "maxLengthCm": 240,
        "maxWidthCm": 100,
        "maxHeightCm": 200
      }
    },
    "options": [
      {
        "key": "DOOR",
        "description": "Delivery to the address of the recipient",
        "rank": 2,
        "code": 0,
        "exclusions": [
          {
            "key": "PS",
            "rank": 1,
            "code": 21,
            "inputType": "text"
          },
          {
            "key": "BP",
            "rank": 3,
            "code": 91
          },
          {
            "key": "NO_TT",
            "rank": 22,
            "code": 0
          }
        ]
      },
      {
        "key": "H",
        "description": "Hold for collection",
        "rank": 4,
        "code": 21,
        "exclusions": [
          {
            "key": "PS",
            "rank": 1,
            "code": 21,
            "inputType": "text"
          },
          {
            "key": "EVE",
            "rank": 13,
            "code": 14
          },
          {
            "key": "EA",
            "rank": 9,
            "code": 58
          },
          {
            "key": "EXP",
            "rank": 15,
            "code": 1
          },
          {
            "key": "BOUW",
            "rank": 19,
            "code": 0
          },
          {
            "key": "BP",
            "rank": 3,
            "code": 91
          },
          {
            "key": "DOOR",
            "rank": 2,
            "code": 0
          }
        ]
      },
      {
        "key": "REFERENCE",
        "description": "Reference",
        "rank": 5,
        "code": 0,
        "inputType": "text",
        "inputMax": "15"
      },
      {
        "key": "PERS_NOTE",
        "description": "E-mail to receiver",
        "rank": 6,
        "code": 0,
        "inputType": "text"
      },
      {
        "key": "ADD_RETURN_LABEL",
        "description": "Print extra label for return shipment",
        "rank": 8,
        "code": 0
      },
      {
        "key": "INS",
        "description": "All risks insurance",
        "rank": 10,
        "code": 0,
        "inputType": "number"
      },
      {
        "key": "EXP",
        "description": "Expresser",
        "rank": 15,
        "code": 1,
        "exclusions": [
          {
            "key": "PS",
            "rank": 1,
            "code": 21,
            "inputType": "text"
          },
          {
            "key": "EVE",
            "rank": 13,
            "code": 14
          },
          {
            "key": "EA",
            "rank": 9,
            "code": 58
          },
          {
            "key": "S",
            "rank": 11,
            "code": 15
          },
          {
            "key": "H",
            "rank": 4,
            "code": 21
          },
          {
            "key": "BP",
            "rank": 3,
            "code": 91
          }
        ]
      },
      {
        "key": "SSN",
        "description": "Undisclosed sender",
        "rank": 16,
        "code": 0,
        "inputType": "address",
        "exclusions": [
          {
            "key": "PS",
            "rank": 1,
            "code": 21,
            "inputType": "text"
          },
          {
            "key": "EVE",
            "rank": 13,
            "code": 14
          },
          {
            "key": "EA",
            "rank": 9,
            "code": 58
          },
          {
            "key": "BP",
            "rank": 3,
            "code": 91
          }
        ]
      },
      {
        "key": "COD_CASH",
        "description": "Cash on delivery. Payment method cash.",
        "rank": 17,
        "code": 0,
        "inputType": "number",
        "exclusions": [
          {
            "key": "COD_CHECK",
            "rank": 18,
            "code": 0,
            "inputType": "number"
          },
          {
            "key": "PS",
            "rank": 1,
            "code": 21,
            "inputType": "text"
          },
          {
            "key": "EVE",
            "rank": 13,
            "code": 14
          },
          {
            "key": "EA",
            "rank": 9,
            "code": 58
          },
          {
            "key": "BP",
            "rank": 3,
            "code": 91
          }
        ]
      },
      {
        "key": "BOUW",
        "description": "Delivery to construction site",
        "rank": 19,
        "code": 0,
        "exclusions": [
          {
            "key": "PS",
            "rank": 1,
            "code": 21,
            "inputType": "text"
          },
          {
            "key": "EVE",
            "rank": 13,
            "code": 14
          },
          {
            "key": "EA",
            "rank": 9,
            "code": 58
          },
          {
            "key": "H",
            "rank": 4,
            "code": 21
          },
          {
            "key": "BP",
            "rank": 3,
            "code": 91
          }
        ]
      },
      {
        "key": "EXW",
        "description": "Ex Works",
        "rank": 20,
        "code": 0,
        "exclusions": [
          {
            "key": "PS",
            "rank": 1,
            "code": 21,
            "inputType": "text"
          },
          {
            "key": "EVE",
            "rank": 13,
            "code": 14
          },
          {
            "key": "EA",
            "rank": 9,
            "code": 58
          },
          {
            "key": "BP",
            "rank": 3,
            "code": 91
          }
        ]
      },
      {
        "key": "REFERENCE2",
        "description": "Reference",
        "rank": 22,
        "code": 0,
        "inputType": "text",
        "inputMax": "70"
      }
    ]
  }
]

2.4 Testing

These test cases with positive outcomes are merely suggestions and it is not an extensive test set, e.g. tests with a 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
Check capabilities business to business	Parcel type(s) with options are returned for a business based on the input of being a business, country code and shipment option(s) and or on a specific parcel type.
Check capabilities business to consumer	Parcel type(s) with options are returned for a consumer based on the input of being a consumer, country code and shipment option(s) and or on a specific parcel type.