DutyCalculator Api Center

Documentation API version 2.0

Version 2.0.2

August 17th 2012

This version of our API will be supported until October 18th 2012. Please migrate to API version 2.1 before that date.

Follow us on twitter for service updates: @DutyCalculator

Contact us at APIsupport @ dutycalculator.com if you have any questions.  


Base URI

The base URI of all resources is http://www.dutycalculator.com/api2.0/{API-key}/ where {API-key} is the API key which you can pick up from your accountdetails.

 

For testing purposes, requests can be passed to the sandbox. The base URI of all sandbox requests is

http://www.dutycalculator.com/api2.0/sandbox/{API-key}/.  

 

List of supported 'Importing from' and ‘Manufactured in’ countries

Returns a list of countries that DutyCalculator accepts as 'importing from' and ‘manufactured in’ parameter. The response includes the country name (in English) and the ISO 3166-1-alpha-3 code for the country (http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3).

 

Request:

GET http://www.dutycalculator.com/api2.0/{API-key}/supported-countries/from

 

Response example:

<?xml version="1.0" encoding="UTF-8"?>

<countries>

  <country code="AFG">Afghanistan</country>

  <country code="ALB">Albania</country>

  <country code="DZA">Algeria</country>

  <!-- Repeat for all supported countries -->

  <country code="ZWE">Zimbabwe</country>

</countries>

 

List of supported 'Importing to' countries

Returns a list of countries that DutyCalculator accepts as 'importing to' parameter. The response includes the country name (in English) and the ISO 3166-1-alpha-3 code for the country (http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3).

 

Request:

GET http://www.dutycalculator.com/api2.0/{API-key}/supported-countries/to

 

Response example:

<?xml version="1.0" encoding="UTF-8"?>

<countries>

  <country code="BEL">Belgium</country>

  <country code="DEU">Germany</country>

  <country code="ESP">Spain</country>

  <!-- Repeat for all supported countries -->

  <country code="NLD">Netherlands</country>

</countries>

 

DutyCalculator is always adding new countries and you can find the country coverage and roll out plan here: https://docs.google.com/spreadsheet/ccc?key=0AnPvB6mM6oe4dHNidWNXV2JDdVp3Z3hxRWU2ZXRFSnc

 

List of supported currencies

Returns a list of currencies that DutyCalculator accepts as 'currency' parameter. The response includes the currency name (in English) and the ISO 4217 code for the currency.

 

Request:

GET http://www.dutycalculator.com/api2.0/{API-key}/supported-currencies

 

Response example:

<?xml version="1.0" encoding="UTF-8"?>

<currencies>

  <currency code="EUR">Euro</currency>

  <currency code="GBP">£ Sterling</currency>

  <currency code="USD">US Dollar</currency>

  <!-- Repeat for all supported currencies -->

  <currency code="JPY">Japanese Yen</currency>

</currencies>

 

List of available Duty categories

Returns the list of the categories, subcategories and product types that DutyCalculator accepts for all of the 'import to' countries. The DutyCalculator Item ID determines the duty & tax rates of a product for all ‘import to’ countries covered by DutyCalculator. So a selected DutyCalcuylator Item ID can be used for import duty & tax calculations for all ‘import to’ countries and will ensure that the correct duty & taxes rates are used.

 

Request:

GET http://www.dutycalculator.com/api2.0/{API-key}/categories

 

Response example:

<?xml version="1.0" encoding="UTF-8"?>

                <category id="L1-321" name="Jewellery &amp; Watches">
                               <subcategory id="L1-322" name="Jewellery">
                                               <item id="25">Cuff Bracelets of Base Metal</item>
                                               <item id="1578">Cuff Links of Metal or Plated Metal</item>
                                               <item id="1163">Jewellery Assembly Sets</item>
                                               <item id="1499">Jewellery of Gold</item>
                                               <item id="1160">Jewellery of non Precious Metal</item>
                                               <item id="1162">Jewellery of Platinum</item>
                                               <item id="1161">Jewellery of Silver</item>
                                               <item id="1893">Jewellery Polishes &amp; Creams</item>
                                               <item id="2159">Gold in raw form </item>
                                               <item id="2570">Diamond Jewellery</item>

                               <!-- Repeat for all other items types within subcategory  -->
                               </subcategory>

