Calculate API

Net Amount Calculate turns a cart, quote, invoice, refund draft, credit memo, void, or adjustment into sales-tax, seller-use-tax, or purchaser-use-tax amounts with jurisdiction components, warning metadata, and a source-aware rule trace. It extends the lookup API; it does not replace GET /lookup or POST /lookup.

The runtime rule is simple: tax decisions must come from effective-dated rule rows or imported commodity taxability data. MVP seed assumptions are not production calculation inputs. If a tax code, jurisdiction, charge type, exemption, marketplace outcome, threshold, cap, holiday, reduced rate, or local override is not modeled, the API returns an explicit error or warning instead of guessing.

Endpoints

/v1/tax/* and /v1/transactions* require Authorization: Bearer <key> or X-Api-Key when billing is enabled. Calculate traffic uses the separate calculate usage meter; lookup traffic continues to use the existing lookup quota.

Setup Requirements

Database-backed Calculate requires the billing schema and the full calculate migration chain. Apply bun run db:migrate:calculate only after you confirm the intended database target; the migration scripts use DATABASE_DIRECT_URL ?? DATABASE_URL, so remote or shared targets should be explicitly approved before migration.

After migration, run the source audit:

bun run audit:calculate-rule-sources -- --as-of 2026-06-29

Audit errors are blockers. Active needs_review rows remain warning-gated coverage. They are useful for QA and review, but they are not legal or tax advice and should not be treated as reviewed Calculate coverage until promoted from source-backed review.

For a live runner check against a migrated database, start the API with TAX_DATA_SOURCE=database and point the scenario pack at it:

BILLING_ENABLED=false PORT=8788 TAX_DATA_SOURCE=database bun run dev:api
NET_AMOUNT_BASE_URL="http://localhost:8788" NET_AMOUNT_SCENARIO_ENVIRONMENT="test" \
  bun qa/calculate-scenarios/tools/run-scenarios.ts --scenarios qa/calculate-scenarios/scenarios

NET_AMOUNT_SCENARIO_ENVIRONMENT=test sends X-NetAmount-Environment: test with live fixture requests.

Calculate

curl http://localhost:8787/v1/tax/calculate \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $NET_AMOUNT_API_KEY" \
  --data '{
    "transaction": {
      "type": "sale",
      "document_code": "ORDER-10001",
      "transaction_date": "2026-05-31",
      "currency": "USD",
      "tax_behavior": "exclusive",
      "tax_obligation": "sales_tax",
      "commit": false
    },
    "seller": {
      "registrations": [
        { "state": "CO", "status": "registered", "effective_from": "2024-01-01" }
      ]
    },
    "addresses": {
      "ship_to": {
        "line1": "200 E Colfax Ave",
        "city": "Denver",
        "state": "CO",
        "postal_code": "80203",
        "country": "US",
        "lat": 39.7392,
        "lon": -104.9903
      }
    },
    "amounts": {
      "order_discount_amount": 0,
      "order_discount_type": "seller_discount",
      "shipping_amount": 0,
      "freight_amount": 0,
      "handling_amount": 0,
      "gift_wrap_amount": 0
    },
    "discounts": {
      "reimbursement_status": "unknown",
      "documentation": "unknown",
      "allocation_method": "proportional"
    },
    "charges": {
      "shipping": {
        "separately_stated": true,
        "bundled": false,
        "billed_by": "unknown",
        "common_carrier": false,
        "allocation_method": "none",
        "allocation_evidence_retained": false,
        "actual_cost_amount": null
      }
    },
    "line_items": [
      {
        "line_id": "1",
        "quantity": "1",
        "unit_amount": 10000,
        "tax_code": "commodity.01",
        "bundle": {
          "type": "none",
          "allocation_method": "proportional",
          "components": []
        }
      }
    ]
  }'

Supported transaction types are sale, quote, invoice, refund, credit_memo, void, and adjustment. transaction.tax_obligation supports sales_tax (the default), seller_use_tax, and consumer_use_tax. Sales obligations prefer explicit Sales rate rows, while both use-tax obligations prefer explicit Use rate rows; combined Sales-and-Use rows are a visible fallback. Distinct Sales and Use rates are selected independently rather than treated as conflicting duplicates.

seller_use_tax retains the normal seller/marketplace nexus and collection workflow. consumer_use_tax is purchaser self-assessment: it bypasses seller nexus, returns collection.liable_party:"purchaser", reports the amount under purchaser_use_tax_due_amount, leaves seller/customer-collected and remittance amounts at zero, and does not add the self-assessed tax to summary.total_amount. Use-tax sourcing prefers line_items[].fulfillment.use_location, then addresses.use_location; if neither is supplied, it uses the delivery destination and emits USE_TAX_LOCATION_FALLBACK. Consumer-use requests accept exclusive purchase prices only. Use-tax requests for seller-business-tax regimes whose separate use-tax model is not yet encoded fail with unsupported_tax_obligation_for_regime instead of treating GET, GRT, TPT, or gross-receipts rates as Use rates.

Supported collection behaviors are exclusive, inclusive, not_collecting, and reverse_calculate. Money fields are integer minor units, quantities are decimal strings, and jurisdiction rates are returned as decimal strings plus integer rate_micros.

Successful single-request Calculate calls return a response with status:"succeeded" and a non-empty calculation_id. With continue_on_error=true, batch requests can return HTTP 207 and status:"partial_failure" when at least one request succeeds and another fails. Batch calculate is draft-only and rejects requests where any calculation has transaction.commit=true with error.code:"committed_batch_not_supported"; committed records should use single-request Calculate or POST /v1/transactions. Replay responses include original_calculation_id, original_request_hash, replayed_at, and a nested response object.

Rule Coverage

Imported commodity codes such as commodity.01 and commodity.05.110 are resolved from tax_taxability_rules rows imported from ../Net Amount-Data/product-taxability/data.json. Those rows are state scoped, effective dated, traceable, and marked needs_review, so responses include a warning until source review promotes the row. Product and matrix refreshes preserve already reviewed rows, and runtime selection prefers reviewed matching rules over newer unreviewed rows unless a future active rule set explicitly changes that policy.

physical_goods.general has source-backed state baseline rows when the full calculate migration chain has been applied. Local overrides can be modeled with jurisdiction-scoped rows, including JSON scopes such as place_id or jurisdiction_type; when an override differs from the state rule, Calculate applies it to the affected jurisdiction components instead of only adding warning text. Digital goods, services, SaaS, software, food, clothing, drugs, books, and state-specific coupon or bundle outcomes still require reviewed rule rows before unsupported coverage should be trusted. Use /v1/tax/coverage and /v1/tax/codes/{tax_code} to see exactly what is modeled.

Rule result_json can model non-binary outcomes when the row is effective and source-reviewed: rate_micros, rate, or rate_multiplier for reduced rates; taxable_percentage for partial taxability; taxable_amount_cap for taxable caps or price thresholds; and holiday metadata such as holiday_name plus effective windows. These outcomes are applied at the jurisdiction-component level, so a state component can use a reduced rate while local components remain taxable at their normal rates. Reduced rows without explicit rate metadata remain unsupported instead of being flattened into ordinary taxable behavior.

Calculate responses include data_version.rules_version and data_version.rule_versions so committed results can identify the active rule/data version marker used alongside the rate and boundary sources.

State summary/sourcing responses can be imported into tax_state_guidance and read from /v1/tax/states/{state_code}. These rows store normalized sourcing, filing, rate, summary, source-link, and raw payload fields as needs_review guidance. They do not become calculation rules until reviewed and promoted into the rule tables.

Tax Regimes

Calculate includes tax_regime metadata on the response, every line, every order charge, and jurisdiction components when tax is calculated. The metadata distinguishes ordinary customer-collected sales/use tax, purchaser-self-assessed use tax, local-only sales/use tax, seller business taxes that may be passed through, GET/GRT/TPT-style regimes, and no-general-sales-tax states. tax_obligation, collection.collection_model, customer_collected, seller_business_tax, and pass_through_allowed are also returned so callers do not have to infer the legal tax model from a numeric amount.

Source-backed regime metadata is currently modeled for Hawaii GET, New Mexico GRT, Arizona TPT, Delaware gross receipts/no sales tax, Alaska local sales/use tax, Oregon no general sales/use/transaction tax, Montana no general-use sales tax with special/local tax review, and New Hampshire no general sales tax. Non-standard or local-only regimes continue to emit warning codes such as GROSS_RECEIPTS_TAX_MODEL, LOCAL_TAX_REVIEW_REQUIRED, or NO_STATEWIDE_SALES_TAX_REVIEW unless the reviewed source supports exact customer-collected treatment for the request.

Sourcing And Nexus

Calculate supports destination, origin, pickup, seller delivery, common carrier, digital delivery, service location, and performance location sourcing as request shapes. Reviewed tax_sourcing_rules rows are evaluated before taxability and rate lookup, so a rule can route a line to destination, origin, pickup, bill-to/receipt, seller business location, performance/service location, seller records, address obtained during the sale, line ship-from, supplier ship-from, direct-mail, lease/rental, or drop-ship facts. If no row resolves, Calculate falls back to the request fulfillment.type route and emits review warnings for incomplete sourcing categories.

Line fulfillment can include sourcing evidence fields such as ship_from, ship_to, supplier_ship_from, receipt_location, service_location, use_location, business_records_address, address_obtained_during_sale, drop_ship, direct_mail, and lease_or_rental. Responses include sourcing evidence on the order, every line, and every order charge: source_type, jurisdiction_address, source_ref, address_source_ref, reason_code, facts, and the resolved rule when rule-backed sourcing was used.

Effective July 11, 2026, reviewed common-carrier destination rows cover ordinary general physical goods in New York, New Jersey, and Washington for sales, quotes, and invoices. They require a known ship-to address and exclude drop shipments, direct mail, leases/rentals, supplier-ship-from and receipt-location facts, use-tax first-use sourcing, and special property families. Pickup, seller delivery, vehicles, florists, transportation equipment, lifecycle documents, and fallback-address hierarchies remain warning-gated until their own reviewed rows exist.

Economic nexus is not silently inferred. With registered_only, seller collection can come from an active state registration in the request or a stored seller nexus profile resolved by billable entity, seller.seller_id, and seller.nexus_profile_id. Stored profiles read seller locations, registration effective dates, physical-presence metadata, marketplace-sales threshold treatment, and seller-provided remote-seller threshold status. When tax_economic_nexus_rules and tax_seller_economic_nexus_history rows provide reviewed threshold and seller-history facts, Calculate evaluates strict versus inclusive threshold comparisons, any versus all tests, current-transaction inclusion, state-scoped current sales, activity freshness, crossing-date provenance, and explicit collection-start timing. Current line activity is assigned only after final reviewed sourcing and address resolution, while order charges follow the final order destination, so preview ship-to facts cannot move a threshold decision to the wrong state. The before/current/after evidence is returned under liability.basis.economic_nexus_threshold; seller-reported threshold status alone never starts collection.

Seller-history rows can be produced from committed calculation audit records with bun run rollup:economic-nexus-history; the evaluator filters activity to the exact rule period and requires an appropriate coverage watermark. The rollup defaults to needs_review. Historical line gross follows each line's final reviewed effective state, while explicitly seller-billed shipping, freight, handling, and gift-wrap charges follow the final order state. Explicit buyer-direct carrier charges are excluded from seller sales; positive legacy or current charges with unknown biller evidence make the rollup needs_review. Malformed or unreconciled response evidence is review-gated and is never assigned to a guessed state.

Migration 021_economic_nexus_activity_evidence.sql makes that gate explicit. Each threshold rule declares history_evidence_requirements and current_transaction_evidence_requirements; reviewed seller-history rows carry the facts they establish in activity_evidence. The closed vocabulary includes complete_state_activity_ledger, destination_tpp_sales_price_basis, taxable_remote_tpp_sales_price_basis, taxable_destination_sales_basis, marketplace_provider_certified_sales_excluded, state_attributed_gross_income_basis, state_consumer_retail_sales_basis, vermont_applicable_destination_sales_basis, related_person_activity_combined, and current_transaction_excluded. Missing history or current-request evidence is returned in the threshold evidence and leaves the result warning-gated rather than treating a monetary total as proof of the required legal basis.

The reviewed California rules require sales of tangible personal property delivered into California, including marketplace sales and combined related-person activity, to be strictly greater than $500,000 in the current or previous calendar year. Two effective intervals preserve the district-use-tax timing documented by CDTFA special notice L-684. From 2019-04-01 through 2019-04-24, the threshold rule uses manual collection review because the new $500,000 district collection threshold did not take effect until April 25; that row does not establish full component-level collection. From 2019-04-25 onward, the crossing sale is not collectible solely because it crosses the threshold and collection starts with the next transaction. The rows are sourced to California Revenue and Taxation Code section 6203, the CDTFA Wayfair FAQ, CDTFA's Marketplace Facilitator Act guide, and CDTFA special notice L-684.

Migration 022_florida_economic_nexus.sql adds reviewed Florida intervals. For 2022 forward, a remote seller exceeds the threshold only when taxable remote sales prices for tangible personal property delivered into Florida are strictly greater than $100,000 in the complete previous calendar year. A marketplace seller counts only qualifying sales made outside the marketplace, and exclusion requires retained marketplace-provider certification evidence. Collection begins January 1 after the measurement year. The July 1 through December 31, 2021 launch interval preserves the same qualified-sales threshold but remains collection-manual because Florida's midyear effective date does not fit the recurring January 1 timing primitive. The rows are sourced to Florida Statutes section 212.0596, section 212.05965, and Florida Administrative Code rule 12A-1.103.

Migration 023_washington_economic_nexus.sql adds Washington's reviewed 2020-forward rule. The strict >$100,000 threshold uses all gross income of the business sourced or attributed to Washington in the current or immediately preceding calendar year, including retail, wholesale, service, other apportionable, exempt, and marketplace activity. Calculate therefore requires state_attributed_gross_income_basis; ordinary committed retail-sale totals do not prove the measure. A reviewed history row must exclude the current transaction and record the matching threshold_rule_key and threshold_crossed_on. Collection begins on the first day of the first calendar month starting at least 30 days after that crossing date. The row is sourced to RCW 82.04.067, RCW 82.08.052, and Washington DOR marketplace-seller guidance.

Migration 024_kansas_economic_nexus.sql adds two reviewed Kansas remote-seller intervals. The July 1 through December 31, 2021 launch interval counts all sales to Kansas customers from January 1, including exempt sales, but does not permit a 2020 lookback and creates no collection duty before July 1. From 2022 forward, a remote seller exceeds the threshold only when gross receipts from all Kansas sales are strictly greater than $100,000 in the current or immediately preceding calendar year. The transaction that first pushes receipts above the threshold is not collected solely because of that crossing; collection begins on the next transaction. The rows are sourced to Kansas Notice 21-17 and Publication KS-1510.

Migration 025_north_carolina_economic_nexus.sql adds North Carolina's reviewed post–July 1, 2024 interval and the typed days_after_threshold collection rule. The state repealed its transaction-count test, leaving a strict >$100,000 threshold for gross remote sales sourced to North Carolina in the current or previous calendar year. Sales as a marketplace seller and marketplace-facilitated sales are included. A reviewed history row must retain the matching crossing date; collection begins exactly 60 days after the threshold is met. Existing registered sellers that cease meeting the threshold can remain obligated until their registration is cancelled, so stored registration evidence continues to govern that case. The row is sourced to Directive SD-24-1, Directive SD-18-6, and current remote-sales guidance.

Migration 026_georgia_economic_nexus.sql adds Georgia's reviewed 2020-forward remote-seller intervals and introduces transaction_count_comparison, because Georgia's amount and count boundaries are not the same: gross revenue must be strictly greater than $100,000, while 200 or more Georgia-destination TPP retail sales independently qualifies, in either the current or previous calendar year. Stored activity excludes the crossing request and collection begins on the next transaction. The April 1, 2020-forward interval excludes facilitator-collected sales from the remote marketplace seller's measures and requires certified marketplace-exclusion evidence; the January–March launch interval precedes that treatment. The rows are sourced to Policy Bulletin SUT-2019-02 and Policy Bulletin SUT-2020-01.

Migration 027_indiana_economic_nexus.sql adds Indiana's reviewed January 1, 2024-forward rule after repeal of its 200-transaction test. A remote seller qualifies only when broad gross revenue from tangible property, electronic products, and services delivered into Indiana—including exempt activity—is strictly greater than $100,000 in the current or preceding calendar year. Facilitator-responsible sales are excluded from the seller's measure with certified evidence, and collection begins on the next transaction after crossing. The row is sourced to Sales Tax Information Bulletin 89, Indiana's remote-seller page, and remote-seller FAQs.

Migration 028_wisconsin_economic_nexus.sql adds Wisconsin's reviewed February 20, 2021-forward interval after its transaction-count test was repealed. The strict >$100,000 current-or-previous-calendar-year measure includes taxable and nontaxable Wisconsin gross sales, including sales made on the remote seller's behalf by a marketplace provider. Stored history excludes the crossing request, and Wisconsin DOR's amount-threshold example explicitly begins collection with the next sales transaction. The row is sourced to current remote-seller FAQs and registration and collection date examples.

Migration 029_missouri_economic_nexus.sql adds Missouri's reviewed January 1, 2023-forward vendor-use-tax rule, the preceding_12_months_at_calendar_quarter_end measurement contract, and first_day_after_full_months_from_period_end timing. At each quarter end, the seller tests gross receipts from taxable TPP shipped to Missouri over the exact preceding 12 months, including marketplace sales, against a strict >$100,000 threshold. The engine requires the most recently completed quarter plus exact first/last-day bounds and complete qualified-ledger evidence. Collection begins no later than the first day after three complete months following the qualifying quarter—for example, October 1 after a June 30 quarter. RSMo section 144.605 supplies the specific quarter-end calculation and timing procedure; Missouri DOR's remote-seller FAQ confirms it with examples, and marketplace-facilitator rule 12 CSR 10-113.400 states the threshold definition.

Migration 030_nevada_economic_nexus.sql adds Nevada's reviewed October 1, 2018-forward remote-seller rule. The current or immediately preceding calendar year qualifies when Nevada-delivered retail TPP sales strictly exceed $100,000 or reach at least 200 transactions; marketplace sales count toward a marketplace seller's threshold. The engine requires a reviewed crossing date and starts collection on the first day of the first month beginning at least 30 days later. NAC 372.851 supplies the threshold and timing, while Nevada Department of Taxation training and its marketplace collection certificate confirm the remote-seller and marketplace responsibilities.

Migration 031_tennessee_economic_nexus.sql adds Tennessee's reviewed rolling-12-month consumer-retail-sales rules. The historical October 1, 2019 through September 30, 2020 interval strictly exceeds $500,000; the current interval beginning October 1, 2020 strictly exceeds $100,000. Taxable and exempt retail sales to Tennessee consumers count while resale is excluded. For an out-of-state marketplace seller, registered-facilitator-collected sales are excluded with certified evidence. A reviewed crossing date starts collection on the first day of the third month following the crossing month. Tennessee DOR's threshold basis, collection timeline, and marketplace seller calculation supply the operative contract.

Migration 032_virginia_economic_nexus.sql adds Virginia's reviewed July 1, 2019-forward rule. Direct Virginia retail sales in the current or previous calendar year qualify when gross revenue strictly exceeds $100,000 or the count reaches 200 separate transactions. Reviewed history must aggregate commonly controlled dealers. A marketplace seller excludes facilitated sales from its direct-sales threshold only with provider evidence. A reviewed crossing date starts collection no later than 30 days later. Code of Virginia §58.1-612 supplies the amount, count, annual window, and related-person aggregation; §58.1-612.1 supplies the marketplace exclusion, and Virginia Tax Public Document 20-43 supplies the 30-day collection guidance.

Migration 033_utah_economic_nexus.sql adds Utah's reviewed January 1, 2019-forward rules. Gross revenue from tangible personal property, electronically transferred products, and services for Utah storage, use, or consumption qualifies when it strictly exceeds $100,000 in the current or previous calendar year. An inclusive 200-transaction alternative applies through June 30, 2025. Marketplace sales count before facilitator collection began October 1, 2019; later marketplace-seller intervals exclude facilitator-required sales with provider evidence. The crossing transaction is excluded and ordinary remote-seller collection begins on the next transaction; the facilitator-only 60-day quarter rule is not reused. The Utah Tax Commission remote-seller page supplies the effective date and transaction-test repeal, Utah Code §59-12-107 supplies the current threshold, and §59-12-107.6 plus Publication 71 supply marketplace treatment.

Migration 034_vermont_economic_nexus.sql adds Vermont's reviewed July 1, 2018-forward rules. Both the $100,000 amount threshold and 200-transaction threshold are inclusive. Reviewed history uses vermont_applicable_destination_sales_basis: ordinary remote sellers measure Vermont-destination tangible-personal-property sales, while marketplace sellers measure combined direct and facilitated retail sales. Marketplace-facilitator collection began June 1, 2019; certified facilitated transactions are the facilitator's obligation but remain in the marketplace seller's threshold. Act 175 changed the window on October 8, 2020 from any qualifying preceding 12-month period to the 12 complete calendar months immediately before the liability month. Act 134 supplies the original threshold and Wayfair-triggered effective date, Act 46 and 32 V.S.A. §9713 supply marketplace treatment, and §9701 supplies the current measurement rule.

Migration 035_west_virginia_economic_nexus.sql adds West Virginia's reviewed January 1, 2019-forward rules. The launch interval strictly exceeds $100,000 or reaches 200 transactions; West Virginia Code §11-15A-6b makes both tests inclusive from July 1, 2019. The current or immediately preceding calendar-year measure includes taxable and nontaxable West Virginia sales, including sales made through a marketplace. Tax Division remote-seller guidance explicitly starts current-year collection after the threshold day, so the crossing transaction is excluded and the next transaction collects. TSD-442 assigns facilitated-transaction collection to the facilitator from July 1 without removing those sales from the marketplace seller's gross-revenue measure.

Migration 036_wyoming_economic_nexus.sql adds Wyoming's reviewed February 1, 2019-forward rules. The strict >$100,000 measure includes wholesale, retail, and exempt gross sales of tangible personal property, admissions, and services delivered into Wyoming during the current or immediately preceding calendar year. An inclusive 200-transaction alternative applies through June 30, 2024; 2024 House Enrolled Act 38 repealed it effective July 1. 2019 House Enrolled Act 23 makes a marketplace facilitator the vendor and collection party for facilitated sales from July 1, 2019, while those seller sales remain in the broad statutory gross-sales measure. Current Department remote-seller guidance identifies the date economic nexus is met as the seller's start date, so the qualifying current transaction is included and collectible.

Migration 037_alabama_economic_nexus.sql adds Alabama's reviewed October 1, 2018-forward rules. Rule 810-6-2-.90.03 and the current Department FAQ use a strict >$250,000 threshold based only on the previous calendar year's direct retail tangible-personal-property sales delivered into Alabama. Taxable and nontaxable retail sales count, documented resale sales do not, and there is no transaction-count alternative. The launch interval begins collection exactly October 1, 2018. From the January 1, 2019 marketplace mandate, certified facilitator-collected sales are excluded from the marketplace seller's direct-sales threshold; SSUT guidance describes the compliance path but does not change the seller-side threshold.

Migration 038_alaska_economic_nexus.sql adds Alaska's reviewed ARSSTC local-only model. The Uniform Code applies an inclusive statewide $100,000 gross-sales threshold in the current or previous calendar year to all remote goods and services, including exempt and marketplace-facilitated sales. The transaction-threshold notice repealed the former inclusive 200-transaction alternative effective January 1, 2025. Because Alaska has no statewide sales tax, a met threshold is not enough by itself: Calculate also matches the point of delivery to the effective dates in the reviewed ARSSTC member-jurisdiction list before authorizing local collection. A nonmember destination remains noncollecting even when statewide sales exceed the threshold.

Migration 039_arkansas_economic_nexus.sql adds Arkansas's reviewed July 1, 2019-forward seller rule. Act 822 and current DFA remote-seller guidance measure direct taxable Arkansas-destination sales in the current or previous calendar year. The statutory tests strictly exceed $100,000 or 200 transactions. Facilitated sales count to the facilitator and not the marketplace seller, so seller history must carry taxable_destination_sales_basis and certified marketplace-exclusion evidence before it can authorize collection. The crossing sale is recorded in reviewed history and the next transaction collects.

Migration 040_arizona_economic_nexus.sql adds Arizona's reviewed remote-seller TPT history. A.R.S. §42-5044 sets strict direct-retail gross-proceeds thresholds of $200,000 for 2019, $150,000 for 2020, and $100,000 from 2021 forward in the current or previous calendar year. ADOR guidance excludes facilitator sales and aggregates affiliated persons. A qualifying previous year begins collection at the applicable year start; a current-year crossing begins on the first day of the month starting at least 30 days later, as confirmed by the licensing guidance. Calculate retains Arizona's transaction_privilege_tax regime and seller-business-tax collection model rather than labeling the result as ordinary sales tax.

Migration 041_connecticut_economic_nexus.sql adds Connecticut's reviewed fixed-year history. Conn. Gen. Stat. §12-407(a)(12)(G) requires both at least $100,000 of gross receipts and at least 200 retail sales from outside Connecticut to Connecticut destinations during the 12 months ended September 30. Public Act 19-117 reduced the launch amount from $250,000 to $100,000 effective July 1, 2019 without changing the inclusive count test. DRS marketplace guidance confirms facilitated sales remain in a marketplace seller's nexus threshold, while the facilitator collects qualifying facilitated transactions. Calculate requires an exact reviewed October 1–September 30 ledger and starts collection on the later of the applicable rule date or the following October 1.

Migration 042_district_of_columbia_economic_nexus.sql adds D.C.'s reviewed January 1, 2019-forward rule. D.C. Code §47-2001(w) uses a strict >$100,000 gross-receipts test or an inclusive 200-sale test for retail sales delivered into the District during the current or previous calendar year. OTR's remote-seller FAQs confirm that exempt-certificate and marketplace sales count, a current-year obligation continues through the following year, and the count-based start is sale 201. A qualifying prior year starts January 1; otherwise the crossing sale enters reviewed history and the next transaction collects. The migration also adds broad facilitator collection from April 1, 2019 under §47-2002.01a, without requiring the marketplace seller itself to meet a threshold.

Migration 043_idaho_economic_nexus.sql adds Idaho's reviewed June 1, 2019-forward rule. House Bill 259, codified in Idaho Code §§63-3611 and 63-3620E, uses a strict >$100,000 test based on cumulative gross receipts from sales delivered into Idaho in the current or previous calendar year, with no transaction-count alternative. Current Tax Commission online-seller guidance confirms that marketplace sales remain in a remote seller's total. A qualifying prior year starts January 1; a current-year crossing enters reviewed history and the next transaction collects. An out-of-state facilitator is the collection party only when its combined own and third-party Idaho sales strictly exceed the same amount threshold, so Calculate requires reviewed threshold_status evidence before shifting marketplace liability.

Migration 044_iowa_economic_nexus.sql adds Iowa's reviewed historical transition. Iowa Code §423.14A (2019) launched January 1, 2019 with inclusive $100,000 or 200-Iowa-sale alternatives. House File 779 removed the transaction alternative from July 1, 2019 forward, leaving an inclusive amount-only test. Current Department guidance and administrative rule 701-207.1 define the base as all Iowa gross revenue—including taxable, exempt, wholesale/resale, service, digital, and marketplace sales—in the current or immediately prior calendar year. A prior-year qualification starts January 1; a current-year crossing starts on the first day of the next calendar month beginning at least 30 days later and continues through the following year. Paired wildcard marketplace rows preserve the same threshold transition and require reviewed threshold_status before shifting collection to the facilitator.

Migration 045_illinois_economic_nexus.sql adds Illinois's reviewed October 1, 2018-forward threshold history. FY 2019-05 establishes the fixed September 2017–August 2018 launch lookback and the recurring inclusive $100,000-or-200 tests for mandatory Use Tax collection. Later tests occur on the last day of each calendar quarter over the exact preceding 12 months and begin a one-year collection period the next day. FY 2020-18 adds threshold-dependent facilitator Use Tax collection and excludes certified marketplace sales from the marketplace seller's measure beginning January 1, 2020. Administrative rules 131.115 and 131.120 switch qualifying remote retailers to destination-based State and local ROT beginning January 1, 2021 while preserving the amount-or-count alternatives through 2025. P.A. 104-0006 guidance removes the 200-sale alternative beginning January 1, 2026. The TPP retail-receipts base includes exempt sales but excludes resale, registered-property, occasional, and qualifying certified marketplace sales.

A current request can automatically establish only destination_tpp_sales_price_basis. That proof is intentionally narrow: every contributing line must be an exclusive, undiscounted, unbundled physical-good line using ship fulfillment, with no drop-shipment, direct-mail, or lease/rental fact, and the order must have no seller-billed or unknown-biller shipping, freight, handling, or gift-wrap amount. Buyer-direct carrier charges may be excluded from the seller's sales-price basis. Inclusive pricing, any line or order discount, bundles, services or other item types, pickup or another non-ship fulfillment method, drop shipments, seller-billed or unknown charges, direct mail, and leases do not receive the automatic evidence token and therefore remain warning-gated when the rule requires it.

Committed-ledger rollups never assert that they represent the seller's complete enterprise activity. When a matched rule has non-empty evidence requirements, the generated row remains needs_review, has no unsupported activity_evidence claims, and reports the unmet tokens in metadata.missing_history_evidence. Applying a rollup can update only a row whose existing source_ref identifies it as a committed-calculation rollup; it does not overwrite an authority or manually reviewed non-rollup row. The existing reviewed Colorado, South Dakota, Texas, California, Florida, Washington, Kansas, North Carolina, and Georgia rules require complete_state_activity_ledger; Colorado, California, Kansas, North Carolina, and Georgia also require current_transaction_excluded. Florida and Georgia require certified marketplace exclusions for their applicable intervals, while Washington requires all state-attributed business income; the committed-ledger rollup claims none of those facts. These reviewed rows are narrow implementations and are not nationwide economic-nexus completeness.

Calendar-year history must cover January 1 through its covered-through date, match the reviewed rule basis, and supply every declared evidence token and any required crossing provenance before it can drive collection. For a current-year row, period_end itself must reach at least the day before the transaction; a newer activity_as_of watermark cannot substitute for missing covered days. For first_day_of_next_calendar_year, Calculate derives January 1 from the reviewed history row's period_end; a missing period end cannot start collection. Texas receives a separate exact preceding-12-calendar-month row: completed months are included, the current partial month and current transaction are excluded, and marketplace sales remain part of gross Texas revenue. A Texas run must include at least one month before the 12-month window so the immediately prior complete window can prove the threshold transition. For example, a July 11, 2026 rollup uses July 1, 2025 through June 30, 2026 and can be inspected with --from 2025-06-01 --to 2026-07-11 --review-status reviewed, but it remains needs_review if the rule's typed evidence requirements are unmet. If the first complete window is already above the threshold, Calculate leaves the crossing date unproven until a matching reviewed consecutive window supplies it. Colorado's official threshold uses retail sales, so undifferentiated gross sales do not establish its basis. Delayed-start rules also require a matching threshold_rule_key and threshold_crossed_on; missing or mismatched crossing evidence returns ECONOMIC_NEXUS_COLLECTION_TIMING_REVIEW and does not collect. Marketplace activity with unknown inclusion treatment, stale history, unsupported sales bases, incomplete authority fields, metadata-only facts, or missing typed evidence remains warning-gated with REMOTE_SELLER_THRESHOLD_REVIEW.

Marketplace facilitator responsibility is resolved from effective tax_marketplace_rules rows when transaction.marketplace.is_marketplace_sale=true. The marketplace object can include marketplace_name or marketplace_id, threshold_status, certification_id, agreement_id, and facilitator_registration_id; missing required evidence returns a warning and falls back to seller nexus rather than silently shifting collection. Rule results can require a specific fact, such as reviewed threshold status, or one of several evidence alternatives, such as provider certification, public agreement, or facilitator registration. A rule-backed marketplace result separates customer-facing liability.collection_party from seller reporting or filing treatment in liability.basis.marketplace_rule. Reviewed seed rows currently cover California, the District of Columbia, New York, Texas, and threshold-dependent Arkansas, Idaho, Iowa, and Illinois facilitator collection; remaining states and transaction families stay warning-gated until reviewed rows are promoted.

always_calculate, manual_override, do_not_collect, transaction.marketplace.marketplace_collects, and nexus_behavior=marketplace_liability are explicit request overrides. They are reflected in warnings, rule_trace, and liability.basis instead of being treated as inferred nexus determinations.

Charges

Order-level shipping, freight, handling, and gift-wrap amounts are resolved through the dedicated charge resolver instead of generic product taxability. Charge rules read tax_shipping_rules, including fee rows for fee.handling and fee.gift_wrap, and can return taxable, exempt, or proportional treatment. Proportional rules allocate the charge across taxable versus exempt/non-taxable line basis before calculating jurisdiction components.

Effective July 11, 2026, reviewed seller-billed shipping, freight, and handling rows cover uniform taxable or uniform exempt carts in Texas and New York. New Jersey also supports its reviewed taxable-sales-price proportional allocation for mixed taxable/exempt carts when the request explicitly elects taxable_sales_price_share and attests that allocation evidence will be retained; the exact election is echoed in order_charges.*.allocation. These rows require sales-tax obligations, destination/common-carrier sourcing, billed_by:"seller", separately stated unbundled common-carrier charges, and only general physical-goods lines using common-carrier fulfillment with one order ship-to destination. Pickup, drop-ship, direct-mail, lease/rental, supplier-ship-from, receipt-location, service-location, business-record, address-obtained-during-sale, use-location, line-level destination, bundle, and unclassified non-taxable bases are excluded. Buyer-direct carrier charges, New York/Texas mixed carts, New Jersey weight or unallocated methods, gift wrap, and special product/service cases remain warning-gated.

The charges object supplies rule facts while amounts supplies money: separately_stated, bundled, billed_by, common_carrier, pickup, drop_ship, allocation_method, allocation_evidence_retained, actual_cost_amount, and metadata. billed_by defaults to unknown, so a reviewed seller-charge rule cannot infer that a charge paid directly to a carrier was seller billed. allocation_method supports none, taxable_sales_price_share, weight, and unallocated; allocation_evidence_retained defaults to false. Rules can use those facts for separately stated versus bundled charges, common-carrier treatment, pickup/drop-ship cases, allocation elections, and actual-cost caps. Missing evidence for a rule-backed cap or allocation returns an unsupported-rule warning/error according to options.unsupported_behavior.

Charge taxability is still evaluated by jurisdiction component. A state-level shipping rule can be paired with a local JSON scope such as { "place_id": "denver" } or { "jurisdiction_type": "city" }, and Calculate will include only taxable components in order_charges.*.jurisdictions.

Discounts And Bundles

Order-level discounts are resolved before line taxability through tax_discount_rules or tax_coupon_rules. amounts.order_discount_type supports seller_discount, manufacturer_coupon, third_party_reimbursed_coupon, gift_card, store_credit, loyalty_points, rebate, and voucher; discounts supplies rule facts such as reimbursement_status, documentation, allocation_method, applies_to_line_ids, source_id, and metadata.

Line-level discount_amount also uses line_items[].discount.reimbursement_status. Seller-funded or unknown discounts reduce the provisional tax base; manufacturer- or third-party-reimbursed discounts remain in the provisional tax base. Until a reviewed jurisdiction-specific line-discount rule is available, any non-zero line discount returns LINE_DISCOUNT_TREATMENT_REVIEW and makes the result non-authoritative rather than silently treating every discount as seller-funded.

Gift cards and store credit are treated as payment tender by default, so they do not reduce the taxable base unless a reviewed rule row explicitly says otherwise. Seller discounts, coupons, rebates, loyalty points, vouchers, and mixed-cart discounts can reduce or preserve the taxable base according to reviewed rule metadata such as tax_base_treatment, allocation_method, eligible_tax_codes, and eligible_item_types. Fallback treatment remains warning-gated with DISCOUNT_ALLOCATION_REVIEW, COUPON_TAXABILITY_REVIEW, MIXED_CART_DISCOUNT_ALLOCATION_REVIEW, or TENDER_DISCOUNT_CLASSIFICATION_REVIEW.

Line items can include bundle metadata for separable bundles, non-separable bundles, mixed transactions, service-with-property transactions, subscriptions, and maintenance contracts. Bundle components carry component_id, tax_code, item_type, quantity, unit_amount, optional allocation_amount, separately_stated, mandatory, and metadata. Reviewed tax_bundle_rules rows can classify and allocate those components; otherwise the response returns line-level bundle evidence plus warning codes such as BUNDLE_TAXABILITY_REVIEW, BUNDLED_SERVICE_TAXABILITY_REVIEW, REPAIR_SERVICE_TAXABILITY_REVIEW, SOFTWARE_MAINTENANCE_BUNDLE_REVIEW, or SUBSCRIPTION_BUNDLE_REVIEW.

Persistence And Lifecycle

When transaction.commit=false, calculate returns a deterministic request_hash and does not persist. When commit=true, the API stores structured request, response, line, component, and rule-trace audit rows before returning success; if persistence fails, the request fails closed with an error response. Replay uses that stored request evidence to rebuild the draft against the current rule/data set and returns the original calculation ID, request hash, replay timestamp, and nested response. Idempotency-Key scopes duplicate protection to billable entity and environment: identical committed retries return the originally stored calculation response, while reusing a key for a different normalized calculate request returns 409 with error.code:"idempotency_conflict".

Refunds, credit memos, voids, and adjustments should include a lifecycle object with an original reference: original_calculation_id, original_transaction_id, or original_document_code. Committed lifecycle calculations require one of those references. Draft lifecycle calculations can run without one, but return LIFECYCLE_ORIGINAL_DOCUMENT_REVIEW until the original document link is supplied.

Lifecycle mode defaults to preserve_original, which loads stored original calculation evidence when the reference can be resolved by calculation ID, transaction ID, or document code. For full-document refunds and credit memos, the refund amount basis comes from the stored original summary, lines, order charges, jurisdiction components, and data-version evidence rather than a current recomputation; the response marks this with lifecycle.rule_preservation.original_amount_basis_applied=true. For partial line returns, Calculate matches lifecycle.line_items[].original_line_id to stored original lines and scales original line amounts and jurisdiction components by return_amount, return_quantity, or the returned line gross amount; matched responses include lifecycle.original_reconciliation.line_amount_basis_applied=true and per-line reconciliation evidence. For charge-only refunds, Calculate scales stored original shipping, freight, handling, or gift-wrap charge components by the requested lifecycle refund amount and marks lifecycle.original_reconciliation.charge_amount_basis_applied=true. For voids, Calculate uses the stored original response as the reconciliation basis, zeros the money impact, and preserves the original line and jurisdiction component identities with amount_basis_kind=void. For tax-only adjustments, Calculate allocates the requested tax delta across stored original tax components while keeping taxable base at zero, marking lifecycle.original_reconciliation.tax_adjustment_basis_applied=true. The response also includes lifecycle.original_reconciliation with the matched original summary, request hash, transaction, and data-version evidence, and lifecycle.rule_preservation.original_evidence_loaded=true. If the original cannot be loaded, Calculate returns LIFECYCLE_ORIGINAL_DOCUMENT_UNVERIFIED or LIFECYCLE_ORIGINAL_DOCUMENT_NOT_FOUND rather than silently treating the reference as verified. If partial lines, charges, or tax-adjustment components cannot be matched or scaled from the original, Calculate returns LIFECYCLE_ORIGINAL_LINE_NOT_FOUND, LIFECYCLE_ORIGINAL_LINE_BASIS_UNVERIFIED, LIFECYCLE_ORIGINAL_CHARGE_NOT_FOUND, LIFECYCLE_ORIGINAL_CHARGE_REFUND_EXCEEDS_ORIGINAL, or LIFECYCLE_ORIGINAL_TAX_ADJUSTMENT_BASIS_UNVERIFIED and leaves the current calculation basis in place. Use mode=recalculate_current only when intentionally recalculating against current request/rule behavior; the response includes LIFECYCLE_RECALCULATION_REQUESTED and lifecycle.rule_preservation.recalculates_with_current_rules=true.

When stored original evidence is available, Calculate also evaluates effective tax_lifecycle_rules rows for state-specific refund, credit memo, void, and adjustment constraints. Rule results can require lifecycle evidence such as marketplace refund references, customer tax-refund documentation, marketplace provider certifications, or restocking-fee documentation; constrain returned total or tax amounts against the stored original summary; apply proportional original-tax ceilings for partial returns; restrict return kinds; or disallow unsupported adjustment patterns. The response returns lifecycle.refund_constraints with matched rule evidence and violations. Reviewed rules with enforcement=error block the calculation with lifecycle_refund_constraint_violation; unreviewed or warning-only constraints return LIFECYCLE_REFUND_CONSTRAINT_REVIEW or LIFECYCLE_REFUND_CONSTRAINT_VIOLATION warnings instead. Reviewed seed rows currently provide a narrow California, New York, and Texas lifecycle baseline from official source pages; other states and more specialized product/claim workflows remain review-gated until their own source rows are promoted.

lifecycle.line_items can carry partial-return and quantity-return evidence with line_id, original_line_id, return_quantity, return_amount, and optional tax_amount. The lifecycle object also supports shipping_refund_amount, freight_refund_amount, handling_refund_amount, gift_wrap_refund_amount, restocking_fee_amount, tax_only_adjustment_amount, tax_adjustment_direction, marketplace_collected, and metadata.

POST /v1/transactions creates a transaction ledger entry from a non-lifecycle committed calculation, or from an inline non-lifecycle calculate request with commit=true. Lifecycle calculation types must be appended to the original transaction with the void, refund, or adjustment endpoints instead of becoming standalone committed transactions. A successful create response returns HTTP 201, status:"committed", a transaction ID, and a calculation ID. Void, refund, and adjustment endpoints can accept an embedded calculate request; when supplied, the API forces the matching lifecycle transaction type and commit=true, persists the lifecycle calculation, and appends the lifecycle event with the committed calculation ID before returning HTTP 200 with status:"voided", status:"refunded", or status:"adjusted". Legacy event-only calls without calculate still append lifecycle evidence directly, but refund and adjustment calls must include a positive amount, linked calculation ID, or positive line, charge, or tax evidence. Malformed lifecycle payloads return HTTP 400 with error.code:"invalid_request". Appended lifecycle events persist original-document links, line-return evidence, refund/adjustment amounts, marketplace-collected evidence, metadata, an idempotency request hash, and limit_evidence in tax_transaction_events.event_json. The transaction endpoints reject cumulative lifecycle events that exceed the original transaction total or original tax amount with lifecycle_over_refund_limit_exceeded or lifecycle_tax_adjustment_limit_exceeded before updating transaction status.

Exemptions

POST /v1/tax/exemptions/validate checks stored certificate records in tax_customer_exemptions. /v1/tax/calculate also validates stored certificates before suppressing tax when exemption fields are present. A certificate is valid for calculation only when it matches the authenticated billable entity and customer, is effective for the transaction date, applies to the destination state/jurisdiction, is reviewed, matches the requested exemption_type and entity_use_code, and explicitly covers the line tax code or item type in certificate_json.

Missing, expired, unreviewed, wrong-state, entity-use/type-mismatched, or product-incompatible certificates do not reduce tax. The response returns exemptions.status, exemptions.reasons, warnings, and rule_trace evidence instead.

Limitations

Net Amount Calculate is not tax or legal advice, managed filing, or remittance software. Unsupported categories and jurisdictions are intentionally explicit. If coverage is unknown, treat the result as incomplete until reviewed rule rows and source references exist.

Consumer-use calculation does not yet apply a credit for sales or use tax previously paid to another jurisdiction. That credit can materially change use tax due, so a consumer-use result is not complete when a prior-jurisdiction tax credit may apply.