tax-calculation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Tax Calculation

税款计算

Overview

概述

Accurate tax calculation at checkout is a legal requirement, not an optimization. In the United States, there are over 13,000 taxing jurisdictions. EU VAT rules require charging the customer's local VAT rate. Getting it wrong leads to under-collection (a liability you must cover) or over-collection (refunds and customer complaints). All major platforms have built-in tax calculation or direct integrations with TaxJar and Avalara that handle this correctly without custom code.
结账时精准计算税款是法律要求,而非优化选项。在美国,有超过13000个征税辖区。欧盟VAT规则要求按照客户所在地区的税率收取税款。计算错误会导致少收税款(需自行承担的负债)或多收税款(退款及客户投诉)。所有主流平台都内置了税款计算功能,或可直接集成TaxJar和Avalara,无需自定义代码即可正确处理此类需求。

When to Use This Skill

何时使用该技能

  • When expanding sales to states or countries where you have tax nexus obligations
  • When manual tax rates are causing compliance issues or needing constant updates
  • When implementing EU VAT compliance (OSS/IOSS registration)
  • When displaying accurate tax before the customer confirms payment
  • 当业务拓展至存在税务关联(nexus)义务的州或国家时
  • 手动设置税率导致合规问题或需要频繁更新时
  • 实施欧盟VAT合规(OSS/IOSS注册)时
  • 需要在客户确认付款前显示准确税款时

Core Instructions

核心操作指南

Step 1: Understand nexus before configuring tax

步骤1:配置税务前先理解税务关联(nexus)

You only need to collect tax in jurisdictions where you have nexus (a tax obligation).
US Sales Tax nexus:
  • Physical nexus: you have employees, warehouses, or offices in a state
  • Economic nexus: most states trigger at $100,000/year in sales OR 200 transactions to customers in that state (California and Texas use $500,000)
  • Check each state's current threshold before configuring — thresholds change
EU VAT:
  • EU-based sellers must charge VAT at the customer's country rate for all EU sales
  • Non-EU sellers must register for EU VAT (via OSS scheme) once annual EU B2C sales exceed €10,000
  • B2B sales within the EU: reverse charge applies — the buyer handles VAT via self-assessment
您仅需在存在税务关联(即税务义务)的辖区收取税款。
美国销售税关联:
  • 实体关联:您在某州拥有员工、仓库或办公场所
  • 经济关联:大多数州的触发条件为年销售额达10万美元,或向该州客户完成200笔交易(加利福尼亚州和德克萨斯州的阈值为50万美元)
  • 配置前请确认各州当前阈值——阈值会发生变化
欧盟VAT:
  • 欧盟境内卖家必须针对所有欧盟销售按照客户所在国税率收取VAT
  • 非欧盟卖家在欧盟境内B2C年销售额超过1万欧元后,必须注册欧盟VAT(通过OSS方案)
  • 欧盟境内B2B销售:适用反向征税——买家通过自行申报处理VAT

Step 2: Set up tax calculation on your platform

步骤2:在您的平台上设置税款计算



Shopify

Shopify

Option A: Shopify's built-in tax (recommended for US stores)
  1. Go to Settings → Taxes and duties
  2. Under Tax regions, select the regions where you have nexus
  3. For US: Shopify calculates taxes automatically at the correct state + county + city rate based on the customer's shipping address — no third-party service needed for basic US compliance
  4. Enable Charge tax on shipping if your state requires it (varies by state)
  5. For product-level exemptions (e.g., clothing exempt in PA): go to Products → [Product] → Tax and set the appropriate tax category or create a custom tax override
Option B: Stripe Tax (via Shopify + Stripe)
Shopify's built-in tax covers US well. For international VAT compliance, install Stripe Tax via a Shopify app integration.
Option C: TaxJar or Avalara (for complex multi-jurisdiction requirements)
  1. Install TaxJar or Avalara AvaTax from the Shopify App Store
  2. Follow the app's setup wizard: connect to your Shopify store, enter your nexus states, and configure product tax categories
  3. The app replaces Shopify's built-in tax calculation with its own real-time calculation at checkout
  4. Committed transactions are automatically sent to TaxJar/Avalara for filing reports
