[IMP] Taxes: improve tax configuration doc

task-5094417

This commit rewrites the Taxes page. Previously, it came across as a
huge list of tax configuration options. We now structure it as follows:
1. an overview of the tax flow in Odoo;
2. a set-up guide for taxes for new users;
3. an explanation of the most common configuration options.

The options related to the tax computation are split into a separate
Tax Computation page, in which we also improve the following sections:
- Tax computations:
  At the moment, the section for the `Percentage of Price tax included`
  tax computation doesn't distinguish itself enough from the 'Included
  in Price' option which people usually want.
  We also improve the examples.
- Included in Price
- Affects base of subsequent taxes
- Base affected by preceding taxes: this option was not documented, so
  we add a section for it.

Ultimately, we plan to rewrite the Tax Computation page to provide a
better explanation of how the tax computation actually works, and be
more helpful at guiding the user to configure their taxes.

X-original-commit: 0f4aa202de

content/applications/finance/accounting/taxes.rst

@@ -4,167 +4,229 @@
 Taxes
 =====
 
-There are numerous types of **taxes**, and their application varies greatly, depending mostly on
-your company's localization. To make sure they are recorded with accuracy, Odoo's tax engine
-supports all kinds of uses and computations.
+Tax regulations generally require companies to compute tax amounts on sales, keep a record of
+accumulated tax debit and credit, and periodically file this information in tax returns.
+
+Overview
+========
+
+In general, managing taxes in Odoo involves the following steps:
+
+1. Taxes are added on individual lines of documents created via the Sale, Purchase, Accounting and
+   Point of Sale apps.
+2. Odoo automatically computes tax amounts on the documents.
+3. On accounting documents, Odoo generates journal items to keep track of tax debit and tax credit.
+4. The total base, tax debit and tax credit for a period can be viewed in the Tax Return report
+   and used to file a tax return.
+
+Taxes on sales and purchases
+----------------------------
+
+Most sale and purchase documents have a :guilabel:`Taxes` field where taxes can be applied to
+individual lines. This includes :doc:`invoices <customer_invoices>` and :doc:`vendor bills
+<vendor_bills>` in the :guilabel:`Accounting` app, :doc:`sales quotations
+<../../sales/sales/sales_quotations>` in the :guilabel:`Sales` app, and :doc:`purchase orders
+<../../inventory_and_mrp/purchase/manage_deals/rfq>` in the :guilabel:`Purchase` app.
+
+.. image:: taxes/invoice-tax.png
+   :alt: Adding a 21% tax on an invoice line.
+
+.. tip::
+   When adding a product to a sale or purchase line, the taxes :ref:`assigned to the product
+   <taxes/product>` are automatically applied on the line.
+
+.. note::
+   In the :doc:`Point of Sale <../../sales/point_of_sale>`, the taxes :ref:`assigned to the products
+   <taxes/product>` are applied directly to the order and cannot be changed except by a
+   :doc:`fiscal position <taxes/fiscal_positions>`.
+
+Automatic computation of tax amounts
+------------------------------------
+
+Applying a tax on a sale or purchase line lets Odoo automatically compute a tax amount based on
+the sale or purchase line's subtotal and the tax's configuration. The details of the computation are
+explained in the :doc:`Tax Computation <taxes/tax_computation>` page.
+
+.. image:: taxes/invoice-tax-amount.png
+   :alt: Odoo automatically computes a tax amount for the 21% tax.
+
+Automatic generation of tax journal items
+-----------------------------------------
+
+Upon applying a tax on an :doc:`Invoice <customer_invoices>` or :doc:`Vendor Bill <vendor_bills>`, a
+tax payable journal item is automatically generated with the tax amount. This keeps track of the tax
+debit or credit associated with the transaction.
+
+Furthermore, the tax amount is added to the amount due on the Account Receivable or Payable journal
+item.
+
+Finally, :ref:`Tax Grids <tax-returns/tax-grids>` are added both to the automatically created tax
+payable journal item and to the invoice line on which the tax is applied. These tags are used to
+retrieve the journal items corresponding to the tax's base and tax amount in the :doc:`Tax Return
+<reporting/tax_returns>` report.
+
+.. image:: taxes/invoice-tax-items.png
+   :alt: Odoo automatically generates a tax payable journal item for the 21% tax.
+
+.. note::
+   If :doc:`Cash Basis <taxes/cash_basis>` is enabled, upon reconciling the invoice or vendor bill
+   with the payment, an additional journal entry is created to represent the creation of the tax
+   debit or credit at that point in time.
+
+Filing tax returns
+------------------
+
+The :doc:`Tax Return <reporting/tax_returns>` report aggregates the base and tax amounts from
+invoices and vendor bills over a given period and presents it in a format tailored to the
+:doc:`fiscal localization <../fiscal_localizations>` country.
+
+The amounts presented in the :guilabel:`Tax Return` can be used to complete tax declarations that
+need to be periodically submitted to the government. In most cases, there is a one-to-one
+correspondence between the lines of the :guilabel:`Tax Return` and the official tax declaration,
+allowing amounts to simply be copied from one to the other.
+
+.. image:: taxes/tax-return-base.png
+   :alt: The base section of the Tax Return report for Belgium.
+
+.. image:: taxes/tax-return-tax.png
+   :alt: The tax section of the Tax Return report for Belgium.
+
+.. _taxes/configuration:
+
+Basic tax configuration
+=======================
+
+The following basic steps will set up taxes for production use in Odoo.
+
+1. Enable any relevant :ref:`company-wide options <taxes/configuration/company>`
+2. Activate any needed :ref:`pre-configured taxes <taxes/list_activation>`
+3. Assign taxes on your :ref:`products <taxes/product>`
+
+.. _taxes/configuration/company:
+
+Company-wide options
+--------------------
+
+To access these configuration options, go to :menuselection:`Accounting --> Configuration
+--> Settings` and scroll down to :guilabel:`Taxes`.
 
 .. _taxes/default:
 
 Default taxes
-=============
+~~~~~~~~~~~~~
 
-**Default taxes** define which taxes are automatically selected when creating a new product. They
-are also used to prefill the :guilabel:`Taxes` field when adding a new line on an invoice in
-:ref:`Accounting Firms <accounting/fiduciaries>` mode.
+The default :guilabel:`Sales Tax` and :guilabel:`Purchase Tax` are automatically set on products
+when creating new products.
 
-.. image:: taxes/default-configuration.png
-   :alt: Odoo fills out the Tax field automatically according to the Default Taxes
+If :ref:`Accounting Firms <accounting/fiduciaries>` mode is enabled, the default sales tax is
+automatically set on new invoice lines, and the default purchase tax is automatically set on new
+vendor bill lines.
 
+<<<<<<< 4b4af5e1e29def3a5a804e4be8535b1bab9d1e3f
 To change your **default taxes**, go to :menuselection:`Accounting --> Configuration --> Settings`,
 scroll down to the :guilabel:`Taxes` section, select the appropriate default sales and purchase
 taxes in the :guilabel:`Default Taxes` field, and click on :guilabel:`Save`.
+||||||| 4186daf2e61a45afefa1be7f5c7cf6169daf2324
+To change your **default taxes**, go to :menuselection:`Accounting --> Configuration --> Settings
+--> Taxes --> Default Taxes`, select the appropriate taxes for your default sales tax and purchase
+tax, and click on :guilabel:`Save`.
+=======
+:guilabel:`Prices` can be changed to :guilabel:`Tax Included` to treat all taxes as :ref:`Tax
+Included <taxes/included-in-price>` by default. This would be appropriate if all of a company's
+pricing is done tax-included. If only some of a company's pricing is tax-included, individual taxes
+can be set as :guilabel:`Tax Included`.
+>>>>>>> 0f4aa202de95a38018c44f21f5c39762cfc11b05
 
-.. image:: taxes/default-taxes.png
-   :alt: Define which taxes to use by default on Odoo
+EU intra-community distance selling
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. note::
-   **Default taxes** are automatically set up according to the country selected at the creation of
-   your database, or when you set up a :ref:`fiscal localization package
-   <fiscal_localizations/packages>` for your company.
+Activate this option if you need to sell to consumers in other EU countries and apply local VAT
+rates.
+
+.. seealso::
+   :doc:`EU intra-community distance selling<taxes/eu_distance_selling>`
+
+Cash basis
+~~~~~~~~~~
+
+Activate this option if taxes must be accounted for on a cash rather than accruals basis. This might
+be the case if the company operates under such a legal regime. Some countries mandate cash basis
+accounting, in which case this option will be activated by default by the :doc:`fiscal localization
+package <../fiscal_localizations>`.
+
+.. seealso::
+   :doc:`Cash Basis <taxes/cash_basis>`
 
 .. _taxes/list_activation:
 
-Activate taxes from the list view
-=================================
+Activate pre-configured taxes
+-----------------------------
 
-As part of your :ref:`fiscal localization package <fiscal_localizations/packages>`, most of your
-country's sales taxes are already preconfigured on your database. However, only a few taxes are
-activated by default. To activate taxes relevant to your business, go to :menuselection:`Accounting
---> Configuration --> Taxes` and enable the toggle button under the :guilabel:`Active` column.
+The list of taxes can be accessed at :menuselection:`Accounting --> Configuration --> Taxes`.
 
-.. image:: taxes/list.png
-   :alt: Activate pre-configured taxes in Odoo Accounting
+By default, inactive taxes are created for most sales tax rates by the :doc:`fiscal localization
+<../fiscal_localizations>` package, but only the main tax rate is active by default. To activate an
+inactive tax, click the toggle in the :guilabel:`Active` column.
 
-.. _taxes/configuration:
+.. _taxes/product:
 
-Configuration
-=============
+Assign taxes on products
+------------------------
 
-To edit or create a **tax**, go to :menuselection:`Accounting --> Configuration --> Taxes` and open
-a tax or click on :guilabel:`New`.
+To configure the taxes used for each product, go to :menuselection:`Accounting --> Customers -->
+Products`, select the product to configure, and fill the :guilabel:`Sales Taxes` and
+:guilabel:`Purchase Taxes` fields. These taxes are automatically applied when adding the product to
+a sale or purchase.
 
-.. image:: taxes/edit.png
-   :alt: Edition of a tax in Odoo Accounting
+.. tip::
+   Use the :ref:`Default Taxes <taxes/default>` company-wide setting to automatically fill these
+   fields on new products.
 
-Basic options
--------------
+.. _taxes/configuration/advanced:
+
+Advanced tax configuration
+==========================
+
+The following aspects of a tax can be customized:
+
+- How the tax :ref:`appears in the backend <taxes/configuration/back-end>`
+- How the tax :ref:`appears to customers <taxes/configuration/customer>`
+- The details of the :doc:`tax computation <taxes/tax_computation>`
+- How tax payable journal items are :ref:`created <taxes/definition-tab>`
+- :doc:`Fiscal positions <taxes/fiscal_positions>` (how to replace a tax by another tax under
+  certain conditions)
+
+To open a tax's configuration, go to :menuselection:`Accounting --> Configuration --> Taxes`, then
+click the tax name.
+
+.. _taxes/configuration/back-end:
+
+Configure back-end appearance and availability
+----------------------------------------------
+
+The following options control how a tax appears to users in the Odoo back-end.
 
 .. _taxes/name:
 
 Tax name
 ~~~~~~~~
 
-The **tax name** is displayed for backend users in the :guilabel:`Taxes` field in
-:doc:`sales orders <../../sales/sales>`, :doc:`invoices <customer_invoices>`, product forms, etc.
-
-.. _taxes/computation:
-
-Tax computation
-~~~~~~~~~~~~~~~
-
-- **Group of Taxes**
-
-  The tax is a combination of multiple sub-taxes. You can add as many taxes as you want, in the
-  order you want them to be applied.
-
-  .. important::
-     Make sure that the tax sequence is correct, as the order in which they are may impact the
-     taxes' amounts computation, especially if one of the taxes :ref:`affects the base of the
-     subsequent ones <taxes/base-subsequent>`.
-
-- **Fixed**
-
-  The tax has a fixed amount in the default currency. The amount remains the same, regardless of the
-  sales price.
-
-.. example::
-   A product has a sales price of $1000, and we apply a $10 *fixed* tax. We then have:
-
-   +-------------+-------------+----------+----------+
-   | Product     | Price       | Tax      | Total    |
-   | sales price | without tax |          |          |
-   +=============+=============+==========+==========+
-   | 1,000       | 1,000       | 10       | 1,010.00 |
-   +-------------+-------------+----------+----------+
-
-- **Percentage of price**
-
-  The *sales price* is the taxable basis: the tax amount is computed by multiplying the sales price
-  by the tax percentage.
-
-.. example::
-   A product has a sales price of $1000, and we apply a *10% of Price* tax. We then have:
-
-   +-------------+-------------+----------+----------+
-   | Product     | Price       | Tax      | Total    |
-   | sales price | without tax |          |          |
-   +=============+=============+==========+==========+
-   | 1,000       | 1,000       | 100      | 1,100.00 |
-   +-------------+-------------+----------+----------+
-
-- **Percentage of Price Tax Included**
-
-  The **total** is the taxable basis: the tax amount is a percentage of the total.
-
-.. example::
-   A product has a Sales Price of $1000, and we apply a *10% of Price Tax Included* tax. We then
-   have:
-
-   +-------------+-------------+----------+----------+
-   | Product     | Price       | Tax      | Total    |
-   | sales price | without tax |          |          |
-   +=============+=============+==========+==========+
-   | 1,000       | 1,000       | 111.11   | 1,111.11 |
-   +-------------+-------------+----------+----------+
-
-- **Python code**
-
-  A tax defined as **Python code** consists of two snippets of Python code that are executed in a
-  local environment containing data such as the unit price, product or partner.
-  :guilabel:`Python Code` defines the amount of the tax, and :guilabel:`Applicable Code` defines if
-  the tax is to be applied. The formula is found at the bottom of the :guilabel:`Definition` tab.
-
-.. example::
-   :guilabel:`Python Code`: `result = price_unit * 0.10`
-   :guilabel:`Applicable Code`: `result = true`
-
-.. _taxes/active:
-
-Active
-~~~~~~
-
-Only **active** taxes can be added to new documents.
-
-.. important::
-   It is not possible to delete taxes that have already been used. Instead, you can deactivate them
-   to prevent future use.
-
-.. note::
-   This field can be modified from the :ref:`list view <taxes/list_activation>`.
+The :guilabel:`Tax Name` appears for backend users in the :guilabel:`Taxes` field in :doc:`sales
+orders <../../sales/sales>`, :doc:`invoices <customer_invoices>`, product forms, etc.
 
 .. _taxes/scope:
 
 Tax type
 ~~~~~~~~
 
-The :guilabel:`Tax Type` determines the tax application, which also restricts where it is displayed.
+The :guilabel:`Tax Type` determines where the tax is available to be selected.
 
 - **Sales**: Customer invoices, product customer taxes, etc.
 - **Purchase**: Vendor bills, product vendor taxes, etc.
 - **None**
 
 .. tip::
-   You can use :guilabel:`None` for taxes that you want to include in a :ref:`Group of Taxes
+   Use :guilabel:`None` for taxes that you want to include in a :ref:`Group of Taxes
    <taxes/computation>` but that you do not want to list along with other sales or purchase taxes.
 
 Tax scope
