Using Product's HSCode

HSCode for taxes calculation

POST https://api.transiteo.io/v1/taxsrv/taxCalculationHscode

This endpoint allows you to calculate locales taxes for a product HSCode.

Headers

Name	Type	Description
Content-type	string	application/json
Authorization	string	"your id_token"

200

{
    "products": [
        {
            "vat": [
                {
                    "label": "string",
                    "percentage": number,
                    "product_taxes_amount": number,
                    "shipping_taxes_amount": number,
                    "packaging_taxes_amount": number,
                    "insurance_taxes_amount": number,
                    "message": "string"
                }
            ],
    ],
    "shipping_global": {
        "vat": [
            {
                "label": "string",
                "amount": number,
                "percentage": number
            }
        ]
    },
    "packaging_global": {
        "vat": [
            {
                "label": "string",
                "amount": number,
                "percentage": number
            }
        ]
    },
    "insurance_global": {
        "vat": [
            {
                "label": "string",
                "amount": number,
                "percentage": number
            }
        ]
    },
    "incoterm": "string",
    "extra_fees": {
        "percentage": number,
        "amount": number,
        "currency": "string"
    },
    "global": {
        "amount": number
    },
    "timestamp": number
}

JSON Request Body Format

{
  "products": [
      {
        "identification": {
          "value": string
        },
        "weight": number,
        "weight_unit": string,
        "quantity": number,
        "unit_price": number,
        "currency_unit_price": string,
        "unit_ship_price": number,
        "unit_packaging_price": number,
        "unit_insurance_price": number,
        "origin_country": string,
        "transport": {
          "type": string,
          "id": number
        },
      }
  ],
  "lang": string,
  "from_country": string,
  "to_country": string,
  "from_district": string,
  "to_district": string,
  "shipment_type": string,
  "global_ship_price": number,
  "currency_global_ship_price": string,
  "global_packaging_price": number,
  "currency_global_packaging_price": string,
  "global_insurance_price": number,
  "currency_global_insurance_price": string,
  "included_tax": boolean,
  "incoterm": string,
  "extra_fees": number,
  "sender": {
    "pro": boolean,
    "revenue_country_annual": number,
    "currency_revenue_country_annual": string
  },
  "transport": {
    "type": string,
    "id": number
  },
  "transit_fees" : {
    "percentage": null,
    "amount" : 10, 
    "currency" : "EUR",  
    "on_products_price": false, 
    "on_shipping_products_price": false, 
    "on_global": true
  },
  "receiver": {
    "pro": boolean,
    "activity_id": string
  }
}

Request fields

"products" / "identification" / "value"

You need to fill this field with a HTS Code version 2017. Between 8 to 13 digits numbers. Examples : 9503006100 Type : string Required : yes

"products" / "weight"

You need to fill the "weight" field of the product with a number. Examples : 12 or 3.5 Type : number Required : yes if "unit_ship_price" and "currency_unit_ship_price"are not mentionned. Or if you request Switzerland in "from_country".

"products" / "weight_unit"

You can fill the "weight_unit" field with one of this two labels : - "kg" : if you use the international metric system - "lbs" : if you use the imperial system Type : string Required : yes if "unit_ship_price" and "currency_unit_ship_price"are not mentionned. Or if you request Switzerland in "from_country".

"products" / "quantity"

You need to fill the "quantity" field with a entire number representing your product units. Examples : 1 or 9 Type : number Required : yes

"products" / "unit_price"

You need to fill the "unit_price" field with a number representing the price of one item. Examples : 39 or 99.90 Type : number Required : yes.

"products" / "currency_unit_price"

You need to fill the "currency_unit_price" field of the product with a currency iso Alpha 3. Download the list of currencies with them name and code. Examples : "EUR" or "CAD" Type : string Required : yes

"products" / "unit_ship_price"

You need to fill the "unit_ship_price" field of the product with a number. Examples : 19 or 34.37 Type : number Required : yes

"products" / "unit_packaging_price"

You need to fill the "unit_packaging_price" field of the product with a number. Examples : 19 or 34.37 Type : number Required : yes

"products" / "unit_insurance_price"

You need to fill the "unit_insurance_price" field of the product with a number. Examples : 19 or 34.37 Type : number Required : yes

"products" / "origin_country"

You need to fill the "origin_country" field with the Iso Alpha 2 or 3 code from where the product had build. Download the list of countries. Examples : "FRA" or "VEN" Type : string Required : yes

"products" / "transport" / "type"

You need to fill the "transport" field of the shipping product(s) price. Type : string Required : optional (required if you want to know the duty fees by product)

"products" / "transport" / "id"

You need to fill the "transport" field of the shipping product(s) price with an id number. Download the list of carriers and freight forwarder. Type : string Required : optional (required if you want to know the duty fees by product)

"products" / "unit"

You need to fill the "unit" field with a entire number representing an other feature of product Examples : 1 or 9 Type : number Required : optional

"products" / "unit_type"

You need to fill the "unit_price" field with a number representing the price of one item. Examples : 39 or 99.90 Type : number Required : optional and yes es if "unit" is mentioned.

"lang"

You need to fill this field with a web language code of your product name or description. 3 languages are available : fr = french en = english es = spanish Examples : "fr" Type : string Required : yes

"from_country"

You need to fill the "from_country" field with the country english label or Iso Alpha 2 or 3 from where the product is sent. Download the list of countries. Examples : "Bulgaria" or "ZHN" Type : string Required : yes

"from_district"

You need to fill the "from_district" field with the Iso codes of the district from where the product is sent. Download the list of districts. Examples : "AL-11" or "FR-GES" Type : string Required : yes

"to_country"

You need to fill the "to_country" field with the country english label or Iso Alpha 2 or 3 from where the product arrives. Download the list of countries. Examples : "Brazil" or "GLP" Type : string Required : yes

"to_district"

You need to fill the "to_district" field with the Iso codes of the district from where the product arrives. Download the list of districts. Examples : "AL-11" or "FR-GES" Type : string Required : yes

"shipment_type" GLOBAL : global shipping ARTICLE : One ship price per article Type : enum Required: yes

"global_ship_price"

You need to fill the "global_ship_price" field with a number. Examples : 450 or 3451.87 Type : number Required : yes if shipment_type is GLOBAL

"currency_global_ship_price"

You need to fill the "currency_global_ship_price" field of the product with a currency iso Alpha 3. Download the list of currencies. Examples : "USD" or "AUD" Type : string Required : yes if shipment_type is GLOBAL

"global_packaging_price"

You need to fill the "global_packaging_price" field with a number. Examples : 450 or 3451.87 Type : number Required : yes if shipment_type is GLOBAL

"currency_global_packaging_price"

You need to fill the "currency_global_packaging_price" field of the product with a currency iso Alpha 3. Download the list of currencies. Examples : "USD" or "AUD" Type : string Required : yes if shipment_type is GLOBAL

"global_insurance_price"

You need to fill the "global_insurance_price" field with a number. Examples : 450 or 3451.87 Type : number Required : yes if shipment_type is GLOBAL

"currency_global_insurance_price"

You need to fill the "currency_global_insurance_price" field of the product with a currency iso Alpha 3. Download the list of currencies. Examples : "USD" or "AUD" Type : string Required : yes if shipment_type is GLOBAL

"included_tax"

If you fill with true, we consider that the product(s) price is tax incl. so we will deduct the taxes attached to the departure country from the duties & taxes amount. If you fill with false or no value, we consider that the product(s) price is tax excl. Examples : true or false Type : boolean Required : optional

"incoterm"

2 choices : if it's CIF, we calcul the duties and taxes on product(s) and shipping price(s). If it's FOB, only on product(s). Examples : CIF or FOB Type : string Required : optional

"extra_fees"

You can add extra fees to duties & taxes amount. You need to fill the "extra_fees" field with a number. Examples : 0.02 or 0.1 (0.02 = 2% / 0.1 = 10%) Type : number Required : optional

"sender" / "pro"

You need to fill the "pro" field with true or false dependind if the sender is a business company or not. Type : boolean Required : yes

"sender" / "revenue_country_annual"

You need to fill the "revenue_country_annual" field with a number. Examples : 34560 or 234567.98 Type : number Required : yes if "sender" / "pro" field is "pro" and from_country & to_country are European countries.

"sender" / "currency_revenue_country_annual"

You need to fill the "currency_global_ship_price" field with a currency iso Alpha 3. Download the list of currencies. Examples : "USD" or "AUD" Type : string Required : yes if "sender" / pro" field is "pro" and from_country & to_country are European countries.

"receiver" / "pro"

You need to fill the "pro" field by "true" or "false" dependind if the receiver is a business company or not. Type : boolean Required : yes

"receiver" / "activity_id"

You need to fill the "activity_id" field with an activity code. Download the list of companies activities. Examples : "0112Z" or "7161A" Type : string Required : yes if "receiver" / "pro" field is "pro".

"transport" / "type"

You can fill the "type" field of the transport company with "CARRIER" or "FREIGHT_FORWARDER". Type : string Required : optional (required if you want to know the duty fees)

"transport" / "id"

You can fill the "id" field of the transport company with an entire number. Download the list of carriers and freight forwarders. Examples : "01" or "28" Type : string Required : optional (required if you want to add automaticaly the duty fees)

"transit_fees" / "percentage"

You can fill the "percentage" field of your duty fees. Examples : "0.01" or "0.3" (0.01 = 1% / 0.3 = 30%) Type : number Required : optional

"transit_fees" / "amount"

You can fill the "amount" field of your duty fees. Examples : "10" or "29.99" Type : number Required : optional

"transit_fees" / "currency"

You can fill the "amount" field of your duty fees. Examples : "10" or "29.99" Type : number Required : optional (required you filled "transit_fees" / "amount" )

"transit_fees" / "on_products_price"

You have three choices : on_products_price / on_shipping_products_price / on_global If on_products_price = true, the transit_fees will be calculated only on the price of product(s). Examples : "true" or "false" Type : boolean Required : optional but required if you fill a value in transit_fees, percentage or amount/currency

"transit_fees" / "on_shipping_products_price"

You have three choices : on_products_price / on_shipping_products_price / on_global If on_shipping_products_price = true, the transit_fees will be calculated only on the price of shipping. Examples : "true" or "false" Type : boolean Required : optional but required if you fill a value in transit_fees, percentage or amount/currency

"transit_fees" / "on_global"

You have three choices : on_products_price / on_shipping_products_price / on_global If on_global = true, the transit_fees will be calculated only on the price of product(s) and the shipping. Examples : "true" or "false" Type : boolean Required : optional but required if you fill a value in transit_fees, percentage or amount/currency

JSON Response Format

{
    "products": [
        {
            "vat": [
                {
                    "label": "string",
                    "percentage": number,
                    "product_taxes_amount": number,
                    "shipping_taxes_amount": number,
                    "packaging_taxes_amount": number,
                    "insurance_taxes_amount": number,
                    "message": "string"
                }
            ],
    ],
    "shipping_global": {
        "vat": [
            {
                "label": "string",
                "amount": number,
                "percentage": number
            }
        ]
    },
    "packaging_global": {
        "vat": [
            {
                "label": "string",
                "amount": number,
                "percentage": number
            }
        ]
    },
    "insurance_global": {
        "vat": [
            {
                "label": "string",
                "amount": number,
                "percentage": number
            }
        ]
    },
    "incoterm": "string",
    "extra_fees": {
        "percentage": number,
        "amount": number,
        "currency": "string"
    },
    "global": {
        "amount": number
    },
    "timestamp": number
}

Response fields & values

"products" / "vat" / "label"

The value is the label of VAT tax. It depends on the "to_country" field in the request. Examples : vat or gst File type : string

"products" / "vat" / "percentage"

The value is the percentage (%) of VAT tax. Examples : 3 or 1.5 File type : number

"products" / "vat" / "product_taxes_amount"

The value is the amount of : ("unit_ship_price" x "products" / "vat" / "percentage"). The currency of this amount depends on "currency_unit_ship_price". Examples : 3.45 or 2 File type : number

"products" / "vat" / "shipping_taxes_amount"

The value is the amount of : ("unit_price" x "products" / "vat" / "percentage"). The currency of this amount depends on "currency_unit_ship_price". Examples : 2.88 or 9 File type : number

"products" / "vat" / "packaging_taxes_amount"

The value is the amount of : ("unit_price" x "products" / "vat" / "percentage"). The currency of this amount depends on "currency_unit_ship_price". Examples : 2.88 or 9 File type : number

"products" / "vat" / "insurance_taxes_amount"

The value is the amount of : ("unit_price" x "products" / "vat" / "percentage"). The currency of this amount depends on "currency_unit_ship_price". Examples : 2.88 or 9 File type : number

"message"

The value is the locale rule. Examples : European Country File type : string

"shipping_global" / "vat" / "label"

The value is the label of VAT tax. It depends on the "to_country" field in the request. Examples : vat or gst File type : string

"shipping_global" / "vat" / "amount"

The value is the amount of : ("global_ship_price" x "shipping_global" / "vat" / "percentage"). The currency of this amount depend of "currency_global_ship_price". Examples : 345 or 29.99 File type : number

"shipping_global" / "vat" / "percentage"

The value is the percentage (%) of VAT tax. Examples : 3 or 1.5 File type : number

"packaging_global" / "vat" / "label"

The value is the label of VAT tax. It depends on the "to_country" field in the request. Examples : vat or gst File type : string

"packaging_global" / "vat" / "amount"

The value is the amount of : ("global_ship_price" x "packaging_global" / "vat" / "percentage"). The currency of this amount depend of "currency_global_ship_price". Examples : 345 or 29.99 File type : number

"packaging_global" / "vat" / "percentage"

The value is the percentage (%) of VAT tax. Examples : 3 or 1.5 File type : number

"insurance_global" / "vat" / "label"

The value is the label of VAT tax. It depends on the "to_country" field in the request. Examples : vat or gst File type : string

"insurance_global" / "vat" / "amount"

The value is the amount of : ("global_ship_price" x "insurance_global" / "vat" / "percentage"). The currency of this amount depend of "currency_global_ship_price". Examples : 345 or 29.99 File type : number

"insurance_global" / "vat" / "percentage"

The value is the percentage (%) of VAT tax. Examples : 3 or 1.5 File type : number

"Incoterm"

The value is CIF or FOB dependind of your request. Type : string Required : yes

"extra_fees" / "percentage"

The value is the percentage (%) of VAT tax. Examples : 3 or 1.5 File type : number

"extra_fees" / "amount"

The value is the amount of : ("global_ship_price" x "extra_fees" / "vat" / "percentage"). The currency of this amount depend of "currency_global_ship_price". Examples : 345 or 29.99 File type : number

"extra_fees" / "currency"

The value is the currency. Examples : EUR File type : string

"global" / "amount"

The value is the sum of all amount fields. Examples : 1675 or 80.98 File type : number

Warning : 1 product = 1 request / 3 products = 3 requests

JSON Examples - Request & Response

It exist many possibilities. Please book a call with our support team.

Video explainer

in progress...