Tax Compliance Automation

Tax Compliance Automation

Overview

Tax compliance for ecommerce is one of the most complex operational challenges at scale. In the United States alone, there are over 13,000 taxing jurisdictions with different rates, product taxability rules, filing frequencies, and economic nexus thresholds. Internationally, VAT (Europe, UK, Australia) and GST (Canada, India, New Zealand) add additional compliance layers with their own registration thresholds, invoice requirements, and reporting obligations.

This skill covers the full tax compliance lifecycle: nexus threshold tracking to know when you must register in a new jurisdiction, real-time tax calculation at checkout, exemption certificate management for B2B customers, automated filing, and audit-ready reporting. All major platforms have direct integrations with TaxJar and Avalara that handle this without custom code.

When to Use This Skill

• When your store ships to customers in multiple US states and you are unsure of nexus obligations
• When you need to collect EU VAT under OSS/IOSS for European customers
• When building B2B ecommerce that requires exemption certificate management
• When current tax rates are hardcoded and have not been updated in 12+ months
• When preparing for an audit and you need documented, reconcilable tax records
• When launching in a new country and you need to understand VAT/GST registration requirements

Core Instructions

Step 1: Determine your platform and choose the right tax compliance tool

For filing automation specifically:

• TaxJar AutoFile: available with TaxJar Plus and Professional plans; files returns automatically in registered states
• Avalara Returns: built into Avalara's subscription; handles US and international returns
• Vertex: enterprise-grade for large retailers with complex product taxability rules; significantly higher cost than TaxJar or Avalara

---

Step 2: Set up nexus registration and real-time tax calculation

---

Shopify

Step 1: Register nexus states in Shopify

1. Go to Settings → Taxes and duties → United States 2. Click Collect sales tax and select the state where you have nexus 3. Enter your sales tax permit number for that state — Shopify uses this in your tax remittance records 4. Repeat for each state where you have nexus (physical or economic) 5. For the EU: click European Union under Tax regions and configure your VAT registration number (OSS or per-country)

Step 2: Install TaxJar for full compliance automation

1. Install TaxJar from the Shopify App Store (search "TaxJar") 2. Sign up at taxjar.com and get your API token from Account → TaxJar API 3. In the TaxJar Shopify app, enter your API token and click Connect 4. Configure your nexus states in TaxJar: go to TaxJar Dashboard → Account → States with Nexus and add each state where you are registered 5. Enable Transaction Sync in the TaxJar app — completed Shopify orders are automatically sent to TaxJar for filing records 6. Enable AutoFile in TaxJar → Account → AutoFile if you want TaxJar to file returns on your behalf (requires TaxJar Plus or Professional plan)

Exemption certificates on Shopify: 1. Install Avalara CertCapture from the Shopify App Store, or use TaxJar's certificate management feature under TaxJar → Exemptions 2. B2B customers can upload their exemption certificates through a hosted portal; once approved, they are automatically applied to future orders

EU VAT on Shopify:

