Taxation documentation #2403

benjaminwil · 2017-11-24T22:02:33Z

I’ve rewritten and expanded the taxation guide. For this PR, I’ve made these changes:

I broke out the section into multiple articles with descriptive subheadings. Developers should be able to skim and scan each article more quickly now.
I more clearly show how zones, tax rates, and tax categories would be set up in a real store.
I fixed inaccurate information about VAT-style taxes and create more extensive context/examples.

There is more work to be done with taxation documentation, but I think this is an improvement over what we had before. In future PRs, I’d like to see the following changes:

We should provide an example of a store that needs to tax using multiple VAT and ship to a country that doesn’t use VAT like the U.S.
We should provide more context and resources for someone who wanted to use a service like Avalara or Tax Cloud to handle taxation.

This is part a larger project to improve Solidus's documentation. See this gist with the high-level table of contents. Where and how this documentation will exist is still up for discussion.

mamhoff

This is a big improvement over the last taxation guide. However, I find a few inaccuracies still.

mamhoff · 2017-11-25T06:56:21Z

guides/taxation/custom-tax-calculator.md

+calculator can be changed if you need to develop a more specialized tax
+calculator for your application.
+
+The `Spree::TaxRate` module includes the `Spree::Calculator` that calculates the


On a Ruby level, this is quite incorrect. The Spree::TaxRate model is a class, not a module, and the Spree::Calculator is an entire group of classes that has to do with tax rates, but also with other things. A developer reading this sentence assuming the person who wrote knows Ruby well will likely be very confused.

What about this:

Every `Spree::TaxRate` you create will be connected to a `Spree::Calculator` instance that calculates the correct tax amount for a given shipment or line item.

Thanks for this (and your continued patience as I figure this stuff out). 👍

mamhoff · 2017-11-25T07:00:58Z

guides/taxation/displaying-prices.md

+Solidus can then proceed to calculate the correct consumer prices for each
+country with `included_in_price` VAT rates. It also generates a fallback
+"export" price, where the price's `country_iso` is `nil`. New products will
+behave as if that checkbox were selected.


that checkbox I believe refers to Rebuild VAT prices, correct? Maybe spell it out, we're two sentences away from the last checkbox, and I think included_in_price can also be displayed as a checkbox.

mamhoff · 2017-11-25T07:01:34Z

guides/taxation/displaying-prices.md

+always uses the most recently updated price.
+
+<!-- TODO:
+  Let's check to see whether there are alternative/automated ways to rebuild VAT


Nope, there isn't any such thing. :)

mamhoff · 2017-11-25T07:04:59Z

guides/taxation/displaying-prices.md

+### Multiple storefronts
+
+Administrators can configure each storefront's "Default currency" and "Tax
+Country for Empty Carts" values from the **Settings -> Store** page in the


The Tax Country for Empty Carts is the same as cart_tax_country_iso, and here it sounds like they are two different things. I suggest merging this with the previous section?

mamhoff · 2017-11-25T07:05:57Z

guides/taxation/displaying-prices.md

+Country for Empty Carts" values from the **Settings -> Store** page in the
+`solidus_backend` admin.
+
+You can customize Solidus's pricing behaviour by creating a custom


Maybe reiterate that VAT and pricing are intricately connected, which is why you're making this point here.

mamhoff · 2017-11-25T07:28:18Z