@@ -173,6 +235,7 @@ Tax scope
 The :guilabel:`Tax Scope` restricts the use of taxes to a type of product, either **goods** or
 **services**.
 
+<<<<<<< 4b4af5e1e29def3a5a804e4be8535b1bab9d1e3f
 .. _taxes/tax-mapping:
 
 Tax mapping
@@ -214,138 +277,82 @@ default product tax.
    Tax mapping only works with :ref:`taxes/active` taxes.
 
 .. _taxes/definition-tab:
+||||||| 4186daf2e61a45afefa1be7f5c7cf6169daf2324
+.. _taxes/definition-tab:
+=======
+Description
+~~~~~~~~~~~
+>>>>>>> 0f4aa202de95a38018c44f21f5c39762cfc11b05
 
-Definition tab
---------------
+The :guilabel:`Description` can be edited for the purpose of internal documentation.
 
-Allocate with precision the amount of the taxable basis or percentages of the computed tax to
-multiple accounts and tax grids.
+.. _taxes/configuration/customer:
 
-.. image:: taxes/definition.png
-   :alt: Allocate tax amounts to the right accounts and tax grids
-
-- **Based On**:
-
-  - :guilabel:`Base`: the price on the invoice line
-  - :guilabel:`% of tax`: a percentage of the computed tax.
-
-- **Account**: if defined, an additional journal item is recorded.
-- **Tax Grids**:  used to generate :doc:`tax reports <reporting/tax_returns>`
-  automatically, according to your country's regulations.
-
-.. _taxes/advanced-tab:
-
-Advanced options tab
---------------------
+Configure how the tax appears to your customers
+-----------------------------------------------
 
 .. _taxes/label-invoices:
 
 Label on invoices
 ~~~~~~~~~~~~~~~~~
 