• Go to Settings → Taxes and duties → European Union
• Add your OSS registration number (format: EU + your country's VAT number)
• Shopify automatically applies the correct VAT rate per EU country based on the customer's shipping address
• For IOSS (import OSS for orders under €150 from outside the EU): enter your IOSS number in Settings → Taxes → Duties and import taxes

---

WooCommerce

Step 1: Install and configure TaxJar

1. Sign up at taxjar.com and get your API token 2. Install the TaxJar for WooCommerce plugin (free, from WordPress.org — search "TaxJar") 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 5. Enable Transaction Sync — completed orders are automatically sent to TaxJar for filing records 6. Enter your from address (warehouse address) — this is used as the origin for nexus determination

Step 2: Configure nexus states in TaxJar

1. Log in to taxjar.com → Account → States with Nexus 2. Add each US state where you have a sales tax permit 3. For each nexus state, enter your sales tax registration number 4. TaxJar will only calculate and record tax for orders shipped to nexus states

Step 3: Enable filing automation

1. Upgrade to TaxJar Plus or Professional for AutoFile access 2. Go to TaxJar → Account → AutoFile and enable AutoFile for each state 3. TaxJar automatically files and remits on your behalf by the due date

Exemption certificates on WooCommerce:

• Install WooCommerce B2B plugin or use TaxJar's certificate management: go to TaxJar → Exemptions and add exempt customers by email address or customer type
• Customers with "wholesale" or "reseller" roles can be automatically flagged as exempt

EU VAT on WooCommerce:

• Install WooCommerce EU VAT Assistant or WooCommerce Germanized (for German-specific compliance)
• Go to WooCommerce → Settings → Tax → EU VAT and enter your OSS registration number
• The plugin automatically applies the correct VAT rate per EU country and generates compliant invoices

---

BigCommerce

Step 1: Connect Avalara AvaTax (recommended)

1. Go to Settings → Tax → Tax Provider 2. Select Avalara AvaTax — BigCommerce has a native Avalara connector 3. Click Connect and log in to your Avalara account (sign up at avalara.com if needed) 4. Avalara automatically replaces BigCommerce's built-in tax engine with real-time compliant rates

Step 2: Configure nexus in Avalara

1. Log in to Avalara Dashboard → Settings → Company → Nexus 2. Add each US state or country where you are registered 3. Enter your registration number for each jurisdiction 4. Avalara will calculate and record tax only for jurisdictions where you have nexus

Step 3: Enable Avalara Returns

1. In the Avalara Dashboard → Returns, enable Managed Returns for each nexus state 2. Avalara prepares and files returns automatically; for states where you want to review before filing, use Unmanaged Returns (Avalara prepares the return for you to submit)

Exemption certificate management on BigCommerce:

• Use Avalara CertCapture — go to Avalara Dashboard → CertCapture and configure the certificate collection portal
• Customers receive a link to upload their exemption certificate; once approved in CertCapture, future orders are automatically exempted

EU VAT on BigCommerce:

• Go to Store Setup → Tax → VAT and enable VAT by country
• Enter your OSS or per-country VAT registration numbers
• For full OSS compliance with automated filing, use Avalara's VAT Reporting module — contact Avalara for international VAT setup

---

Custom / Headless

Use the TaxJar API or Avalara AvaTax API for real-time calculation and filing records:

TaxJar real-time calculation at checkout:

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.taxCode ?? null, // e.g., '20010' for general goods
      exemption_type: item.exemptionType ?? null,
    })),
    exemption_type: customer.exemptionType ?? null, // 'wholesale', 'government', etc.
  });

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

Commit transaction after payment (required for filing records):

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,
    })),
  });
}

// On refund: void the transaction so it is excluded from filing reports
async function voidTaxTransaction(orderId) {
  await taxjar.deleteOrder(orderId);
}

EU VAT B2B reverse charge — validate VAT number via VIES:

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;
  // If valid: apply zero-rate (reverse charge); if invalid: charge local VAT rate
}

Nexus threshold monitoring: TaxJar provides an Economic Nexus Insights feature in the TaxJar Dashboard that automatically tracks your sales volume per state and alerts you when you approach thresholds. Access it under TaxJar Dashboard → Economic Nexus Insights — this eliminates the need to build custom threshold tracking code.

---

Step 3: Validate and manage exemption certificates

For US B2B sales: Exemption certificates must be collected and validated before applying zero-rate to a customer. Do not apply exemptions based on a customer's self-declaration alone.

• Avalara CertCapture: the most complete solution — handles certificate collection, validation, renewal reminders, and state-specific form requirements. Available as an add-on to any Avalara subscription.
• TaxJar Exemptions: simpler option — add exempt customers in TaxJar Dashboard → Customers → Exemptions by email, customer ID, or customer type. TaxJar automatically skips tax calculation for those customers.
• For WooCommerce: the WooCommerce B2B plugin or WooCommerce Tax Exemptions plugin can gate exemption certificate uploads during checkout for wholesale customers.

