Avalara Developer Network Developer landedcost

LandedCost Calculation API

Landed Cost API providing duty rates, calculation, and item harmonization. A set of sample requests are available as a Postman Collection.

Basics

Timestamps

Timestamps should be formatted using ISO-8601 to the nearest second, in UTC e.g 2015-06-12T09:17:37Z

Expiries

All Requests will have an associated timestamp. The validity for any request is 1 minute to account for any clock-skew.

Authorization

All API requests require an http header that contains your account ID and your account API Key. During account provisioning, you will be issued an API Key which you must supply with every request.

Authorization Header

To make an authorized API request, set the following HTTP header: authorization: avalaraapikey id:<accountId> key:<apiKey>


Validate Credentials

Convenience API to check credentials. This API is purposefully non-performant.

Api Endpoint
GET http://sandbox.landedcost.api.avalara.com/v3/validate-creds

Headers

Try Validate Credentials now!

Input

Reset
API Endpoint
http://sandbox.landedcost.api.avalara.com/v3/validate-creds
Method
GET
Response
 

Calculate Landed Cost

Returns the fully qualified landed cost calculation for a shipment

Api Endpoint
POST http://sandbox.landedcost.api.avalara.com/v3/calculate

Headers
Content-Type: application/json

Post Body Parameters

charges

Charges to include

Array[string]
date
Required

Transaction date in ISO 8601 format

string
incoterms
Required

Terms of sale. Used to determine buyer obligations

string
Source
country
Required

Source country of the shipment, in ISO 3166-1 alpha-2 format

string
region

Source region of the shipment, in ISO 3166-2 format

string
Destination
country
Required
string
region

Destination region of the shipment, in ISO 3166-2 format

string
entityType
Required

Type of sale. Can be used to determine applicable tax types

string
currency
Required

Currency, in ISO 4217 format

string
Shipping
cost
Required

Cost of shipping

number
insurance
Required

Cost of shipping insurance

number
mode

Shipping method. Can be used to determine applicable tax types

string
express
Required

Is Shipping method. Can be used to determine applicable tax types

boolean
Discount
type

The type of discount to apply. Currently, the system only supports sales discounts offered directly to consumers

string
rate

A percentage to discount the shipment or item

number
amount

A flate amount to discount the shipment or item

number
Array[Items]
id
Required

Transaction line number

string
hsCode
Required

The harmonized classification code of the product

string
description
Required

Description of the product

string
price

Item price of the product

number
quantity

Quantity of the item shipped

number
extendedPrice

Extended price (price * quantity) of the item shipped

number
Array[Units]
name
Required

Name of the unit of measure

string
amount

Value associated with this unit of measure

number
total

Total value associated with this unit of measure (amount * quantity)

number
Discount
type

The type of discount to apply. Currently, the system only supports sales discounts offered directly to consumers

string
rate

A percentage to discount the shipment or item

number
amount

A flate amount to discount the shipment or item

number
preferenceProgram

Included when a shipment item qualifies for a special rate, such as NAFTA

string

Response

charges

Charges to include

Array[string]
date
Required

Transaction date in ISO 8601 format

string
incoterms
Required

Terms of sale. Used to determine buyer obligations

string
Source
country
Required

Source country of the shipment, in ISO 3166-1 alpha-2 format

string
region

Source region of the shipment, in ISO 3166-2 format

string
Destination
country
Required
string
region

Destination region of the shipment, in ISO 3166-2 format

string
entityType
Required

Type of sale. Can be used to determine applicable tax types

string
currency
Required

Currency, in ISO 4217 format

string
Shipping
cost
Required

Cost of shipping

number
insurance
Required

Cost of shipping insurance

number
mode

Shipping method. Can be used to determine applicable tax types

string
express
Required

Is Shipping method. Can be used to determine applicable tax types

boolean
Discount
type

The type of discount to apply. Currently, the system only supports sales discounts offered directly to consumers

string
rate

A percentage to discount the shipment or item

number
amount

A flate amount to discount the shipment or item

number
Array[Items]
id
Required

Transaction line number

string
hsCode
Required

The harmonized classification code of the product

string
description
Required

Description of the product