-The tax label is displayed on each invoice line in the :guilabel:`Taxes` column. This is visible to
-*front-end* users on exported invoices, in customer portals, etc.
+The :guilabel:`Label on Invoices` appears on invoice lines in invoice PDFs and on the customer
+portal.
 
-.. image:: taxes/invoice-label.png
-   :alt: The label on invoices is displayed on each invoice line
+.. image:: taxes/invoice-portal-tax.png
+   :alt: The Label on Invoice shows on the invoice line when viewed in the customer portal.
 
 .. _taxes/tax-group:
 
 Tax group
 ~~~~~~~~~
 
-Select which **tax group** the tax belongs to. The tax group name is the displayed above the
-**total** line on exported invoices and in customer portals.
+The :guilabel:`Tax Group` is shown in the totals section of the invoice, in invoice PDFs and on the
+customer portal. Multiple taxes that belong to the same tax group are aggregated together into a
+single tax amount.
 
-Tax groups include different iterations of the same tax. This can be useful when you must record
-the same tax differently according to :doc:`fiscal positions <taxes/fiscal_positions>`.
+.. image:: taxes/invoice-portal-total.png
+   :alt: The Tax Group shows in the totals section when viewed in the customer portal.
 
-.. example::
+.. _taxes/definition-tab:
 
