[MOV] accounting: restructuration of the accounting documentation

This commit improves the structure of the accounting documentation by
- reducing the levels necessary to reach the information
- grouping some docs
- moving content to their parent category page (content in all levels)
- renaming some sections to reflect the structure of the app better

task-3330093

closes odoo/documentation#4479

X-original-commit: c68cc154ed
Signed-off-by: Castillo Jonathan (jcs) <jcs@odoo.com>

content/applications/finance/accounting/taxes/B2B_B2C.rst

@@ -0,0 +1,185 @@
+=================================================
+B2B (tax excluded) and B2C (tax included) pricing
+=================================================
+
+When working with consumers, prices are usually expressed with taxes
+included in the price (e.g., in most eCommerce). But, when you work in a
+B2B environment, companies usually negotiate prices with taxes excluded.
+
+Odoo manages both use cases easily, as long as you register your prices
+on the product with taxes excluded or included, but not both together.
+If you manage all your prices with tax included (or excluded) only, you
+can still easily do sales order with a price having taxes excluded (or
+included): that's easy.
+
+This documentation is only for the specific use case where you need to
+have two references for the price (tax included or excluded), for the
+same product. The reason of the complexity is that there is not a
+symmetrical relationship with prices included and prices excluded, as
+shown in this use case, in belgium with a tax of 21%:
+
+-  Your eCommerce has a product at **10€ (taxes included)**
+
+-  This would do **8.26€ (taxes excluded)** and a **tax of 1.74€**
+
+But for the same use case, if you register the price without taxes on
+the product form (8.26€), you get a price with tax included at 9.99€,
+because:
+
+-  **8.26€ \* 1.21 = 9.99€**
+
+So, depending on how you register your prices on the product form, you
+will have different results for the price including taxes and the price
+excluding taxes:
+
+-  Taxes Excluded: **8.26€ & 10.00€**
+
+-  Taxes Included: **8.26€ & 9.99€**
+
+.. note::
+  If you buy 100 pieces at 10€ taxes included, it gets even more
+  tricky. You will get: **1000€ (taxes included) = 826.45€ (price) +
+  173.55€ (taxes)** Which is very different from a price per piece at
+  8.26€ tax excluded.
+
+This documentation explains how to handle the very specific use case
+where you need to handle the two prices (tax excluded and included) on
+the product form within the same company.
+
+.. note::
+  In terms of finance, you have no more revenues selling your
+  product at 10€ instead of 9.99€ (for a 21% tax), because your revenue
+  will be exactly the same at 9.99€, only the tax is 0.01€ higher. So, if
+  you run an eCommerce in Belgium, make your customer a favor and set your
+  price at 9.99€ instead of 10€. Please note that this does not apply to
+  20€ or 30€, or other tax rates, or a quantity >1. You will also make you
+  a favor since you can manage everything tax excluded, which is less
+  error prone and easier for your salespeople.
+
+Configuration
+=============
+
+Introduction
+------------
+
+The best way to avoid this complexity is to choose only one way of
+managing your prices and stick to it: price without taxes or price with
+taxes included. Define which one is the default stored on the product
+form (on the default tax related to the product), and let Odoo compute
+the other one automatically, based on the pricelist and fiscal position.
+Negotiate your contracts with customers accordingly. This perfectly
+works out-of-the-box and you have no specific configuration to do.
+
+If you can not do that and if you really negotiate some prices with tax
+excluded and, for other customers, others prices with tax included, you
+must:
+
+#.  always store the default price **tax excluded** on the product form, and
+    apply a tax (price excluded on the product form)
+
+#.  create a pricelist with prices in **tax included**, for specific
+    customers
+
+#.  create a fiscal position that switches the tax excluded to a tax
+    included
+
+#.  assign both the pricelist and the fiscal position to customers who
+    want to benefit to this pricelist and fiscal position
+
+For the purpose of this documentation, we will use the above use case:
+
+-   your product default sale price is 8.26€ tax excluded
+
+-   but we want to sell it at 10€, tax included, in our shops or
+    eCommerce website
+
+.. _b2b_b2c/ecommerce:
+
+eCommerce
+---------
+
+If you only use B2C or B2B prices on your website, simply select the appropriate setting in the
+**Website** app settings.
+
+If you have both B2B and B2C prices on a single website, please follow these instructions:
+
+#. Activate the :ref:`developer mode <developer-mode>` and go to :menuselection:`General Settings
+   --> Users & Companies --> Groups`.
+#. Open either `Technical / Tax display B2B` or `Technical / Tax display B2C`.
+#. Under the :guilabel:`Users` tab, add the users requiring access to the price type. Add B2C users
+   in the B2C group and B2B users in the B2B group.
+
+Setting your products
+---------------------
+
+Your company must be configured with tax excluded by default. This is
+usually the default configuration, but you can check your **Default Sale
+Tax** from the menu :menuselection:`Configuration --> Settings`
+of the Accounting application.
+
+.. image:: B2B_B2C/price_B2C_B2B01.png
+  :align: center
+
+Once done, you can create a **B2C** pricelist. You can activate the
+pricelist feature per customer from the menu:
+:menuselection:`Configuration --> Settings` of the Sale application.
+Choose the option **different prices per customer segment**.
+
+Once done, create a B2C pricelist from the menu
+:menuselection:`Configuration --> Pricelists`.
+It's also good to rename the default pricelist into B2B to avoid confusion.
+
+Then, create a product at 8.26€, with a tax of 21% (defined as tax not
+included in price) and set a price on this product for B2C customers at
+10€, from the :menuselection:`Sales --> Products`
+menu of the Sales application:
+
+.. image:: B2B_B2C/price_B2C_B2B02.png
+  :align: center
+
+Setting the B2C fiscal position
+-------------------------------
+
+From the accounting application, create a B2C fiscal position from this
+menu: :menuselection:`Configuration --> Fiscal Positions`.
+This fiscal position should map the VAT 21% (tax excluded of price)
+with a VAT 21% (tax included in price)
+
+.. image:: B2B_B2C/price_B2C_B2B03.png
+  :align: center
+
+Test by creating a quotation
+============================
+
+Create a quotation from the Sale application, using the
+:menuselection:`Sales --> Quotations` menu. You should have the
+following result: 8.26€ + 1.73€ = 9.99€.
+
+.. image:: B2B_B2C/price_B2C_B2B04.png
+  :align: center
+
+Then, create a quotation but **change the pricelist to B2C and the
+fiscal position to B2C** on the quotation, before adding your product.
+You should have the expected result, which is a total price of 10€ for
+the customer: 8.26€ + 1.74€ = 10.00€.
+
+.. image:: B2B_B2C/price_B2C_B2B05.png
+  :align: center
+
+This is the expected behavior for a customer of your shop.
+
+Avoid changing every sale order
+===============================
+
+If you negotiate a contract with a customer, whether you negotiate tax
+included or tax excluded, you can set the pricelist and the fiscal
+position on the customer form so that it will be applied automatically
+at every sale of this customer.
+
+The pricelist is in the **Sales & Purchases** tab of the customer form,
+and the fiscal position is in the accounting tab.
+
+Note that this is error prone: if you set a fiscal position with tax
+included in prices but use a pricelist that is not included, you might
+have wrong prices calculated for you. That's why we usually recommend
+companies to only work with one price reference.

content/applications/finance/accounting/taxes/avatax.rst

@@ -0,0 +1,74 @@
+==================
+Avatax integration
+==================
+
+Avatax is a tax calculation provider that can be integrated in Odoo.
+
+.. _avatax/credentials:
+
+Credential configuration
+========================
+
+To integrate Avatax with Odoo, go to :menuselection:`Accounting --> Configuration --> Settings -->
+Taxes` and add your Avatax credentials in the :guilabel:`Avatax` section.
+
+.. tip::
+   If you do not yet have credentials, click on :guilabel:`How to Get Credentials`.
+
+.. image:: avatax/avatax-configuration-settings.png
+   :align: center
+   :alt: Configure Avatax settings
+
+.. _avatax/tax-mapping:
+
+Tax mapping
+===========
+
+The Avatax integration is available on Sale Orders and Invoices with the included Avatax fiscal
+position.
+
+Before using the integration, specify an :guilabel:`Avatax Category` on the product categories.
+
+.. image:: avatax/avatax-category.png
+   :align: center
+   :alt: Specify Avatax Category on products
+
+Avatax Categories may be overridden or set on individual products as well.
+
+.. image:: avatax/override-avatax-product-category.png
+   :align: center
+   :alt: Override product categories as needed
+
+.. _avatax/address-mapping:
+
+Address validation
+==================
+
+Manually validate customer addresses by clicking the :guilabel:`Validate address` link in the
+customer form view.
+
+.. image:: avatax/validate-customer-address.png
+   :align: center
+   :alt: Validate customer addresses
+
+If preferred, choose to keep the newly validated address or the original address in the wizard that
+pops up.
+
+.. image:: avatax/choose-customer-address.png
+   :align: center
+   :alt: Address validation wizard
+
+.. _avatax/tax-calculation:
+
+Tax calculation
+===============
+
+Automatically calculate taxes on Odoo quotations and invoices with Avatax by confirming the
+documents. Alternatively, calculate the taxes manually by clicking the :guilabel:`Compute taxes
+using Avatax` button while these documents are in draft mode.
+
+Use the :guilabel:`Avalara Code` field that's available on customers, quotations, and invoices to
+cross-reference data in Odoo and Avatax.
+
+.. seealso::
+   - :doc:`fiscal_positions`

content/applications/finance/accounting/taxes/cash_basis.rst

@@ -0,0 +1,116 @@
+================
+Cash basis taxes
+================
+
+Cash basis taxes are due when the payment is made, as opposed to standard taxes that are due when
+the invoice is confirmed. Reporting your income and expenses to the government based on the cash
+basis method is mandatory in some countries and under some conditions.
+
+.. example::
+   You sell a product in the 1st quarter of your fiscal year, and the payment is received in the 2nd
+   quarter. Based on the cash basis method, the tax you must pay is for the 2nd quarter.
+
+Configuration
+-------------
+
+Go to :menuselection:`Accounting --> Configuration --> Settings` and under the :guilabel:`Taxes`
+section, enable :guilabel:`Cash Basis`.
+
+Then, define the :guilabel:`Tax Cash Basis Journal`. Click on the external link button next to the
+journal to update its default properties such as the :guilabel:`Journal Name`, :guilabel:`Type` or
+:guilabel:`Short Code`.
+
+.. image:: cash_basis/tax_cash_basis_journal.png
+    :align: center
+    :alt: Select your Tax Cash Basis Journal and click on the external link
+
+.. note::
+   By default, the journal entries of the :guilabel:`Cash Basis Taxes` journal are named using the
+   :guilabel:`CABA` short code.
+
+Once this is done, go to :menuselection:`Accounting --> Configuration --> Accounting: Taxes` to
+configure your taxes. You can either :guilabel:`Create` a new tax or update an existing one by
+clicking on it.
+
+The :guilabel:`Account` column reflects the proper transitional accounts to post taxes until the
+payment is registered.
+
+.. image:: cash_basis/account_column.png
+    :align: center
+    :alt: Fill in the account column with a transitional accounts where taxes go until the payment
+       is registered
+
+In the :guilabel:`Advanced Options` tab, decide of the :guilabel:`Tax Exigilibity`. Select
+:guilabel:`Based on Payment`, so the tax is due when the payment of the invoice is received. You can
+then also define the :guilabel:`Cash Basis Transition Account` where the tax amount is recorded as
+long as the original invoice has not been reconciled.
+
+.. image:: cash_basis/advanced_options.png
+    :align: center
+    :alt: Fill in the Cash Basis Transition Account where taxes amounts go until payment
+        reconciliation.
+
+Impact of cash basis taxes on accounting
+----------------------------------------
+
+To illustrate the impact of cash basis taxes on accounting transactions, let's take an example with
+the sales of a product that costs 1,000$, with a cash basis tax of 15%.
+
+.. image:: cash_basis/customer_invoice_with_cbt.png
+    :align: center
+    :alt:
+
+The following entries are created in your accounting, and the tax report is currently empty.
+
++----------------------------+----------------------------+
+|**Customer journal (INV)**                               |
++============================+============================+
+| **Debit**                  |**Credit**                  |
++----------------------------+----------------------------+
+| Receivable $1,150          |                            |
++----------------------------+----------------------------+
+|                            |Income $1,000               |
++----------------------------+----------------------------+
+|                            |Temporary tax account $150  |
++----------------------------+----------------------------+
+
+When the payment is then received, it is registered as below :
+
++----------------------------+----------------------------+
+| **Bank journal (BANK)**                                 |
++============================+============================+
+| **Debit**                  |**Credit**                  |
++----------------------------+----------------------------+
+| Bank $1,150                |                            |
++----------------------------+----------------------------+
+|                            |Receivable $1,150           |
++----------------------------+----------------------------+
+
+.. note::
+    Once the payment is registered, you can use the :guilabel:`Cash Basis Entries` smart button on
+    the invoice to access them directly.
+
+Finally, upon reconciliation of the invoice with the payment, the below entry is automatically
+created:
+
++----------------------------+----------------------------+
+| **Tax Cash Basis Journal (Caba)**                       |
++============================+============================+
+| **Debit**                  |**Credit**                  |
++----------------------------+----------------------------+
+| Income account $1,000      |                            |
++----------------------------+----------------------------+
+| Temporary tax account $150 |                            |
++----------------------------+----------------------------+
+|                            |  Income account $1,000     |
++----------------------------+----------------------------+
+|                            | Tax Received $150          |
++----------------------------+----------------------------+
+
+The journal items :guilabel:`Income account` vs. :guilabel:`Income account` are neutral, but they
+are needed to ensure correct tax reports in Odoo with accurate base tax amounts.
+
+Using a default :guilabel:`Base Tax Received Account` is recommended so your balance is at zero and
+your income account is not polluted by unnecessary accounting movements. To do so, go to
+:menuselection:`Configuration --> Settings --> Taxes`, and select a
+:guilabel:`Base Tax Received Account` under :guilabel:`Cash Basis`.

content/applications/finance/accounting/taxes/eu_distance_selling.rst

@@ -0,0 +1,69 @@
+===================================
+EU intra-community distance selling
+===================================
+
+**Distance sales within the European Union** include cross-border sales of goods and services to a
+private consumer (B2C) in another EU Member State when the seller doesn't meet face-to-face with the
+customer. Organizations must ensure that the VAT on distance sales is paid to the Member State in
+which the goods or services are delivered.
+
+.. note::
+   This remains true even if your organization is located outside of the European Union.
+
+While this regulation mainly applies to :doc:`eCommerce <../../../websites/ecommerce>` sales to
+private EU consumers, it is also valid for mail order sales and telesales.
+
+The Union **One-Stop Shop (OSS)** is an online portal where businesses can register for the OSS and
+declare their intra-community distance sales. Each EU member state integrates an online OSS portal.
+
+The **EU intra-community Distance Selling** feature helps your organization comply with this
+regulation by creating and configuring new :doc:`fiscal positions <fiscal_positions>` and
+:doc:`taxes <../taxes>` based on your company's country.
+
+.. seealso::
+   - `European Commission: OSS | Taxation and Customs Union
+     <https://ec.europa.eu/taxation_customs/business/vat/oss_en>`_
+
+.. _eu_distance_selling/configuration:
+
+Configuration
+=============
+
+Go to :menuselection:`Accounting/Invoicing --> Settings --> Taxes`, then enable **EU intra-community
+Distance Selling** (or **EU Digital Goods VAT** if you created your database before July 1, 2021),
+and *Save*.
+
+.. image:: eu_distance_selling/enable-feature.png
+   :align: center
+   :alt: EU intra-community Distance Selling feature in Odoo Accounting settings
+
+.. important::
+   Please :ref:`upgrade the module <general/upgrade>` `l10n_eu_service` if you already installed it
+   before **July 1, 2021**, or if you activated the feature **EU Digital Goods VAT** in the
+   Accounting settings. Then, make sure to :ref:`refresh the tax mapping
+   <eu_distance_selling/refresh-mapping>`.
+
+.. _eu_distance_selling/taxes:
+
+Fiscal Positions and Taxes
+==========================
+
+Once enabled, the feature automatically creates all the necessary taxes and fiscal positions needed
+for each EU member state, based on your company's country.
+
+We highly recommend checking that the proposed mapping is suitable for the products and services you
+sell before using it.
+
+.. _eu_distance_selling/refresh-mapping:
+
+Refresh tax mapping
+-------------------
+
+Whenever you add or modify taxes, you can update automatically your fiscal positions.
+
+To do so, go to :menuselection:`Accounting/Invoicing --> Settings --> Taxes --> EU intra-community
+Distance Selling` and click on the *Refresh tax mapping* button.
+
+.. seealso::
+   - :doc:`fiscal_positions`
+   - :doc:`../taxes`

