[MOV] Accounting: create a new "Fiscality" section

The new "Fisality" section includes all the doc about taxes + fiscal year. All of these were in the "Other" section.

accounting/fiscality/fiscal_year.rst

@@ -0,0 +1,9 @@
+===========
+Fiscal Year
+===========
+
+.. toctree::
+   :titlesonly:
+
+   fiscal_year/fiscal_year
+   fiscal_year/close_fiscal_year

accounting/fiscality/fiscal_year/close_fiscal_year.rst

@@ -0,0 +1,93 @@
+=====================================================
+How to do a year end in Odoo? (close a fiscal year)
+=====================================================
+
+Before going ahead with closing a fiscal year, there are a few steps one
+should typically take to ensure that your accounting is correct, up to
+date, and accurate:
+
+- Make sure you have fully reconciled your **bank account(s)** up to
+  year end and confirm that your ending book balances agree with
+  your bank statement balances.
+
+-  Verify that all **customer invoices** have been entered and approved.
+
+-  Confirm that you have entered and agreed all **vendor bills**.
+
+-  Validate all **expenses**, ensuring their accuracy.
+
+- Corroborate that all **received payments** have been entered and
+  recorded accurately.
+
+Year-end checklist
+==================
+
+- Run a **Tax report**, and verify that your tax information is correct.
+
+- Reconcile all accounts on your **Balance Sheet**:
+
+  - Agree your bank balances in Odoo against your actual bank balances
+    on your statements. Utilize the **Bank Reconciliation** report to
+    assist with this.
+
+  - Reconcile all transactions in your cash and bank accounts by
+    running your **Aged Receivables** and **Aged Payables** reports.
+
+  - Audit your accounts, being sure to fully understand the
+    transactions affecting them and the nature of the
+    transactions, making sure to include loans and fixed assets.
+
+- Run the optional **Payments Matching** feature, under the **More**
+  dropdown on the dashboard, validating any open **Vendor Bills** and
+  **Customer Invoices** with their payments. This step is optional,
+  however it may assist the year-end process if all outstanding
+  payments and invoices are reconciled, and could lead finding
+  errors or mistakes in the system.
+
+- Your accountant/bookkeeper will likely verify your balance sheet
+  items and book entries for:
+
+  - Year-end manual adjustments, using the **Adviser Journal Entries**
+    menu (For example, the **Current Year Earnings** and **Retained
+    Earnings** reports).
+
+  - **Work in Progress**.
+
+  - **Depreciation Journal Entries**.
+
+  - **Loans**.
+
+  - **Tax adjustments**.
+
+If your accountant/bookkeeper is going through end of the year auditing,
+they may want to have paper copies of all balance sheet items (such as
+loans, bank accounts, prepayments, sales tax statements, etc...) to
+agree these against your Odoo balances.
+
+During this process, it is good practice to set the **Lock date for
+Non-Advisers** to the last day of the preceding financial year, which is
+set under the accounting configuration. This way, the accountant can be
+confident that nobody is changing the previous year transactions
+while auditing the books.
+
+.. image:: media/close_fiscal_year01.png
+   :align: center
+
+Closing the fiscal year
+=======================
+
+In Odoo there is no need to do a specific year end closing entry in order to
+close out income statement accounts. The reports are created in
+real-time, meaning that the **Income statement** corresponds directly with
+the year-end date you specify in Odoo. Therefore, any time you generate
+the **Income Statement**, the beginning date will correspond with the
+beginning of the **Fiscal Year** and the account balances will all be 0.
+
+Once the accountant/bookkeeper has created the journal entry to allocate
+the **Current Year Earnings**, you should set the **Lock Date** to the last day
+of the fiscal year. Making sure that before doing so, you confirm
+whether or not the current year earnings in the **Balance Sheet** is
+correctly reporting a 0 balance.
+
+.. seealso::
+  * :doc:`fiscal_year`

accounting/fiscality/fiscal_year/fiscal_year.rst

@@ -0,0 +1,34 @@
+===================
+Manage Fiscal Years
+===================
+
+In most cases, the fiscal years last 12 months. If it is your case, you
+just have to define what is the last day of your fiscal year in the
+accounting settings. By default, it is set on the 31st December.
+
+.. image:: media/fiscal_year01.png
+    :align: center
+
+However, there might be some exceptions. For example, if it is the first
+fiscal year of your business, it could last more or less than 12 months.
+In this case, some additional configuration is required.
+
+Go in :menuselection:`accounting --> configuration --> settings` and activate
+the fiscal years.
+
+.. image:: media/fiscal_year02.png
+    :align: center
+
+You can then configure your fiscal years in
+:menuselection:`accounting --> configuration --> fiscal years`.
+
+.. image:: media/fiscal_year03.png
+    :align: center
+
+.. note::
+    You only have to create fiscal years if they last more or less
+    than 12 months.
+
+.. seealso:: 
+
+    * :doc:`close_fiscal_year`

