SuperGood::SolidusTaxjar

SuperGood::SolidusTaxjar is a Solidus extension that allows Solidus stores to use TaxJar for tax calculations.

This is not a fork of spree_taxjar like Boomer Digital's solidus_taxjar extension. Instead of using a custom calculator, SuperGood::SolidusTaxjar uses the new configurable tax system by @adammathys introduced in Solidus v2.4. This maps better to how the TaxJar API itself works.

Documentation

If you're a developer, any information you need about this Solidus extension should be referenced in this file or in the source code of the extension.

If you're not a developer, see the wiki for additional documentation about using the Solidus TaxJar extension after it has been installed.

Installation

1. Add this line to your application's Gemfile:

   gem 'super_good-solidus_taxjar'

   And then execute:

   bundle

2. Next, configure Solidus to use this gem by running the install generator:

   bundle exec rails generate super_good:solidus_taxjar:install

3. Also, configure your own exception handler.

4. Finally, make sure that the TAXJAR_API_KEY environment variable is set to your TaxJar API key.

Warning: Installing on Production

Before you install this extension in your production environment, we strongly recommend that you install and configure a supported ActiveJob backend.

By default, ActiveJob performs jobs in memory. The order reporting backfill functionality of this extension may enqueue a lot of jobs if you have hundreds or thousands of historical orders to report.

Using this extension without a backend like Sidekiq, Resque, or Delayed Job, may cause your application to crash with out-of-memory errors. For more information, read the Rails Guides's Active Jobs Basics article. You may find the Job Execution section particularly helpful.

Developer Support

If you're having trouble integrating this extension with your store and would like some assistance, please reach out to Jared via e-mail at jared@super.gd or on the official Solidus Slack as @Jared Norman.

Features

This extension provides two high level calculator classes that wrap the low-level Ruby taxjar gem API calls:

• tax calculator
• tax rate calculator

⚠️ The transaction reporting features this extension provides depend on the Solidus event system, and in particular the order_recalculated event. That does not exist on Solidus < 2.11, so if you're version of Solidus is older than that and you want to use the reporting feature you will need to backport that event to your applicaiton.

This extension also supports:

• syncing orders to TaxJar's reporting dashboard
• syncing nexus regions as configured in the connected TaxJar account (including automatic and manual sync)
• connecting your Solidus store's tax categories to TaxJar's tax categories (U.S. tax codes)

Note that reporting is turned off by default.

TaxCalculator

SuperGood::SolidusTaxjar::TaxCalculator allows calculating the full tax breakdown for a given Spree::Order. The breakdown includes separate line items taxes and shipment taxes.

This tax calculator will create a Spree::TaxRate that is required for tax adjustments. All other Spree::TaxRates will be ignored in calculations. See this wiki page for more details.

TaxRateCalculator

SuperGood::SolidusTaxjar::TaxRateCalculator allows calculating the tax rate for a given Spree::Address. It relies on the same low-level Ruby TaxJar API endpoint of the tax calculator in order to provide the most coherent and reliable results. TaxJar support recommends using this endpoint for live calculations.

Order-level Adjustments are Unsupported

Although Solidus supports order-level adjustments, TaxJar does not support order-level adjustments. Currently, this extension does not make any assumptions about how order-level adjustments should be reported to TaxJar. After enabling the extension, any attempts to create an order-level adjustment will result in an error being raised by default.

If you need to support order-level adjustments, you'll need to configure the discount_calculator setting to handle them. See Configuration for more more information about configuring the extension.

Configuration

Developers can configure the extension in a Rails initializer file. All of the configuration settings, and their default values, are defined in lib/super_good/solidus_taxjar.rb. The settings are described in the Settings section below.

As an example, your application's initializer might look like this:

# config/initializers/taxjar.rb

SuperGood::SolidusTaxjar.tap do |config|
  config.cache_duration = 2.hours
  config.line_item_tax_label_maker = ->(taxjar_line_item, spree_line_item) {
    "My Tax Label"
  }
  config.test_mode = true
end

Settings

Developers can configure the following settings in an initializer:

• cache_duration: The length of time that cacheable responses from the TaxJar API are cached. Cacheable responses include the list of active nexus regions, as well as tax and tax rate calculations.

  Default value: 3.hours

• cache_key: function that returns a distinct cache key for a cacheable response from the TaxJar API. A safe default function is provided.

  Default value: (See the source code.)