content/applications/finance/accounting/taxes/fiscal_positions.rst

@@ -0,0 +1,113 @@
+==========================================
+Fiscal positions (tax and account mapping)
+==========================================
+
+Default taxes and accounts are set on products and customers to create new transactions on the fly.
+However, you might have to use different taxes and record the transactions on different accounts,
+according to your customers' and providers' localizations and business types.
+
+**Fiscal Positions** allow you to create *sets of rules* to automatically adapt the taxes and the
+accounts used for a transaction.
+
+.. image:: fiscal_positions/fiscal-positions-intra-community.png
+   :align: center
+   :alt: Example: Belgian to Intra-Community tax mapping with Fiscal Positions in Odoo Accounting
+
+They can be applied in various ways:
+
+- :ref:`automatically applied, based on some rules <fiscal_positions/automatic>`
+- :ref:`manually applied on a transaction <fiscal_positions/partner>`
+- :ref:`assigned to a partner, on its contact form <fiscal_positions/transaction>`
+
+.. note::
+   A few Fiscal Positions are already preconfigured on your database, as part of your :ref:`fiscal
+   localization package <fiscal_localizations/packages>`.
+
+Configuration
+=============
+
+ .. _fiscal_positions/mapping:
+
+Tax and Account Mapping
+-----------------------
+
+To edit or create a Fiscal Position, go to :menuselection:`Accounting --> Configuration --> Fiscal
+Positions`, and open the entry you want to modify or click on *Create*.
+
+The mapping of taxes and accounts is based on the default taxes and accounts defined in the
+products' forms.
+
+- To map to another tax or account, fill out the right column (**Tax to Apply**/**Account to Use
+  Instead**).
+- To remove a tax, rather than replacing it with another, leave the field **Tax to Apply** empty.
+- To replace a tax with multiple other taxes, add multiple lines with the same **Tax on Product**.
+
+.. note::
+   The mapping only works with *active* taxes. Therefore, make sure they are active by going to
+   :menuselection:`Accounting --> Configuration --> Taxes`.
+
+.. _fiscal_positions/automatic:
+
+Automatic application
+---------------------
+
+You can configure your Fiscal Positions to be applied automatically, following a set of conditions.
+
+To do so, open the Fiscal Position you want to modify and click on **Detect Automatically**. You can
+configure a few conditions:
+
+- **VAT Required**: The VAT number *must* be indicated in the customer's contact form.
+- **Country Group** / **Country**: The Fiscal Position is applied to these countries.
+
+.. image:: fiscal_positions/fiscal-positions-automatic.png
+   :align: center
+   :alt: Example of settings to apply a Fiscal Position automatically
+
+.. note::
+   Taxes on **eCommerce orders** are automatically updated once the visitor has logged in or filled
+   out their billing details.
+
+.. important::
+   The Fiscal Positions' **sequence** - the order in which they are arranged - defines which
+   Fiscal Position to apply if the conditions are met in multiple Fiscal Positions.
+
+   For example, if the first Fiscal Position targets *country A*, and the second Fiscal Position
+   targets a *Country Group* that also comprises *country A*, only the first Fiscal Position will be
+   applied to customers from *country A*.
+
+.. _fiscal_positions/application:
+
+Application
+===========
+
+.. _fiscal_positions/partner:
+
+Assign a Fiscal Position to a partner
+-------------------------------------
+
+You can manually define which Fiscal Position must be used by default for a specific partner.
+
+To do so, open the partner's contact form, go to the **Sales & Purchase** tab, edit the **Fiscal
+Position** field, and click on *Save*.
+
+.. image:: fiscal_positions/fiscal-positions-partner.png
+   :align: center
+   :alt: Selection of a Fiscal Position on a Sales Order / Invoice / Bill in Odoo Accounting
+
+.. _fiscal_positions/transaction:
+
+Choose Fiscal Positions manually on Sales Orders, Invoices, and Bills
+---------------------------------------------------------------------
+
+To manually select which Fiscal Position to use for a new Sales Order, Invoice, or Bill, go to the
+**Other Info** tab and select the right **Fiscal Position** *before* adding product lines.
+
+.. image:: fiscal_positions/fiscal-positions-transaction.png
+   :align: center
+   :alt: Selection of a Fiscal Position on a Sales Order / Invoice / Bill in Odoo Accounting
+
+.. seealso::
+
+  * :doc:`../taxes`
+  * :doc:`taxcloud`
+  * :doc:`B2B_B2C`

content/applications/finance/accounting/taxes/retention.rst

@@ -0,0 +1,70 @@
+=================
+Withholding taxes
+=================
+
+A withholding tax, also called a retention tax, is a government
+requirement for the payer of a customer invoice to withhold or deduct
+tax from the payment, and pay that tax to the government. In most
+jurisdictions, withholding tax applies to employment income.
+
+With normal taxes, the tax is added to the subtotal to give you the
+total to pay. As opposed to normal taxes, withholding taxes are deducted
+from the amount to pay, as the tax will be paid by the customer.
+
+As, an example, in Colombia you may have the following invoice:
+
+.. image:: retention/retention03.png
+   :align: center
+
+In this example, the **company** who sent the invoice owes $20 of taxes to
+the **government** and the **customer** owes $10 of taxes to the **government**.
+
+Configuration
+=============
+
+In Odoo, a withholding tax is defined by creating a negative tax. For a
+retention of 10%, you would configure the following tax (accessible
+through :menuselection:`Configuration --> Taxes`):
+
+.. image:: retention/retention04.png
+   :align: center
+
+In order to make it appear as a retention on the invoice, you should set
+a specific tax group **Retention** on your tax, in the **Advanced Options**
+tab.
+
+.. image:: retention/retention02.png
+   :align: center
+
+Once the tax is defined, you can use it in your products, sales order or
+invoices.
+
+.. tip::
+    If the retention is a percentage of a regular tax, create a Tax with a
+    **Tax Computation** as a **Tax Group** and set the two taxes in this group
+    (normal tax and retention).
+
+Applying retention taxes on invoices
+====================================
+
+Once your tax is created, you can use it on customer forms, sales order
+or customer invoices. You can apply several taxes on a single customer
+invoice line.
+
+.. image:: retention/retention01.png
+   :align: center
+
+.. note::
+    When you see the customer invoice on the screen, you get only a
+    **Taxes line** summarizing all the taxes (normal taxes & retentions).
+    But when you print or send the invoice, Odoo does the correct
+    grouping amongst all the taxes.
+
+The printed invoice will show the different amounts in each tax group.
+
+.. image:: retention/retention03.png
+   :align: center
+
+.. seealso::
+
+  * :doc:`../taxes`

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

@@ -0,0 +1,151 @@
+====================
+TaxCloud integration
+====================
+
+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.
+
+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.
+
+.. 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.
+
+   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`.
+
+.. 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`.
+
+Click on :guilabel:`Field` drop-down menu and then on :guilabel:`Search More...`.
+
+.. image:: taxcloud/user-defaults-search-more.png
+   :alt: User-defined Defaults Field search
+   :align: center
+
+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-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.
+
+Select the company for which this configuration should apply under the :guilabel:`Company` field and
+click :guilabel:`Save`.
+
+.. image:: taxcloud/user-defaults-complete-configuration.png
+   :align: center
+   :alt: Example of a User-defined Defaults configuration
+
+Automatically detect the fiscal position
+========================================
+
+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.
+
+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/fiscal-position-detect.png
+   :align: center
+   :alt: Detect Automatically setting on the TaxCloud fiscal position
+
+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`.
+
+Interaction with coupons and promotions
+=======================================
+
+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.
+
+.. 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 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`

content/applications/finance/accounting/taxes/vat_validation.rst

@@ -0,0 +1,43 @@
+===========================
+VIES VAT numbers validation
+===========================
+
+**VAT Information Exchange System** - abbreviated **VIES** - is a tool provided by the European
+Commission that allows you to check the validity of VAT numbers of companies registered in the
+European Union.
+
+Odoo provides a feature to **Verify VAT Numbers** when you save a contact. This helps you make sure
+that your contacts provided you with a valid VAT number without leaving Odoo interface.
+
+Configuration
+=============
+
+To enable this feature, go to :menuselection:`Accounting --> Configuration --> Settings --> Taxes`,
+enable the **Verify VAT Numbers** feature, and click on *Save*.
+
+.. image:: vat_validation/vat-validation-configuration.png
+   :align: center
+   :alt: Enable "Verify VAT Numbers" in Odoo Accounting
+
+VAT Number validation
+=====================
+
+Whenever you create or modify a contact, make sure to fill out the **Country** and **VAT** fields.
+
+.. image:: vat_validation/vat-validation-contact-form.png
+   :align: center
+   :alt: Fill out the contact form with the country and VAT number before clicking on *Save*
+
+When you click on *Save*, Odoo runs a VIES VAT number check, and displays an error message if the
+VAT number is invalid.
+
+.. image:: vat_validation/vat-validation-error.png
+   :align: center
+   :alt: Odoo displays an error message instead of saving when the VAT number is invalid
+
+.. important::
+   This tool checks the VAT number's validity but does not check the other fields' validity.
+
+.. seealso::
+
+   - `European Commission: VIES search engine <https://ec.europa.eu/taxation_customs/vies/vatRequest.html>`__