accounting/fiscality/taxes.rst

@@ -0,0 +1,15 @@
+===========
+Taxes
+===========
+
+.. toctree::
+   :titlesonly:
+
+   taxes/create
+   taxes/default_taxes
+   taxes/application
+   taxes/taxcloud
+   taxes/tax_included
+   taxes/retention
+   taxes/B2B_B2C
+   taxes/cash_basis_taxes

accounting/fiscality/taxes/B2B_B2C.rst

@@ -0,0 +1,169 @@
+===================================================================
+How to manage prices for B2B (tax excluded) and B2C (tax included)?
+===================================================================
+
+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:
+
+1.  always store the default price TAX EXCLUDED on the product form, and
+    apply a tax (price included on the product form)
+
+2.  create a pricelist with prices in TAX INCLUDED, for specific
+    customers
+
+3.  create a fiscal position that switches the tax excluded to a tax
+    included
+
+4.  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
+
+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:: media/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:: media/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:: media/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:: media/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:: media/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.

accounting/fiscality/taxes/application.rst

@@ -0,0 +1,87 @@
+==========================================================
+How to adapt taxes to my customer status or localization
+==========================================================
+
+Most often sales tax rates depend on your customer status or localization.
+To map taxes, Odoo brings the so-called *Fiscal Positions*. 
+
+Create tax mapping
+==================
+
+A fiscal position is just a set of rules that maps default taxes (as defined
+on product form) into other taxes. In the screenshot below, foreign customers
+get a 0% tax instead of the default 15%, for both sales and purchases.
+
+.. image:: media/application02.png
+   :align: center
+
+The main fiscal positions are automatically created according to your
+localization. But you may have to create fiscal positions for specific use cases.
+To define fiscal positions, go to
+:menuselection:`Invoicing/Accounting --> Configuration --> Fiscal Positions`.
+
+.. note::
+    If you use Odoo Accounting, you can also map the Income/Expense accounts according to the fiscal
+    position. For example, in some countries, revenues from sales are not posted in
+    the same account than revenues from sales in foreign countries.
+
+Adapt taxes to your customer status
+===================================
+
+If a customer falls into a specific taxation rule, you need to apply a tax-mapping.
+To do so, create a fiscal position and assign it to your customers.
+
+.. image:: media/application01.png
+   :align: center
+
+Odoo will use this specific fiscal position for any order/invoice recorded for the customer.
+
+.. note:: 
+    If you set the fiscal position in the sales order or invoice manually, it will only
+    apply to this document and not to future orders/invoices of the same customer.
+
+Adapt taxes to your customer address (destination-based)
+========================================================
+
+Depending on your localization, sales taxes may be origin-based or destination-based.
+Most states or countries require you to collect taxes at the rate of the destination
+(i.e. your buyer’s address) while some others require to collect them at the rate effective
+at the point of origin (i.e. your office or warehouse).
+
+If you are under the destination-based rule, create one fiscal position per tax-mapping to apply.
+
+* Check the box *Detect Automatically*.
+* Select a country group, country, state or city to trigger the tax-mapping.
+
+.. image:: media/application04.png
+   :align: center
+
+This way if no fiscal position is set on the customer, Odoo will choose the fiscal position matching the
+shipping address on creating an order.
+
+.. note::
+    For eCommerce orders, the tax of the visitor's cart will automatically
+    update and apply the new tax after the visitor has logged in or filled
+    in his shipping address.
+
+Specific use cases
+==================
+
+If, for some fiscal positions, you want to remove a tax, instead of
+replacing by another, just keep the *Tax to Apply* field empty.
+
+.. image:: media/application03.png
+   :align: center
+
+If, for some fiscal positions, you want to replace a tax by two other
+taxes, just create two lines having the same *Tax on Product*.
+
+.. note::
+  The fiscal positions are not applied on assets and deferred revenues.
+
+.. seealso::
+
+  * :doc:`create`
+  * :doc:`taxcloud`
+  * :doc:`tax_included`
+  * :doc:`B2B_B2C`

accounting/fiscality/taxes/cash_basis_taxes.rst

