Calculate API

Net Amount Calculate turns a cart, quote, invoice, refund draft, credit memo, void, or adjustment into seller-collected 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

Method	Path	Purpose
`POST`	`/v1/tax/validate-address`	Validate an address or coordinate against the lookup source.
`POST`	`/v1/tax/calculate`	Calculate one transaction request.
`POST`	`/v1/tax/calculate/batch`	Calculate up to 50 requests.
`GET`	`/v1/tax/calculations/{calculation_id}`	Retrieve a committed calculation/audit record.
`POST`	`/v1/tax/calculations/{calculation_id}/replay`	Re-run a stored request against the current rule/data set without persisting.
`GET`	`/v1/tax/codes`	List tax-code taxonomy and rule coverage counts.
`GET`	`/v1/tax/codes/{tax_code}`	Inspect one tax code and its rule rows.
`GET`	`/v1/tax/coverage`	Return deterministic rule coverage by code and jurisdiction scope.
`GET`	`/v1/tax/states/{state_code}`	Return imported state guidance, sourcing, filing, and source metadata.
`GET`	`/v1/tax/states/{state_code}/sourcing`	Return the sourcing slice for an imported state.
`POST`	`/v1/tax/exemptions/validate`	Validate a stored exemption certificate reference.
`POST`	`/v1/transactions`	Create a transaction ledger record from a committed calculation.
`POST`	`/v1/transactions/{id}/void`	Append a void lifecycle event.
`POST`	`/v1/transactions/{id}/refund`	Append a refund lifecycle event.
`POST`	`/v1/transactions/{id}/adjust`	Append an adjustment lifecycle event.

/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.

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",
      "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,
      "shipping_amount": 0,
      "freight_amount": 0,
      "handling_amount": 0,
      "gift_wrap_amount": 0
    },
    "line_items": [
      {
        "line_id": "1",
        "quantity": "1",
        "unit_amount": 10000,
        "tax_code": "commodity.01"
      }
    ]
  }'

Supported transaction types are sale, quote, invoice, refund, credit_memo, void, and adjustment. 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.

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.

physical_goods.general, shipping.delivery, freight, handling, gift wrap, digital goods, services, SaaS, software, food, clothing, drugs, books, reduced rates, partial taxability, thresholds, caps, holidays, local overrides, bundles, and coupon-specific treatments require reviewed rule rows before they are calculated. Use /v1/tax/coverage and /v1/tax/codes/{tax_code} to see exactly what is modeled.

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.

Sourcing And Nexus

Calculate supports destination, origin, pickup, seller delivery, common carrier, digital delivery, service location, and performance location sourcing as request shapes. The selected source address is recorded in rule_trace; category-specific sourcing law still requires reviewed tax_sourcing_rules data before unsupported coverage can be trusted.

Economic nexus is not silently inferred. With registered_only, seller collection requires an active state registration in the request. always_calculate, manual_override, do_not_collect, and marketplace liability options are explicit request instructions and are reflected in warnings/trace output.

Persistence And Lifecycle

When transaction.commit=false, calculate returns a deterministic request_hash and does not persist. When commit=true, the API stores request, response, line, component, and rule-trace audit rows. Idempotency-Key scopes duplicate protection to billable entity and environment.

POST /v1/transactions creates a transaction ledger entry from a committed calculation or from an inline calculate request with commit=true. Void, refund, and adjustment endpoints append lifecycle events; they do not rewrite the original calculation audit record.

Exemptions

POST /v1/tax/exemptions/validate checks stored certificate records in tax_customer_exemptions. A certificate is valid for calculation only when it is effective for the transaction date and reviewed. Missing or unreviewed certificates return explicit not_validated or needs_review statuses.

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.