string
price

Item price of the product

number
netPrice

Original price of the product, returned if a discount was applied on the item

number
quantity

Quantity of the item shipped

number
extendedPrice

Extended price (price * quantity) of the item shipped

number
Array[Units]
name
Required

Name of the unit of measure

string
amount

Value associated with this unit of measure

number
total

Total value associated with this unit of measure (amount * quantity)

number
Rates
Array[Duties]
hsCode
Required

The harmonized classification code of the product

string
rate
Required

The rate as written in the source material

string
currency
Required

Currency, in ISO 4217 format

string
type
Required

The type of duty

string
Jurisdiction
country
Required
string
region

Destination region of the shipment, in ISO 3166-2 format

string
Array[Taxes]
rate
Required

The rate as written in the source material

string
currency
Required

Currency, in ISO 4217 format

string
type
Required

The type of tax

string
Jurisdiction
country
Required
string
region

Destination region of the shipment, in ISO 3166-2 format

string
TaxesAndFees
Duties
amount
Required

Duties subtotal

number
Array[Details]
name
Required

Duty name

string
amount
Required

Duty amount

number
taxBasis
Required

Tax basis the rate is applied to

number
Taxes
amount
Required

Taxes subtotal

number
Array[Details]
name
Required

Tax name

string
amount
Required

Tax amount

number
taxBasis
Required

Tax basis the rate is applied to

number
Fees
amount
Required

Fees subtotal

number
Array[Details]
name
Required

Fee name

string
amount
Required

Fee amount

number
Discount
type

The type of discount to apply. Currently, the system only supports sales discounts offered directly to consumers

string
rate

A percentage to discount the shipment or item

number
amount

A flate amount to discount the shipment or item

number
taxExemptions

The rate section

Array[string]
preferenceProgram

Included when a shipment item qualifies for a special rate, such as NAFTA

string
TaxesAndFees
Duties
amount
Required

Duties subtotal

number
Array[Details]
name
Required

Duty name

string
amount
Required

Duty amount

number
Taxes
amount
Required

Taxes subtotal

number
Array[Details]
name
Required

Tax name

string
amount
Required

Tax amount

number
Fees
amount
Required

Fees subtotal

number
Array[Details]
name
Required

Fee name

string
amount
Required

Fee amount

number
LandedCost
amount
Required

Calculated landedCost. Total of all products, shipping, and applicable duties, taxes, and fees

number
costInsuranceFreight

Total of all products and shipping

number
dutiesTaxesAndFees

Total of all applicable duties, taxes, and fees

number
isCrossBorder
Required

Is shipment cross-border

boolean
Details
Items
amount
Required

Item subtotal

number
Shipping
amount
Required

Shipping subtotal

number
Discounts
amount
Required

The total discount from the order, which can include an order-level discount as well as discounts on each individual item

number
Array[Details]
name

The type of discount

string
amount

The cash value of the item or order level discount

number
Duties
amount
Required

Duties subtotal

number
Array[Details]
name
Required

Duty name

string
amount
Required

Duty amount

number
Taxes
amount
Required

Taxes subtotal

number
Array[Details]
name
Required

Tax name

string
amount
Required

Tax amount

number
Fees
amount
Required

Fees subtotal

number
Array[Details]
name
Required

Fee name

string
amount
Required

Fee amount

number
Obligations
Array[Buyer]
currency
Required

Currency, in ISO 4217 format

string
amount
Required

Buyer's obligation amount

number
messages

Special messages that apply

Array[string]
Status
result
Required

The response status

string
messages
Array[string]
Try Calculate Landed Cost now!

Input

Fill with Sample Data
Reset
Show all request attributes

Post Body

source

destination

shipping

items

item 1

units

item 1

Add units
Add items
Reset
API Endpoint
http://sandbox.landedcost.api.avalara.com/v3/calculate
Method
POST
Request
{
  "source": {},
  "destination": {},
  "shipping": {},
  "items": [
    {
      "units": [
        {}
      ]
    }
  ]
}
Response
 

Get Rates

Returns rate information given an HS code, source country and destination country

Api Endpoint
POST http://sandbox.landedcost.api.avalara.com/v3/rates