-   .. image:: taxes/invoice-tax-group.png
-      :alt: The Tax Group name is different from the Label on Invoices
+Configure how tax journal items are created
+-------------------------------------------
 
-   In the example above, the :guilabel:`0% EU S` tax for intra-community customers in Europe records
-   the amount on specific accounts and tax grids. However, it remains a 0% tax to the customer. This
-   is why the label indicates :guilabel:`0% EU S`, and the tax group name above the
-   :guilabel:`Total` line indicates :guilabel:`VAT 0%`.
+The :guilabel:`Distribution for Invoices` and :guilabel:`Distribution for Refunds` sections control
+the generation of tax payable journal items in invoices and credit notes, respectively. They also
+determine which :guilabel:`Tax Grids` are set on invoice lines when this tax is applied.
 
-.. important::
-   Taxes have three different labels, each one having a specific use. Refer to the following table
-   to see where they are displayed.
+Each of these sections should contain one :guilabel:`Base` line, one or more :guilabel:`% of tax`
+lines amounting to 100% (e.g. one 100% line, or two 50% lines), and optionally, one or more
+:guilabel:`% of tax` lines amounting to -100.00%.
 
-   +------------------+-------------------------+-------------------------+
-   | :ref:`Tax Name   | :ref:`Label on Invoice  | :ref:`Tax Group         |
-   | <taxes/name>`    | <taxes/label-invoices>` | <taxes/tax-group>`      |
-   +==================+=========================+=========================+
-   | Backend          | :guilabel:`Taxes` column| Above the               |
-   |                  | on exported invoices    | :guilabel:`Total` line  |
-   |                  |                         | on exported invoices    |
-   +------------------+-------------------------+-------------------------+
+The :guilabel:`Base` line can have one or more :ref:`Tax Grids <tax-returns/tax-grids>` set, which
+are added to the invoice line on which the tax is applied.
 