<!-- All subcategories with item types for category -->
</category>

<!-- Repeat for all categories -->

</categories>

 

Classification service - get DutyCalculator item ID

Auto-suggests the most relevant DutyCalculator categories and items for your product. Using your short product categories and keywords including make and material will yield better results than long verbose product descriptions.

 

Request:

GET http://www.dutycalculator.com/api2.0/{API-key}/dc-id-classification \

?product_desc={product description}

The product description is used to populate suggested categories in the response.

 

Response example:

<?xml version="1.0" encoding="UTF-8"?>

<categories>

 <suggested-categories>

                <category id="L1-321" name="Jewellery &amp; Watches">
                               <subcategory id="L1-322" name="Jewellery">
                                               <item id="25">Cuff Bracelets of Base Metal</item>
                                               <item id="1578">Cuff Links of Metal or Plated Metal</item>
                               </subcategory>
                </category>

  </suggested-categories>

  <all-categories>

                <category id="L1-321" name="Jewellery &amp; Watches">
                               <subcategory id="L1-322" name="Jewellery">
                                               <item id="1163">Jewellery Assembly Sets</item>
                                               <item id="1499">Jewellery of Gold</item>
                                               <item id="1160">Jewellery of non Precious Metal</item>
                                               <item id="1162">Jewellery of Platinum</item>
                                               <item id="1161">Jewellery of Silver</item>
                                               <item id="1893">Jewellery Polishes &amp; Creams</item>
                                               <item id="2159">Gold in raw form </item>
                                               <item id="2570">Diamond Jewellery</item>

                               <!-- Repeat for all other items types within subcategory  -->
                               </subcategory>

<!-- All subcategories with item types for category -->
</category>

<!-- Repeat for all categories --></all-categories>

</categories>

 

Classification service - get HS codes, duty & tax rates and import restrictions

Returns HS code, duty & tax rates and any import restrictions for a given product and ‘import to’ country.

Request:

GET http://www.dutycalculator.com/api2.0/{API-key}/get-hscode \
&to={ISO alpha-3 country code} \
&classify_by={items classification identifier} \
&cat[0]={item ID} \
&hs[0]={item HS code} \
&desc[0]={product description} \
&sku[0]={item sku} \
&detailed_result={1 for full details with duty & taxes rates and import restrictions, 0 for HS codes only}

Response example:

<?xml version="1.0" encoding="UTF-8"?>
<classifications country-to-code3="CAN" country-to-province-code=”AB”>
 <classification>
  <hs-code>8471.30.0090</hs-code>
  <duty>
      <![CDATA[5%, subject to minimum of AU$4 per KG]]>
  </duty>
  <sales-tax name="GST">
      <![CDATA[10%]]>
  </sales-tax>
  <additional-import-taxes>
      <tax name="Excise">
          <![CDATA[50%]]>
      </tax>
      <tax name="Customs Service Fee">
          <![CDATA[AU$38.19]]>
      </tax>
  </additional-import-taxes>
  <import-restrictions>
      <![CDATA[As per List of Restricted Imports, this product is subject to a Letter of Authorization (LOA).]]>
  </import-restrictions>
 </classification>
 <!-- Repeat for all classified items -->
<classifications>

Parameter classify_by is used to specify the request field that is used to classify the item and accepts values “cat”, “hs”, “hs+desc”, “desc” and “cat + desc”, and “sku”. If left out the value of “cat+desc” is assumed.

If “cat” is used, the returned data is for the provided DutyCalculator item ID.

If “hs” is used, the returned data is for the provided 6 digit or 10/12 digit HS code. In case a 6 digit HS code is provided, the returned data is for the underlying 10-digit HS code with the highest duty rate. You can include product description as well, using “hs+desc” to use auto-classification with 6 digit HS codes.