@@ -0,0 +1,95 @@
+==============================
+How to manage cash basis taxes
+==============================
+
+The cash basis taxes are due when the payment has been done and not at
+the validation of the invoice (as it is the case with standard taxes).
+Reporting your income and expenses to the administration based on the
+cash basis method is legal in some countries and under some conditions.
+
+Example : You sell a product in the 1st quarter of your fiscal year and
+receive the payment the 2nd quarter of your fiscal year. Based on the
+cash basis method, the tax you have to pay to the administration is due
+for the 2nd quarter.
+
+How to configure cash basis taxes ? 
+------------------------------------
+
+You first have to activate the setting in
+:menuselection:`Accounting --> Configuration --> Settings --> Allow Tax Cash Basis`.
+You will be asked to define the Tax Cash Basis Journal.
+
+.. image:: media/cash_basis_taxes01.png
+    :width: 5.04688in
+    :height: 0.79688in
+    :align: center
+
+Once this is done, you can configure your taxes in
+:menuselection:`Accounting --> Configuration --> Taxes`.
+At first set the proper transitional accounts to post taxes
+until you register the payment.
+
+.. image:: media/cash_basis_taxes02.png
+    :align: center
+
+In the *Advanced Options* tab you will turn *Tax Due* to
+*Based on Payment*. You will then have to
+define the *Tax Received* account in which to post the tax amount
+when the payment is received and the *Base Tax Received Account*
+to post the base tax amount for an accurate tax report.
+
+.. image:: media/cash_basis_taxes03.png
+    :align: center
+
+What is the impact of cash basis taxes in my accounting ? 
+----------------------------------------------------------
+
+Let’s take an example. You make a sale of $100 with a 15% cash basis
+tax. When you validate the customer invoice, the following entry is
+created in your accounting:
+
++-----------------------------+---------------------------+
+| Customer Invoices Journal   |                           |
++=============================+===========================+
+| **Debit**                   | **Credit**                |
++-----------------------------+---------------------------+
+| Receivables $115            |                           |
++-----------------------------+---------------------------+
+|                             | Temporary Tax Account $15 |
++-----------------------------+---------------------------+
+|                             | Income Account $100       |
++-----------------------------+---------------------------+
+
+A few days later, you receive the payment:
+
++----------------+--------------------+
+| Bank Journal   |                    |
++================+====================+
+| **Debit**      | **Credit**         |
++----------------+--------------------+
+| Bank $115      |                    |
++----------------+--------------------+
+|                | Receivables $115   |
++----------------+--------------------+
+
+When you reconcile the invoice and the payment, this entry is generated:
+
++--------------------------+----------------------------+
+| Tax Cash Basis Journal                                |
++==========================+============================+
+| **Debit**                | **Credit**                 |
++--------------------------+----------------------------+
+| Temporary Tax Account $15|                            |
++--------------------------+----------------------------+
+|                          | Tax Received Account $15   |
++--------------------------+----------------------------+
+| Income Account $100      |                            |
++--------------------------+----------------------------+
+|                          | Income Account $100        |
++--------------------------+----------------------------+
+
+.. tip::
+    The last two journal items are neutral but they are needed to insure 
+    correct tax reports in Odoo with accurate base tax amounts.
+    We advise to use a default revenue account.
+    The balance of this account will then always be at zero.

accounting/fiscality/taxes/create.rst

@@ -0,0 +1,70 @@
+========================
+How to create new taxes
+========================
+
+Odoo's tax engine is very flexible and support many different type of
+taxes: value added taxes (VAT), eco-taxes, federal/states/city taxes, retention,
+withholding taxes, etc. For most countries, your system is pre-configured with the
+right taxes.
+
+This section details how you can define new taxes for specific use cases.
+
+* Go to :menuselection:`Accounting --> Configuration --> Taxes`. From this menu, you
+  get all the taxes you can use: sales taxes and purchase taxes.
+
+.. image:: media/create01.png
+   :align: center
+
+* Choose a scope: Sales, Purchase or None (e.g. deprecated tax).
+
+* Select a computation method:
+
+  * **Fixed**: eco-taxes, etc.
+
+  * **Percentage of Price**: most common (e.g. 15% sales tax)
+
+  * **Percentage of Price Tax Included**: used in Brazil, etc.
+
+  * **Group of taxes**: allows to have a compound tax
+
+.. image:: media/create02.png
+   :align: center
+
+
+* If you use Odoo Accounting, set a tax account (i.e. where the tax journal item will be
+  posted). This field is optional, if you keep it empty, Odoo posts
+  the tax journal item in the income account.
+
+.. tip::
+    If you want to avoid using a tax, you can not delete it because the tax
+    is probably used in several invoices. So, in order to avoid users to
+    continue using this tax, you should set the field *Tax Scope* to *None*.
+
+.. note::
+    If you need more advanced tax mechanism, you can install the
+    module **account_tax_python** and you will be able to define new taxes
+    with Python code.
+
+Advanced configuration
+======================
+
+* **Label on Invoices**: a short text on how you want this tax to be
+  printed on invoice line. For example, a tax named "15% on
+  Services" can have the following label on invoice "15%".
+
+* **Tax Group**: defines where this tax is summed in the invoice footer.
+  All the tax belonging to the same tax group will be grouped on
+  the invoice footer. Examples of tax group: VAT, Retention.
+
+* **Include in Analytic Cost**: the tax is counted as a cost and, thus,
+  generate an analytic entry if your invoice uses analytic
+  accounts.
+
+* **Tags**: are used for custom reports. Usually, you can keep this field
+  empty.
+
+
+.. seealso::
+
+  * :doc:`application`
+  * :doc:`tax_included`

