Introduction
The Duty & Tax Calculation service calculates shopping cart taxes for Marketplace. For example, a buyer wants to purchase products from the marketplace and adds them to the shopping cart. Marketplace sends shopping cart information to Eurora and receives tax data.
Note:
Integrating with Eurora
1. Firstly, open the API “Calculate shopping cart taxes” on Postman and set up your token.
2. Next, you can put your data into the body of your request, then click Send button on Postman.
Please refer to the Legal HS Code in EU searching tool and Acceptable Goods Description released by EU Commission in the References section below.
3. If the request succeeds, it will return a 200(OK) status.
References
Searching Legal HS Code accepted by EU Customs
Guidance on acceptable and unacceptable goods description published by EU Commission
API Documentation
Environment | API Documentation | API Collection |
Production | Link | Link |
Integration | Link | Link |
D&T Calculation Specification |
||||
Order/Shipment info |
||||
externalID |
required |
string |
|
Shipment/Order ID. must be unique |
orderCurrency |
required |
string |
3 char |
Currency code for the order. ISO 4217. must be upper case |
transportationPrice |
required |
number |
>=0 |
Shipment/Order shipping price |
insurancePrice |
optional |
number |
>=0 |
Shipment/Order insurance price |
otherAdditionalCosts |
optional |
number |
>=0 |
Shipment/Order other additional costs (clearance, surcharges, etc.) |
originCountry |
required |
string |
2 char |
Order/Shipment goods country of origin. ISO-3166-1 alpha-2, uppercase Example: ES=Spain |
destinationCountry |
required |
string |
2 char |
Order/Shipment consignee country. ISO-3166-1 alpha-2, uppercase Example: ES=Spain |
destinationRegion |
required |
string |
[A-Z0-9_\-]+ |
Order/Shipment consignee country region. ISO 3166-2, uppercase. Required only if destinationCountry is Canada (CA); United States of America (US); Brasil (BR); Spain (ES). |
additionalValueShare |
optional |
string |
Enum: "MANUAL" "VALUE" "WEIGHT" |
Parameter used to the determine additional value share ratio. If MANUAL is selected then additionalValueShareRatio need to be set on each goods line |
date |
optional |
string |
<date> |
Transaction date in UTC. Required only if the transaction date occurred in the past. Calculation up to 7 days in the past and up to 1 day in the future is supported. No need to send if a real-time calc. is required. Format: YYYY-MM-DD |
useDeMinimis |
optional |
boolean |
Default: TRUE |
Parameter defining whether de minimis thresholds should be applied |
hsCodeReplaceAllowed |
required |
boolean |
Default: TRUE |
Parameter defining whether Eurora should allocate HS codes or should Eurora use the ones provided in the request |
declarationType |
optional |
string |
Enum: "H1" "H7" |
Parameter defining oroder/shipment customs declaration type |
transactionModel |
optional |
string |
Enum: "B2C "B2B" "C2C" |
Defines shipment/order transaction channel (type of participants involved in the transaction). Impacts de minimis thresholds |
transactionCategory |
optional |
string |
Enum: "COMMERCIAL" "GIFT" |
Defines the transaction type. Impacts de minimis thresholds |
Order/Shipment Goods info |
||||
external ID |
required |
string |
|
Order/Shipment line ID. must be unique |
originCountry |
optional |
string |
2 char |
goods country of origin (production country) ISO-3166-1 alpha-2, uppercase Example: ES=Spain |
gtin |
optional |
string |
|
Global Trade Item Number to uniquely identify a trade item. (ITEM ID) |
title |
optional |
string |
|
Product Name/Title |
description |
required |
string |
[ 3 .. 512 ] characters |
Goods description (Product name or title if a description is not available) |
hsCode |
optional |
string |
|
Harmonized system code, if available. Can have length of 6, 8 or 10. |
weight |
required |
number |
> 0 |
Single item NET weight |
quantity |
required |
number |
>=1 |
Items quantity |
additionalValueShareRatio |
optional |
number |
[ 0 .. 1 ] |
Goods ratio of the whole shipment. MANDATORY if additionalValueShare is set to "MANUAL" on the order/shipment level. |
Goods Price info |
||||
currency |
required |
string |
3 char |
Currency code for the item. ISO 4217. must be upper case |
value |
required |
number |
>=0 |
Single item price in the given currency |
|
|
|
|
|
D&T Calculation Response Specification |
||||
Order/Shipment info |
||||
externalID |
|
string |
|
Shipment/Order ID. must be unique |
totalVat |
|
number |
|
Total VAT or GST of a shipment/order |
totalDuties |
|
number |
|
Total import duty of a ship[ment/order |
destinationCountry |
|
string |
2 char |
Order/Shipment consignee country. ISO-3166-1 alpha-2, uppercase Example: ES=Spain |
originCountry |
|
string |
2 char |
Order/Shipment goods country of origin. ISO-3166-1 alpha-2, uppercase Example: ES=Spain |
Order/Shipment Goods info |
||||
externalID |
|
string |
|
Shipment/Order ID. must be unique |
description |
|
string |
[ 3 .. 512 ] characters |
Goods description (Product name or title if a description is not available) |
vat |
|
number |
|
goods VAT or GST amount |
duty |
|
number |
|
goods import duty amount |
vatRate |
|
number |
|
VAT or GST rate coefficient |
dutyRate |
|
number |
|
Import duty rate coefficient |
hsCodeCorrectness |
|
number |
|
Indication of the confidence level between the product description and matched HS-code |
calculatedHsCode |
|
string |
|
HS Code allocated by Eurora (if requested) |
|
|
|
|
|
D&T Calculation Errors Specification |
||||
Response Status |
Error Field |
Error Message |
Possible Root Cause |
Possible Solution |
400 |
transportationPrice |
"field":"transportationPrice","reason":"NotNull","message":"must not be null" |
transportationPrice not provided |
Please add transportationPrice value in the payload and re-submit. |
400 |
destinationRegion |
"field":"request[0]","reason":"NotNullExistsConditional","message":"Destination region has to be provided when destination country is CA" |
destinationRegion not provided |
Please provide destinationRegion and re-submit. |
400 |
parameters |
"field":"parameters","reason":"HarmonizedSystemVersionExists","message":"harmonized system 4201003000 is not available on 2022-09-29" |
AI always allocates 10-digit codes and if fewer digits are asked, the last digits are simply cut off. Now, when the final code reaches taxes applications for the official nomenclature description, then it might happen that the code actually does not exist in the nomenclature. |
If you prefer to replace your provided HS code with the one allocated by Eurora, please contact Eurora support. You may also leave the HS code field empty, in which case the longest possible HS code will be returned. |
400 |
goods.description |
"field":"goods[0].description","reason":"Size","message":"size must be between 3 and 5000" |
The goods description is too short (<3) or too long (>5000). Example: "description":"礼服" |
Please make sure the goods.description contains 3 to 5000 symbols and re-submit. |
400 |
destinationRegion |
"field":"destinationRegion","reason":"Region","message":"region code not found" |
Invalid destinationRegion code provided for the country. |
Please provide an existing destinationRegion code and re-submit. |
400 |
hsCode |
"field":"request[0]","reason":"HarmonizedSystem","message":"Harmonized system code not found" |
Invalid HS Code providedD11:E19D11:E18E19D11:E20D11:E19 |
Please validate the HS Code at https://trade.ec.europa.eu/access-to-markets/en/home , correct the code and re-submit. |
400 |
originCountry |
"field":"originCountry","reason":"NotBlank","message":"must not be blank" |
originCountry is not provided for Duty and Tax in the request. |
Please make sure originCountry is provided and re-submit. |
400 |
weight |
"field":"weight","reason":"NotNull","message":"must not be null" |
Weight is not provided for Duty and Tax in the request |
The weight in the Payload should not be empty and must be greater than 0. Please modify and re-submit. |
400 |
date |
"field":"date","reason":"RelativeDateRange","message":"Duty and Tax calculation not supported more than 60 days in past and more than 1 day in the future." |
Provided date for Duty and Tax calculation in request payload is more than 60 days in the past or more than 1 day in the future |
Please modify the date for Duty and Tax calculation and re-submit. |
400 |
destinationRegion |
"field":"destinationRegion","reason":"Pattern","message":"string must be uppercase" |
Destination region code is provided with lowercase letters |
Please provide the correct destination region with uppercase letters and re-submit. |
400 |
dutyRequest |
"field":"dutyRequest","reason":"CodeLengthByCountry","message":"goodsNomenclatureCode size must be between 6 and 8 for country AE" |
Provided HS code for Bahrain, Kuwait, Oman, Qatar, Saudi Arabia and UAE is below or above the range of 6 to 8 digits |
Provided HS code for Bahrain, Kuwait, Oman, Qatar, Saudi Arabia and UAE must meet the range between 6 and 8 digits Please check that provided HS code is within the range of 6 to 8 digits and resubmit |
400 |
externalId |
"field":"goods","reason":"GoodsExternalId","message":"goods externalId must not repeat within shipment" |
Value for "externalId" is not unique |
Please make sure your goods externalId is always a unique value and re-submit. |
404 |
amount of digits after harmonized-system in request URL |
"entity":"HarmonizedSystem","field":"code","value":"8542310000" |
"The provided amount of digits for the HS code in the request is incorrect. EU, UK - 6, 8 and 10-digit codes CA- 10- Digits for Canada (Canada Customs Tariff) US - 8 and 10-digit codes for the US (Harmonized Tariff Schedule) GCC - 8 - digit codes SA - 8 and 10 - digit codes Rest of the world - above or below 6 digits" |
Please make sure provided HS code meets the "amount of digits" for the destination country and re-submit |
404 |
goodsNomenclatureCode |
"entity":"Duty","field":"goodsNomenclatureCode","value":"847170" |
Incorrect goodsNomenclatureCode provided in the request |
Please provide the correct goodsNomenclatureCode for the destination country and re-submit. |
404 |
version |
"entity":"AreaTaxRate","field":"version","value":"9" |
area_tax_rate table is missing data related to: region-code, tax_rate_type_id and other relevant parameters |
Please contact Eurora support |
501 |
destinationCountry |
"Country \"CH\" is not supported for performing DUTY requests." |
Provided destinationCountry is not supported for Duty requests |
"Please check that provided destination country is supported for Duty requests. https://api.eurora.com/taxes/v1/countries/supported/dutyAndTax " |
501 |
destinationCountry |
"Country \"MQ\" is not supported for performing TAX requests." |
Provided destinationCountry is not supported for TAX requests. |
"Please check that provided destination country is supported for Tax requests. https://api.eurora.com/taxes/v1/countries/supported/dutyAndTax " |
501 |
destinationCountry |
There is a Duty Expression for at least one additional duty applied for the country of origin, therefore duty rate calculation is not supported. |
One of the nomenclature codes in the hierarchy for the requested code may include a complex expression. Due to the heavy analysis requirement, it's not yet supported |
"Please check that provided destination country is supported for Tax requests. https://api.eurora.com/taxes/v1/countries/supported/dutyAndTax or Contact Eurora support Comment: Eurora is continuously monitoring and prioritizing adding more duty expressions and country coverage to the Duty & Tax Calculator service. With urgent matters, please notify Eurora that unsupported country and provided product group are crucial and impactful for your business" |
500 |
id |
"id": "Io4qz22GitkiiuNcENVg" |
Internal server error |
Please contact Eurora support |