TaxHacker Tax Scenarios: Inclusive, Exclusive, and VAT Calculations Explained

TaxHacker supports both inclusive and exclusive tax calculations, unlimited custom taxes with arbitrary names and rates, dedicated VAT fields for automated reporting, and tax-ready CSV exports suitable for professional tax advisors.

The open-source TaxHacker repository (vas3k/TaxHacker) provides a flexible invoicing system designed for freelancers and small businesses navigating complex tax requirements. Whether you need to handle VAT-registered transactions in the EU, apply multiple jurisdictional sales taxes, or generate compliant reports for quarterly filings, the codebase implements comprehensive tax logic through first-class data structures attached to every transaction.

Inclusive vs Exclusive Tax Calculations

TaxHacker handles two fundamental tax models through the taxIncluded boolean flag in the invoice configuration. According to the source code in app/(app)/apps/invoices/components/invoice-page.tsx, the calculateTotal() function branches based on this flag to either treat the subtotal as the final amount or append additional taxes on top.

When taxIncluded is set to true, the system assumes the displayed price already contains tax, and the calculateTotal() method returns the subtotal directly without adding additionalTaxes. Conversely, when taxIncluded is false, the function sums all entries in the additionalTaxes array and adds them to the subtotal.

Creating an Inclusive Tax Invoice

For transactions where the price already includes tax, such as B2C sales in VAT-inclusive jurisdictions:

// app/(app)/apps/invoices/components/invoice-page.tsx (simplified)
const formData = {
  title: "Website redesign",
  invoiceNumber: "#001",
  taxIncluded: true,                     // Tax is already in the subtotal
  additionalTaxes: [],
  items: [{ name: "Design work", quantity: 1, unitPrice: 500, subtotal: 500 }],
};

The calculateTotal() implementation returns the subtotal unchanged:

const calculateTotal = () => {
  const subtotal = calculateSubtotal();   // 500
  const taxes = calculateTaxes();         // 0
  return data.taxIncluded ? subtotal : subtotal + taxes;
}; // → 500

Adding Exclusive Taxes

For B2B transactions or jurisdictions requiring tax-added pricing:

const formData = {
  taxIncluded: false,                    // Tax added on top
  additionalTaxes: [
    { name: "VAT", rate: 20, amount: 100 },
    { name: "Sales Tax", rate: 5, amount: 25 },
  ],
  items: [{ name: "Design work", quantity: 1, unitPrice: 500, subtotal: 500 }],
};

This configuration results in a total of 625 (500 + 100 + 25), with the tax breakdown preserved in the invoice data.

Multiple Custom Taxes with Arbitrary Rates

The system supports unlimited additional tax lines through the additionalTaxes array, defined as an array of { name, rate, amount } objects. As implemented in app/(app)/apps/invoices/components/invoice-generator.tsx, you can attach any number of tax lines—whether VAT, GST, state sales tax, or custom digital services taxes—each with distinct percentage rates and calculated amounts.

This flexibility allows freelancers operating across multiple jurisdictions to itemize local, state, and federal taxes on a single invoice without hardcoded tax categories.

Built-in VAT Fields and Automated Reporting

TaxHacker provides dedicated VAT fields through the DEFAULT_FIELDS configuration in models/defaults.ts. Every transaction automatically includes vat_rate (percentage) and vat (absolute amount) fields, which the AI system can auto-populate during transaction creation.

For VAT-registered businesses, the landing page (app/landing/landing.tsx) advertises Monthly or quarterly VAT reports, indicating a built-in reporting pipeline that aggregates these fields for compliance submissions. The fields integrate seamlessly with the transaction model:

// Using built-in VAT fields (auto-filled by AI)
const transaction = await createTransaction(userId, {
  name: "Hosting fee",
  total: 120,
  vat_rate: 20,            // Percentage
  vat: 20,                 // Absolute amount
});

Tax-Ready CSV and PDF Exports

Every exported document includes comprehensive tax columns suitable for professional tax advisors. The invoice-pdf.tsx component renders tax rows explicitly in generated documents, while the CSV export functionality serializes all tax-related fields—including vat_rate, vat, and the JSON-encoded additionalTaxes array—into downloadable spreadsheets.

// Export button triggering tax-ready CSV download
<button onClick={() => download('/api/export/transactions', 'tax-data.csv')}>
  Export CSV (tax-ready)
</button>

This export capability ensures that freelancers can hand complete tax breakdowns to accountants without manual data re-entry.

Summary

• TaxHacker supports both inclusive and exclusive tax models via the taxIncluded flag in invoice-page.tsx, determining whether taxes are absorbed into the displayed price or added as separate line items.
• Unlimited custom taxes can be defined through the additionalTaxes array with arbitrary names, rates, and amounts.
• Dedicated VAT fields (vat_rate and vat) are included by default in every transaction and support automated AI population.
• Tax-ready exports in CSV and PDF formats include full tax breakdowns suitable for professional accounting and VAT reporting.

Frequently Asked Questions

Does TaxHacker support VAT reporting for EU freelancers?

Yes. The codebase includes dedicated vat_rate and vat fields in models/defaults.ts that appear on every transaction, and the landing page explicitly lists "Monthly or quarterly VAT reports" as a feature. The exported CSV files contain these columns in a format suitable for EU VAT return submissions.

Can I add multiple taxes to a single invoice, such as VAT plus local sales tax?

Yes. The additionalTaxes array in app/(app)/apps/invoices/components/invoice-generator.tsx accepts an unlimited number of tax objects. Each entry specifies a name, rate (percentage), and amount (calculated value), allowing you to combine VAT, GST, state tax, or any jurisdiction-specific levy on one invoice.

What is the difference between inclusive and exclusive tax calculation in TaxHacker?

Inclusive tax means the displayed price already contains tax; when taxIncluded is true, the calculateTotal() function in invoice-page.tsx returns the subtotal without adding additional taxes. Exclusive tax means tax is calculated on top; when taxIncluded is false, the system sums all additionalTaxes and adds them to the subtotal to compute the final amount.

Is there a limit to how many custom tax rates I can define per transaction?

No. The additionalTaxes field is implemented as an unbounded array in the invoice data structure. You can define as many custom tax lines as your jurisdiction requires, each with unique names and percentage rates.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}