If “desc” is used, the returned data is for the HS code with the best keyword match based on DutyCalculator auto-classification algorithms. You can further enhance the auto-classification by using “cat + desc” and include for “cat” DutyCalculator category IDs or DutyCalculator subcategory IDs.

If “sku” is used, you can use your SKU as used when you uploaded your product catalog into DutyCalculator Rapid Classification Tool:http://www.dutycalculator.com/rapid-classification-tool-overview/. Please note, you need to first upload your product catalog and classify for this parameter to work.

Parameter detailed_result indicates the desired level of details in the classification result. If set as “1”, import duty & taxes rates and import restrictions are returned for each item as well as the HS codes. If set as “0”, only the HS codes are returned.


Import Duty & Taxes Calculation service

 

Returns the import duties and taxes due for a specified shipment.

 

Request:

GET http://www.dutycalculator.com/api2.0/{API-key}/calculation \

?from={ISO alpha-3 country code} \

&to={ISO alpha-3 country code} \

&province={ISO alpha-2 province code of ‘importing to’ country (only required for Canada)} \

&commercial_importer={importer status (only required for Russia)} \

&imported_wt={total weight of products imported during the month (only required for Russia)} \

&imported_value={total value of products imported during the month (only required for Russia)} \

&classify_by={items classification identifier} \

&cat[0]={item ID or category ID} \

&hs[0]={item HS code} \

&desc[0]={product description} \

&sku[0]={item sku } \

&value[0]={value per one item} \

&wt[0]={weight of one item} \

&qty[0]={item quantity} \

&amt_unit[0]={items amount unit} \

&amt[0]={items amount} \

&origin[0]={ISO alpha-3 country code} \

&reference[0]={product reference}  \

&shipping={shipping cost} \

&insurance={cost of insurance} \

&currency={ISO currency code} \

&shipment_wt={total shipment weight}

&output_currency={ISO currency code} \

&detailed_result={1 for detailed result, 0 for short result} \

&incl_hs_codes={include HS code for each item in response}

 

 

Parameter classify_by is used to specify the request field that is used to classify the item and accepts values “cat”, “hs”, “hs+desc”, “desc” and “cat + desc”, and “sku”. If left out the value of “cat+desc” is assumed. The selected value applies to all products in the shipment.

 

If “cat” is used, the calculation is run for the provided DutyCalculator item ID or the item ID of the highest duty and sales tax rates under the selected DutyCalculator category or subcategory ID.

 

If “hs” is used, the calculation is run for the provided 6 digit or 10/12 digit HS code. In case a 6 digit HS code is provided, the returned data is for the underlying 10-digit HS code with the highest duty rate. You can include product description as well, using “hs+desc” to use auto-classification with 6 digit HS codes.

 

If “desc” is used, the calculation is run using the DutyCalculator Item ID with the best keyword match based on DutyCalculator auto-classification algorithms. You can further enhance the auto-classification by using “cat + desc” and include for “cat” DutyCalculator category IDs or DutyCalculator (sub-)category IDs.

 

If “sku” is used, you can use your SKU as used when you uploaded your product catalog into DutyCalculator Rapid Classification Tool: http://www.dutycalculator.com/rapid-classification-tool-overview/. Please note, you need to first upload your product catalog and classify for this parameter to work.

 

Parameter province is currently only required if the ‘importing to’ country is Canada where provincial sales taxes rates are used in calculations.

 

The parameter commercial importer is only required if the “importing to’ country is Russia. This parameter accepts values 1 (commercial importer) and 0 (private importer). For a ‘Private importer’ the parameters imported_wt (imported weight (in KG)) and imported_value (imported value) are required. Default values are 0 KG and €1000 and ensure maximum possible duty & tax liabilities are calculated.

 

The parameter value and wt are the value in indicated currency (parameter currency) and weight in KG of a single item or order unit. Parameter qty is the number of items or order units in the shipment. For example, if a shipment contains 5 pairs of Nike Jordan Airs of $100 and 2 kilograms the parameters would be &value[0]= 100 \ &wt[0]={2} \ &qty[0]={5} \.  Parameter wt is only required for ‘import to’ Switzerland and for a few products for other ‘import to’ countries (see table below). Default values for wt=1 and qty=1.

 

