Tax Calculation Service Low-Level Design: Jurisdiction Detection, Rate Lookup, and Compliance Reporting

Tax Service Components

A production tax calculation service has five distinct responsibilities: nexus determination (does the business owe tax in this jurisdiction?), jurisdiction detection (which tax authorities apply to this transaction?), product taxability classification (is this item taxable?), rate lookup (what rate applies?), and compliance reporting (what do we file with each authority?). Conflating these concerns is the most common source of tax engine bugs.

Jurisdiction Detection

The ship-to address is geocoded to geographic coordinates, then mapped to overlapping tax jurisdictions. In the United States, a single address can fall under up to four simultaneous jurisdictions:

State (e.g., California)
County (e.g., Los Angeles County)
City (e.g., City of Los Angeles)
Special district (e.g., transit district, stadium district)

Each jurisdiction has its own rate and its own rules about what is taxable. The jurisdictions are stored as a polygon database (from the Census Bureau or a commercial provider) and queried by point-in-polygon lookup.

Nexus Determination

A business is only obligated to collect tax in states where it has nexus — a sufficient connection to that state. Two nexus types exist:

Physical nexus: office, warehouse, employees, or inventory in the state
Economic nexus: post-Wayfair rule — exceeding $100,000 in sales or 200 transactions in a state in a calendar year triggers obligation even without physical presence

Nexus status is maintained per state and recomputed when sales thresholds are approached. Transactions in non-nexus states are recorded but no tax is collected.

Product Taxability Classification

Tax treatment varies by product category and jurisdiction:

Clothing under $110 per item is exempt in New York State
Unprepared food is exempt in most states; prepared food is taxable
Digital goods (ebooks, SaaS) are taxable in some states and exempt in others
Prescription drugs and medical devices are generally exempt

Each product is assigned a tax code (similar to Avalara's product tax codes). The taxability matrix maps (tax_code, jurisdiction_id) to a taxability flag and any applicable exemptions. This matrix is the most maintenance-intensive part of the system — it changes whenever legislation changes.

Rate Lookup

Given a jurisdiction and a product tax code, the rate lookup returns the applicable combined rate for a given effective date:

SELECT rate FROM jurisdiction_rates
WHERE jurisdiction_id = ? AND tax_code = ?
AND effective_date <= ? ORDER BY effective_date DESC LIMIT 1

Rates are sourced from a commercial provider (Avalara, TaxJar, Vertex) or maintained in-house from legislative feeds. New rates are loaded with a future effective_date before they take effect. Historical rates are never deleted — they are needed to recalculate tax on amended returns.

Calculation

For each overlapping jurisdiction, calculate tax independently then sum:

tax_amount = ROUND(taxable_amount * rate, 2)

Rounding is applied per-jurisdiction per-line-item, not on the total. The IRS and most state authorities specify rounding rules; the most common is round-half-up to two decimal places.

Tax-Inclusive vs Tax-Exclusive

Two pricing models:

Tax-exclusive: displayed price does not include tax; tax added at checkout. tax = price * rate
Tax-inclusive: displayed price includes tax (common in EU VAT). Back-calculate: tax = price - (price / (1 + rate))

The mode is stored per price list and must be consistent across the calculation.

Marketplace Facilitator Laws

Over 40 US states now require marketplace platforms to collect and remit tax on behalf of third-party sellers. The platform is the marketplace facilitator. In facilitator states, tax is calculated on the gross sale price and remitted by the platform, regardless of whether the individual seller has nexus in that state. This significantly simplifies seller compliance but requires the platform to track facilitator obligations separately from its own direct sales.

Compliance Reporting

Monthly and quarterly, the service generates file-ready reports per state:

Gross sales by jurisdiction
Taxable sales by jurisdiction
Tax collected by jurisdiction
Exempt sales with exemption reason codes

These reports are pre-formatted for state e-file systems. The reporting query aggregates the transaction audit log — never the live rate tables — to ensure reports reflect the rates that were actually applied.

Audit Trail

Every tax calculation is stored with full detail: jurisdiction IDs used, rate applied per jurisdiction, taxability flag, calculation basis, and the rate table version. Retention is seven years minimum. This data is the primary defense in a state audit — you must be able to reproduce the exact calculation for any past transaction.

{
“@context”: “https://schema.org”,
“@type”: “FAQPage”,
“mainEntity”: [
{
“@type”: “Question”,
“name”: “How do you detect the correct tax jurisdiction for a transaction in a multi-country e-commerce platform?”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “Jurisdiction detection depends on the transaction type and legal nexus rules. For physical goods, use the shipping destination address — parse it into country, state/province, county, and city, then look up which tax authorities have jurisdiction over that location (e.g., US sales tax is origin- or destination-based per state). For digital goods and SaaS, most jurisdictions tax based on the buyer's location, so resolve the buyer's country from the billing address, falling back to GeoIP. Store a jurisdiction_code per transaction derived from a geo-to-jurisdiction mapping table (updated from providers like Avalara or TaxJar, or from official government data). Cache jurisdiction lookups aggressively since they are read-heavy and change infrequently, but invalidate on known rule-change effective dates.”
}
},
{
“@type”: “Question”,
“name”: “How should a tax rate lookup service be architected to handle rate changes without requiring code deploys?”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “Store tax rates in a database table with columns: jurisdiction_code, product_tax_category, rate, effective_from, effective_to. To look up the rate applicable on a given transaction date, query WHERE jurisdiction_code = ? AND product_tax_category = ? AND effective_from txn_date). This schema allows rate changes to be inserted as new rows with future effective dates — no deploy needed, and historical recalculations use the rate that was active at the original transaction time. Product tax categories (standard, reduced, exempt, zero-rated) must be assigned per SKU in the product catalog so the lookup can vary by item type within the same cart.”
}
},
{
“@type”: “Question”,
“name”: “What data must a tax service record at transaction time to satisfy audit and compliance reporting requirements?”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “At the moment a taxable transaction settles, snapshot and persist: the jurisdiction code, the tax rate applied, the taxable amount, the calculated tax amount, the product tax category, the buyer's address used for jurisdiction detection, and the effective date of the rate. Never rely on recomputing these from current rates later — rates change and auditors need the figures that were accurate at transaction time. Also store the tax rule version or provider response ID if using an external tax engine (Avalara, TaxJar) so you can reproduce the calculation. Generate periodic tax remittance reports grouped by jurisdiction and filing period (monthly, quarterly) that sum collected tax, net of any refunds, to produce the remittance amount due.”
}
},
{
“@type”: “Question”,
“name”: “How do you handle tax on refunds and partial refunds in a tax service?”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “A refund must reverse the tax proportionally. For a full refund, create a negative tax entry referencing the original transaction's tax record, using the same rate and jurisdiction that was applied at sale time — do not recalculate at the current rate. For a partial refund of amount R on an original taxable amount T with tax X, the refunded tax is X * (R / T). Store the refund tax entry linked to both the original tax record and the refund transaction. Update the jurisdiction's remittance balance by subtracting the refunded tax from the next filing period. If the refund crosses a filing period boundary (original sale in Q1, refund in Q2), apply the credit to Q2's remittance — do not amend the Q1 filing unless legally required in that jurisdiction.”
}
}
]
}