TaxJar: Complete Guide

TaxJar calculates accurate, real-time US sales tax for every invoice and checkout, based on your nexus and your customer's address. With the TaxJar integration, SubscriptionFlow can:

• Calculate sales tax on invoices, renewals and hosted checkout pages.
• Record paid invoices in TaxJar as order transactions, so your TaxJar reports are ready for filing.
• Record refunds against those transactions automatically.

This guide walks you through connecting TaxJar, choosing your settings, creating a TaxJar tax, and seeing the tax on invoices and checkout.

Before You Start

• You need a TaxJar account with access to the SmartCalcs API.
• Copy your API token. In TaxJar, go to Account → SmartCalcs API. To test first, use a TaxJar sandbox token.
• Have your ship-from address ready. This is the address you sell from. TaxJar uses it as the origin for its sourcing rules.
• Your user needs permission to manage external tax engines.

Step 1: Connect TaxJar

1. Go to Settings → Administration Settings. Under API & Integrations, click Apps.
2. Open the Tax-Management category and select TaxJar.

3. On the Connection tab, paste your token into API Token.
4. If it is a sandbox token, turn on Sandbox (use a TaxJar sandbox token). The switch must match the type of token you use.
5. Click Test Connection. A message confirms that the token is valid.
6. Under Ship-from (origin) address, enter the Street, City, State / Province code (for example CA), Postal code, and Country as a 2-letter ISO code (for example US). State, postal code and country are required.
7. Click Save & Install. TaxJar is now installed and shows as Active.

To disconnect TaxJar later, click Uninstall. This also removes the integration's log history.

Step 2: Choose Your Tax Settings

Open the Settings tab and choose how TaxJar should work.

1. Calculate tax using: choose which customer address TaxJar uses.
   • Customer's shipping address (billing as fallback): most businesses use this option.
   • Customer's billing address (shipping as fallback)
   • Ship-from (origin) address only
2. Transaction recording: choose what is sent to TaxJar after the sale.
   • Record paid invoices and refunds in TaxJar: keeps your TaxJar reports ready for filing.
   • Calculate only (do not record transactions): TaxJar calculates tax but nothing is recorded.
3. Log TaxJar requests: keep this on to make troubleshooting easier.
4. Click Save.

Note: If a customer's address is incomplete, SubscriptionFlow uses your ship-from address to calculate the tax.

Step 3: Create a TaxJar Tax

1. Go to Settings → Administration Settings → Taxes and click New Tax.
2. Set Tax Engine to TaxJar Tax Engine. There is no rate to enter, because TaxJar supplies the rate for each sale.
3. Enter a Tax Code / Name, for example US Sales Tax.
4. Optional: enter a TaxJar Product Tax Code. For example, 30070 is software as a service. Leave it empty for fully taxable general goods and services. Use a product tax code for exempt or reduced-rate items.
5. Click Save.

The tax appears in the list with TaxJar as its engine.

Step 4: Assign the Tax to Your Plan Prices

Assign the TaxJar tax to a plan price the same way you assign any other tax:

1. Open the product, click … on the price, and choose Edit price.
2. Select Taxable, choose the Tax mode, and select the TaxJar tax in Tax code.
3. Click Update price.

For the full steps, see Make a Plan Price Taxable.

Tax groups: a tax group can contain TaxJar taxes or SubscriptionFlow taxes, but not a mix of both.

Step 5: See TaxJar Tax on an Invoice

From now on, whenever SubscriptionFlow generates an invoice, it sends the line items and the customer's address to TaxJar. TaxJar calculates the tax and SubscriptionFlow adds it to the invoice.

1. Go to the Invoices module and open an invoice.
2. Check the Tax column for each line, and Total Tax under More details.

In this example the first invoice covers a partial month, so the line is prorated to $260.42. TaxJar applied the combined Los Angeles rate of 10.25%, covering state, county and district taxes, for $26.69 in tax. The tax is included in the invoice total, ready to be charged.

TaxJar Tax at Checkout

TaxJar also calculates tax on your hosted checkout pages, so your customers see accurate sales tax as they type their address.

1. The customer opens your checkout link. Until a billing address is entered, the order summary shows no tax.

2. As soon as the customer enters the State and ZIP code, SubscriptionFlow asks TaxJar for the exact rate at that address.
3. A Tax line appears in the order summary and the Total updates.

In this example, TaxJar applies 10.25% for a Los Angeles address. That adds $30.65 to the $299.00 plan, for a total of $329.65. The new subscription and its invoice include the same TaxJar tax.

Customers Who Are Tax Exempt

If a customer is marked Tax Exempt on their customer record, SubscriptionFlow tells TaxJar that the customer is exempt when it calculates tax for their invoices.

How Paid Invoices and Refunds Are Recorded

When Transaction recording is set to Record paid invoices and refunds in TaxJar:

• An invoice is recorded in TaxJar as an order transaction once it is Paid.
• A refund on a recorded invoice is recorded in TaxJar as a refund.
• Only paid invoices are recorded. Previews, projected invoices and checkout estimates are calculated but never recorded.
• An invoice whose tax could not be calculated by TaxJar is not recorded.

Review the TaxJar Logs

Open Settings → Administration Settings → Apps → TaxJar and click the Logs tab. Every connection test, tax calculation and recorded transaction appears here with its Time, Action, Status and Detail.

Troubleshooting

The log shows "Calculation / Failed: Unauthorized: Not authorized for route 'POST /v2/taxes'".

TaxJar rejected the request. Open the Connection tab and check that:

• The API Token is correct and was copied in full.
• Sandbox matches your token: on for a sandbox token, off for a live token.
• Your TaxJar plan includes SmartCalcs API access.

Then click Test Connection.

An invoice was created without tax.

If TaxJar cannot be reached or rejects the request, the invoice is still created, but without tax. The Logs tab shows a Calculation entry with the status Failed and the reason. Fix the cause shown in the log, then review the invoices created while TaxJar was unavailable.

No tax appears on an invoice or at checkout.

• Check that the plan price is Taxable and that its Tax code is a TaxJar tax.
• At checkout, the tax appears after the customer enters the state and ZIP code.
• Check that TaxJar shows Active on the Connection tab.

The tax rate is not what you expected.

• Check the Calculate tax using setting, and that the customer has a complete address. If it is incomplete, your ship-from address is used.
• Check the TaxJar Product Tax Code on the tax. A product tax code can make an item exempt or reduced-rate.
• Sales tax collection depends on the nexus set up in your TaxJar account.

Paid invoices do not appear in TaxJar.

• Check that Transaction recording is set to Record paid invoices and refunds in TaxJar.
• Check the Logs tab for a Transaction entry with the status Failed.

Related Articles

• Taxes in SubscriptionFlow: Overview and Setup
• Make a Plan Price Taxable
• Combine Taxes with a Tax Group
• Tax Each Line Item of a Subscription Separately