• custom_order_params: A function that returns any parameterized custom order information you need to send to TaxJar in every API request that includes a customer's order. By default no custom order parameters are sent.

  Note that all the essential Spree::Order, Spree::LineItem, and Spree::Address attributes are already sent by default.

  Default value: {}

• discount_calculator: A discount calculator class. A safe default calculator is provided: it handles promotions that rely on line item and shipment adjustments. Since TaxJar requires dicounts to be specified per line item, you need to provide a custom version of this calculator in order to support any of your promotions that create order-level adjustments.

  Default value: ::SuperGood::SolidusTaxjar::DiscountCalculator

• exception_handler: A function that returns your own exception handler. See Exception handling.

  Default value: (See the source code.)

• job_queue: A string or symbol that matches the name of a job queue in your application's job queuer. (The extension uses ActiveJob to delegate new jobs.)

  Default value: :default

• line_item_tax_label_maker: A string to label line item taxes in TaxJar.

  Default value: "Sales Tax"

• logging_enabled: Boolean. Whether logging is enabled.

  Default value: true

• shipping_calculator: A function that calculates the total cost of the shipments for an order. A default default is provided inline, but your store may require additional logic for accurate calculations.

  Default value: (See the source code.)

• shipping_tax_label_maker: A string to label shipment taxes in TaxJar.

  Default value: "Sales Tax"

• taxable_address_check: A function that returns a boolean after checking whether an address should be considered taxable. By default this function returns true.

  Default value: true

• taxable_order_check: A function that returns a boolean after checking whether an order should be considered taxable. By default this function always returns true.

  Default value: true

• test_mode: Boolean. Whether the extension is in test mode. If true, no tax or tax rate calculations will be requested via the TaxJar API.

  Default value: false

Taxable Orders

Note that the configuration setting taxable_order_check can be customized if there is specific criteria that make some orders taxable and other orders not taxable. By default this extension considers all orders taxable.

Exception Handling

You can configure your own exception handler in an initializer. using the exception_handler configuration point:

# Put this in config/initializers/taxjar.rb

SuperGood::SolidusTaxjar.exception_handler = ->(e) {
  # Report exceptions in here. For example, if you were using the Sentry's
  # raven-ruby gem to report errors, you might do this:
  Raven.capture_exception(e)
}

For more information about configuring the extension, see Configuration.

Logging

By default, all requests to TaxJar are logged to the Rails logger. URIs, HTTP method, and response codes will be logged at the info level, any further details (such as response body) are logged at the debug level.

If you are interested in logs for full request responses, be sure to set your logger to the debug level:

Rails.logger.level = 0 # debug

Or, if you want an alternate logger implementation, you can provide your own:

SuperGood::SolidusTaxjar.tap do |config|
  logger = Logger.new(STDOUT)
  logger.log_level = :warn
  config.logger = logger
end

More details on the Rails Logger are available here.

Logging can also be disabled all together:

SuperGood::SolidusTaxjar.tap do |config|
  config.logging_enabled = false
end

Development

Run bin/setup to install dependencies. Then, run bundle exec rake to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Changing the Rails/Solidus Versions

The Rails and the Solidus version can be changed by setting the RAILS_VERSION and SOLIDUS_BRANCH environment variables, respectively. See the Gemfile for examples.

Changing the Database Vendor

The database vendor can also be changed from the default (sqlite3) by setting the DB environment variable.

Testing the Extension

When testing your application's integration with this extension you may use its factories. You can load Solidus core factories along with this extension's factories using this statement:

SolidusDevSupport::TestingSupport::Factories.load_for(SuperGoodSolidusTaxjar::Engine)

Releasing a New Version

1. Update the master header in changelog to the version that you're releasing.
2. Commit your changes and open a PR for the release
3. Once the PR has been merged into master, run gem bump -v [<major>|<minor>|<patch>] -p -t -r to create a tag and release the gem to ✨ RubyGems ✨
4. Push your local master branch with --tags to the repository to add the tag to github.
5. Create a new release on github with the tag
   • Ensure the changelog since the previous release is included
   • Ensure you have noted version migration instructions if applicable
   • Ensure breaking/significant changes are clearly highlighted
   • Ensure changes that are not production ready are clearly highlighted

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/SuperGoodSoft/solidus_taxjar. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the SuperGood::SolidusTaxjar project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.