Setup

← Documentation index

This page covers installation and day-to-day configuration. For hooks, code paths, and API behavior, see Integration.


Requirements

  • ERPNext v15 with a United States company. Tax is calculated only for US companies; other regions are ignored even if a TaxJar Account exists.
  • A TaxJar account with Live or Sandbox API keys.
  • ERPNext United States regional setup applied on the site if you rely on sales tax exemption fields on Customer or selling documents.

This app is a fork of Frappe’s TaxJar Integration. License and acknowledgements are in Troubleshooting and contributing.


Installation

From your bench directory (commonly frappe-bench):

bench get-app https://github.com/washmoredevelopment/taxjar_erpnext.git
bench --site your-site.localhost install-app taxjar_erpnext
bench --site your-site.localhost migrate

Before you configure

Complete these on each company that will use TaxJar:

RequirementWhere in ERPNext
TaxJar Account with Enable Tax CalculationTaxJar Account (one per company)
Default company address (ship-from)Company
Shipping address on selling documents (or customer address as fallback)Quotation / Sales Order / Sales Invoice
Tax Account Head and Shipping Account Head GL accountsTaxJar Account
Product Tax Category on item defaultsItem → Item Defaults (per company)
Nexus list synced from TaxJarTaxJar Account → Update Nexus List

Without a company address or a resolvable destination address, tax calculation stops and any existing TaxJar tax row is removed.


What to expect by document type

ScenarioQuotationSales OrderSales Invoice
Ship-to in a nexus stateSales Tax rowSales Tax rowSales Tax row; per-line amounts on invoice lines when TaxJar provides a breakdown
Ship-to outside nexusEstimated Sales Tax when Calculate Estimated Tax for All States is enabled; otherwise no taxNo taxNo tax
Non-nexus alert—ToDo for Notification Recipient when enabled—
Sync to TaxJar——Order or refund on submit; delete on cancel when Create TaxJar Transaction is enabled

Mixed carts: lines with different product tax categories on one document are supported. TaxJar may collect tax on some lines only; the document tax row shows the total.


TaxJar Account

Open TaxJar Account and create one record per company.

  1. Select the Company.
  2. Check Enable Tax Calculation (required before any other TaxJar feature can be saved).
  3. Enter credentials:
    • Live: Live API Key
    • Testing: enable Sandbox Mode and enter Sandbox API Key
  4. Set Tax Account Head and Shipping Account Head to non-group accounts for that company. The integration reads the selling document’s taxes table: the row matching Tax Account Head is sales tax; the row matching Shipping Account Head is shipping in the TaxJar payload.
  5. Save, then click Update Nexus List to load nexus regions into the read-only child table.
  6. Optionally enable Create TaxJar Transaction to push submitted Sales Invoices to TaxJar.

Example posting for a simple taxable sale (Tax Account Head = Sales Tax Payable):

AccountPartyDebitCredit
DebtorsCustomer A$108.00
Sales$100.00
Sales Tax Payable$8.00

Optional non-nexus features

Both settings are on the TaxJar Account form under Non-Nexus State Settings.

Calculate Estimated Tax for All States

  • Applies to Quotations only.
  • Shows Estimated Sales Tax for destinations outside your nexus list.
  • Uses general location rates; product exemptions are not applied. Quoted tax may be higher than tax on a real order so quotes do not undercharge.

Notify User on Non-Nexus Sales Orders

  • When a Sales Order is submitted to a state without nexus, creates a ToDo for the Notification Recipient with order details.
  • Failures are logged only; submission is never blocked.

Product tax categories

  1. Open Product Tax Category. Default categories are created on app install and when tax calculation is first enabled on a TaxJar Account (if the list is empty).
  2. Ensure Product Tax Code values match your TaxJar product tax codes.
  3. On each Item, open Item Defaults and set Product Tax Category for every company that sells the item. Use Item Defaults for multi-company sites; the Item-level field is optional.

On Sales Invoice, the integration fills blank line categories from the item default before calling TaxJar.


Next steps

Please contact us for corrections, additions, questions, or to request a topic.

© 2026 AgriTheory. All Rights Reserved.