The parameters amt_unit (items amount unit) and amt (items amount) are only required for some ‘import to’ countries for some products. The table below indicates the required amt_unit required per ‘import to’ country and product, including default values. Parameter amt_unit accepts values “m3”, “cm3”, “in3”, “l”, “pcs” (pieces), “doz” (dozen), “gr” (gross), “pairs”, “jwl” (number of jewels) and “m2”.  Parameters amt and amt_unit are used to determine whether special duty rules should be applied to the shipment/product and also determine the import duty & sales taxes if they are applied. For example, if a shipment contains 5 pairs of Nike Jordan Airs of $100 and 2 kilograms the parameters would be &value[0]= 100 \ &wt[0]={2} \ &qty[0]={5} \ &amt_unit[0]=pairs \

&amt[0]={1} \

 

Parameter origin indicates country of manufacture. If left out it is assumed that country of manufacture equals country from.

 

Parameter reference is optional and can be used for your reference, calculation of import duty & taxes for split shipments and refunds for return shipments (see below).

 

Parameter shipping and insurance are shipping cost and cost of insurance of the whole shipment (not per item!) in indicated currency (parameter currency).

 

Parameter shipment_wt (total shipment weight (in KG)) is required when importing into Brazil and import CIF exceeds US$3000.

 

Parameter output_currency indicates the desired currency of the calculation results. If left out, the currency of ‘import to’ country is used.

 

Parameter detailed_result (details) indicates the desired level of details in the calculation result. If set as “1”, import duty & taxes are returned for each item as well as the total import duty & taxes due for the whole shipment. If set as “0”, only the total import duty & taxes for the shipment are returned. Parameter incl_hs_codes (inclusion of HS codes into the calculation call response) accepts the values of “1” and “0”. If set to “1”, for each product, the 10/12 digit HS codes for country of destination are included in the response for each item. If set to “0” or left out the HS codes are not included in the response.

 

 

DutyCalculator Category

Weight and ‘amt_unit’ parameters requirement by import to country

Antiques, Art & Collectibles

Weight (default value is 1kg) for some items (Russia)

Weight (default value is 1kg) for monuments of granite (Thailand)

Baby clothes & essentials

Weight (default value is 1kg) for clothing items (Russia, New Zealand)

Pieces (default value = “item quantity”) for blankets (India)

Bags & Accessories

Weight (default value is 1kg) for some items (Russia, USA)

Pieces (default value = “item quantity”) for ties (India)

Books, Movies & Music

Weight (default value is 1kg) for some items (Russia)

Surface (default value is 1m2) for tapes (USA)

Business & industrial

Weight (default value is 1kg) for display stands (Russia)

Car Parts, DIY & Tools

Weight (default value is 1kg) for some parts (Russia)

Pieces (default value = “item quantity”) for some tools (USA)

Cars & Motorcycles

Volume (default value is 1cm3) for all items (Russia)

Clothes for Children

Weight (default value is 1kg) when importing into Russia, USA, New Zealand

Pieces (default value = “item quantity”) when importing into India

Clothes for Men

Weight (default value is 1kg) when importing into Russia, USA, New Zealand

Pieces (default value = “item quantity”) when importing into India

Clothes for Women

Weight (default value is 1kg) when importing into Russia, USA, New Zealand

Pieces (default value = “item quantity”) when importing into India

Computers & Office

Weight (default value is 1kg) for some items (Russia)

Pieces (default value = “item quantity”) for pens (USA)

Gross (default value is 1) for pencils (USA)

Pieces (default value = “item quantity”)

Electronics & Video games

Weight (default value is 1kg) for some items (Russia, USA)

Weight (default value is 1kg) for wire glue (Thailand)

Health & Beauty

Weight (default value is 1kg) for olive oil and coconut water (EU)

Weight (default value is 1kg) for some items (Norway, Russia, USA, New Zealand)

