Tax Calculation

About

The Reach cartridge provides a duty and tax calculation component utilizing DHL’s Fully Landed Cost Calculator which calculates the total cost of a cross-border shipment.

👍

Be sure to configure DHL's service profiles in order to use the DHL FLC calculator.

Configuration

Site Preferences

• Enable DHL tax calculation, if disabled the default SFRA tax calculation will be used.
• Enable Sandbox Mode switches between .production or .sandbox credentials.
• Customer Account number, should provided for with DHL account.
• Merchant Name (itemSeller) associated with the pickup account number.
• Sender Address Country is the country from which item will be shipped.
• Sender Address State where the item is shipped from, only used for USA, Canada and Brasil.
• Pricing Strategy that will be use for the FLC calculation.
  • EXACT, selected by default, requires an exact match to an HS Code to generate exact duty rates. If an exact HS Code is not found an INVALID HS CODE: HS CODE error is returned.
    • For non-EXACT pricing strategies DHL attempts to match all, 6, 4, or 2 digits of the HS code.
  • MAXIMUM the maximum duty rate is returned.
  • MINIMUM the minimum duty rate is returned.
  • AVERAGE the average duty rate is returned.
• Fallback Pricing Strategy is used if the primary pricing strategy is EXACT and the calculation fails.
• Logger is the file location where the logs will be written. You can select from the root, common, dedicated log file or a combination of them.

Shipping Methods

• Delivered Duty determines if duties and taxes will be calculated and applied.
  • NONE, the default SFRA tax calculation will be used instead of DHL FLC calculation.
  • PAID (DDP), DHL FLC is used to calculate taxes that should be paid when the order is placed.
  • UNPAID (DDU), duties and taxes are not calculated, set to 0 and expected to be paid on delivery.
• Transport Mode is the method of transport used which may impact the duties and taxes calculation.
• Clearance Mode is the mode of customs clearance which may impact the duties, taxes and fees calculation

Optionally, use the existing Estimated Arrival Time attribute to indicate DDU/DDP in the basket or checkout flow.

Product attributes

The product model is extended to support Harmonized System (HS) Codes and the product's Country of Origin to calculate the fully landed cost.

📘

HS Codes are required for all products and if it is missing an error will be returned.

• HS CODE is the required Harmonized System Code for the item which may be 2, 4, 6 or all classification digits.
  • Acceptable characters:
    • 0-9, including leading zeroes
    • A through Z
    • hyphens and periods, will be stripped
    • spaces and blanks
  • if the HS Code is missing, the DHL FLC calculator will throw an error
• Country of Origin is the product's two character ISO 3166-1 alpha 2 Country Code of origin.

Implementation

The cartridge's tax calculator hooks into the calculate.calculateTax method and replaces the default tax calculation module scripts/ hooks/taxes.js.

After ensuring that the DHL FLC component is enabled, DDP is selected and the order is not shipping domestically, the cartridge:

• Transforms basket data to data transfer objects expected by the DHL FLC API.
• Makes an API call to the DHL FLC API to request a fully landed cost quote.
• Builds a taxes object expected by calculate.calculateTax from the FLC quote.
• Returns the taxes data and the control flow back to the calculate.calculateTax caller.

Customization

SFRA standards should be followed when customizing the Reach component. The cartridge is built in a modular and object oriented way to facilitate overriding code.

Business logic and product models vary between merchants which may require the DHL FLC request to be modified. The DhlQuote class abstracts the DHL FLC request: scripts/reach/DhlQuote.

DHL FLC objects are represented by data transfer object classes with each attribute value built using corresponding getter functions. The objects are located in: bc_reach/cartridge/scripts/reach/dto/dhl/*.

Example

The product dimension attributes in SFRA are Strings while the DHL API expects data in this format: {value: Number, unit: String}.

A product that weighs 10.50 kg may have Product.custom.weight attribute set to:

1. "10.5 kg",
2. "10.5", assuming kg units
3. a separate attribute Product.custom.weightUnit to hold the unit type.

Here is how the weight attribute can be customized with a separate Product.custom.weightUnit attribute to hold the unit type. Assuming your retailer storefront cartridge is app_mycoolstore create the following file:

/**
* Extend Product Line Item (pli) DHL DTO with MyCoolStore logic
* file: app_mycoolstore/cartridge/scripts/reach/dto/dhl/request/pli.js
* overrides: bc_reach/cartridge/scripts/reach/dto/dhl/request/pli.js
*/

function PliDto () {}
PliDto.prototype = Object.create(module.superModule);

PliDto.prototype.getWeight = function () {
  return {
    value: this._product.custom.weight,
    unit: this._product.custom.weightUnit
  }
};

module.exports = PliDto;

The DHL FLC API documentation requires an account to be accessed and may be helpful if extensive customization is required.

Privacy Data

No privacy data is collected or saved by this module. The customer's shipping Country and State are sent to DHL to calculate the order's fully landed cost.