Cross-Border Customs Duty Calculations with REST v2

Cross-Border Customs Duty Calculations with REST v2

Updated March 22, 2018 - AvaTax REST has a new syntax for making customs duty calculations. This post is retained for historical purposes. You may read about the new AvaTax Cross-Border calculator at

Selling Cross-Border

With the release of the customs duty calculation functionality, AvaTax now provides features to help you sell across country borders. AvaTax Cross-Border will help you identify customs duty for various types of harmonized tariff codes.

Once you’ve begun using AvaTax REST v2, you’ll have to make a few minor changes to begin calculating customs duties for cross-border sales. Here’s what you need to know.

Harmonized Systems Codes

For every product in your taxable transaction, you need to identify the Harmonized System code for that item. These tariff codes are published by the customs authorities in each destination country and you’ll need to assign the appropriate code to your items. Update 2018-03-22: AvaTax REST has a new APIs for HS Code lookup. You may read about the new HS Code endpoints at .

To identify this code for your item, you will add a “Parameter” for each line in your transaction. That parameter is called the AvaTax.LandedCost.HTSCode. For today’s example, we’ll use the code 6403519030, which refers to “Other Footwear With Outer Soles Of Leather”. The exact details of these HS codes are quite complex; but if you have a question you should certainly contact a customs office to verify that your code is correct!

Interesting item of note: most countries have a “de minimis” threshold - this is each country’s threshold under which customs duty and tax does not apply. This example shipment will ship from Canada to the United States. In the United States, the value of a shipment must be greater than $800 USD for it to be subject to customs duty. For this example, this shipment will have a value of $1000.00 USD, which surpasses the de minimis threshold amount and triggers a customs duty to apply.

Who Pays?

The next thing we need to know about your transaction is who is responsible for paying the your customs duty. The AvaTax Cross-Border calculator supports two options:

  • DAP = Stands for Delivered at Place. Means the Seller bears the risk & responsibility of coordinating the import clearance and transportation from their ship-from facility & country to the Buyer's door. The Buyer is responsible for declaring the shipment to the customs authorities in the destination country and remitting any/all customs duty & import tax (including VAT).
  • DDP = Stands for Delivered Duty Paid. Means the Seller (or their 3rd party) bears the risk & responsibility of coordinating the import clearance, transportation and declaring the shipment to the customs authority in the destination country and remitting any/all customs duties and import taxes (including VAT).

For this example, we’ll say that the customer, the Buyer, is responsible. That means we’ll use the code “DAP”. This parameter is attached to the main body of the transaction, and it’s called AvaTax.LandedCost.Incoterms. (Please note that this incoterm parameter applies to a version of duty calculation no longer in use. You may read more about the current version at

Shipping and Insurance

Calculating the landed cost for cross-border transactions requires knowing how much is paid for shipping and insurance. To provide these data elements, we’ll add a line item into our transaction for TaxCode FR010000, which is the tax code for freight charges, and a line item for TaxCode FR070100, which is insurance. If you forget what tax codes you want to use, you can always call the API at /api/v2/definitions/taxcodes - this will give a full list of all Avalara defined tax codes you can use for your transactions.

What does our transaction look like now?

Let’s plan to ship these shoes from Prince Edward Island in Canada to Bainbridge Island in WA. Here’s what our request will look like:


  "isSellerImporterOfRecord": true,
  "type": "SalesOrder",
  "companyCode": "DEFAULT",
  "date": "2020-04-03",
  "customerCode": "ABC",
  "addresses": {
    "ShipFrom": {
      "region": "PE",
      "country": "CA",
      "postalCode": "C1A 4P3"
    "ShipTo": {
      "city": "Bainbridge Island",
      "region": "WA",
      "country": "US",
      "postalCode": "98110"
  "lines": [
      "number": "1",
      "quantity": 1,
      "amount": 1000,
      "description": "Footwear",
      "taxCode": "P0000000",
      "hsCode": "6403519030"
      "number": "2",
      "quantity": 1,
      "amount": 50,
      "description": "Shipping",
      "taxCode": "FR010000"
      "number": "3",
      "quantity": 1,
      "amount": 50,
      "description": "Insurance",
      "taxCode": "FR070100"
  "taxDate": "2020-04-03",
  "currencyCode": "USD"


The result object is huge. It has information about all the line items, all the jurisdictions, and all the tax codes applied. For the moment, let’s focus on the real results:

      "country": "US",
      "region": "US",
      "jurisType": "Country",
      "jurisCode": "US",
      "jurisName": "UNITED STATES",
      "taxAuthorityType": 45,
      "stateAssignedNo": "",
      "taxType": "LandedCost",
      "taxSubType": "ImportDuty",
      "taxName": "US LandedCost",
      "rateType": "General",
      "taxable": 1000,
      "rate": 0.1,
      "tax": 100,
      "taxCalculated": 100,
      "nonTaxable": 0,
      "exemption": 0

As you can see, the customs duty calculations made on this amount estimated that $100.00 USD would be the customs duty for importing this product in this manner. That’s how it works! There are lots of other options available; we’ll share more features and functionality here on the Avalara developer site each week.

How do I find what other parameters are available?

In the REST v2 API, you can find a list of all other parameters via the /api/v2/definitions/parameters endpoint. When you call this API, it will list all the parameters that are available, and provide a quick description of each one. For further reading on parameters, check out the developer website.

May all of your shipments be speedy!

Recent posts

The 2021 sales tax changes report: midyear update

Your guide to navigating the complicated world of tax compliance and preparing for the future 

The 2021 sales tax changes report: midyear update

Hear tax and industry experts break down the latest legislative updates and industry trends in our upcoming virtual event.

Stay up to date

Sign up for our free newsletter and stay up to date with the latest tax news.