DHL eCommerce Americas Product Finder API enables clients to determine which DHL shipping products are suitable for a given shipping request including associated rates and estimated delivery dates (EDD). The rates returned are account-specific along with a list of applicable surcharges (if any). The DHL Product Finder API covers most DHL eCommerce Americas shipping products, both Domestic and International.

Scope

The following operations are allowed in the Product Finder API:

Workflow

The Product Finder request consists of three parts -

• label request: with or without

  orderedProductId

• rate: true or false, if true provide more optional information
• estimatedDeliveryDate: true or false, if true provide more optional information

The first part of the request is exactly the same as the label request except for orderedProductId, which is mandatory in the label request. In the Product Finder, this field is optional, allowing the Product Finder to search for all possible products which satisfy the given request.

This allows clients to send a product finder request, choose a desired product from the response, and then reuse the 'label' part of the request to generate a shipping label after inserting the desired

orderedProductId.

Product Finder returns list of possible products in a products array that contains the following objects:

• orderedProductId 

• productName

• description

• trackingAvailable

• rate

• estimatedDeliveryDate

Rate and EDD

rate and estimatedDeliveryDate are optional objects.

rate contains a rateComponents array object that contains the breakdown of all rate components with a total amount.

Below is a list of rate components:

ZBPT – Base Rate

 

ZFL1 – Fuel Surcharge

 

ZSCL – Dim Length Surcharge

 

ZSCV – Dim Volume Surcharge

 

ZVAS – Value Added Service

 

ZSC7 – Non-Qualified Dim

 

ZDAS – Delivery Area Surcharge

deliveryDaysMax field which shows the service level in number of days (E.g.: 2 days) along with a(n) estimatedDeliveryMin and estimatedDeliveryMax field which shows the service level in terms of date (E.g.: 2020-07-13).

At this time, EDD is available for international product DHL Parcel International Direct (DDP only) to Canada, United Kingdom, Mexico and select European Union countries (Austria, Belgium, Denmark, France, Germany, Ireland, Italy, Netherlands and Spain).

Product Finder Response

A Product Finder request can return zero products, one product, more than one product or a 400 error code in the response.

Each of these scenarios is explained below -

Zero products

For the products that are not available in the given combination of Origin, Destination and weight provided in the request -

• some other request element(s) have failed Validation. E.g.: Covid related temporary shipping restriction on the lane

• maxPrice is below the lowest available total amount

• expectedTransit could not be met by any product

• deliveryBy date could not be met by any product 
  In this case, the response will contain an empty products array

"products": [] 

One product

Only one product is possible for the given combination of Origin, Destination and weight that also passes all applicable hard validation rules for the request -

• Providing an orderedProductId in the request. Only that product will be evaluated.

• maxPrice is below the lowest available total amount for exactly one product.

• expectedTransit is met by exactly one product.

• deliveryBy date is met by exactly one product.

  One or more 'soft' validation errors may be reported in the form of messages. Please refer below for what these mean and how to handle them.

More than one product

Multiple products are possible for the given combination of Origin, Destination and weight that also passed all applicable hard validation rules for the request -

• Not providing an orderedProductId in the request. All possible products will be evaluated and returned.

• maxPrice is below the lowest available total amount for more than one product.

• expectedTransit is met by more than one product.

• deliveryBy date is met by more than one product.

  One or more 'soft' validation errors may be reported in the form of messages. Please refer below for what these mean and how to handle them.

Error Response

In multiple scenarios, Product Finder request can return a 400 code along with an error response that can be one of the following -

• Static Validation Failed (400.0604001) - the request did not pass the JSON schema validation. E.g: Date format is invalid for one or more date fields such as rateDate or deliveryBy date

• Dynamic Validation Failed (400.0604002) - the request did not pass certain hard validation rules hence it makes it unsuitable for any product. E.g.: Invalid consigneeAddress country code, customsDetails not provided for an International Product.

• Data Validation Failed (400.0604003) - the request did not pass master data validation. E.g.: distributionCenter value in invalid, pickup is invalid

• Product Finding Failed (400.0604004) - there is no product found in the given combination of Origin, Destination and weight. E.g.: shipping GND product above 400 OZ in weight.

*In this case, there will be no products array in the response.

These are errors that are driven directly by the data provided in the request. There are other error codes that may not be related to the request. Refer to the Errors section for complete reference on all possible errors.

Soft Validations

These are special validations that are returned as messages inside each product. Soft validations are applied when the request is good enough to identify one or more products and return a response, however additional issues exists in the request which need to be fixed before a shipping label can be generated for the product.

Once again, there are multiple scenarios where soft validations are returned in the form of messages -

• Product is DDU only and does not offer prepaid Duties & Taxes (DDP)

• One or more of the dimension attributes is outside the allowed limits

• declaredValue exceeds maximum allowed limit

• A phone number is required to facilitate customs clearance

• A valid email is required for ordered product and destination

• A Postal Code is a required field for this destination

• and several more..

While it's not important to know the complete list of soft validation errors that are possible (as they keep changing from time to time), the integration should take into consideration that these messages must be addressed. Otherwise, trying to generate a label for the orderedProductId with the same request will return a dynamic validation error.

Each iteration of the messages object has the following elements -

• messageId

• messageText

messageId is classified as follows -

• 100 - Soft Dynamic Validation errors

• 200 - Rate related messages

• 300 - EDD related messages

• 400 - General failures and unknown exceptions

messageText will describe the soft validation error.

An example is shown below -

"messages": [
    {
        "messageId": "100",
        "messageText": "Height must be less than or equal to 23.62 in."
    },
    {
        "messageId": "100",
        "messageText": "This Product is DDU only and does not offer prepaid Duties & Taxes (DDP)"
    },
    {
        "messageId": "300",
        "messageText": "No estimated delivery date available"
    }
]

As shown in the example above, messages are also used to return issues with rate and EDD. E.g.: Rate Finding Failed, No estimated delivery date available etc. Use the messageId to differentiate between types of messages.

Why do we have hard and soft validations?

Product Finder service returns the list of possible products (with rates and EDD when required) as long as the minimum viable request is acceptable. If not, it returns an error.

If there are errors in the request that do not affect product finding, these are returned as soft validations so that the client can fix these errors before generating a shipping label.