service market / Import tax trial calculation API development documentation

Taiwan import tax trial calculation API · v1

Import tax trial calculation API development documentation

Based on the product (CCC tax code, or just automatic AI classification of product description) + foreign currency amount, instantly calculate Taiwan import taxes: tariff (including ECFA / fixed tax), business tax, promotion fee, goods tax, tobacco and alcohol tax, and automatically determine the small amount of NT$2,000 tax-free. Specially designed for docking with cross-border e-commerce platforms such as 0337.tw.

5 major taxes and fees

Tariff + business tax + promotion fee + goods tax + tobacco and alcohol tax

NT$2,000

Automatic determination of small amount tax exemption

AI tax rules

Automatically classify product descriptions CCC

Exchange rate per ten days

Official customs declaration exchange rate conversion

1 Overview

Let your platform directly display "How much tax will be paid when importing this product into Taiwan?" on the front desk.

what can be done

Tax calculation - Bring in the goods (CCC tax code or product description) + foreign currency amount, return the complete tax details (tariff/business tax/promotion fee/goods tax/tobacco and alcohol tax) and the total cost of implementation including tax.
Check the tax rate — Check the tariff rate and goods tax flag according to the CCC tariff number.
automatic tariff — When there is no CCC, only product_description is given, and the system uses the AI model of the Customs Administration to automatically recommend the tariff and calculate the tax.

Tax currency: New Taiwan Dollar (TWD). The amount of goods you bring in in foreign currency (such as CNY) will be calculated by the system after converting it into New Taiwan Dollars based on the official ten-day customs declaration exchange rate. The tax amount will all be in New Taiwan Dollars.

The relationship between and the freight API :. The shipping_fee in the tax trial calculation response is the HowBridge NT$ reference freight (for implementation cost estimation). For the actual collection fee collected from 0337.tw, please use freight API (sea express, RMB). The tax of this API does not include freight (tax base = commodity FOB, convenient basis; the formal customs declaration shall be subject to the customs approval of CIF).

2 Certification and basic information

All requests require an API Key (the same key as the shipping fee/shipment status is sufficient, and the tax:read permission is required).

Base URL

https://0523.tw/api/v1/tax

Authentication header (choose one)

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx
// or
X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Please call from the server side and do not expose the key to the front end. The rate limit is in key units, and the response header X-RateLimit-Remaining reports the remaining quota, and HTTP 429 is returned when the limit is exceeded.

3 Endpoint: Tax Trial Calculation

GETPOST /api/v1/tax/estimate

It is recommended to use POST + JSON.

Request parameters

parameter	Type	Required	illustrate
`currency_code`	string(3)	Required	Foreign currency type, such as `CNY`.
`price_foreign`	number	Required	Amount of merchandise in foreign currency.
`product_description`	string	Optional*	Product description. When `hs_code` is not given, AI is used to automatically push the tax rules.
`hs_code`	string	Optional*	CCC Tariff Code (8–11 digits).
`quantity`	int	Optional	Quantity, default 1.
`weight_kg` / `dimensions`	number / [3]	Optional	Weight / Length, Width and Height (refer to freight estimate).
`over_exempt_limit`	bool	Optional	The six tax exemptions for half a year have been exhausted → compulsory taxation.
`volume_liters` / `alcohol_degree` / `tobacco_sticks`	number/int	Optional	Used for calculation of alcohol/cigarette fixed tax.

* hs_code and product_description Choose at least one .

Request example (POST JSON)

curl -X POST https://0523.tw/api/v1/tax/estimate \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"product_description":"Cotton women's tops","currency_code":"CNY","price_foreign":300,"quantity":1}'

Responses 200 (excerpt)

{
  "success": true,
  "data": {
    "input": { "hs_code": "61061000", "currency_code": "CNY", "price_foreign": 300 },
    "exchange": { "rate_to_twd": 4.612, "price_twd": 1383.6 },
    "tariff_info": { "duty_rate": 10.5, "duty_rate_text": "10.5%", "ecfa_applied": false },
    "tax_base": 1383.6,
    "tax_breakdown": {
      "is_tax_exempt": true,            // Tax base ≤ NT$2,000 → small amount tax exemption
      "duty": 0, "promo_fee": 0, "vat": 0, "total_tax": 0,
      "if_over_limit": {           // If the tax exemption is exhausted 6 times in half a year, the amount payable
        "duty": 145.28, "vat": 76.44, "total_tax": 221.72
      }
    },
    "antidumping": [],
    "total_landed_cost": 1453.6,
    "disclaimer": "..."
  }
}

4 Endpoint: check tax rate

GET /api/v1/tax/rate/{hsCode}

