US Sales Tax

Per-state nexus monitoring in the Recurso dashboard

Nexus and authoritative rates

After South Dakota v. Wayfair, US sales-tax obligations turn on nexus — you must register and collect in a state once you cross its threshold, and there are 45+ states each with its own numbers. Recurso handles the two hard parts:

Nexus monitoring — Recurso tracks your year-to-date taxable sales and transaction count in every state, shows how close you are to each state’s economic-nexus threshold, and auto-establishes economic nexus the moment you cross one, so a registration obligation never sneaks up on you.
Authoritative rates — US rates are jurisdiction-level (state + county + city + special districts), so exact rates come from a provider. Recurso integrates with both Avalara and TaxJar, and each tenant can bring their own account.

The US engine applies when the seller is US-based and the customer’s billing country is US (or unset). Buyers outside the US are invoiced with no US sales tax (tax_type: "export").

Recurso never guesses a rate. With no provider configured, US invoices carry 0% tax, explicitly marked sales_tax_stub — there are no silently wrong rates. And tax is collected only where you have nexus (see Nexus), so you never over-collect in a state you have no obligation in.

Choose a tax provider

Recurso resolves rates through a provider two ways — a platform default and a per-tenant bring-your-own connection. A tenant’s own connection always wins over the platform default.

Bring your own (per tenant)

Connect a tenant’s own Avalara or TaxJar account through the integrations API — credentials are encrypted at rest and used only for that tenant. This is also available in the dashboard under Settings → Integrations.

# Connect a tenant's TaxJar account
POST /v1/integration-connections
{
  "category": "tax",
  "provider": "taxjar",          // or "avalara"
  "config": { "api_key": "your_taxjar_token" }
}

# List connected integrations
GET /v1/integration-connections

# Disconnect
DELETE /v1/integration-connections/tax/taxjar

For Avalara, the config carries the account id, license key, and company code.

Platform default (environment)

For a single-tenant or self-managed deployment, configure one provider via the environment. TaxJar takes precedence if both are set:

.env

# Seller jurisdiction used by the tax engine
COMPANY_COUNTRY=US
COMPANY_STATE=CA

# Option A — TaxJar
TAXJAR_API_KEY=your_taxjar_api_token
# TAXJAR_API_URL=https://api.sandbox.taxjar.com   # sandbox for testing

# Option B — Avalara (used when TAXJAR_API_KEY is unset)
# AVALARA_ACCOUNT_ID=...
# AVALARA_LICENSE_KEY=...
# AVALARA_COMPANY_CODE=...
# AVALARA_API_URL=https://sandbox-rest.avatax.com   # sandbox for testing

On startup the API logs which mode it is in:

US sales tax: TaxJar provider enabled
# or
US sales tax: 0% stub (TAXJAR_API_KEY not set)

How rates are applied

At invoice time the engine sends the seller’s state and the buyer’s billing state + zip to the configured provider (Avalara or TaxJar) and applies the combined jurisdiction rate. Make sure your US customers have billing addresses with at least state and zip populated.

Rate caching

Lookups are cached in-memory for 24 hours per buyer (state, zip) pair. Sales-tax rates change rarely, so this keeps provider API spend proportional to the number of distinct buyer locations — not the number of invoices. The cache lives for the process lifetime; a restart clears it.

Error handling

Provider calls time out after 10 seconds and are retried once, and only on 5xx/network failures — auth errors (bad API key) and request-shape errors are never retried.
A provider failure never blocks invoice generation (see the matrix below).

Behavior Matrix

Every US invoice records how its tax was computed in tax_type:

