DHL’s Duty and Tax Calculator (DTC) API calculates the duties, taxes and governmental fees for any cross border shipment, taking into consideration country de minimis values and preferential tariff rates that may apply.

We currently have private plugins that support Duty and Tax Calculation for the following three platforms: Shopify, Magento II, and SalesForce Commerce Cloud. For additional information regarding the plugins, please contact us here .

Scope

This API offers Duty and Tax Calculation, including foreign exchange conversion where necessary, for shipments from any country and to any country in the supported countries list.

The following operations are allowed in the DTC API:

Workflow

Calculate The Duties, Taxes and other Fees for an international Shipment

For eCommerce stores selling to customers in international destinations,

• Call the Duty and Tax Calculator when the customer is checking out their shopping cart
• Get the quote for the shipment based on the contents + value + other landed costs
• Display duties, taxes and any other fees to the customer to be included in payment

The API will return calculated duties and taxes, taking into account the price of the goods contained in the shipment, freight and insurance costs, and currency conversion.

Clients can define a pricingStrategy that will be utilized when calculating duties and taxes. The following strategies are supported:

• MINIMUM - The system will return the minimum duty rate found in the tariffs based on the number of HS digits the caller provides in the request.
• MAXIMUM - The system will return the maximum duty rate found in the tariffs based on the number of HS digits the callers provides in the request.
• AVERAGE - The system will return the average duty rate found in the tariffs based on the number of HS digits the caller provides in the request.
• EXACT - The system will return the exact rate found in the tariffs based on the full HS Code. This is the default strategy that will be applied if no pricing strategy is defined by the caller.

For Minimum, Maximum, and Average strategies, the input HS digit length can be any length over two digits.

VAT included strategy

Some merchants prefer to include VAT/Tax in the cost of the goods displayed on their site so that shoppers don’t have the VAT/Tax charge added at checkout, but still want to use the Duty/Tax Calculator API to calculate duties and other fees, and take into account all deminimis rules. The tax object is used for this purpose. This allows merchants to send in item prices with the VAT included in the cost; the VAT is then backed out of the price; only duties, taxes and fees are returned; and there is no ‘double taxation’.

This optional tax object is available at the Shipment or Item level.

Shipment level only:

If a merchant has added the same tax percent to all item prices, then the shipment level object is the best approach. The tax object is provided at the shipment level, with ‘included’ set to true, and the percent of tax in the ‘percent’ field. For example, if 20% is added to the cost of all items, the object would be:

{
  "included": true,
  "percent": 20,
  "return": true
}

The ‘return’ field indicates whether the merchant wants the actual tax calculation returned from the API as well. In most cases, this would be set to ‘false’ as the tax is already included, but could be useful as a tool to check the actual tax.

Item Level:

If the object is sent at the item level, it applies to that item only. It is not necessary to have the object on every item; the DTC API will only apply tax to that item. The format is the same as at the shipment level.

Note:

• If the Tax object is included at the shipment level, any tax objects(s) at the item level will be ignored.
• If “return” is true, then the tax value calculated by the API is returned.

Minimum attributes required

The more information you provide about your shipment, the more accurate the quote returned will be. For example, the consigneeAddress/state field is required when shipping into Canada and Brazil in order to produce accurate results. Freight charges and insurance charges are required because duties are often calculated on Cost, Insurance and Freight (CIF).

The minimum information that's necessary for a return quote is shown below:

{
  "pickupAccount": "0005331234",
  "itemSeller": "Mysite.com",
  "senderAddress": {
    "country": "US"
  },
  "consigneeAddress": {
    "country": "SG"
  },
  "packageDetails": {
    "outputCurrency": "USD"
  },
  "customsDetails": [
    {
      "itemId": "29616088973377",
      "itemQuantity": {
        "value": 2,
        "unit": "EA"
      },
      "itemValue": {
        "value": 200,
        "currency": "USD"
      }
    }
  ]
}

• pickupAccount and itemSeller are mandatory to identify the client.
• senderAddress/country and consigneeAddress/country are mandatory as duty calculation is mainly driven by where it's shipped from and where it's shipped to.
• outputCurrency determines what currency you would like the duties to be returned in. For example, you can choose the currency of your shopping cart so you can get duties in the customer's purchase currency.
• itemId is required to identify the item.
• itemQuantity and itemValue are mandatory as in most cases duties are calculated on an ad valorem basis.

Duty Calculator Response

In the Duty Calculator response, the quote will be returned in the following objects:

• feeTotals
• packageFees
• itemFees

Each of these will have the following elements:

• name - name of the fee
• currency - currency of the fee
• value - value of the fee

The sum of the itemFees for all items + packageFees should equal the feeTotals.

In addition, the itemFees will contain an optional ruleInfo element that will contain details about how the item fee was calculated.

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

• Static Validation Failed (400.0904001)- the request did not pass the JSON schema validation. E.g: Mandatory element not found, invalid JSON element in request, JSON element had a value which is not a valid enum etc. Example -

{
  "type": "https://api.dhlecs.com/docs/errors/400.0904001",
  "title": "Static Validation Failed",
  "quoteId": "fbcbc29b-ec34-4ff9-8552-94790d6af327",
  "invalidParams": [
    {
      "name": "pickupAccount",
      "path": "/",
      "reason": "required key [pickupAccount] not found"
    }
  ]
}

• Data Validation Failed (400.0904003)- the request did not pass master data validation. E.g.currency value is invalid,

  pickupAccount is invalid, itemSeller is invalid, pricingStrategy value is not from enum etc. Example -

{
  "type": "https://api.dhlecs.com/docs/errors/400.0904003",
  "title": "Data Validation Failed",
  "quoteId": "33b6f512-3699-4dd5-8bb0-46049d202e91",
  "invalidParams": [
    {
      "name": "country",
      "path": "/senderAddress",
      "reason": "Country UX not found in master data"
    }
  ]
}

• Processing Error(400.0904002) - when the calculator runs into an error when processing the request for a quote. Example:

{
  "type": "https://api.dhlecs.com/docs/errors/400.0904002",
  "title": "Processing Error",
  "quoteId": "603b8f4c-4566-4642-ae4b-e6bffe7ef6d4",
  "invalidParams": [
    {
      "reason": "DTC Calculation failed => Default Duty Rate was not found for HS : 120010"
    }
  ]
}

Static and Data validation errors are driven directly by the data provided in the request. Processing errors may be related to master data and trade sheets available for the engine. 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.