Weight (default value is 1kg) for beeswax (Thailand)

Home & Garden

Weight (default value is 1kg) for sugar, chewing gums, pasta (EU)

Weight (default value is 1kg) for some items (Norway, Russia, Canada, USA, India, Japan, South Africa, Thailand)

Surface (default value is 1m2) for fabrics (India, Japan)

Volume (default value is 1L) for wine (Australia, Japan)

Volume (default value is 1L) for fridges (Russia)

Pieces (default value = “item quantity”) for clocks (Russia)

Jewellery & Watches

Pieces (default value = “item quantity”) for watches and watch cases (EU, USA, Russia, Turkey, Switzerland, Turkey)

Weight (default value is 1kg) for imitation jewellery (Russia)

Musical instruments

Weight (default value is 1kg) for instruments cases (Russia)

Shoes & Footwear

Pairs (default value = 1) for shoes (USA, Russia, Japan, South Africa)

Sports & Leisure

Weight (default value is 1kg) for some items (Russia)

Weight (default value is 1kg) for table tennis and billiard items (Thailand)

Pieces (default value = “item quantity”) for some clothes (India)

Pieces (default value = “item quantity”) for very few items (USA)

Pieces (default value = “item quantity”) for bicycles

Pairs (default value = 1) for riding boots (Russia, Japan)

Gross (default value is 1) for combs (USA)

 

Toys & Games

Weight (default value is 1kg) for some items (Russia, New Zealand, Thailand)

Pieces (default value = “item quantity”) for few items (India)

 

 

 

Request example for a single item:

 

GET http://www.dutycalculator.com/api2.0/{API-key}/calculation?from=usa&to=nld&classify_by=cat&cat[0]=25&reference[0]=product-1&desc[0]=Nike+Air+Jordans&qty[0]=1&value[0]=29.95&shipping=6.25&insurance=1.30&currency=usd

 

Request example for multiple items:

 

GET http://www.dutycalculator.com/api2.0/{API-key}/calculation?from=usa&to=nld&classify_by=cat&cat[0]=25&desc[0]=Nike+Air+Jordans&qty[0]=1&value[0]=29.95&cat[1]=1578&desc[1]=Apple+iPhone+3G&qty[1]=2&value[1]=400&shipping=6.25&insurance=1.30&currency=usd

 

Request example for importing to Russian Federation:

 

GET http://www.dutycalculator.com/api2.0/{API-key}/calculation?from=usa&to=rus&commercial_importer=0&imported-wt=7&imported-value=950&cat[0]=25&desc[0]=Nike+Air+Jordans&qty[0]=1&wt[0]=2.54&amt=1&amt-unit=pairs&value[0]=29.95&shipping=6.25&insurance=1.30&currency=usd

 

Response example with full details and all possible nodes - example for importing to USA:

 

<?xml version="1.0" encoding="UTF-8"?>

<duty-calculation id=”6542”>

  <item id="1" hs-code=”53409809841” reference=”product-1”>

                <duty>

                               <amount currency="USD">1.23</amount>

                </duty>

                <sales-tax name=”VAT”>

                               <amount currency="USD">2.34</amount>    

                </sales-tax>

                <additional-import-taxes>

                               <tax name=”Excise”>

                                               <amount currency="USD">0.21</amount>

                               </tax>

                               <tax name=”Merchandize Processing Fee”>

                                               <amount currency="USD">2</amount>

                               </tax>

                               <tax name=”Internal Revenue Tax”>

                                               <amount currency="USD">5</amount>

                               </tax>

                </additional-import-taxes>

                <total>

                               <amount currency="USD">10.78</amount>

                </total>

  </item>

  <!-- Repeat item element for any additional items -->

  <total-charges>

                <duty>

                               <amount currency="USD">1.23</amount>

                </duty>

                <sales-tax name=”VAT”>

                               <amount currency="USD">2.34</amount>

                </sales-tax>

                <additional-import-taxes>

               <tax name=”Excise”>

                               <amount currency="USD">0.21</amount>

               </tax>

               <tax name=”Merchandize Processing Fee”>

                               <amount currency="USD">2</amount>

               </tax>

               <tax name=”Internal Revenue Tax”>

                               <amount currency="USD">5</amount>

               </tax>

                </additional-import-taxes>

                <total>

                               <amount currency="USD">10.78</amount>

                </total>

  </total-charges>