`tax_type`	When	Rate applied	What it means
`sales_tax`	Provider configured, lookup succeeded	Live jurisdiction rate	The note names the provider and jurisdiction (e.g. `US sales tax via taxjar (CA)`). If the provider reports you have no nexus in the buyer’s state, tax is 0 and the note flags it honestly: `no nexus in buyer state per provider — nothing to collect`.
`sales_tax_exempt`	Buyer has a tax exemption on file	0%	The exemption number + entity-use code were passed to the provider, which returned 0 and recorded an exempt sale. Distinct from a no-nexus $0 line so the liability report can break exempt out. See Customer exemptions.
`no_nexus`	Buyer is in a US state you have not declared nexus in (and you’ve declared at least one)	0%	The native nexus gate: `No sales-tax nexus in <ST> — not collected`. Not an error — you’re correctly not collecting where you have no obligation. See Nexus Configuration.
`sales_tax_error`	TaxJar configured, lookup failed after the retry	0%	The invoice ships anyway — a tax lookup outage must never block billing. The note says `invoiced at 0% (needs review)` and a warning is logged. Treat these invoices as an audit queue: find them, recompute, and issue corrections.
`sales_tax_stub`	`TAXJAR_API_KEY` not set	0%	The historical placeholder behavior, honestly labeled. Fine for development; not for production US billing.
`export`	Buyer’s billing country is outside the US	—	No US sales tax on the sale.

sales_tax_error is deliberate honesty rather than a failure mode to hide: Recurso chooses “invoice now at 0%, flag for review” over “block the billing run”. Monitor for it (the API logs a warning per occurrence) and review flagged invoices promptly.

Nexus Configuration

Recurso models nexus natively: you declare the US states where you’re registered to collect sales tax, and Recurso collects only there. A sale to a buyer in a state you haven’t declared is invoiced at 0% with an auditable note — No sales-tax nexus in <ST> — not collected (tax_type: no_nexus). Manage your nexus states with the settings endpoints (owner/admin for dashboard users; API keys always pass):

# List your declared nexus states
GET /v1/settings/tax/nexus

# Replace the full set (this is a full replacement, not a merge)
PUT /v1/settings/tax/nexus
{
  "states": [
    { "state_code": "CA", "nexus_type": "physical" },
    { "state_code": "NY", "nexus_type": "voluntary" }
  ]
}

nexus_type is physical (office / employees / inventory), voluntary (registered by choice), or economic (a threshold was crossed — see below); it defaults to physical.

How the native gate interacts with TaxJar

Native nexus and the provider are both gates — a sale is taxed only where both allow it:

You’ve declared at least one nexus state: Recurso collects only in your declared states; buyers elsewhere get no_nexus (0%). Where you do have nexus, TaxJar (if configured) computes the exact rate — and can still independently return 0% for a specific exempt address (no nexus in buyer state per provider).
You’ve declared no nexus states: the native gate is off for backward compatibility — tax falls through to TaxJar’s own nexus configuration (or the 0% sales_tax_stub if TaxJar isn’t configured). This is the pre-nexus behavior.

So a declared state is necessary to collect, and the provider can still exempt a specific address — Recurso never collects where you haven’t declared nexus.

Beyond manually declared physical / voluntary nexus, Recurso tracks economic-nexus thresholds ($100k / 200 transactions, varying by state) from your year-to-date sales and transaction counts, and auto-establishes economic nexus when you cross one. Monitor per-state proximity with GET /v1/settings/tax/nexus/status — see the US sales tax setup tutorial and the nexus status endpoint.

The seeded threshold dataset self-reports dataset_certified: false until it passes professional review. While it’s false, treat threshold crossings as indicative — confirm each state’s current rule with a tax professional before relying on it for a filing or registration decision.

Threshold alerts

Recurso doesn’t just establish economic nexus on a crossing — it tells you. A daily job emails your workspace owner/admin when a state’s year-to-date activity approaches (≥80% of the threshold) and again when it crosses, so a registration obligation never passes unnoticed. Each state+level is alerted at most once per calendar year (a state that stays crossed isn’t re-alerted daily), and the alert carries the state’s YTD sales, transactions, and the threshold.

