Metadata-Version: 2.4
Name: landed-cost-calculator
Version: 0.3.1
Summary: True per-unit landed cost for foreign-trade sellers based in China shipping any product to any country: China-side costs in CNY, destination duty + VAT/GST, brokerage and last-mile, in any currency.
License: MIT
Keywords: landed-cost,ecommerce,tariff,import,cross-border,calculator
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Landed Cost Calculator

**Source in China. Sell anywhere. Know your true cost first.**

A small, zero-dependency tool for **foreign-trade sellers based in China**
who ship any product category to any country. It adds up the full chain —
factory price, China domestic logistics, export fees, international
freight, destination import duty, destination VAT/GST, brokerage and
local last-mile delivery — into one honest landed cost per unit, and
shows your real margin at a planned selling price.

全品类通用：不预设任何产品，关税按你自己查到的 HS 税率填入；目的国预设只提供
当地的增值税/消费税标准税率和官方查询入口。

## Why this exists

Sellers in China usually quote and price in CNY, sell in EUR/USD/JPY, and
pay a stack of charges in between that simple spreadsheets miss:

- **Destination VAT/GST is often bigger than the duty.** In the worked
  example below (China → Germany), duty is €84.17 but import VAT is
  €339.93 — over 4× the duty, on the same shipment. Sellers who only
  budget for duty underprice every order.
- **China-side costs are real costs**: domestic shipping to the port or
  export warehouse, customs declaration and document fees per shipment.
- **Duty bases differ** (goods value vs goods + freight), and payment
  fees quietly take ~3% of the selling price.

This project is maintained by a seller preparing her own cross-border
store; the calculator is the pricing tool used for those decisions,
published so other China-based sellers can use and improve it.

## Destinations built in

Presets for 12 destinations set the settlement currency and the standard
VAT/GST rate, with a sourced note per country (official tariff lookup,
trade-agreement hints, gotchas). Duty is **never** preset — it depends on
your HS code, so you look it up in the official source we link and enter
it yourself.

US · Germany · France · Spain · Netherlands · United Kingdom · Japan ·
South Korea · Australia · Singapore · UAE · Canada
(see `data/destinations.json`; any other country works with the Custom
rates in the web version / `--vat-rate` on the CLI)

## What the tool looks up for you (v0.3)

You should only have to type numbers that are *yours* — your factory
price, your freight quote, your selling price. Everything generic is
filled in or one click away:

- **VAT/GST** — preset per destination (above), editable.
- **Exchange rate** — the web version fetches the live reference rate
  (ECB via Frankfurter, exchangerate-api as fallback) and shows its
  source and date; the CLI does the same with `--auto-fx`. Reference
  rates are not bank settlement rates, so the field stays editable.
- **Duty rate** — enter your HS code and the tool links you straight to
  that code in the destination's official tariff (deep links for the UK
  and US, official tariff homepages elsewhere). Duty itself is never
  guessed: it is HS-specific, and a wrong guess costs real money.
- **Payment fees** — typical channel presets (Stripe / Shopify Payments
  2.9%, PayPal 3.49%; percentage part only), editable.
- **Your repeat routes** — the web version saves your common routes
  (freight, brokerage, last-mile…) in your browser, so a repeat
  calculation is: pick the route, change the factory price, done.
  Nothing is uploaded; profiles live in `localStorage` only.

## Two ways to use it

### 1. Web version (no install)

Open `web/index.html` in any browser, or use the live version linked from
this repo's About section. The web UI is **bilingual （中文 / English)** —
it auto-detects your browser language and has a one-click toggle, because
most of its users are sellers in China. Pick a destination, enter your
CNY factory price and the exchange rate — everything runs locally;
nothing is sent anywhere.

### 2. Command line (Python 3.9+, no dependencies)

```bash
pip install landed-cost-calculator
# or run the file directly:
python3 landed_cost.py --config examples/china_to_germany.json
```