</duty-calculation>

 

Possible additional duties and taxes for are listed for each ‘import to’ country in the table below.

 

 ‘Import to’ Country

Possible additional duties & taxes

Australia

Customs Service Fee

Brazil

Airport fee, Storage fee, Handling fee, Declaration fee, ICMS tax, IPI

Canada

Excise

Chile

Luxury tax, Beverage tax

China

Consumption tax

EU

Excise

India

Landing charges, Countervailing duty, CESS, Education CESS, Additional Customs Duty

New Zealand

Import Entry Transaction Fee, Inward Cargo Transaction Fee

Norway

Other Import Fee

Singapore

Excise

South Korea

Education tax, Special tax for rural development, Transportation tax, Special consumption tax, Liquor tax

Thailand

Interior tax, Surcharge

Turkey

Special consumption tax

USA

Merchandize processing fee, Internal revenue tax

Vietnam

Special sales tax

 

Import duty & taxes calculation service with multiple shipping and insurance options

Returns the import duties and taxes calculations for specified set of items with multiple shipping and insurance options.

 

Request for multiple shipping and insurance options:

 

GET http://www.dutycalculator.com/api2.0/{API-key}/calculation \

?from={ISO alpha-3 country code} \

&to={ISO alpha-3 country code} \

&province={ISO alpha-2 province code of ‘importing to’ country (only required for Canada)} \

&commercial_importer={importer status (only required for Russia)} \

&imported_wt={total weight of products imported during the month (only required for Russia)} \

&imported_value={total value of products imported during the month (only required for Russia)} \

&classify_by={items classification identifier} \

&cat[0]={item ID} \

&hs[0]={item HS code} \

&desc[0]={product description} \

&sku[0]={item sku } \

&value[0]={value per one item} \

&wt[0]={weight of one item} \

&qty[0]={item quantity} \

&amt_unit[0]={items amount unit} \

&amt[0]={items amount} \

&origin[0]={ISO alpha-3 country code} \

&reference[0]={product reference}  \

&shipping[0]={shipping option cost} \

&shipping[1]={shipping option cost} \

&shipping[2]={shipping option cost} \

&insurance[0]={cost of insurance option} \

&insurance[1]={cost of insurance option} \

&insurance[2]={cost of insurance option} \

&currency={ISO currency code} \

&shipment_wt={total shipment weight}

&output_currency={ISO currency code} \

&detailed_result={1 for detailed result, 0 for short result} \

&incl_hs_codes={include HS code for each item in response}

 

Request example with multiple shipping options:

 

GET

http://www.dutycalculator.com/api2.0/{API-key}/calculation?from=gbr&to=usa&commercial_importer=0&cat[0]=25&desc[0]=Nike+Air+Jordans&qty[0]=3&value[0]=1000&shipping[0]=15&insurance[0]=29&shipping[1]=20&insurance[1]=30&currency=gbp

 

Response example:

 

