Skip to content

TaxJar

TaxJar connects Vectis to TaxJar for real-time US sales tax at cart and checkout, period liability reports, and automatic syncing of placed orders into TaxJar's transaction ledger — the data TaxJar's AutoFile service and reporting rely on. Use it when you want jurisdiction-accurate sales tax computed by TaxJar instead of maintaining DB rate tables by hand.

At a glance
Extension id taxjar
Category tax
Version 0.1.0
Provides Tax calculation strategy (stage 100), tax filing strategy, order.placed sync handler, admin settings link
External account TaxJar account with an API token

What It Provides

  • Sales tax calculation — a TaxCalculationStrategy registered under the name taxjar at stage 100 in the stage-sorted tax engine. Each calculation calls TaxJar's POST /v2/taxes endpoint and emits per-line tax lines of type sales with the jurisdiction (city, county, state, country) TaxJar resolved. Excise strategies at stage 200 (see ExciseEngine) run after it and can read its rounded output via TaxContext.prior_stage_tax_by_line.
  • Tax filing — a TaxFilingStrategy registered under the same name. generate_report aggregates a period's liability from TaxJar's transaction ledger (GET /v2/transactions/orders and GET /v2/transactions/refunds, then per-transaction detail fetches). submit_filing marks the period as submitted locally only — TaxJar exposes no programmatic file-return endpoint; actual remittance is handled by TaxJar AutoFile out-of-band. list_filings returns an empty list; filing history is read from local records.
  • Order sync — subscribes to the order.placed event (priority 80). When Auto-sync Orders to TaxJar is on, each placed order is pushed to POST /v2/transactions/orders with per-line quantities, unit prices, and the sales-type tax amounts recorded on the order.
  • Admin settings link — the manifest contributes a Tax Filing settings page entry pointing at /settings/tax-filing.

Setup

  1. Enable the extension for your channel under Settings > Extensions.
  2. In the extension's configuration, enter your TaxJar API Token and the required ship-from fields (Ship-from Country, Ship-from Postal Code; state/city/street are optional but improve sourcing accuracy — TaxJar uses the from_* fields for nexus routing).
  3. Toggle Use Sandbox Environment to point at https://api.sandbox.taxjar.com/v2 instead of https://api.taxjar.com/v2.
  4. Alternatively, credentials can come from environment variables — channel config is checked first, then TAXJAR_API_KEY, TAXJAR_SANDBOX, TAXJAR_FROM_COUNTRY, TAXJAR_FROM_ZIP, TAXJAR_FROM_STATE, TAXJAR_FROM_CITY, TAXJAR_FROM_STREET, and TAXJAR_AUTO_SYNC.

Strategies register at activation

Strategy registration happens when the extension activates at boot. If no API key is resolvable at that point, the extension activates its manifest (so it appears in the admin) but registers no strategies — the log shows TaxJar extension activated without API key — strategies not registered and the core DB-rate tax strategies continue to run. Once registered, credentials are re-resolved on every call, so credential rotation takes effect immediately.

Configuration Reference

Key Type Required Secret Description
api_key password Yes Yes API Token
sandbox boolean No No Use Sandbox Environment (default false)
from_country string Yes No Ship-from Country (default US)
from_zip string Yes No Ship-from Postal Code
from_state string No No Ship-from State
from_city string No No Ship-from City
from_street string No No Ship-from Street
auto_sync_orders boolean No No Auto-sync Orders to TaxJar (default true)

Secret fields are stored Fernet-encrypted and masked in the admin.

Permissions

  • tax.manage

Permissions are upserted at boot from the manifest; assigning them to roles is manual.

Operational Notes

  • Rate limiting — the API client retries up to 3 times on HTTP 429, honoring the Retry-After header (fallback backoff 2 s x attempt number). If retries are exhausted, the calculation logs a warning and returns no tax lines.
  • Fail-open calculation — TaxJar API errors during checkout are logged and produce zero TaxJar tax lines; checkout is not blocked. Calculation is also skipped when the destination address has neither a postal code nor a state, and for tax-exempt contexts (respecting per-strategy exemptions).
  • Order sync is best-effort — a failed POST /v2/transactions/orders push is logged as a warning and does not affect order placement.
  • Filing is report-plus-local-record — see the Tax usage guide for the filing workflow; the extension never remits money.
  • Every API call uses a 15 s timeout.

For the extension developer view, see Building Extensions.