Solidus::TaxCloud

Solidus::TaxCloud is a US sales tax extension for Solidus using the Tax Cloud service.

Installation

Set up your TaxCloud account

If you don't have TaxCloud credentials, now is the time to create them. Sign up for a TaxCloud account and note your API ID and API key.

Once you have the credentials, go to Your Account -> Tax States in the TaxCloud dashboard and turn on sales tax collection for the states where you wish to collect sales tax.

Set up Solidus::TaxCloud

Once you have an account, add this extension to your Gemfile:

gem 'solidus_tax_cloud', github: 'solidusio-contrib/solidus_tax_cloud'

Install the gem:

$ bundle install

Run the installer:

$ bundle exec rails g solidus_tax_cloud:install

Configure the extension with your TaxCloud credentials:

TaxCloud.configure do |config|
  config.api_login_id = 'YOUR_TAX_CLOUD_API_ID'
  config.api_key = 'YOUR_TAX_CLOUD_API_KEY'
end

Finally, go to the Solidus backend and create a tax rate in order to apply rates obtained from TaxCloud to your line items and shipments. You can use the following configuration:

Name: Sales Tax
Zone: USA
Rate: 0.0 (because the actual rates will be applied by the calculator)
Tax Category: Taxable
Included in Price: no
Show Rate in Label: no
Calculator: Tax Cloud

If you wish, you may also configure the default Product TIC and Shipping TIC for TaxCloud to use in Settings -> Store -> TaxCloud Settings. It is recommended to leave the defaults (00000 for products and 11010 for shipping) unless you know what you're doing.

Usage

Product-level TICs may be specified in the Products section of the Solidus backend. If you are uncertain about the correct TIC for a product, you can get the TIC from TaxCloud.

Other than that, everything should work automatically! Sales tax rates will be retrieved from TaxCloud and applied to your orders.

Gotchas

Here are a few things to keep in mind:

Solidus::TaxCloud is designed to function in a single TaxCategory. It is expected that all products and shipping methods are in the same tax category as the one configured for the TaxCloud tax rate.
Solidus::TaxCloud is designed to perform all US-related tax calculation itself, and does not use Solidus configurations like tax categories to determine whether goods are taxable, tax-exempt etc.
Solidus::TaxCloud does not use the Solidus configuration tax_address (which specifies whether the shipping or billing address should be used to compute tax). Instead, it always uses the shipping address if possible, only falling back to the billing address if the shipping address is nil.

Testing

First bundle your dependencies, then run bin/rake. bin/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 bin/rake extension:test_app.

bundle
bin/rake

To run Rubocop static code analysis run

bundle exec rubocop

When testing your application's integration with this extension you may use its factories. Simply add this require statement to your spec_helper:

require '<%= file_name %>/factories'

Sandbox app

To run this extension in a sandboxed Solidus application, you can run bin/sandbox. The path for the sandbox app is ./sandbox and bin/rails will forward any Rails command to sandbox/bin/rails. Here's an example:

$ bin/rails server
=> Booting Puma
=> Rails 6.0.2.1 application starting in development
* Listening on tcp://127.0.0.1:3000
Use Ctrl-C to stop

Releasing

New extension versions can be released using gem-release like this:

bundle exec gem bump -v VERSION --tag --push --remote upstream && gem release