“Crossed” alerts fire only for economic nexus established this calendar year — an already-established state isn’t re-alerted every January. Declared physical/voluntary nexus is never alerted (you set it yourself).

Customer exemptions

A tax-exempt customer (resale, government, non-profit) carries an exemption on their record: an exemption certificate number and a provider entity-use code (e.g. Avalara A = federal government). Set it in the dashboard on the customer, or via the API:

PUT /v1/customers/{id}
{ "tax_exempt": true, "tax_exemption_number": "RESALE-0001", "tax_exemption_code": "A" }

At invoice time the exemption is passed through to Avalara/TaxJar rather than short-circuited: the provider returns zero tax and records an exempt sale on its side. The invoice line is marked sales_tax_exempt (distinct from a no-nexus $0 line), so exempt sales are unambiguous in your liability report and audit trail. Exempt lookups bypass the jurisdiction rate cache, so one exempt buyer never affects another’s rate.

Liability report

GET /v1/settings/tax/liability returns per-state figures for a filing period — gross sales, taxable, exempt, and non-taxable (no-nexus / below-threshold) sales, tax collected, invoice count, and whether you have nexus in each state. The three sale buckets partition gross, and a state collecting tax without declared nexus is surfaced.

# Current calendar year (default), or ?year=YYYY, or ?from=YYYY-MM-DD&to=YYYY-MM-DD
curl "https://api.recurso.dev/v1/settings/tax/liability?year=2026" \
  -H "Authorization: Bearer $API_KEY"

The dashboard renders this on the US sales-tax page (Settings → Tax nexus) with a year selector and totals.

Registrations

Nexus tells you where you must collect; registrations record where you actually can. Track a registration number and status (registered / pending / not_registered) per state:

GET /v1/settings/tax/registrations
PUT /v1/settings/tax/registrations
{ "registrations": [ { "state_code": "CA", "registration_number": "CA-123", "status": "registered" } ] }

The dashboard flags the gap that matters: states where you have nexus but no registration on file — the compliance dots to connect before you file.

Testing

Point TAXJAR_API_URL at TaxJar’s sandbox to test the full path without live rates:

.env

TAXJAR_API_KEY=your_sandbox_token
TAXJAR_API_URL=https://api.sandbox.taxjar.com

Then create a US customer with a full billing address and generate an invoice — the invoice’s tax_type should be sales_tax.

Other Jurisdictions

Seller country	Engine	Docs
India	GST (CGST/SGST/IGST)	GST Invoicing
EU / UK	VAT (reverse charge, exports)	—
US	Sales tax (this page)	—

US tax identity settings — US tax identity (W-9) in Settings

Get Started

Migrate to Recurso

Core Concepts

Usage & Monetization

Money & Books

Tax & Compliance

Recover & Retain

Customer Portal

Platform & Integrations

Deploy & Operate

Reference

Nexus and authoritative rates

Choose a tax provider

Bring your own (per tenant)

Platform default (environment)

How rates are applied

Rate caching

Error handling

Behavior Matrix

Nexus Configuration

How the native gate interacts with TaxJar

Threshold alerts

Customer exemptions

Liability report

Registrations

Testing

Other Jurisdictions

​Nexus and authoritative rates

​Choose a tax provider

​Bring your own (per tenant)

​Platform default (environment)

​How rates are applied

​Rate caching

​Error handling

​Behavior Matrix

​Nexus Configuration

​How the native gate interacts with TaxJar

​Threshold alerts

​Customer exemptions

​Liability report

​Registrations

​Testing

​Other Jurisdictions

Nexus and authoritative rates

Choose a tax provider

Bring your own (per tenant)

Platform default (environment)

How rates are applied

Rate caching

Error handling

Behavior Matrix

Nexus Configuration

How the native gate interacts with TaxJar

Threshold alerts

Customer exemptions

Liability report

Registrations

Testing

Other Jurisdictions