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 solidus_taxjar. 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.
-
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.
This extension is under active development and not yet at a v1.0 release, but it's currently being used in production by multiple Solidus stores.
Requirements for TaxJar integrations vary as some stores also need reporting, which isn't provided out of the box by this extension. This is because individual stores will be using different background job frameworks or runners (Sidekiq, delayed_job, ActiveJob, etc.) and a reliable integration will rely on one of these. Because this part of the integration is small, we've chosen to provide the transaction reporting functionality, but have skipped directly integrating it.
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
The extension requires the order_recalculated
event which is not supported on
Solidus < 2.11, so this extension provides a compatibility layer.
This extension also supports:
- syncing orders to TaxJar's reporting dashboard
- syncing nexus regions as configured in the connected TaxJar account
- connecting your Solidus store's tax categories to TaxJar's tax categories (U.S. tax codes)
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
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.
- 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.