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

By /
⏱ 6 min read

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.

See also: Stripe Interview Guide 2026: Process, Bug Bash Round, and Payment Systems

See also: Shopify Interview Guide

See also: Scale AI Interview Guide 2026: Data Infrastructure, RLHF Pipelines, and ML Engineering

Scroll to Top