[IMP] TaxCloud: updated doc

content/applications/finance/accounting/taxation/taxes/taxcloud.rst

@@ -1,139 +1,151 @@
-=========================================================
-Get correct tax rates in the United States using TaxCloud
-=========================================================
-
-The **TaxCloud** integration allows you to correctly calculate the sales
-tax for every address in the United States and keeps track of which products
-are exempt from sales tax and in which states each exemption applies.
-TaxCloud calculates sales tax in real-time for every state, city, and
-special jurisdiction in the United States.
-
-Configuration
-=============
-
-In TaxCloud
------------
-* Create a free account on `TaxCloud
-  <https://taxcloud.com/#register>`__ website.
-* Register your Odoo website on TaxCloud to get an *API ID* and an *API Key*.
-
-.. image:: taxcloud/taxcloud01.png
-  :align: center
-
-* In Settings on TaxCloud, click *Locations* to enter the location of your Office(s) & Warehouse(s).
-* In Settings on TaxCloud, click *Manage Tax States* to verify the states where you collect sales tax.
-
-In Odoo
--------
-* Go to :menuselection:`Invoicing / Accounting --> Configuration --> Settings`
-  and check *TaxCloud - Compute tax rates based on U.S. ZIP codes* (note: actually uses complete street address).
-* Enter your TaxCloud credentials.
-* Click SAVE to store your credentials.
-
-.. image:: taxcloud/taxcloud02.png
-  :align: center
-
-* Click the Refresh Icon next to *Default Category* to import the TIC product categories
-  from TaxCloud (Taxability Information Codes). Some categories may imply specific rates or attract product/service type exemptions.
-* Select your default *TIC Code*. This will apply to any new
-  product created.
-* Set a specific TaxCloud TIC Category on the *General Information* tab of the Product,
-  or on the Product Category.
-* Make sure your company address is complete (including the state
-  and the zip code). Go to :menuselection:`Settings --> Users & Companies --> Companies`
-  to open and edit your Company record.
-
-Automatically post taxes to the correct Tax Payable account
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-* For each one of your companies that uses TaxCloud, it might be necessary to create a 
-  **User-Defined Default** so that the new taxes generated by the TaxCloud integration are created 
-  with the correct Tax Payable account:
-
-.. warning::
-   A User-Defined Default impacts all records at creation.  It means that **every** new tax will be 
-   set up to record income in the specified Tax Payable account, unless the tax is manually edited
-   to specify a different income account (or there exists another User-Defined Default that takes 
-   precedence).
+====================
+TaxCloud integration
+====================
 
-* In :menuselection:`Accounting --> Configuration --> Chart of Accounts`, select the Tax Payable
-  account for the company. Take note of the account's ``id`` in the URL string. 
+TaxCloud calculates the sales tax rate in real time for every state, city, and special jurisdiction
+in the United States. It keeps track of which products are exempt from sales tax and in which states
+each exemption applies.
 
-.. image:: taxcloud/user-default-find-account-id.png
-   :alt: The account's ID can be found in the URL string as 'id=...'. 
+TaxCloud registration
+=====================
+
+Register an account on `TaxCloud.com <https://taxcloud.com/register>`_ and complete the setup.
+Once you go live, get the :guilabel:`TaxCloud API Keys` by clicking on :guilabel:`Stores`, then
+:guilabel:`Get Details`.
+
+.. image:: taxcloud/taxcloud-api-keys.png
    :align: center
+   :alt: Example of a store's TaxCloud API Keys
+
+Enable TaxCloud
+===============
+
+#. Go to :menuselection:`Accounting Dashboard --> Configuration --> Settings` and in the
+   :guilabel:`Taxes` section enable :guilabel:`TaxCloud`.
+#. Add the store's :guilabel:`Login ID` under :guilabel:`API ID` and the store's :guilabel:`Key`
+   under :guilabel:`API KEY`. Click on :guilabel:`Save`.
+#. Click the :guilabel:`Refresh` button (:guilabel:`🗘`) next to :guilabel:`Default Category` to
+   import the TIC :dfn:`Taxability Information Codes` product categories from TaxCloud. Some
+   categories may imply specific tax rates or exemptions.
+#. Select a :guilabel:`Default Category` and :guilabel:`Save`. The :guilabel:`Default Category` is
+   applied when no :guilabel:`TaxCloud Category` is set on your products or product categories,
+   or when no product is found on an order/invoice.
+
+   .. image:: taxcloud/taxcloud-settings.png
+      :align: center
+      :alt: Filling in TaxCloud API Keys in Odoo
+
+Set TaxCloud categories on products
+===================================
+
+If you need to use more than one TIC category (i.e., the :guilabel:`Default Category`), go to the
+product's :guilabel:`General Information` tab and select a :guilabel:`TaxCloud Category`.
+
+If you want to configure multiple products simultaneously, ensure they share the same
+:guilabel:`Product Category` and click on the external link button (:guilabel:`🡕`) to set a
+:guilabel:`TaxCloud Category` on the :guilabel:`Product Category` instead.
 