选项A:Shopify内置税务功能(推荐美国店铺使用)
  1. 进入设置 → 税费与关税
  2. 税务区域下,选择您存在税务关联的区域
  3. 针对美国:Shopify会根据客户的收货地址自动计算正确的州+县+市税率——基础美国合规无需第三方服务
  4. 若您所在州要求,则启用对运费征税(各州规定不同)
  5. 针对产品级免税(如宾夕法尼亚州的服装免税):进入产品 → [对应产品] → 税费,设置合适的税分类或创建自定义税费覆盖规则
选项B:Stripe Tax(通过Shopify + Stripe集成)
Shopify内置税务功能能很好地覆盖美国场景。针对国际VAT合规,可通过Shopify应用集成安装Stripe Tax
选项C:TaxJar或Avalara(适用于复杂多辖区需求)
  1. 从Shopify应用商店安装TaxJarAvalara AvaTax
  2. 跟随应用设置向导:连接您的Shopify店铺,输入您的关联州信息,配置产品税分类
  3. 应用会替换Shopify内置的税款计算功能,在结账时进行实时计算
  4. 已完成的交易将自动发送至TaxJar/Avalara用于申报报告

WooCommerce

WooCommerce

Option A: WooCommerce built-in tax
  1. Go to WooCommerce → Settings → Tax and enable tax calculation
  2. Set your store base address (this affects which rates apply)
  3. Go to Tax → Standard rates and manually enter rates per state/country
  4. Limitation: manual rates are not updated automatically; for compliance, use TaxJar or Avalara
Option B: TaxJar (recommended for US compliance)
  1. Sign up at taxjar.com and get your API token
  2. Install TaxJar for WooCommerce plugin (free, from WordPress.org)
  3. Go to WooCommerce → TaxJar and enter your API token
  4. Enable Automatic tax calculation — TaxJar calculates the correct rate at checkout in real-time based on your nexus states and the customer's address
  5. Enable Transaction sync — completed orders are automatically sent to TaxJar for filing reports
Option C: Avalara AvaTax
  1. Sign up at avalara.com and create a company in AvaTax
  2. Install the Avalara AvaTax for WooCommerce plugin
  3. Enter your Account ID, License Key, and Company Code from the Avalara dashboard
  4. Enable calculation and transaction recording
选项A:WooCommerce内置税务功能
  1. 进入WooCommerce → 设置 → 税费并启用税款计算
  2. 设置您的店铺基础地址(这会影响适用税率)
  3. 进入税费 → 标准税率,手动输入各州/国家的税率
  4. 局限性:手动税率不会自动更新;为确保合规,请使用TaxJar或Avalara
选项B:TaxJar(推荐用于美国合规)
  1. taxjar.com注册并获取API令牌
  2. 安装TaxJar for WooCommerce插件(免费,来自WordPress.org)
  3. 进入WooCommerce → TaxJar并输入您的API令牌
  4. 启用自动税款计算——TaxJar会根据您的关联州和客户地址实时计算正确税率
  5. 启用交易同步——已完成订单会自动发送至TaxJar用于申报报告
选项C:Avalara AvaTax
  1. avalara.com注册并在AvaTax中创建公司
  2. 安装Avalara AvaTax for WooCommerce插件
  3. 输入Avalara仪表板中的账户ID、许可证密钥和公司代码
  4. 启用计算和交易记录功能

BigCommerce

BigCommerce

  1. Go to Store Setup → Tax
  2. BigCommerce has a built-in tax calculation for basic US rates
  3. For full compliance: go to Store Setup → Tax → Tax Provider and connect Avalara AvaTax or TaxJar
  4. Follow the provider's BigCommerce setup guide — both have native integrations that replace the built-in tax engine with real-time compliant calculations