**Worked example 1 — China → Germany** (fictional sample, in
`examples/china_to_germany.json`): a product bought at **¥46/unit** in
China, 200 units, duty 6.5%, Germany VAT 19%:

```
Goods value (converted)      €  1,294.95
Export fees in China         €     40.05
International freight        €    410.00
Duty (on €1,294.95)          €     84.17
VAT/GST (on €1,789.12)       €    339.93
Brokerage / customs fees     €     95.00
Last-mile + packaging        €  1,020.00
TOTAL LANDED COST            €  3,284.10   →  €16.42 per unit
```

At a €24.99 selling price that is €7.84 profit per unit (31.39% margin)
— after payment fees, before ads and returns.

**Worked example 2 — China → US** (in `examples/sample_shipment.json`):
500 phone cases bought in Shenzhen at **¥9.9/unit** become a **$6.81
landed cost per unit** — 4.6× the factory price — once international
freight, 12.5% duty, brokerage and US last-mile are counted. At a
$12.99 selling price that is $5.80 profit per unit (44.69% margin).

With a destination preset on the CLI (sets currency + standard VAT):

```bash
python3 landed_cost.py --destination DE --unit-price 46 --quantity 200 \
  --fx-rate 0.1335 --freight-total 410 --tariff-rate 6.5
```

Config files (JSON) use fractions for rates (`0.19` = 19%); CLI flags
use percents. China-side costs (unit price, origin logistics, export
fees) are entered in the source currency and converted at `--fx-rate`;
destination-side costs are entered in the settlement currency.

## Not customs or tax advice

Duty depends on your product's exact HS classification, origin and the
rules in force on the entry date; VAT/GST presets are standard rates and
reduced rates exist for some categories. Every rate in
`data/destinations.json` carries its sources and a review date. Verify
with the destination's official tariff/tax sources or a licensed customs
broker before a large shipment.

## Roadmap

- [x] v0.1 — US-focused CLI + web calculator, tests
- [x] v0.2 — Any destination: 12 presets with VAT/GST, CNY→any-currency
  conversion, China-side logistics & export fees
- [x] v0.3 — Less to look up: live FX rates, HS-code tariff lookup
  links, saved routes, payment-fee presets
- [ ] Break-even selling price for a target margin
- [ ] Multi-destination comparison (same product, several countries)
- [ ] CSV batch mode for a whole product catalogue
- [ ] More destination presets, each with sourced notes

Suggestions and corrections are very welcome — see
[CONTRIBUTING.md](CONTRIBUTING.md).

## Tests

```bash
python3 -m unittest discover -s tests   # 12 tests
```

## License

MIT — see [LICENSE](LICENSE).

---

## 中文说明

**给在中国做外贸的卖家的落地成本计算器**：全品类通用、发往任何国家都能算。
把出厂价、中国国内物流、报关杂费、国际运费、目的国关税、目的国增值税、
清关费和当地尾程全部摊开，得出一件商品真正的落地成本和真实毛利。

为什么需要它：在中国进货的人用人民币算成本、用外币卖货，中间漏算的重灾区是——
目的国增值税经常比关税还大（示例里中国→德国一票货：关税 €84.17，进口增值税
€339.93，是关税的4倍多）；中国这边的国内物流和每票报关费也是真成本；
支付手续费还要吃掉售价的约3%。

用法：打开网页版选目的国（自动带出当地增值税标准税率和币种），填人民币出厂价
和汇率即可；也可用命令行或 `pip` 安装。关税不预设，请按自己产品的 HS 编码到
目的国官方税则查询后填入。示例（虚构数据）：¥46/件的货发到德国，落地成本
€16.42/件；卖 €24.99 时每件赚 €7.84（未扣广告与退货）。

注意：本工具只做估算，不构成报关或税务建议；大货下单前请向持牌报关行或
目的国官方渠道核实税率。
