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.
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.
-
Add this line to your application's Gemfile:
gem 'super_good-solidus_taxjar'
And then execute:
bundle
-
Next, configure Solidus to use this gem by running the install generator:
bundle exec rails generate super_good:solidus_taxjar:install
-
Also, configure your own exception handler.
-
Finally, make sure that the
TAXJAR_API_KEY
environment variable is set to your TaxJar API key.
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.
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
.
This extension provides two high level calculator
classes that wrap the
low-level Ruby taxjar
gem API calls:
- tax calculator
- tax rate calculator
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.
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::TaxRate
s will be ignored in calculations. See
this wiki
page
for more details.
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.
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.
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
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
, andSpree::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 returnstrue
.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 returnstrue
.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
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.
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.
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
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
.
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.
The database vendor can also be changed from the default (sqlite3
) by setting
the DB
environment variable.
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)
- Update the
master
header in changelog to the version that you're releasing. - Commit your changes and open a PR for the release
- 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 ✨ - Push your local master branch with
--tags
to the repository to add the tag to github. - 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
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.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the SuperGood::SolidusTaxjar
project’s codebases,
issue trackers, chat rooms and mailing lists is expected to follow the
code of conduct.