<duty-calculations>

    <duty-calculation id="54" input-shipping-cost="15">

                 <total-charges>

                                <duty>

                                                <amount currency="USD">1454.28</amount>

                                </duty>

                                <sales-tax name="sales tax">

                                                <amount currency="USD">0</amount>

                                </sales-tax>

                                <cif>

                                                <amount currency="USD">4760.04</amount>

                                </cif>

                                <additional-import-taxes>

                                                <tax name="Merchandize Processing Fee">

                                                                <amount currency="USD">25</amount>

                                                </tax>

                                                <tax name="Internal Revenue Tax">

                                                                <amount currency="USD">0</amount>

                                                </tax>

                                </additional-import-taxes>

                                <total>

                                                <amount currency="USD">1479.28</amount>

                                </total>

                 </total-charges>

    </duty-calculation>

    <duty-calculation id="55" input-shipping-cost="20">

                <total-charges>

                                <duty>

                                                <amount currency="USD">1454.28</amount>

                                </duty>

                                <sales-tax name="sales tax">

                                                <amount currency="USD">0</amount>

                                </sales-tax>

                                <cif>

                                                <amount currency="USD">4769.42</amount>

                                </cif>

                                <additional-import-taxes>

                                                <tax name="Merchandize Processing Fee">

                                                                <amount currency="USD">25</amount>

                                                </tax>

                                                <tax name="Internal Revenue Tax">

                                                                <amount currency="USD">0</amount>

                                                </tax>

                                </additional-import-taxes>

                                <total>

                                                <amount currency="USD">1479.28</amount>

                                </total>

                 </total-charges>

    </duty-calculation>

    <!-- Repeat duty-calculation nodes for all shipping options -->

</duty-calculations>

 

Import duty & tax calculation service for split shipments or refunds

Returns the import duties and taxes for a specified invoice / credit note.

 

Request

GET http://www.dutycalculator.com/api2.0/{API-key}/invoice_calculation \

?calculation_id={duty calculation id}

&reference[0]={product reference} \

&qty[0]={item quantity} \

&shipping={shipping cost} \

&shipment_wt={total shipment weight}

&detailed_result={1 for detailed result, 0 for short result} \

&output_currency={ISO currency code} \

&incl_hs_codes={inclusion of HS codes in the calculation response}

 

Besides the “invoice_calculation” the aliases that could be used to call the service are also “shipment_calculation” and “credit_note_calculation”.

 

Parameter reference is the item reference that was used in the original duty & tax calculation (referred to by calculation_id parameter) which is being shipped in a split shipment or refunded. Parameter qty indicated the quantity of items being shipped or refunded.

 

When calling this request DutyCalculator creates a separate duty & tax calculation for a given set of items from the  original calculation.

 

Response is the same as for duty & tax calculation described above.

 

Document & reporting services

Returns the URLs to the documents of the shipment (commercial invoice & packing list) for a specified duty & taxes calculation:

 

Request:

GET http://www.dutycalculator.com/api2.0/{API-key}/documents \

?calculation_id={duty calculation id} \

&output_currency={ISO currency code} \

&seller_first_name={seller first name} \

&seller_last_name={seller last name} \

&seller_address_line_1={seller address line 1} \

&seller_address_line_2={seller address line 2} \

&seller_importer_type={commercial or private} \

&seller_company_name={seller company name} \

&seller_company_vat_number={seller company tax/VAT number} \

&seller_city={seller city} \

&seller_zip={seller ZIP} \

&seller_country={reseller ISO alpha-3 or alpha-2 country code} \

&seller_phone={seller phone number} \

&seller_tax_id={seller tax ID} \

&shipment_invoice_no={seller internal invoice number} \

&shipment_date={shipment date, e.g. 2012-03-26} \

&shipment_number_parcels={number of shipment parcels} \

&shipment_total_actual_weight={shipment total actual weight in KG} \

&shipment_total_dimensional_weight={shipment total dimensional weight in KG} \

&shipment_currency_sale={shipment currency of sale ISO code} \

&shipment_tracking_id={shipment tracking number} \

&shipment_incoterms={shipment incoterms} \

&shipto_first_name={receiver first name} \

&shipto_last_name={receiver last name } \

&shipto_importer_type={commercial or private} \

&shipto_address_line_1={receiver address line 1} \

&shipto_address_line_2={receiver address line 2} \

&shipto_company_name={receiver company name} \

&shipto_company_vat_number={receiver company tax/VAT number} \

&shipto_city={receiver city} \

&shipto_zip={receiver ZIP} \

&shipto_country={receiver ISO alpha-3 or alpha-2 country code} \

&shipto_phone={receiver phone number} \

&shipto_tax_id={receiver tax ID} \

&soldto_first_name={payer first name} \

&soldto_last_name={ payer last name} \

&soldto_address_line_1={ payer address line 1} \