Certificate storage requirements:

• Keep certificates for a minimum of 4 years (most states) or until 3 years after your last transaction with that customer in the issuing state
• Store in a searchable system — during an audit, you may need to produce certificates on short notice

---

Step 4: Set up automated filing

Filing calendar setup: 1. Log in to your TaxJar or Avalara dashboard and confirm the filing frequency for each registered state (monthly, quarterly, or annual — set by the state based on your sales volume) 2. Enable AutoFile or Managed Returns for each state 3. Verify bank account is connected for automatic remittance — go to TaxJar → Account → AutoFile → Payment Method or Avalara → Settings → Bank Accounts 4. Set up email alerts for filing confirmations under your account notification settings

Best Practices

• Never build your own tax rate tables — rates change constantly. The API cost is far lower than the risk of collecting the wrong amount or missing a rate update.
• Register before you hit the nexus threshold — once economic nexus is triggered you may owe tax retroactively from the trigger date. Monitor the TaxJar Economic Nexus Insights dashboard and register when you reach 80% of a state threshold.
• Commit transactions after payment, not before — only committed transactions appear in filing reports. Commit when the payment is confirmed, not when the order is created.
• Void tax transactions on refunds — when you issue a refund, void the corresponding tax transaction in TaxJar or Avalara to avoid over-reporting on your filing.
• Validate exemption certificates before applying zero-rate — use Avalara CertCapture or TaxJar Exemptions to manage certificates; never accept exemptions without documented certificates.
• Handle digital goods separately — most US states and all EU countries have special taxability rules for digital goods, SaaS, and streaming. Set the correct TaxJar product tax code (e.g., DC010100 for SaaS) or Avalara tax code for each digital product.

Common Pitfalls

Related Skills

• @tax-calculation
• @payment-reconciliation-automation
• @invoice-generation-automation
• @checkout-flow-optimization
• @multi-currency

Tax Audit Report Generator

Problem/Feature Description

BrightCart is a mid-size B2B and B2C ecommerce platform that has just received a sales tax audit notice from the California state tax authority covering the prior fiscal year. The auditor will want to see a complete, reconcilable record of every taxable transaction: what was charged, at what rate, for which customer, and whether any exemptions were applied. The compliance team also needs to confirm that their process for handling B2B customers who claim tax-exempt status is documented and defensible.

The engineering team needs to build a tax audit reporting module that generates a structured transaction-level report from their database of tax records. They also want the implementation to correctly handle the scenario where a B2B customer presents an exemption certificate — the system should check for a valid, active certificate before skipping tax collection, and should log an error gracefully if the third-party tax calculation service is temporarily unavailable (rather than blocking the customer from completing their purchase). Additionally, they want a script that generates a sample CSV-format audit report and demonstrates the correct column formatting.

Output Specification

Produce the following files:

• tax-reporting.js — A module implementing at minimum:
• A generateTaxReport({ jurisdiction, startDate, endDate, transactions }) function that takes an array of transaction objects and returns rows (one per transaction) and a summary object
• A checkExemptionCertificate(customer, state, certificates) function that checks whether a valid, active exemption certificate exists for the given customer and state
• A calculateTaxSafe(order, taxCalculateFn) function (or equivalent) that wraps tax calculation with error resilience so checkout is never blocked
• generate-sample-report.js — A runnable script that creates sample transaction data and writes a CSV audit report to audit-report.csv
• audit-report.csv — The CSV output produced by running generate-sample-report.js, containing at least 5 sample rows showing a mix of taxable and exempt transactions, including at least one refunded/voided transaction that should be excluded

The implementation should not require any API keys or external services to run.

Input Files

The following sample transaction schema is provided for reference. Extract it before beginning.