Check the tariff rate and goods tax flag according to the CCC tariff number (pure numbers).

curl https://0523.tw/api/v1/tax/rate/6109100000 \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

{
  "success": true,
  "data": {
    "hs_code": "6109100000",
    "duty_rate": 10.5,
    "duty_rate_text": "10.5%",
    "is_commodity_tax": false,
    "name_zh": "Cotton T-shirts, undershirts…",
    "source": "tariffs_db"
  }
}

5 Response field description (data)

field	illustrate
`exchange.rate_to_twd`	The daily customs declaration exchange rate used (Foreign Currency → New Taiwan Dollar).
`exchange.price_twd`	The product amount is converted into New Taiwan Dollars.
`tariff_info.duty_rate`	Tariff rate applied (%); ECFA second column when applicable.
`tax_base`	Tax base (NTD) = item FOB × quantity (excluding shipping charges).
`tax_breakdown.is_tax_exempt`	Is it exempt from small amount tax exemption (tax base ≤ NT$2,000 and non-tobacco and alcoholic beverages).
`tax_breakdown.duty`	Tariff (NTD).
`tax_breakdown.promo_fee`	Promotional trade service fee (0.04%, no charge if less than NT$100).
`tax_breakdown.commodity_tax`	Excise tax (home appliances, etc.; generally 0 for ready-made clothing).
`tax_breakdown.alcohol_tax`	Tobacco and alcohol tax (fixed amount).
`tax_breakdown.vat`	Sales tax 5%.
`tax_breakdown.total_tax`	Total tax payable (NTD).
`tax_breakdown.if_over_limit`	In the case of tax exemption, the estimated tax payable if the tax exemption is used up 6 times in half a year.
`antidumping`	Anti-dumping/balanced tax reminder (depending on the country of origin, only the reminder is not incorporated into the total).
`total_landed_cost`	Total landing cost including tax (tax base + reference freight + tax).

6 tax formula

tax base = commodity FOB (foreign currency × exchange rate) × quantity
small amount tax exemption = tax base ≤ NT$2,000 and not tobacco and alcohol → tax 0 (6 times in half a year)
tariff = tax base × tariff rate (or fixed tax, whichever is higher)
Promotion fee = tax base × 0.04% (no charge if the amount does not reach NT$100)
Goods tax = (Tax base + Tariff) × Goods tax rate (applicable items)
Business tax = (tax base + tariff + goods tax + alcohol and tobacco tax) × 5%
Tax payable = Customs duty + Promotion fee + Goods tax + Tobacco and alcohol tax + Business tax

Legal basis: Tariff Law, Value-Added and Non-Value-Added Business Tax Law, Trade Law (Promotion of Trade Service Fees), Goods Tax Regulations, Tobacco and Alcohol Tax Law. The actual tax amount is subject to customs approval.

7 error code

HTTP	`error` / situation	illustrate
401	missing_api_key / invalid_api_key	No/invalid API Key.
403	insufficient_scope	The key is not activated `tax:read`.
422	Missing currency_code / price_foreign	The required parameters are missing or in the wrong format.
422	tax deficiency rules	hs_code not given and product_description cannot be classified.
422	There is no exchange rate for this currency	The currency_code has not yet provided an exchange rate, please contact customer service.
429	rate_limit_exceeded	Per minute limit exceeded.

8 Program example

$client = new GuzzleHttp\Client(['base_uri' => 'https://0523.tw']);
$res = $client->post('/api/v1/tax/estimate', [
    'headers' => ['Authorization' => 'Bearer ' . env('LUCKY_FREIGHT_KEY')],
    'json' => [
        'product_description' => 'Cotton women's tops',
        'currency_code' => 'CNY',
        'price_foreign' => 300,
    ],
]);
$tax = json_decode($res->getBody(), true)['data']['tax_breakdown'];
echo 'Taxes payable NT$' . $tax['total_tax'];

const r = await fetch('https://0523.tw/api/v1/tax/estimate', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${process.env.LUCKY_FREIGHT_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ product_description: 'Cotton women's tops', currency_code: 'CNY', price_foreign: 300 }),
});
const { data } = await r.json();
console.log(data.tax_breakdown.total_tax);

curl -X POST https://0523.tw/api/v1/tax/estimate \
  -H "Authorization: Bearer $LUCKY_FREIGHT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_description":"Cotton women's tops","currency_code":"CNY","price_foreign":300}'

9 Support and versions

technical support: howyunqisoftware@gmail.com

API version: v1 (stable).

Change history: 2026-06-01 — Import tax trial calculation API v1 is online.

Shipping API Availability API Apply for an API key