Tax Module Technical Specifications
across engine, providers, and configuration — 5 postal code strategies + ReDoS protection, 3 external providers, compound/inclusive tax math, seasonal holidays, and 3 configurable building blocks (rates, classes, exemptions).
System Metrics
Core calculation engine
compound, inclusive, and threshold-aware tax math
Test coverage
every calculation branch covered by automated tests
Built-in external providers
3
Starter data
pre-loaded rates and classes for common jurisdictions
Configurable building blocks
3 (tax rates, tax classes, exemption certificates)
Postal code strategies
5 (exact, prefix, range, regex, list)
External providers
3 (API Ninjas 50K/mo free, ZipTax, TaxJar)
Tax types
sales, vat, gst, excise, custom
Jurisdiction analytics
tax collected + transaction counts, grouped by country/state
Architecture Overview
| Component | Responsibility |
|---|---|
| Checkout integration | Hooks into commerce checkout and billing subscription renewal automatically |
| Calculation engine | Core tax computation pipeline — rates, classes, exemptions, compound/inclusive math |
| Test coverage | Every calculation branch covered by automated tests |
| Provider adapters | External provider integrations (API Ninjas, ZipTax, TaxJar) |
| Starter data | Pre-loaded rates and classes for common jurisdictions |
| Configuration model | Tax Classes (product categories), Tax Rates (jurisdiction rates), Exemption Certificates (customer records) |
Tax Engine — Core Calculation
| Field | Purpose |
|---|---|
| `items` | Line items — unit price (in cents), quantity, product tax class |
| `shippingAddress` | Country, state, county, city, postal code — used for jurisdiction lookup |
| `billingAddress` | Optional, for split billing/shipping scenarios |
| `customerId` | Used to look up exemption certificates |
| `orderAmount`, `shippingAmount`, `discountAmount` | Order totals, in cents |
| `transactionDate` | Ensures the right rate is used for effective-dated and seasonal rates |
| Field | Purpose |
| ------------------------- | ------------------------------------------------------------------------------------------- |
| `adjustments` | Every individual tax line applied (e.g., "CA State" 7.25%, "LA County" 2.25%) |
| `totalTax`, `shippingTax` | Tax totals, in cents |
| `itemTaxes` | Per-item breakdown with effective rate |
| `exemptionsApplied` | Which exemptions fired, and how much they exempted |
| `summary` | Subtotal, total tax, grand total, and effective rate (e.g., 8.875% for a combined NYC rate) |
Rate Matching — Priority & Specificity
| Match type | Weight |
|---|---|
| State | +1 |
| County | +2 |
| City | +4 |
| Postal code (any strategy other than "any") | +8 |
Postal Code Matching — 5 Strategies
| Strategy | Behavior |
|---|---|
| `any` | Matches every postal code in the jurisdiction (wildcard) |
| `exact` | Matches a single postal code |
| `prefix` | Matches everything starting with a given prefix (e.g., "902" for a region) |
| `range` | Matches a numeric range of codes |
| `list` | Matches against an explicit list of codes |
| `regex` | Matches a custom pattern, with ReDoS protection (below) |
Compound & Inclusive Tax Math
How compound tax is applied:
Each applicable rate is evaluated in order. A rate is skipped if it doesn't apply to the item's tax class, or if the order falls outside a configured minimum/maximum order-value threshold. Otherwise the tax is computed on the running amount, optionally capped at a maximum per-item tax amount.
The key detail for compound jurisdictions: when a rate is marked compound, its tax is added back into the base amount before the next rate is calculated — so county tax is computed on (subtotal + state tax), and city tax is computed on (subtotal + state + county tax). That's how a $100 sale in Los Angeles correctly comes out to $11.30 in tax (an 11.30% effective rate) instead of a flat 11.00%.
Inclusive (VAT-style) pricing:
When a rate is marked inclusive, the listed price already contains the tax. A $120 gross price with 20% VAT nets out to $100 (net) + $20 (tax) — computed as gross ÷ (1 + rate).
External Provider Integration
How provider fallback works:
If a tenant has an external rate provider configured, it's tried first for the shipping address. If the provider returns usable rates, those are used immediately. If the provider is unreachable or returns nothing, the calculation falls through to local rate tables automatically — customers never see a failed checkout because of a third-party outage.
API Ninjas (50,000 free calculations/month):
US-only live rate lookups by ZIP code, returning the combined rate for the address. Beyond the free tier, usage is billed at roughly $0.002/request. A CSV bulk-import path from API Ninjas' rate tables is also available as a zero-API alternative.
TaxJar (fallback provider):
Returns TaxJar's combined rate (state + county + city) for an address — for tenants who want TaxJar-sourced accuracy without routing every calculation through TaxJar's per-call billing.
Tax Rates, Classes & Exemption Certificates — What You Configure
Three building blocks make up the tax model:
Tax Rates — one record per jurisdiction rate (e.g., "California State Tax," "LA County Tax"):
- Jurisdiction: country, state, county, city
- Postal-code targeting: one of the five strategies above
- Rate (percentage) and tax type (sales / VAT / GST / excise / custom)
- Product scope: applies to all products, or only/except specific tax classes
- Compound and inclusive flags
- Shipping taxability, with an optional override rate
- Order-value thresholds and a per-item tax cap
- Effective-date range and optional seasonal (date-range) activation
- Priority, for resolving overlapping rates
- Running totals — how many times the rate has been applied and total tax collected, which power nexus tracking
Tax Classes — product tax categories (e.g., "clothing," "groceries," "digital downloads"):
- Code and display name
- Default treatment (taxable / exempt / reduced)
- Per-jurisdiction rule overrides — a class can be exempt in Texas, partially exempt above a threshold in Pennsylvania, and seasonally exempt in Minnesota, all on the same record
- Optional rate override, exemption percentage/amount, and effective or seasonal dates per rule
Exemption Certificates — per-customer tax-exempt status:
- Customer reference and exemption type (resale, government, nonprofit, industrial, other)
- Geographic scope (all jurisdictions, or specific states/countries)
- Product scope (all products, or specific tax classes)
- Full or partial exemption (percentage or fixed exempt amount)
- Certificate number, uploaded document, issuing authority
- Expiration handling, with renewal reminders before the certificate lapses
Jurisdiction Analytics
Tax collected, by state:
Every tax rate carries its own usage counters — how many times it's been applied and how much tax it's collected. A dedicated analytics endpoint groups those counters by country and state, surfacing tax collected and transaction count per jurisdiction in a single call.
What this is useful for:
Economic nexus thresholds are set individually by each state (a revenue amount, a transaction count, or both) and change over time, so Aeion Tax doesn't hardcode or auto-enforce them for you. The jurisdiction breakdown gives your finance team the per-state numbers they need to evaluate their own nexus exposure against whatever thresholds currently apply, rather than exporting raw order data and reconstructing it by hand.
Key Architecture Decisions
Rates storage
Local storage (bring-your-own) — Zero per-calculation cost, full control
Provider fallback
Try external first, local as backup — Best of both: live rates when configured, zero-cost local otherwise
Compound tax
Accumulative base amount — Real-world: county tax on (subtotal + state tax), city on (subtotal + state + county)
Inclusive tax
Gross ÷ (1 + rate) — VAT standard: divide gross by (1 + rate) to get net
Postal regex
Safe regex with whitelist — ReDoS protection: block exponential patterns, limit length to 100 chars
Exemption check
Per-item, per-jurisdiction — Full exemptions bypass all taxes. Partial exemptions apply percentage or fixed amount
Seasonal dates
Month/day span check — Handles same-year and year-boundary spans (Nov-Jan)
Adjustment traceability
Every returned adjustment is self-describing — jurisdiction, rate, exemptions applied, and effective rate, enough to reconstruct how the total was reached