-.. _taxes/analytic-cost:
+The :guilabel:`% of tax` lines control the creation of tax payable journal items. The tax amount is
+distributed according to the percentages on these lines, and each line is then used as a template to
+create a tax payable journal item with the same :guilabel:`Account` and :guilabel:`Tax Grids`. If
+the :guilabel:`Account` is not specified, it defaults to the account of the original invoice line on
+which the tax is applied.
 
-Include in analytic cost
-~~~~~~~~~~~~~~~~~~~~~~~~
+Typical cases include:
 
-With this option activated, the tax amount is assigned to the same **analytic account** as the
-invoice line.
+- one :guilabel:`100% of tax` line: this is the most common case where the tax amount should appear
+  on a single tax payable journal item.
+- one :guilabel:`100% of tax` and one :guilabel:`-100% of tax` line: this is appropriate if the tax
+  simultaneously generates both a tax debit and a tax credit which cancel each other out (e.g. EU
+  intra-community reverse-charge VAT).
+- one :guilabel:`50% of tax` line that specifies a Tax Payable :guilabel:`Account` and another
+  :guilabel:`50% of tax` line that does not specify an account: this is appropriate for partially
+  deductible purchase VAT, where part of the tax must be considered an expense rather than a tax
+  credit asset that can offset tax liability.
 
-.. _taxes/included-in-price:
+.. image:: taxes/distribution-invoices.png
+   :alt: The Distribution for Invoices of a 21% VAT tax.
 
-Included in price
-~~~~~~~~~~~~~~~~~
-
-With this option activated, the total (including the tax) equals the **sales price**.
-
-`Total = Sales Price = Computed Tax-Excluded price + Tax`
-
-.. example::
-   A product has a sales price of $1000, and we apply a *10% of Price* tax, which is *included in
-   the price*. We then have:
-
-   +-------------+-------------+----------+----------+
-   | Product     | Price       | Tax      | Total    |
-   | sales price | without tax |          |          |
-   +=============+=============+==========+==========+
-   | 1,000       | 900.10      | 90.9     | 1,000.00 |
-   +-------------+-------------+----------+----------+
-
-.. note::
-   If you need to define prices accurately, both tax-included and tax-excluded, please refer to the
-   following documentation: :doc:`taxes/B2B_B2C`.
-
-.. note::
-   By default, only the :guilabel:`Tax excluded` column is displayed on invoices. To display the
-   :guilabel:`Tax included` column, click the **dropdown toggle** button and check
-   :guilabel:`Tax incl.`.
-
-   .. image:: taxes/toggle-button.png
-
-.. _taxes/base-subsequent:
-
-Affect base of subsequent taxes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-With this option, the total tax-included becomes the taxable basis for the other taxes applied to
-the same product.
-
-You can configure a new :ref:`group of taxes <taxes/computation>` to include this tax or add it
-directly to a product line.
-
-.. image:: taxes/subsequent-line.png
-   :alt: The eco-tax is taken into the basis of the 21% VAT tax
-
-.. warning::
-   The order in which you add the taxes on a product line has no effect on how amounts are computed.
-   If you add taxes directly on a product line, only the tax sequence determines the order in which
-   they are applied.
-
-   To reorder the sequence, go to :menuselection:`Accounting --> Configuration --> Taxes`, and drag
-   and drop the lines with the handles next to the tax names.
-
-   .. image:: taxes/list-sequence.png
-      :alt: The taxes' sequence in Odoo determines which tax is applied first
+.. image:: taxes/distribution-refunds.png
+   :alt: The Distribution for Refunds of a 21% VAT tax.
 
 Extra taxes
 ===========
@@ -360,7 +367,7 @@ imposed by governments. These extra taxes can be **luxury** taxes, **environment
 
 To compute an extra tax in Odoo, :ref:`create a tax <taxes/configuration>`, enter a tax name, select
 a :ref:`Tax Computation <taxes/configuration>`, set an :guilabel:`Amount`, and in the
-:guilabel:`Advanced Options` tab, check :guilabel:`Affect Base of Subsequent Taxes`. Then, drag and
+:guilabel:`Advanced Options` tab, enable :guilabel:`Affect Base of Subsequent Taxes`. Then, drag and
 drop the taxes in the :ref:`order they should be computed <taxes/base-subsequent>`.
 
 .. example::
@@ -374,6 +381,7 @@ drop the taxes in the :ref:`order they should be computed <taxes/base-subsequent
       :alt: Environmental tax sequence in Belgium.
 
 .. seealso::
+  - :doc:`taxes/tax_computation`
   - :doc:`taxes/fiscal_positions`
   - :doc:`taxes/B2B_B2C`
   - :doc:`reporting/tax_returns`
@@ -382,6 +390,7 @@ drop the taxes in the :ref:`order they should be computed <taxes/base-subsequent
    :titlesonly:
 
    taxes/cash_basis
+   taxes/tax_computation
    taxes/retention
    taxes/vat_verification
    taxes/fiscal_positions

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

