US sales tax
A US company charges sales tax, not VAT: by the state the goods or services go to, only in the states where it is registered, at the state's rate plus the local rates of the customer's place, never to a customer with a valid exemption certificate and only on what the state taxes. It files a return per state. The design is ADR-0064; the controls are in the control matrix (section "US sales tax", ST1 to ST5).
Everything is a REST operation first (tag "sales tax" in the generated reference); the screen is Sales tax in the menu of a US company.
Setting up
| What | How | Notes |
|---|---|---|
| Registration in a state | POST /v1/entities/{entity}/sales-tax/registrations (state, permit number, registered from, filing frequency month, quarter or year, and in the company's own state the use tax area) |
Creates the state's own liability account, 2200-CA under the company's sales tax payable account, and the state's rate from data-vNext (California, New York, Texas); for another state give state_rate. PATCH .../registrations/{state} changes the permit, the end, the use tax area, and the frequency while no return is recorded as filed. |
| Local rates | POST .../sales-tax/jurisdictions (county, city or district with its rate from a day; without a code one is made from the name, -2 when taken), POST .../jurisdictions/{code}/rates for a new rate from a day |
The rate of a day is the latest from on or before it: a posted invoice keeps the rate it was charged. |
| Tax areas | POST .../sales-tax/areas (a place: its state and the local jurisdictions that apply there; without a code one is made from the name), PATCH .../areas/{code} |
Los Angeles is California's 7.25% plus the county's 2.5% = 9.75%. |
| What a state does not tax | PUT .../sales-tax/category-rules (state, category, taxable percent) |
Categories: general, saas, digital goods, professional services, clothing, groceries, medical. Without a rule a category is taxed in full. Texas taxes 80% of a SaaS fee, California none of it. |
| A product's category | PUT /v1/products/{product_id}/sales-tax (admin) |
A line without a product is general. |
| A customer's place and exemption | PUT /v1/entities/{entity}/customers/{party}/sales-tax (tax area, certificate number, reason, valid from, valid until, the states it is valid in) |
The customer's state is its address's (subdivision, one of its country's); once the customer has posted documents a new state waits for a second person. A certificate is valid from the day it is recorded unless given, and in the customer's own state unless the states are given (a multistate certificate). Recording an exemption is a person's act: agents are always refused. |
On an invoice
Each line is decided on the document's day:
- The customer is outside the US: no sales tax (an export).
- The customer's state has no sales tax (Alaska, Delaware, Montana, New Hampshire, Oregon) and the company is not registered there: no tax, no warning.
- The company is not registered in the customer's state: no tax, and the document warns. The year's sales into such states are listed under Sales into states without a registration, the first sign of nexus; they are on no state's return, also when a registration starts later in the period. A company registered nowhere also sells to a US customer without a state.
- The customer has a certificate valid on the day in that state: exempt. An expired one is ignored and warned about.
- The state taxes none of the product's category: exempt.
- Otherwise the taxable part (all, or the state's percent) is taxed at the state's rate plus the rates of the customer's tax area. A customer without one pays the state's rate, with a warning.
The tax is rounded once per line at the combined rate and split over the jurisdictions to the cent. The posting credits each state's account, one line per jurisdiction, so the account is what the state is owed. A credit note line takes the decision of the invoice line it credits (the line it names, else the line of the same product): its treatment, taxable part, jurisdictions and rates, whatever changed since, such as a certificate recorded later or a new rate; only the amounts are its own. A cash discount taken corrects the tax on the state's account in proportion. VAT reports and VAT returns never see these lines. The invoice and its PDF show the taxable amount as the base of the tax, and an exempt part as a 0% row.
On a bill, a US vendor's sales tax (printed_tax_amount on the line) is part of the cost: it is
debited to the line's expense account, tagged so it can be found, and is never reclaimed.
Use tax. A bill line the vendor charged no sales tax on, for something used in the company's own
state (an out-of-state supplier, say), is marked use_tax. The company self-assesses use tax at its
state's rate plus the rates of the registration's use tax area: 500.00 of server racks from Oregon
used in Los Angeles books Dr expense 548.75 (500.00 and 48.75 of use tax, a cost), Cr the vendor
500.00 and Cr 2200-CA 48.75 by jurisdiction. The company must be registered in its own state.
The return
GET /v1/entities/{entity}/sales-tax/periods?year=2026 lists each registration's periods (month,
quarter or year as it files) with the day each return is due and its status: open (the period
has not ended), to file, due soon (within 10 days), overdue, awaiting approval,
filed or paid. New York's quarters run March to May, June to August, September to November
and December to February (2026-Q4 ends in February 2027), and its year March to February (2026
ends in February 2027); the others' follow the calendar. A
return is due on the 20th of the month after the period, California's on the last day of that month
(a due day on a weekend or holiday moves to the state's next business day, which the page does not
compute). GET .../sales-tax/returns/{state}/{period} rebuilds a return from the ledger: gross
sales, exempt sales (by certificate and by product), taxable sales, the purchases use tax was
self-assessed on, and the sales and use tax per jurisdiction; the tax due is both, checked against
the state's account (unexplained_difference, for example a manual journal on the account).
Filing is recorded, never sent: POST .../sales-tax/returns (state, period, the day it was filed and
the state's confirmation) keeps the figures as filed. A later change to the period shows as
changed_since_filing. A second person approves the record (POST /v1/sales-tax-returns/{id}/approve; whoever recorded it is refused unless the approval policy allows
finalize_own_vat_return). Only then is it paid: the payment is a posted entry after the period that
debits the state's account (a bank line booked to 2200-TX, say):
GET /v1/sales-tax-returns/{id}/payment-candidates and POST .../payments link it. Withdrawing a
filing (not while paid) and unlinking a payment need a reason. Recording, approving, withdrawing,
linking and unlinking are the policy action finalize_vat_return, which agents are always denied.
In the demo
The demo organization's Demo Inc. (US01, Los Angeles) is registered in California and Texas from January 2026 and New York from July. Its August invoices go to Los Angeles (9.75%), Austin (8.25%, SaaS taxed at 80%), New York City (8.875%), a reseller with a resale certificate (exempt) and Florida (not registered), and it self-assesses 48.75 USD of California use tax on server racks bought from Oregon. Its Texas return of August, 116.33 USD, is filed, approved by a second person and paid from the bank on 18 September.
Not built yet
Automatic rates by address, economic nexus thresholds, partial use tax where a vendor charged a lower rate, due days moved for weekends and holidays, e-filing and the states' own return forms. See the ADR.