Headers
Content-Type: application/json

Post Body Parameters[Array]

hsCode
Required

The harmonized classification code of the product

string
Source
country
Required

Source country of the shipment, in ISO 3166-1 alpha-2 format

string
region

Source region of the shipment, in ISO 3166-2 format

string
Destination
country
Required
string
region

Destination region of the shipment, in ISO 3166-2 format

string

Response[Array]

hsCode
Required

The harmonized classification code of the product

string
Source
country
Required

Source country of the shipment, in ISO 3166-1 alpha-2 format

string
region

Source region of the shipment, in ISO 3166-2 format

string
Destination
country
Required
string
region

Destination region of the shipment, in ISO 3166-2 format

string
Rates
Array[Duties]
hsCode
Required

The harmonized classification code of the product

string
rate
Required

The rate as written in the source material

string
currency
Required

Currency, in ISO 4217 format

string
type
Required

The type of duty

string
Jurisdiction
country
Required
string
region

Destination region of the shipment, in ISO 3166-2 format

string
Array[Taxes]
rate
Required

The rate as written in the source material

string
currency
Required

Currency, in ISO 4217 format

string
type
Required

The type of tax

string
Jurisdiction
country
Required
string
region

Destination region of the shipment, in ISO 3166-2 format

string
Status
result
Required

The response status

string
messages
Array[string]
Try Get Rates now!

Input

Fill with Sample Data
Reset

Post Body

item 1

source

destination

Add Item
Reset
API Endpoint
http://sandbox.landedcost.api.avalara.com/v3/rates
Method
POST
Request
[
  {
    "source": {},
    "destination": {}
  }
]
Response
 

Get Rate Units

Returns units used in all rate formulas for given HS codes. Can optionally be filtered by providing source and destination country codes

Api Endpoint
POST http://sandbox.landedcost.api.avalara.com/v3/units

Headers
Content-Type: application/json

Post Body Parameters[Array]

hsCode
Required

The harmonized classification code of the product

string
Source
country
Required

Source country of the shipment, in ISO 3166-1 alpha-2 format

string
region

Source region of the shipment, in ISO 3166-2 format

string
Destination
country
Required
string
region

Destination region of the shipment, in ISO 3166-2 format

string

Response[Array]

hsCode
Required

The harmonized classification code of the product

string
Source
country
Required

Source country of the shipment, in ISO 3166-1 alpha-2 format

string
region

Source region of the shipment, in ISO 3166-2 format

string
Destination
country
Required
string
region

Destination region of the shipment, in ISO 3166-2 format

string
units
Array[string]
Status
result
Required

The response status

string
messages
Array[string]
Try Get Rate Units now!

Input

Fill with Sample Data
Reset

Post Body

item 1

source

destination

Add Item
Reset
API Endpoint
http://sandbox.landedcost.api.avalara.com/v3/units
Method
POST
Request
[
  {
    "source": {},
    "destination": {}
  }
]
Response
 

Get Countries

Returns the countries we currently support, along with most common classification system for both import and export. No request parameters are required for this call. The method returns a full list of supported countries

Api Endpoint
GET http://sandbox.landedcost.api.avalara.com/v2/countries

Headers

Response

Array[Destination]
code
string
name
string
system
string
Array[Source]
code
string
name
string
system
string
Try Get Countries now!

Input

Reset
API Endpoint
http://sandbox.landedcost.api.avalara.com/v2/countries
Method
GET
Response
 

Get Systems

Returns a pair of classification (import and export) systems for trade between two countries

Api Endpoint
GET http://sandbox.landedcost.api.avalara.com/v2/systems

Headers

Querystring Parameters

source
Required

The two character ISO code for the source country

string
destination
Required

The two character ISO code for the destination country

string

Response

Export
system

The classification system. Must be one of:

  • TARIC
  • SCHEDULEB
  • HTS
string
Import
system

The classification system. Must be one of:

  • TARIC
  • SCHEDULEB
  • HTS
string
Try Get Systems now!

Input

Fill with Sample Data
Reset

Query String