@@ -0,0 +1,344 @@
+===============
+Tax computation
+===============
+
+.. _taxes/computation:
+
+Tax computation
+---------------
+
+The :guilabel:`Tax Computation` field determines the relation between the tax amount and the base
+the tax is based on. The following options are available:
+
+- :ref:`Group of Taxes <taxes/computation/group-of-taxes>`: a combination of several other taxes
+- :ref:`Fixed <taxes/computation/fixed>`: a fixed amount
+- :ref:`Percentage of Price <taxes/computation/percentage-of-price>`: a percentage of the
+  tax-excluded sales price
+- :ref:`Percentage of Price Tax Included <taxes/computation/percentage-of-price-tax-included>`: a
+  percentage of the tax-included total
+- :ref:`Custom Formula <taxes/computation/python-code>`: a custom, user-defined formula
+
+.. _taxes/computation/group-of-taxes:
+
+Group of taxes
+~~~~~~~~~~~~~~
+
+  The tax is a combination of multiple sub-taxes. You can add as many taxes as you want, in the
+  order you want them to be applied.
+
+.. important::
+   Make sure the tax sequence is correct, as the display order determines the application order and
+   may affect tax computation, particularly if a tax :ref:`affects the base of subsequent taxes
+   <taxes/base-subsequent>`.
+
+.. _taxes/computation/fixed:
+
+Fixed
+~~~~~
+
+The tax has a fixed amount in the default currency. The amount remains the same per unit,
+regardless of the sales price.
+
+The computation is :math:`\text{tax amount} = \text{fixed tax amount} \times \text{quantity}`.
+
+.. example::
+   A product has a sales price of $1000, and we apply a $10 :guilabel:`Fixed` tax. We then have:
+
+   +-------------+-------------+----------+----------+
+   | Product     | Price       | Tax      | Total    |
+   | sales price | without tax |          |          |
+   +=============+=============+==========+==========+
+   | 1,000       | 1,000       | 10       | 1,010.00 |
+   +-------------+-------------+----------+----------+
+
+.. _taxes/computation/percentage-of-price:
+
+Percentage of price
+~~~~~~~~~~~~~~~~~~~
+
+The tax rate is a percentage of the **tax-excluded** subtotal.
+
+The exact tax computation depends on the :ref:`Included in Price <taxes/included-in-price>` field,
+which determines whether the tax amount is included in the sales price.
+
+.. tabs::
+   .. tab:: Tax-excluded
+
+      If :guilabel:`Included in Price` is :guilabel:`Tax Excluded`, the computation is
+      :math:`\text{tax amount} = \text{sales price} \times \text{tax rate}`.
+
+      .. example::
+         A product has a sales price of $1000, and we apply a 10% :guilabel:`Percentage of Price`
+         tax that is :guilabel:`Tax Excluded`. We then have:
+
+         +-------------+-------------+----------+----------+
+         | Product     | Price       | Tax      | Total    |
+         | sales price | without tax |          |          |
+         +=============+=============+==========+==========+
+         | 1,000       | 1,000       | 100      | 1,100.00 |
+         +-------------+-------------+----------+----------+
+
+   .. tab:: Tax-included
+
+      If :guilabel:`Included in Price` is :guilabel:`Tax Included`, the computation is
+      :math:`\text{tax amount} = \text{sales price} \times \frac{\text{tax rate}}{1 +
+      \text{tax rate}}`.
+
+      .. example::
+         A product has a sales price of $1000, and we apply a 10% :guilabel:`Percentage of Price`
+         tax that is :guilabel:`Tax Included`. We then have:
+
+         +-------------+-------------+----------+----------+
+         | Product     | Price       | Tax      | Total    |
+         | sales price | without tax |          |          |
+         +=============+=============+==========+==========+
+         | 1,000       | 909.09      | 90.91    | 1,000.00 |
+         +-------------+-------------+----------+----------+
+
+.. _taxes/computation/percentage-of-price-tax-included:
+
+Percentage of price tax included
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. important::
+   This tax computation is rarely used and only useful in countries (e.g., Brazil, Bolivia) that
+   quote tax rates as a percentage of the tax-included total.
+   For the more common need to compute tax amounts from a tax-included price, use the
+   :ref:`Percentage of Price <taxes/computation/percentage-of-price>` tax computation with
+   :ref:`Included in Price <taxes/included-in-price>` set to :guilabel:`Tax Included`.
+
+The tax rate is a percentage of the **tax-included** total.
+
+The exact tax computation depends on the :ref:`Included in Price <taxes/included-in-price>` field,
+which determines whether the tax amount is included in the sales price.
+
+.. tabs::
+   .. tab:: Tax-excluded
+      If :guilabel:`Included in Price` is set to :guilabel:`Tax Excluded`, the computation is
+      :math:`\text{tax amount} = \text{sales price} \times \frac{\text{tax rate}}{1 -
+      \text{tax rate}}`.
+
+      .. example::
+         A product has a sales price of $1000, and we apply a 10% :guilabel:`Percentage of Price
+         Tax Included` tax that is :guilabel:`Tax Excluded`. We then have:
+
+         +-------------+-------------+----------+----------+
+         | Product     | Price       | Tax      | Total    |
+         | sales price | without tax |          |          |
+         +=============+=============+==========+==========+
+         | 1,000       | 1,000       | 111.11   | 1,111.11 |
+         +-------------+-------------+----------+----------+
+
+         Note that the real tax rate in terms of the tax-excluded price is
+         :math:`\frac{111.11}{1000} = 11.111\%`.
+
+   .. tab:: Tax-included
+
+      If :guilabel:`Included in Price` is set to :guilabel:`Tax Included`, the computation is
+      :math:`\text{tax amount} = \text{sales price} \times \text{tax rate}`.
+
+      .. example::
+         A product has a sales price of $1000, and we apply a 10%
+         :guilabel:`Percentage of Price Tax Included` tax that is :guilabel:`Tax Included`.
+         We then have:
+
+         +-------------+-------------+----------+----------+
+         | Product     | Price       | Tax      | Total    |
+         | sales price | without tax |          |          |
+         +=============+=============+==========+==========+
+         | 1,000       | 900         | 100      | 1,000.00 |
+         +-------------+-------------+----------+----------+
+
+         Note that the real tax rate in terms of the tax-excluded price is
+         :math:`\frac{100}{900} = 11.111\%`.
+
+.. _taxes/computation/python-code:
+
+Custom formula
+~~~~~~~~~~~~~~
+
+.. important::
+   If a tax can be expressed as a multiple of the quantity of the product to which it applies, it
+   can be defined as a :ref:`Fixed <taxes/computation/fixed>` tax. Doing so is strongly recommended
+   over defining a :guilabel:`Custom Formula` tax.
+
+.. note::
+   To use :guilabel:`Custom Formula` taxes, :ref:`install <general/install>` the :guilabel:`Define
+   Taxes as Python Code` (`account_python_tax`) module.
+
+For a :guilabel:`Custom Formula` tax, the tax amount is computed according to a Python expression
+defined in the :guilabel:`Formula` field. The Python expression may contain the following tokens:
+
+- any of the following variables:
+
+  - `price_unit`: the unit price of the product
+  - `base`: the taxable basis on which the tax is applied - may differ from the `price_unit` if
+    other taxes are applied first
+  - `quantity`: the quantity of the product
+  - `product`: the product record - product fields can also be accessed
+
+- integers and floating-point numbers
+
+- the following permitted tokens: `(`, `)`, `+`, `-`, `*`, `/`, `,`, `<`, `>`, `<=`, `>=`, `and`,
+  `or`, `None`, `min`, and `max`
+
+.. example::
+   A product has a sales price of $1000, and we apply a :guilabel:`Custom Formula` tax with a
+   :guilabel:`Formula` of `min(base, 500) * 0.10 + max(base - 500, 0) * 0.20`
+
+   We then have:
+
+   +-------------+-------------+----------+----------+
+   | Product     | Price       | Tax      | Total    |
+   | sales price | without tax |          |          |
+   +=============+=============+==========+==========+
+   | 1,000       | 1,000       | 150      | 1,150.00 |
+   +-------------+-------------+----------+----------+
+
+.. _taxes/included-in-price:
+
+Included in price
+-----------------
+
+.. tip::
+   To set a company-wide default for this setting, go to :menuselection:`Accounting -->
+   Configuration --> Settings`, find the :guilabel:`Taxes` section, and set the :guilabel:`Prices`
+   setting to :guilabel:`Tax Excluded` or :guilabel:`Tax Included`. This setting cannot be changed
+   once invoices have been created.
+
+:guilabel:`Default` indicates that the tax follows the company-wide default.
+
+:guilabel:`Tax Excluded` indicates that the tax amount is not included in the sales price. The tax
+computation will therefore compute a tax amount on top of the sales price.
+
+:guilabel:`Tax Included` indicates that the tax amount is included in the sales price. The tax
+computation will therefore split the sales price into a tax-excluded base and the tax amount. This
+makes it suitable for B2C sales in most countries, where prices are quoted tax-inclusive.
+
+.. example::
+   A product has a sales price of $1000, and we apply a 10% :guilabel:`Percentage of Price` tax
+   with :guilabel:`Included in Price` set to :guilabel:`Tax Included`. We then have:
+
+   +-------------+-------------+----------+----------+
+   | Product     | Price       | Tax      | Total    |
+   | sales price | without tax |          |          |
+   +=============+=============+==========+==========+
+   | 1,000       | 909.09      | 90.91    | 1,000.00 |
+   +-------------+-------------+----------+----------+
+
+.. note::
+   For a guide on configuring tax-excluded and tax-included prices for B2B and B2C customers,
+   see :doc:`B2B_B2C`.
+
+.. _taxes/base-subsequent:
+
+Affect base of subsequent taxes
+-------------------------------
+
+This setting controls how multiple taxes on a product line affect each other.
+
+If this setting is enabled, this tax's tax amount is included in the base of any subsequent tax
+applied on the same product line that has its :ref:`taxes/base-affected` setting enabled. As such,
+the subsequent tax's base is the sum of the tax-excluded base and this tax's tax amount.
+
+.. tabs::
+   .. tab:: Tax-excluded
+      If :guilabel:`Affect base of subsequent taxes` is enabled and :guilabel:`Included in Price` is
+      set to :guilabel:`Tax Excluded`, subsequent taxes with the :guilabel:`Base affected by
+      preceding taxes` setting enabled will be based on a modified sales price equal to the original
+      sales price plus the tax amount.
+
+      .. example::
+         A product has a sales price of $1000, and we apply a 10% :guilabel:`Percentage of Price`
+         tax where the :guilabel:`Included in Price` setting is set to :guilabel:`Tax Excluded` and
+         the :guilabel:`Affect base of subsequent taxes` setting is enabled. Any subsequent tax with
+         its :guilabel:`Base affected by preceding taxes` will be based on a modified sales price of
+         $1100.
+
+   .. tab:: Tax-included
+      If :guilabel:`Affect base of subsequent taxes` is enabled and :guilabel:`Included in Price` is
+      set to :guilabel:`Tax Included`, subsequent taxes with the :guilabel:`Base affected by
+      preceding taxes` setting enabled will be based on the original sales price.
+
+      .. example::
+         A product has a sales price of $1000, and we apply a 10% :guilabel:`Percentage of Price`
+         tax where the :guilabel:`Included in Price` setting is set to :guilabel:`Tax Included` and
+         the :guilabel:`Affect base of subsequent taxes` setting is enabled. Any subsequent tax with
+         its :guilabel:`Base affected by preceding taxes` will be based on the original sales price
+         of $1000.
+
+If this setting is disabled, the tax amount will not be included in the base of any subsequent tax
+applied on the same product line.
+
+.. tabs::
+   .. tab:: Tax-excluded
+      If :guilabel:`Affect base of subsequent taxes` is disabled and :guilabel:`Included in Price`
+      is set to :guilabel:`Tax Excluded`, subsequent taxes with the :guilabel:`Base affected by
+      preceding taxes` setting enabled will be based on the original sales price.
+
+      .. example::
+         A product has a sales price of $1000, and we apply a 10% :guilabel:`Percentage of Price`
+         tax where the :guilabel:`Included in Price` setting is set to :guilabel:`Tax Excluded` and
+         the :guilabel:`Affect base of subsequent taxes` setting is enabled. Any subsequent tax with
+         its :guilabel:`Base affected by preceding taxes` will be based on the original sales price
+         of $1000.
+
+   .. tab:: Tax-included
+      If :guilabel:`Affect base of subsequent taxes` is disabled and :guilabel:`Included in Price`
+      is set to :guilabel:`Tax Included`, subsequent taxes with the :guilabel:`Base affected by
+      preceding taxes` setting enabled will be based on a modified sales price equal to the original
+      sales price minus the tax amount.
+
+      .. example::
+         A product has a sales price of $1000, and we apply a 10% :guilabel:`Percentage of Price`
+         tax where the :guilabel:`Included in Price` setting is set to :guilabel:`Tax Included` and
+         the :guilabel:`Affect base of subsequent taxes` setting is enabled. Any subsequent tax with
+         its :guilabel:`Base affected by preceding taxes` will be based on a modified sales price of
+         $909.09.
+
+This setting is considered any time multiple taxes are applied to the same product line, whether
+via a :ref:`group of taxes <taxes/computation>` or multiple taxes added directly to a product line.
+
+.. note::
+   The order in which taxes are applied depends only on the order in which they appear in the
+   :guilabel:`Taxes` list, not on the order in which they are added to a product line.
+
+   To modify the order, go to :menuselection:`Accounting --> Configuration --> Taxes`, and drag and
+   drop taxes using the handles to the left of the tax names.
+
+   .. image:: tax_computation/list-sequence.png
+      :alt: The order of appearance of taxes in the Taxes list determines which tax is applied first
+
+   Regardless of the order in the :guilabel:`Taxes` list, :guilabel:`Tax Excluded` taxes do not
+   affect the base of subsequent :guilabel:`Tax Included` taxes (see the note in
+   :ref:`taxes/base-affected`).
+
+.. example::
+   In the following example:
+
+   - the Ecotax is a :guilabel:`Fixed` tax of €0.90 per unit, with the :guilabel:`Affect base of
+     subsequent taxes` setting enabled.
+   - The 21% VAT tax is a 21% :guilabel:`Percentage of Price` tax with the :guilabel:`Base affected
+     by preceding taxes` setting enabled.
+   - In the :guilabel:`Taxes` list, the 21% VAT tax comes after the Ecotax, as shown in the
+     configuration above.
+
+   When applying both taxes to a product line, the Ecotax amount is added to the basis of the 21%
+   VAT tax.
+
+   .. image:: tax_computation/subsequent-line.png
+      :alt: The Ecotax is added to the basis of the 21% VAT tax
+
+.. _taxes/base-affected:
+
+Base affected by preceding taxes
+--------------------------------
+
+This setting, which is only visible in :doc:`developer mode <../../../general/developer_mode>`,
+determines whether any previous tax that :ref:`affects the base of subsequent taxes
+<taxes/base-subsequent>` will modify the sales price that this tax is based on.
+
+.. note::
+   Taxes with :ref:`Included in Price <taxes/included-in-price>` set to :guilabel:`Tax Included` do
+   not have this setting. Such taxes are never affected by previous :guilabel:`Tax Excluded` taxes,
+   except if they have the :guilabel:`Fixed` :ref:`Tax computation <taxes/computation>` type.