China Personal Income Tax Calculator V2

Problem

Engineers evaluating salaries, offers, or bonuses often estimate tax as monthly salary times a rate, missing cumulative withholding, special additional deductions, year-end bonus separate-taxation thresholds, social insurance and housing fund, and foreign tax credits. China personal income tax is not a single linear calculation: comprehensive income is withheld cumulatively from the start of the year; the annual bonus can be taxed separately or combined with comprehensive income, with the incentive running through December 31, 2027; and labor remuneration, royalties, business income, property transfers, dividends, and other categories use different rules.

How It Works

The skill centralizes core logic in scripts/tax_calc.py and exposes functions for common workflows:
- Wages and offer comparison: quick_calc(), calculate_monthly_tax(), reverse_gross_from_net(), and compare_job_offers() handle monthly tax, net take-home, gross-to-net reverse calculation, and multi-offer net comparisons.
- Bonus optimization: compare_bonus_methods(), check_bonus_trap(), and optimize_bonus_avoiding_traps() compare separate versus combined taxation, detect tax-bracket jump traps, and suggest safer amounts.
- Social insurance and housing fund: calculate_social_insurance(salary, city) estimates contributions for supported cities such as Beijing, Shanghai, Shenzhen, Guangzhou, Hangzhou, and Chengdu.
- Batch and reporting: batch_calculate_tax(), generate_tax_report(), generate_feishu_report(), and generate_tax_distribution_chart() support HR batch calculations, Markdown or Feishu reports, and ASCII visualizations.
Other income types such as labor remuneration, royalties, business income, property transfers, and dividends are calculated according to the rules listed in the skill; foreign income is handled by computing the tax credit limit and applying the lower of foreign taxes paid and that limit.

Boundaries

The output is useful for salary estimation, offer comparison, and annual settlement preparation, but it is not a final filing authority. Results are precise to cents, yet actual filings depend on tax authority review. Special additional deductions follow the 2025 standards listed in the skill, social insurance coverage is limited to supported cities, and nonresident, annuity, or stock-option cases should be checked against the applicable local and national rules.