=============== FILE: inputs/transaction-schema.json =============== { "description": "Shape of a tax transaction record", "fields": { "id": "uuid", "order_id": "uuid", "jurisdiction": "string (e.g. 'US-CA', 'US-TX')", "tax_type": "string ('sales_tax' | 'vat' | 'gst')", "taxable_amount": "decimal", "tax_rate": "decimal (e.g. 0.0875 for 8.75%)", "tax_amount": "decimal", "tax_name": "string", "exemption_applied": "boolean", "exemption_type": "string | null", "provider": "string ('taxjar' | 'avalara' | 'vertex' | 'manual')", "provider_transaction_id": "string | null", "collected_at": "ISO 8601 timestamp", "voided_at": "ISO 8601 timestamp | null", "customer": { "name": "string", "email": "string" } } }

EU VAT Calculation and Quarterly OSS Report Generator

Problem/Feature Description

Papyrus & Co. is a small UK-based online retailer that sells books, stationery, baby accessories, food hampers, and general merchandise to customers across the European Union. Since Brexit, they ship into EU countries as a non-EU seller. Their checkout currently charges a flat 20% rate on everything — meaning they are under-charging VAT on some items, over-charging on others, and filing incorrect OSS returns each quarter.

The finance team has been burned by incorrect filings and needs to get things right for Q1. They need a proper VAT calculation module that applies the correct per-country standard and reduced rates depending on what type of product is in the cart, and a quarterly OSS return data generator that aggregates VAT collected by destination country. The team is particularly concerned about two things: that their book and food product lines get the reduced rates they're legally entitled to, and that their quarterly return numbers can be reconciled against the transaction database.

Output Specification

Produce the following files:

• eu-vat.js — A JavaScript module with at minimum:
• A calculateEUVAT({ order, customer, items }) function that returns VAT amounts per line item and total VAT for a given order
• A generateOSSQuarterlyData(year, quarter, transactions) function that accepts an array of tax transactions and aggregates them by destination country for OSS filing purposes
• eu-vat.test.js — Tests that verify:
• Correct VAT rates are applied for at least Germany, France, Italy, Spain, and the Netherlands
• Reduced rates are applied to qualifying product categories
• OSS quarterly aggregation groups data correctly by country
• vat-rates-reference.md — A reference document listing the standard and reduced VAT rates for each supported EU country, and which product categories qualify for reduced rates

The implementation should work with a JavaScript object representing the VAT rate table rather than making API calls (no external API keys are needed).

US Economic Nexus Tracker

Problem/Feature Description

A direct-to-consumer apparel brand called ThreadWell has been fulfilling orders from a single warehouse in Oregon for the past 18 months. They started small, but sales have been climbing steadily into states like California, Texas, New York, and the typical mix of smaller states. The finance team has just flagged that they've never properly tracked whether they've crossed economic nexus thresholds — the revenue and transaction volume levels at which a state can require you to collect and remit sales tax.

The stakes are high: if ThreadWell crossed thresholds without registering, they may already owe back taxes, interest, and penalties. The CTO needs a JavaScript/Node.js module that tracks cumulative sales and transaction counts per state per year, detects when thresholds are breached, and fires off alerts so the tax team can take immediate action before the situation gets worse. They also want early-warning alerts so they can prepare before a threshold is actually hit.

Output Specification

Produce the following files:

• nexus-tracker.js — A complete Node.js module implementing the economic nexus threshold tracking logic. The module should export at minimum a trackTowardThreshold(order, customer) function. You may use console.log or a stub sendEmail() in place of a real email service.
• nexus-tracker.test.js — Unit tests that verify threshold detection logic for at least California, Texas, New York, and the default case. Tests should verify both the sales threshold and transaction count threshold branches where applicable. You can use any standard test framework (e.g., Jest or plain assertions).
• README.md — A short explanation of how the threshold logic works, what states have custom thresholds, and what actions the system recommends when thresholds are approached or triggered.

The implementation should handle the case where an order arrives from a state where no nexus currently exists and correctly accumulate running totals over time.