EU VAT on BigCommerce: Enable VAT by country under Store Setup → Tax → VAT for EU VAT compliance. For full OSS compliance, use Avalara's EU VAT module.

  1. 进入店铺设置 → 税费
  2. BigCommerce内置了针对美国基础税率的税款计算功能
  3. 如需全面合规:进入店铺设置 → 税费 → 税务服务商并连接Avalara AvaTaxTaxJar
  4. 跟随服务商的BigCommerce设置指南——两者均有原生集成,可替换内置税务引擎实现实时合规计算
BigCommerce上的欧盟VAT:店铺设置 → 税费 → VAT下启用按国家收取VAT以满足欧盟VAT合规。如需全面OSS合规,请使用Avalara的欧盟VAT模块。

Custom / Headless

自定义/无头电商

Use Stripe Tax (simplest) or the TaxJar/Avalara API directly:
Option A: Stripe Tax (recommended for Stripe-based stores)
javascript
// Enable Stripe Tax on the PaymentIntent — Stripe calculates and collects tax automatically
const paymentIntent = await stripe.paymentIntents.create({
  amount: orderSubtotalCents, // Subtotal only — Stripe adds tax
  currency: 'usd',
  automatic_payment_methods: { enabled: true },
  // Stripe Tax configuration
  // See: https://stripe.com/docs/tax/integration
});

// Or use Stripe Checkout with automatic_tax enabled:
const session = await stripe.checkout.sessions.create({
  line_items: lineItems,
  mode: 'payment',
  automatic_tax: { enabled: true }, // Stripe Tax handles calculation
  customer_details: { address: { country: customerCountry }, address_source: 'shipping' },
  success_url: `${domain}/success`,
  cancel_url: `${domain}/cart`,
});
Configure Stripe Tax under Stripe Dashboard → Tax → Configure — set your tax registration numbers and the tax behaviors for each product category.
Option B: TaxJar API
javascript
const Taxjar = require('taxjar');
const taxjar = new Taxjar({ apiKey: process.env.TAXJAR_API_KEY });

async function calculateTaxForOrder({ fromAddress, toAddress, lineItems, shippingCost }) {
  const response = await taxjar.taxForOrder({
    from_country: fromAddress.country,
    from_zip: fromAddress.zip,
    from_state: fromAddress.state,
    to_country: toAddress.country,
    to_zip: toAddress.zip,
    to_state: toAddress.state,
    to_city: toAddress.city,
    amount: lineItems.reduce((sum, i) => sum + i.unit_price * i.quantity, 0),
    shipping: shippingCost,
    line_items: lineItems.map(item => ({
      id: item.id,
      quantity: item.quantity,
      unit_price: item.unit_price,
      product_tax_code: item.tax_code ?? null, // e.g., '20010' for general goods
    })),
  });

  return {
    totalTax: response.tax.amount_to_collect,
    taxRate: response.tax.rate,
    hasNexus: response.tax.has_nexus, // false = no tax to collect
    breakdown: response.tax.breakdown,
  };
}

// After order is confirmed, commit the transaction for filing reports
async function commitTaxTransaction(order) {
  await taxjar.createOrder({
    transaction_id: order.id,
    transaction_date: new Date().toISOString().split('T')[0],
    from_country: WAREHOUSE_ADDRESS.country,
    from_zip: WAREHOUSE_ADDRESS.zip,
    from_state: WAREHOUSE_ADDRESS.state,
    to_country: order.shippingAddress.country,
    to_zip: order.shippingAddress.zip,
    to_state: order.shippingAddress.state,
    amount: order.subtotal,
    shipping: order.shippingCost,
    sales_tax: order.taxAmount,
    line_items: order.lineItems.map(item => ({
      id: item.id,
      quantity: item.quantity,
      unit_price: item.price,
      sales_tax: item.taxAmount,
    })),
  });
}
EU VAT reverse charge (B2B cross-border within EU):
For EU B2B transactions, validate the buyer's VAT number via the EU VIES service before applying zero-rate:
javascript
async function validateEUVATNumber(vatNumber) {
  const countryCode = vatNumber.slice(0, 2);
  const number = vatNumber.slice(2);
  const res = await fetch(
    `https://ec.europa.eu/taxation_customs/vies/rest-api/ms/${countryCode}/vat/${number}`
  );
  const data = await res.json();
  return data.isValid === true;
}
使用Stripe Tax(最简单)或直接调用TaxJar/Avalara API:
选项A:Stripe Tax(推荐基于Stripe的店铺使用)
javascript
// Enable Stripe Tax on the PaymentIntent — Stripe calculates and collects tax automatically
const paymentIntent = await stripe.paymentIntents.create({
  amount: orderSubtotalCents, // Subtotal only — Stripe adds tax
  currency: 'usd',
  automatic_payment_methods: { enabled: true },
  // Stripe Tax configuration
  // See: https://stripe.com/docs/tax/integration
});

