README.md

SpreeTaxjar

Spree::Taxjar is a Sales Tax extension for Spree using the Taxjar Service.

Prerequisite

• Create an account with Taxjar
• Go to Your Account >> SmartCalcs Api Setting and Get an API Key
  • API key is needed to calculate sales tax from Taxjar over API
• Go to Your Account >> States Setting, and create Nexus for the relevant states in which you want/need to collect sales tax.
  • NOTE: Taxjar returns ZERO sales tax by default for orders shipping to the states which are not registered as Nexuses.

Installation

1. Add this extension to your Gemfile with this line:

gem 'spree_taxjar', github: 'vinsol-spree-contrib/spree_taxjar', branch: <spree-version-compatible>

The branch option is important: it must match the version of Spree you're using. For example, use 3-1-stable if you're using Spree 3-1-stable or any 3.1.x version.

2. Install the gem using Bundler:

bundle install

3. Copy & run migrations

bundle exec rails g spree_taxjar:install

4. Restart your server

If your server was running, restart it so that it can find the assets properly.

5. Go to Admin >> Configurations >> Taxjar Settings

• Add your taxjar api_key.
• Check TAXJAR ENABLED
• You can optionally also check TAXJAR DEBUG ENABLED but its not recommended for production unless need help debugging production issue.

Developing / Debugging Extension

• Ensure Spree::Config[:taxjar_enabled] is set as expected (true/false)
• Set Spree::Config[:taxjar_debug_enabled] as true
  • It starts logging the interactions in spec/dummy/log/spree_taxjar.log if using tests
  • Check the logs in your Rails application AT log/spree_taxjar.log where you have installed the spree_taxjar extension
  • The same logs are also added to Rails log file like log/development.log (works for all environments)
• As most of the API interactions are recorded and stored in vcr cassettes AT spec/fixtures/vcr_cassettes
  • Start with getting familiar with request and response expected
  • Feel free to delete the cassettes to debug your live use-case by setting Spree::Config[:taxjar_api_key] as your api_key and inspect results

API cost and implication to Taxjar Billing Plan

• We have chosen accuracy over price for obvious reasons (high fine by states if sales tax compliance breach is found)
• Minimum of N + 1 tax calculation API calls are made for each order with N shipments

Why

Taxjar provides 2 set of API tiers (Standard and Advanced) but shipping in both cases is sent as single unit which makes Sales Tax calculation for different shipments a bit tricky or hacky

• We chose to use both API methods at our advantage
• For line_items sales tax, Advanced Tier API call is made to take advantage of in-built product_tax_code and discount fields and all line_items are grouped and sent in same API call
  • Shipping component is ignored as it returns tax for whole order shipping cost and not shipment wise
• For shipments, standard tier API call is made for each shipment with order amount as ZERO and shipping as shipment cost as we are only interested in shipping charge and not the whole order tax which solves the problem of inaccurate and hackish implementation.

Testing

First bundle your dependencies, then run rake. rake will default to building the dummy app if it does not exist, then it will run specs. The dummy app can be regenerated by using rake test_app.

bundle
bundle exec rake

Credits

Copyright (c) 2016 vinsol.com, released under the New MIT License

#Note

For better handling of exception raised by taxjar due to various validations add following code in your project's application_controller.rb

rescue_from Taxjar::Error, with: :taxjar_rollback

private
  def taxjar_rollback(e)
    flash[:error] = 'TaxJar::' + e.message
    redirect_to cart_path
  end