-* Activate the :ref:`developer mode <developer-mode>`, then go to 
-  :menuselection:`Settings --> Technical --> Actions --> User-Defined Defaults`, and 
-  click on *Create*.
+.. note::
+   If you set a :guilabel:`TaxCloud Category` on a product and another on its :guilabel:`Product
+   Category`, Odoo only considers the :guilabel:`TaxCloud Category` found on the product itself.
 
-* Click on *Field*, then, in the drop-down menu, on *Search More*. 
+   A :guilabel:`TaxCloud Category` set on a **parent product category** does not apply to its
+   **child product categories**. For example, if you set :guilabel:`TaxCloud Category` on the *All*
+   :guilabel:`Product Category`, it is not applied to the *All/Sales* :guilabel:`Product Category`.
 
-.. image:: taxcloud/user-default-search-field.png
-   :alt: Click on 'Search More' in the 'Field' drop-down menu. 
+.. important::
+   Make sure your company address is complete, including the state and the ZIP code. Go to
+   :menuselection:`Settings --> Companies: Update Info` to open and edit your company address.
+
+Automatically post taxes in the correct tax payable account
+===========================================================
+
+To make sure the new taxes generated by the TaxCloud integration are created with the correct
+**Tax Payable** account, create a **user-defined default**. This process should be repeated for each
+one of your companies that uses TaxCloud.
+
+.. warning::
+   A user-defined default impacts all records at creation. It means that **every** new tax is
+   set up to record income in the specified Tax Payable account unless the tax is manually edited to
+   specify a different income account (or if another user-defined default takes precedence).
+
+To do so, go to :menuselection:`Accounting Dashboard --> Configuration --> Accounting: Chart of
+Accounts`, find the company's :guilabel:`Tax Payable` account, and click on :guilabel:`Setup`. Take
+note of the number after `id=` in the URL string; it is the **Tax Payable account ID** and will
+be used later.
+
+.. image:: taxcloud/tax-payable-id.png
    :align: center
+   :alt: Example of Tax Payable account id in the URL string
+
+Activate the :ref:`developer mode <developer-mode>`, then go to :menuselection:`Settings -->
+Technical --> Actions: User-defined Defaults` and click on :guilabel:`Create`.
 
-* In the pop-up's search box, filter on the model ``tax.repartition.line`` and the field ``account``. 
-  Select the ``account`` field of the ``tax.repartition.line`` model. 
+Click on :guilabel:`Field` drop-down menu and then on :guilabel:`Search More...`.
 
-.. image:: taxcloud/user-default-select-field.png
-   :alt: Select the 'account' field of the 'tax.repartition.line' model. 
+.. image:: taxcloud/user-defaults-search-more.png
+   :alt: User-defined Defaults Field search
    :align: center
 
-* In the **Default Value** field, enter the ID of the company's Tax Payable account. 
-  Select the company for which this configuration should apply in the *Company* field. 
-  Click *Save*. 
+Use the search bar to filter for the :guilabel:`Tax Repartition Line` model, and use it a second
+time to filter for the :guilabel:`Account` field. Select the line with :guilabel:`Tax Repartition
+Line` under the :guilabel:`Model` column.
 
-.. image:: taxcloud/user-default-enter-default-account-id.png
-   :alt: Enter the ID of the company's Tax Payable account. 
+.. image:: taxcloud/user-defaults-search-filters.png
+   :alt: Searching for the Tax Repartition Line model and Account field
    :align: center
 
+Once you are back to the :guilabel:`User-defined Defaults` creation, enter the **Tax Payable account
+ID** you took note of earlier under the :guilabel:`Default Value (JSON format)` field.
 