// Or use Stripe Checkout with automatic_tax enabled:
const session = await stripe.checkout.sessions.create({
  line_items: lineItems,
  mode: 'payment',
  automatic_tax: { enabled: true }, // Stripe Tax handles calculation
  customer_details: { address: { country: customerCountry }, address_source: 'shipping' },
  success_url: `${domain}/success`,
  cancel_url: `${domain}/cart`,
});
Stripe控制台 → 税费 → 配置中设置Stripe Tax——输入您的税务注册号,并为每个产品类别配置税务行为。
选项B:TaxJar API
javascript
const Taxjar = require('taxjar');
const taxjar = new Taxjar({ apiKey: process.env.TAXJAR_API_KEY });

async function calculateTaxForOrder({ fromAddress, toAddress, lineItems, shippingCost }) {
  const response = await taxjar.taxForOrder({
    from_country: fromAddress.country,
    from_zip: fromAddress.zip,
    from_state: fromAddress.state,
    to_country: toAddress.country,
    to_zip: toAddress.zip,
    to_state: toAddress.state,
    to_city: toAddress.city,
    amount: lineItems.reduce((sum, i) => sum + i.unit_price * i.quantity, 0),
    shipping: shippingCost,
    line_items: lineItems.map(item => ({
      id: item.id,
      quantity: item.quantity,
      unit_price: item.unit_price,
      product_tax_code: item.tax_code ?? null, // e.g., '20010' for general goods
    })),
  });

  return {
    totalTax: response.tax.amount_to_collect,
    taxRate: response.tax.rate,
    hasNexus: response.tax.has_nexus, // false = no tax to collect
    breakdown: response.tax.breakdown,
  };
}

// After order is confirmed, commit the transaction for filing reports
async function commitTaxTransaction(order) {
  await taxjar.createOrder({
    transaction_id: order.id,
    transaction_date: new Date().toISOString().split('T')[0],
    from_country: WAREHOUSE_ADDRESS.country,
    from_zip: WAREHOUSE_ADDRESS.zip,
    from_state: WAREHOUSE_ADDRESS.state,
    to_country: order.shippingAddress.country,
    to_zip: order.shippingAddress.zip,
    to_state: order.shippingAddress.state,
    amount: order.subtotal,
    shipping: order.shippingCost,
    sales_tax: order.taxAmount,
    line_items: order.lineItems.map(item => ({
      id: item.id,
      quantity: item.quantity,
      unit_price: item.price,
      sales_tax: item.taxAmount,
    })),
  });
}
欧盟VAT反向征税(欧盟境内B2B跨境交易):
针对欧盟B2B交易,在适用零税率前需通过欧盟VIES服务验证买家的VAT编号:
javascript
async function validateEUVATNumber(vatNumber) {
  const countryCode = vatNumber.slice(0, 2);
  const number = vatNumber.slice(2);
  const res = await fetch(
    `https://ec.europa.eu/taxation_customs/vies/rest-api/ms/${countryCode}/vat/${number}`
  );
  const data = await res.json();
  return data.isValid === true;
}

Step 3: Commit tax transactions after order completion

步骤3:订单完成后提交税务交易