&soldto_address_line_2={address line 2} \

&soldto_importer_type={commercial or private} \

&soldto_company_name={payer company name} \

&soldto_company_vat_number={payer company tax/VAT number} \

&soldto_city={payer city} \

&soldto_zip={payer ZIP} \

&soldto_country={payer ISO alpha-3 or alpha-3 country code} \

&soldto_phone={payer phone number} \

&soldto_tax_id={payer tax ID} \

&print_first_name={print first name} \

&print_last_name={print last name} \

&print_date={print date, e.g. 2012-03-26}

 

All the parameters are required except the seller_company_name, seller_address_line_2, seller_importer_type, seller_company_vat_number, seller_tax_id, shipment_tracking_id, shipment_total_dimensional_weight, shipto_company_name, shipto_address_line_2, shipto_importer_type, shipto_company_vat_number,  shipto_tax_id, soldto_company_name, soldto_address_line_2, soldto_importer_type, soldto_company_vat_number, soldto_tax_id.

 

Parameters seller_importer_type, shipto_importer_type, soldto_importer_type accept values commercial and private.

 

Response example:

 

<?xml version="1.0" encoding="UTF-8"?>

<documents>

                <commercial-invoice>

               <url>http://www.dutycalculator.com/doc/7a0s8duflaksjd09f87.pdf</url>

                </commercial-invoice>

                <packing-list>

               <url>http://www.dutycalculator.com/doc/7a0s8duf4568jd09f87.pdf</url>

                </packing-list>

  </documents>

 

Reporting service

Stores a calculation result with DutyCalculator, with all associated data, for your reporting and compliance purposes, usually once an order has been actually fulfilled.

 

Request:

GET http://www.dutycalculator.com/api2.0/{API-key}/store_calculation \

?calculation_id={duty calculation id} \

&order_id={order internal id} \

&order_type={‘order’ or ‘credit_note’} \

&shipment_id={shipment id}  \

&credit_note_id={credit note id}

 

Response examples:

<?xml version="1.0" encoding="UTF-8"?>

<order id=”ORD543VB” shipment-id=”LKJ98098” calculation-id=”123123”>

                <status>Stored</status>

</order>

 

<?xml version="1.0" encoding="UTF-8"?>

<order id=”ORD543VB” credit-note-id=”LKJ98098” calculation-id=”123123”>

                <status>Stored</status>

</order>

 

Parameters order_id, shipment_id and credit_note_id are corresponding references to an order, shipment or refund in your own system. They are used for the reporting purposes (see Transactions section of your DutyCalculator account).

 

Parameter order_type accepts values ‘order’ and ‘credit_note’ and indicates the type of the calculation being stored for reporting.

 

Parameter shipment_id is used when order_type is set to ‘order’. Parameter credit_note_id is used when order_type is set to ‘credit_note’.

 

Status messages

To indicate the result of a request, the following standard HTTP status codes are returned by the server:

  • 200 ("OK") when the operation was successful
  • 400 ("Bad request") when the operation cannot be completed due to a problem on client side: invalid or incomplete parameters. The entity-body of the response will contain a message explaining what's wrong
  • 404 ("Not found") when the client requests a URI that doesn't map to any resource or client calling a URI with a non-existing client id
  • 500 ("Internal Server Error") when the operation cannot be complete due to a problem on the server side

 

 Version History

Version number

Date

What’s new?

2.0.1

July 4th 2012

  • Duty and tax calculation service for multiple shipping cost and cost of insurance options
  • Calculation using high level DutyCalculator categories
  • Duty and tax calculation with classify_by parameter accepting ‘cat+desc’ value
  • Country of maufacture as an input parameter on the item level in the duty and tax calculation
  • Updated weight and units parameters requirements by import country. Added South Korea, Thailand and Vietnam

2.0.0

April 27th 2012

  • Import duty and tax calculation service for split shipments or refund
  • Documents and reporting services
  • Classification service - get DutyCalculator item ID

 

Cookies help us to improve our services and deliver these to you. Read moreOK