-How it works
-============
+Select the company for which this configuration should apply under the :guilabel:`Company` field and
+click :guilabel:`Save`.
 
-Salestax is calculated in Odoo based on fiscal positions
-(see :doc:`fiscal_positions`).
-A Fiscal Position for the United States is created when installing *TaxCloud*.
-Everything works out-of-the-box.
+.. image:: taxcloud/user-defaults-complete-configuration.png
+   :align: center
+   :alt: Example of a User-defined Defaults configuration
 
-You can configure Odoo to automatically detect which Customers should use this fiscal
-position.  Go to :menuselection:`Accounting --> Configuration --> Fiscal Positions`
-to open and edit the record.
+Automatically detect the fiscal position
+========================================
 
-.. image:: taxcloud/taxcloud03.png
-  :align: center
+Sales taxes are calculated in Odoo based on :doc:`fiscal positions <fiscal_positions>`. A fiscal
+position for the United States is created when enabling TaxCloud.
 
-Now, this fiscal position is automatically set on any sales order, web order, or invoice
-when the customer country is *United States*. This triggers the
-automated tax computation.
+You can configure Odoo to automatically detect to which customers the fiscal position should be
+applied. To do so, go to :menuselection:`Accounting Dashboard --> Configuration --> Accounting:
+Fiscal Positions` and select :guilabel:`Automatic Tax Mapping (TaxCloud)`. Enable :guilabel:`Detect
+Automatically` and then :guilabel:`Save`.
 
-.. image:: taxcloud/taxcloud04.png
-  :align: center
+.. image:: taxcloud/fiscal-position-detect.png
+   :align: center
+   :alt: Detect Automatically setting on the TaxCloud fiscal position
 
-Add your product(s). You have two options to get Sales Tax on the Order.  You can confirm it,
-or you can save it and from the *Action* Menu choose **Update Taxes with TaxCloud**.
+Now, this fiscal position is automatically set on any order or invoice if the customer country is
+*United States*. This triggers the automated tax computation.
 
+.. note::
+   To get the sales taxes on a sales order, confirm it or click the :guilabel:`Update Taxes` button
+   next to :guilabel:`Add Shipping`.
 
-Coupons & Promotions
-====================
+Interaction with coupons and promotions
+=======================================
 
-If you use the Coupon or Promotion Programs, the integration with Taxcloud might seem a bit odd.
+If you use the **Coupon** or **Promotion Programs**, the integration with TaxCloud might behave
+unexpectedly. Indeed, as TaxCloud does not accept lines with negative amounts as part of the tax
+computation, the amount of the lines added by the promotion program must be deduced from the total
+of the lines it impacts.
 
-The problem lies with the fact that Taxcloud does not accept lines with negative amounts as part of
-the tax computation. This means that the amount of the lines added by the promotion program must be
-deduced from the total of the lines it impacts. This means, amongst other complications, that orders
-that use coupons or promotions with a Taxcloud fiscal position **must** be invoiced completely -
-you cannot create invoices for partial deliveries, etc.
+.. important::
+   This means, amongst other complications, that orders using coupons or promotions with a TaxCloud
+   fiscal position **must** be invoiced completely - you cannot create invoices for partial
+   deliveries, etc.
 
-Another specific oddity is possible in the UI: imagine that you sell a product from the Taxcloud
-category *[20110] Computers* and that you have a promotion program in place that provides a 50%
-discount on this product. If the tax rate for this particular product is 7%, the tax rate that will
-be computed from the Taxcloud integration will display 3.5%. This happens because the discount is
-included in the price that is sent to Taxcloud, but in Odoo this discount is in another line
-entirely. At the end of the day, your tax computation will be correct (since a 3.5% tax on the full
-price is the equivalent of a 7% tax on half the price), but this might be surprising from a user
-point of view.
+Another unexpected behavior is possible. For example, you sell a product for which you have a
+promotion program that provides a 50% discount. If the product's tax rate is 7%, the tax rate
+computed from the TaxCloud integration displays 3.5%. This happens because the discount is included
+in the price sent to TaxCloud. However, in Odoo, the discount is on another line entirely. Still,
+the tax computation is correct. Indeed, a 3.5% tax on the full price is the equivalent of a 7% tax
+on half the price, but this might be unexpected from a user point of view.
 
 .. seealso::
-   - :doc:`fiscal_positions`
+   :doc:`fiscal_positions`