Tax calculation services require you to "commit" each transaction after payment is confirmed — this records it in your filing reports. TaxJar and Avalara apps for Shopify/WooCommerce do this automatically. For custom integrations, call the create/commit API after the order is confirmed (not before payment).
税款计算服务要求您在付款确认后“提交”每笔交易——这会将交易记录到您的申报报告中。Shopify/WooCommerce的TaxJar和Avalara应用会自动完成此操作。对于自定义集成,请在订单确认后(而非付款前)调用创建/提交API。

Best Practices

最佳实践

  • Never hard-code tax rates — rates change constantly; use TaxJar, Avalara, Stripe Tax, or your platform's built-in tax engine
  • Calculate tax in real-time at checkout — display the exact tax amount before the customer confirms payment; estimated tax that changes at payment causes distrust and cart abandonment
  • Commit transactions after payment, not before — only committed transactions appear in filing reports; commit when the payment is confirmed
  • Void tax transactions on refunds — when you issue a refund, void the corresponding tax transaction in TaxJar/Avalara to avoid over-reporting on your filing
  • Handle tax API errors gracefully — if the tax API is unavailable, apply a fallback rate (US average ~8.5%) rather than blocking checkout
  • 切勿硬编码税率——税率会频繁变化;使用TaxJar、Avalara、Stripe Tax或平台内置的税务引擎
  • 在结账时实时计算税款——在客户确认付款前显示准确的税款金额;预估税款在付款时变更会引发客户不信任并导致购物车弃购
  • 付款完成后再提交税务交易——只有提交的交易才会出现在申报报告中;在付款确认后提交
  • 退款时作废税务交易——当您处理退款时,在TaxJar/Avalara中作废对应的税务交易,避免申报时多报
  • 优雅处理税务API错误——若税务API不可用,采用 fallback 税率(美国平均约8.5%),而非阻止结账

Common Pitfalls

常见陷阱

ProblemSolution
Tax calculated but not committed to the filing APIEnsure your platform integration (TaxJar plugin, Avalara plugin) is configured to auto-commit on order completion; verify in the provider's transaction dashboard
EU VAT charged on B2B cross-border salesValidate VAT numbers via VIES before applying reverse charge; if validation fails, charge VAT as B2C
Tax API adds 500ms to checkoutTaxJar and Avalara both have caching built into their Shopify/WooCommerce plugins; for custom builds, cache estimates by destination zip code and cart total for 1 hour
Shopify charging wrong tax rate for a stateVerify your nexus state list in Settings → Taxes is correct and up to date; check for product-level tax overrides that may be incorrectly configured
WooCommerce showing "0 tax" after TaxJar installVerify TaxJar API key is correct; check the plugin's status page for API errors; confirm your warehouse address and nexus states are configured in the TaxJar dashboard
问题解决方案
已计算税款但未提交至申报API确保您的平台集成(TaxJar插件、Avalara插件)已配置为订单完成时自动提交;在服务商的交易仪表板中验证
欧盟境内B2B跨境销售收取了VAT在应用反向征税前,通过VIES验证VAT编号;若验证失败,按照B2C收取VAT
税务API使结账延迟500msTaxJar和Avalara的Shopify/WooCommerce插件均内置缓存功能;对于自定义开发,按目标邮政编码和购物车总额缓存预估税款,有效期1小时
Shopify针对某州收取错误税率验证设置 → 税费中的关联州列表是否正确且最新;检查可能配置错误的产品级税费覆盖规则
WooCommerce安装TaxJar后显示“0税费”验证TaxJar API密钥是否正确;查看插件状态页面的API错误信息;确认TaxJar仪表板中已配置仓库地址和关联州

Related Skills

相关技能

  • @checkout-flow-optimization
  • @multi-currency
  • @order-processing-pipeline
  • @stripe-integration
  • @tax-compliance-automation
  • @checkout-flow-optimization
  • @multi-currency
  • @order-processing-pipeline
  • @stripe-integration
  • @tax-compliance-automation