API Endpoint
http://sandbox.landedcost.api.avalara.com/v2/systems
Method
GET
Request
curl -X GET "http://sandbox.landedcost.api.avalara.com/v2/systems" -H "Accept: application/json"
Response
 

Get HS Code Trees

Presents all of the available Harmonized Codes as a browesable tree. Each request specifies a parent node, and the response lists all child nodes of that parent. If no parent node is specified, all root-level nodes will be returned

Api Endpoint
GET http://sandbox.landedcost.api.avalara.com/v2/browse

Headers

Querystring Parameters

system

The classification system you want to browse.

string
parent

The name of the parent node. Note that it is important to use the name of the node, as not all nodes have a harmonized code, and the code itself is different than the name

string

Response[Array]

hsCode
Required

The harmonized code

string
description
Required

The human-readable description of the classification

string
name
Required

The name of the node; this can be used to find the child nodes

string
Try Get HS Code Trees now!

Input

Fill with Sample Data
Reset

Query String

API Endpoint
http://sandbox.landedcost.api.avalara.com/v2/browse
Method
GET
Request
curl -X GET "http://sandbox.landedcost.api.avalara.com/v2/browse" -H "Accept: application/json"
Response
 

Get HS Code Details Including Rates

Search for Duty Rates for a harmonized code. Rates are dependant on at least a destination country

Api Endpoint
GET http://sandbox.landedcost.api.avalara.com/v2/hscodes

Headers

Querystring Parameters

code
Required

The harmonized code

string
system
Required

The classification system to which the code belongs

string
destination
Required

The destination country for which rate data is desired

string
source

An optional filter for rates that limits results to a specific origin country

string

Response[Array]

hsCode
Required
string
system
Required
string
Array[CodePath]
hsCode

The harmonized code

string
description

Harmonized code description

string
name

A concatenation of the system and harmonized code: <system>_<harmonizedCode>

string
Array[Rates]
sourceCountry

The two-character ISO code identifying the origin country associated with the duty

string
formula

The formula used to calculate the rate, presented in Avalara-specific format

string
type

There are three types of landed cost rates that may be returned.

  • ad valorem: this rate applies to the declared customs-value This is typically represented as a percentage of the cost.
  • units: this is a rate that is tied to unit of meaure. This is typically expressed as a monetary value per quantity, such as: $1/kg
  • unknown: there is no stored rate data (or no applicable taxes) for the specified combination. Note that these will always have `"formula": "notax()"
string
unit

If the rate is assessed at a unit level, the appropriate unit involved. If type is not units, this value will be an empty string

string
raw

The human-readable version of the rate

string
currency

The three-character ISO code for the currency in which the duty should be assessed

string
customsValue

The customs value describes how to apply the duty rate. There are two current types

  • fob
  • cif
string
Try Get HS Code Details Including Rates now!

Input

Fill with Sample Data
Reset

Query String

API Endpoint
http://sandbox.landedcost.api.avalara.com/v2/hscodes
Method
GET
Request
curl -X GET "http://sandbox.landedcost.api.avalara.com/v2/hscodes" -H "Accept: application/json"
Response
 

Get HS Code Details

Allows for the traversal of classification system, harmonized codes, and duty rates, allowing the user to browse the available content

Api Endpoint
GET http://sandbox.landedcost.api.avalara.com/v2/hscodes/{system}/{code}

Headers

Querystring Parameters

fullpath

If present, the response will include the entire chapter, subchapter, etc. and description data for a code

boolean

Path Parameters

system
Required

The classification system. If omitted, the response will be all current classification systems

string
code
Required

The harmonized code within a system. If code is provided, system must also be provided

string

Response[Array]

hsCode
Required

The harmonized code

string
name
Required

A concatenation of the system and harmonized code: <system>_<harmonizedCode>

string
description
Required

A description of the harmonized code classification

string
Try Get HS Code Details now!

Input

Fill with Sample Data
Reset

Path Parameters

Query String

API Endpoint
http://sandbox.landedcost.api.avalara.com/v2/hscodes/{system}/{code}
Method
GET
Request
curl -X GET "http://sandbox.landedcost.api.avalara.com/v2/hscodes/{system}/{code}" -H "Accept: application/json"
Response