Most of us are aware that in any kind of business, taxes need to be paid in one form or another. Taxes are regularized and controlled by different government bodies and at different levels like country, state, city or might be more granular level. Tax calculations have so many variables that proper adherence and compliance can be a daunting/time-consuming task for many businesses.

Online businesses adds to the complexity more as it increases the reach further to many locations.

To save time, hassle and proper compliance, there are many solutions from which you can choose like Taxjar, Avalara and Tax Cloud to name a few.


We will talk about Taxjar and how it eases realtime tax calculations, their help filing taxes and excellent reports to have an edge over sales tax audits and be relaxed.

But, wait, why are we so interested in telling about Taxjar which has awesome documentation already.

Yeah, you guessed it right, we will be talking about integrating taxjar in Spree store (an excellent open source, easily customizable e-commerce store).

We, Vinsol, met with the task to integrate Taxjar in Spree store for showing sales tax calculation in realtime and handling sales tax update as order line_items/shipment detail changes.

On the journey, we found that Taxjar already maintains the Taxjar Ruby API Wrapper which would save a lot of hassle and time for us.

Being experts in spree and big believers in keeping thing simple for end user, we developed a spree extension for TaxJar managing setting of Taxjar Api key, showing sales tax while checkout and creating transactions on Taxjar when order is created, updated (managing refunds) and cancelled.


To start using taxjar sales tax calculations:

  • Integrate the extension by following steps in README
  • Go to TaxJar account and note the api key under SmartCalcs Api


  • Add your taxjar api key in Configuration -> Taxjar Settings


  • Create a Tax Category to easily identify TaxJar tax category while assigning in products
  • Create a Zone to include the Nexus 1 region to identify and collect sales taxes as applicable
  • Create a tax rate
    • Choose the zone created above or as applicable
    • Choose the tax category created above or as applicable
    • Add Rate as 0.0 as sales tax would be calculated using taxjar api
    • Choose Taxjar Calculator 2 as made available by the spree taxjar extension
    • Ensure INCLUDED IN PRICE is unchecked
    • Ensure SHOW RATE IN LABEL is unchecked as sales tax would be calculated using taxjar api
  • You should also assign TaxJar Tax Category created above to “Shipping Methods” to calculate sales tax on shipping charges whenever necessary.


  • Start assigning Taxjar Tax Category to products for whom sales tax need to be calculated or set the tax category as default
  • Lets see the Sample Checkout for Product having taxjar tax_category with shipping address of Texas where shipping is taxable and tax rules are origin based
    • Cart with Product of cost 50 and 2 items
      • taxjar_cart
    • On Address step, Shipping to Adrian, Texas 79001
      • Note, no Tax till this step as address is still not known
      • taxjar_address
    • On Delivery step
      • Note, some Tax is shown with Title as Taxjar
      • taxjar_delivery
    • On Payment step
      • Note, the difference in tax under Title Taxjar from the Delivery Step
      • The difference is due to tax added on shipments cost (shipping_cost) as Texas charges shipping cost for tax
      • If, you will choose the California address with same items, the tax would remain same in Delivery and Payment Step as California does not charge tax on shipping cost
      • taxjar_payment
    • Order Details as charged
      • taxjar_order

Samples to test origin and destination based sales tax

To Nexus Origin or Destination Based Nexus Shipping Taxable in Nexus Order Subtotal Shipping Cost (10 % of Subtotal) Tax
Los Angeles, CA, US 90002 San Diego, CA, US 92093 Destination No 100 10 8.75
Adrian, TX, US 79001 Irving, TX, US 75014 Origin Yes 100 10 8.53 (7.75 + 0.78)

Handling exemptions and state varied rules for different items

  • Taxjar can also be used to tax products on different product tax categories which help taxjar apply more tax rules per state
    • In New York, for instance, following rules exist
      • Food & grocery items (Product Tax Code: 40030) are exempt from all sales tax.
      • Clothing items (Product Tax Code: 20010) sold in New York under $110 are exempt from the state tax rate, but only exempt from county taxes in certain jurisdictions.
    • If, product_tax_codes are sent along with other line_item details to Taxjar then while shipping to New York, it can calculate correct sales tax on food items which is ZERO and in absence will tax fully.
  • Spree Taxjar extension helps you with fetching and creating available tax categories with an in-built rake task bundle exec rake spree_taxjar:refresh_categories which will query and create/update spree tax_categories which can then be assigned to appropriate products
  • To fully exempt a product from sales tax, just assign 99999 Tax Category to it and it would just work !! 🙂


Especially for Developers

  • When things are looking fishy or unexpected, Enable TAXJAR DEBUG ENABLED in Taxjar Settings
    • you can trace the log and steps, both in your Rails log and also in a separate file spree_taxjar.log under Rails log folder (log/spree_taxjar.log)

Note for Admins

  • Always ensure that TAXJAR ENABLED in Taxjar Settings is ON else you would loose on sales tax
  • It can be helpful if you are celebrating Sales Tax Holidays or have some other business usecase to not collect sales tax
  • Always, cross-check and confirm that TAXJAR ENABLED is set as per business requirements whether ON or OFF

We, at Vinsol, believe in partnering with our clients to offer them the most business friendly e-commerce solutions

Checkout Launch Your Store in One Day to not miss the edge.


  1. You might have noticed we talked about a new term Nexus, some of us might be already aware of it but for those not aware and new to it. You can find the more information here â†©
  2. There might be questions like why do we need Taxjar when Spree already has such a flexible and robust system to define and handle taxes using tax_category, tax_rate, zones and product tax_categories. Short answer is, Spree helps collecting taxes (and complex calculators like SalesTax be better managed by experts) but taxjar takes you next mile by helping with remitting collected sales tax to authorities, preparing reports to inform any difference in owed and collected sales tax and reports at different levels as needed by authorities. Check the youtube video and presentation here â†©
Share this:

Privacy Preference Center