accounting/fiscality/taxes/default_taxes.rst

@@ -0,0 +1,31 @@
+========================
+How to set default taxes
+========================
+
+Taxes applied in your country are installed automatically for most localizations.
+
+Default taxes set in orders and invoices come from each product's Invoicing tab.
+Such taxes are used when you sell to companies that are in the same country/state than you.
+
+.. image:: media/application05.png
+   :align: center
+
+To change the default taxes set for any new product created go to
+:menuselection:`Invoicing/Accounting --> Configuration --> Settings`.
+
+.. image:: media/create04.png
+   :align: center
+
+.. tip::
+    If you work in a multi-companies environment, the sales and 
+    purchase taxes may have a different value according to the 
+    company you work for. You can login into two different companies 
+    and change this field for each company.
+
+.. seealso::
+
+  * :doc:`create`
+  * :doc:`application`
+  * :doc:`taxcloud`
+  * :doc:`B2B_B2C`
+  * :doc:`tax_included`

accounting/fiscality/taxes/retention.rst

@@ -0,0 +1,70 @@
+================================
+How to manage 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:: media/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:: media/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:: media/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:: media/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:: media/retention03.png
+   :align: center
+
+.. seealso::
+
+  * :doc:`create`

accounting/fiscality/taxes/tax_included.rst

@@ -0,0 +1,41 @@
+==============================
+How to set tax-included prices
+==============================
+
+In most countries, B2C prices are tax-included. To do that in Odoo, check
+*Included in Price* for each of your sales taxes in
+:menuselection:`Accounting --> Configuration --> Accounting --> Taxes`.
+
+.. image:: media/tax_included.png
+   :align: center
+
+This way the price set on the product form includes the tax. As an example,
+let's say you have a product with a sales tax of 10%. The sales price on
+the product form is $100.
+
+- If the tax is not included in the price, you will get:
+
+  - Price without tax: $100
+
+  - Taxes: $10
+
+  - Total to pay: $110
+
+- If the tax is included in the price
+
+  - Price without tax: 90.91
+
+  - Taxes: $9.09
+
+  - Total to pay: $100
+
+You can rely on following documentation if you need both tax-included (B2C) and
+tax-excluded prices (B2B): :doc:`B2B_B2C`.
+
+Show tax-included prices in eCommerce catalog
+=============================================
+
+By default prices displayed in your eCommerce catalog are tax-excluded. To display
+it in tax-included, check *Show line subtotals with taxes included (B2C)* in
+:menuselection:`Sales --> Configuration --> Settings` (Tax Display).
+

accounting/fiscality/taxes/taxcloud.rst

@@ -0,0 +1,93 @@
+================================================================
+How to 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:: media/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:: media/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.
+
+How it works
+============
+
+Salestax is calculated in Odoo based on fiscal positions
+(see :doc:`application`).
+A Fiscal Position for the United States is created when installing *TaxCloud*.
+Everything works out-of-the-box.
+
+You can configure Odoo to automtically detect which Customers should use this fiscal
+position.  Go to :menuselection:`Accounting --> Configuration --> Fiscal Positions`
+to open and edit the record.
+
+.. image:: media/taxcloud03.png
+  :align: center
+
+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.
+
+.. image:: media/taxcloud04.png
+  :align: center
+
+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**.
+
+
+Coupons & Promotions
+====================
+
+If you use the Coupon or Promotion Programs, the integration with Taxcloud might seem a bit odd.
+
+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.
+
+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.
+
+.. seealso::
+   - :doc:`application`