diff --git a/content/applications/finance/accounting/taxation/taxes/taxcloud.rst b/content/applications/finance/accounting/taxation/taxes/taxcloud.rst index 84fb78254..9073e9a52 100644 --- a/content/applications/finance/accounting/taxation/taxes/taxcloud.rst +++ b/content/applications/finance/accounting/taxation/taxes/taxcloud.rst @@ -1,139 +1,151 @@ -========================================================= -Get correct tax rates in the United States using TaxCloud -========================================================= - -The **TaxCloud** integration allows you to correctly calculate the sales -tax for every address in the United States and keeps track of which products -are exempt from sales tax and in which states each exemption applies. -TaxCloud calculates sales tax in real-time for every state, city, and -special jurisdiction in the United States. - -Configuration -============= - -In TaxCloud ------------ -* Create a free account on `TaxCloud - `__ website. -* Register your Odoo website on TaxCloud to get an *API ID* and an *API Key*. - -.. image:: taxcloud/taxcloud01.png - :align: center - -* In Settings on TaxCloud, click *Locations* to enter the location of your Office(s) & Warehouse(s). -* In Settings on TaxCloud, click *Manage Tax States* to verify the states where you collect sales tax. - -In Odoo -------- -* Go to :menuselection:`Invoicing / Accounting --> Configuration --> Settings` - and check *TaxCloud - Compute tax rates based on U.S. ZIP codes* (note: actually uses complete street address). -* Enter your TaxCloud credentials. -* Click SAVE to store your credentials. - -.. image:: taxcloud/taxcloud02.png - :align: center - -* Click the Refresh Icon next to *Default Category* to import the TIC product categories - from TaxCloud (Taxability Information Codes). Some categories may imply specific rates or attract product/service type exemptions. -* Select your default *TIC Code*. This will apply to any new - product created. -* Set a specific TaxCloud TIC Category on the *General Information* tab of the Product, - or on the Product Category. -* Make sure your company address is complete (including the state - and the zip code). Go to :menuselection:`Settings --> Users & Companies --> Companies` - to open and edit your Company record. - -Automatically post taxes to the correct Tax Payable account -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -* For each one of your companies that uses TaxCloud, it might be necessary to create a - **User-Defined Default** so that the new taxes generated by the TaxCloud integration are created - with the correct Tax Payable account: - -.. warning:: - A User-Defined Default impacts all records at creation. It means that **every** new tax will be - set up to record income in the specified Tax Payable account, unless the tax is manually edited - to specify a different income account (or there exists another User-Defined Default that takes - precedence). - -* In :menuselection:`Accounting --> Configuration --> Chart of Accounts`, select the Tax Payable - account for the company. Take note of the account's ``id`` in the URL string. - -.. image:: taxcloud/user-default-find-account-id.png - :alt: The account's ID can be found in the URL string as 'id=...'. - :align: center - -* Activate the :ref:`developer mode `, then go to - :menuselection:`Settings --> Technical --> Actions --> User-Defined Defaults`, and - click on *Create*. - -* Click on *Field*, then, in the drop-down menu, on *Search More*. - -.. image:: taxcloud/user-default-search-field.png - :alt: Click on 'Search More' in the 'Field' drop-down menu. - :align: center - -* In the pop-up's search box, filter on the model ``tax.repartition.line`` and the field ``account``. - Select the ``account`` field of the ``tax.repartition.line`` model. - -.. image:: taxcloud/user-default-select-field.png - :alt: Select the 'account' field of the 'tax.repartition.line' model. - :align: center - -* In the **Default Value** field, enter the ID of the company's Tax Payable account. - Select the company for which this configuration should apply in the *Company* field. - Click *Save*. - -.. image:: taxcloud/user-default-enter-default-account-id.png - :alt: Enter the ID of the company's Tax Payable account. - :align: center - - -How it works -============ - -Salestax is calculated in Odoo based on fiscal positions -(see :doc:`fiscal_positions`). -A Fiscal Position for the United States is created when installing *TaxCloud*. -Everything works out-of-the-box. - -You can configure Odoo to automatically detect which Customers should use this fiscal -position. Go to :menuselection:`Accounting --> Configuration --> Fiscal Positions` -to open and edit the record. - -.. image:: taxcloud/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:: taxcloud/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 +==================== +TaxCloud integration ==================== -If you use the Coupon or Promotion Programs, the integration with Taxcloud might seem a bit odd. +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. -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. +TaxCloud registration +===================== -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. +Register an account on `TaxCloud.com `_ 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 `, 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 `. 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` + :doc:`fiscal_positions` \ No newline at end of file diff --git a/content/applications/finance/accounting/taxation/taxes/taxcloud/fiscal-position-detect.png b/content/applications/finance/accounting/taxation/taxes/taxcloud/fiscal-position-detect.png new file mode 100644 index 000000000..64cf7bc23 Binary files /dev/null and b/content/applications/finance/accounting/taxation/taxes/taxcloud/fiscal-position-detect.png differ diff --git a/content/applications/finance/accounting/taxation/taxes/taxcloud/tax-payable-id.png b/content/applications/finance/accounting/taxation/taxes/taxcloud/tax-payable-id.png new file mode 100644 index 000000000..a841c0b86 Binary files /dev/null and b/content/applications/finance/accounting/taxation/taxes/taxcloud/tax-payable-id.png differ diff --git a/content/applications/finance/accounting/taxation/taxes/taxcloud/taxcloud-api-keys.png b/content/applications/finance/accounting/taxation/taxes/taxcloud/taxcloud-api-keys.png new file mode 100644 index 000000000..140e8bb02 Binary files /dev/null and b/content/applications/finance/accounting/taxation/taxes/taxcloud/taxcloud-api-keys.png differ diff --git a/content/applications/finance/accounting/taxation/taxes/taxcloud/taxcloud-settings.png b/content/applications/finance/accounting/taxation/taxes/taxcloud/taxcloud-settings.png new file mode 100644 index 000000000..689bba465 Binary files /dev/null and b/content/applications/finance/accounting/taxation/taxes/taxcloud/taxcloud-settings.png differ diff --git a/content/applications/finance/accounting/taxation/taxes/taxcloud/taxcloud01.png b/content/applications/finance/accounting/taxation/taxes/taxcloud/taxcloud01.png deleted file mode 100644 index 30e3b9110..000000000 Binary files a/content/applications/finance/accounting/taxation/taxes/taxcloud/taxcloud01.png and /dev/null differ diff --git a/content/applications/finance/accounting/taxation/taxes/taxcloud/taxcloud02.png b/content/applications/finance/accounting/taxation/taxes/taxcloud/taxcloud02.png deleted file mode 100644 index b463c4c95..000000000 Binary files a/content/applications/finance/accounting/taxation/taxes/taxcloud/taxcloud02.png and /dev/null differ diff --git a/content/applications/finance/accounting/taxation/taxes/taxcloud/taxcloud03.png b/content/applications/finance/accounting/taxation/taxes/taxcloud/taxcloud03.png deleted file mode 100644 index 9731f0705..000000000 Binary files a/content/applications/finance/accounting/taxation/taxes/taxcloud/taxcloud03.png and /dev/null differ diff --git a/content/applications/finance/accounting/taxation/taxes/taxcloud/taxcloud04.png b/content/applications/finance/accounting/taxation/taxes/taxcloud/taxcloud04.png deleted file mode 100644 index 8acd54a09..000000000 Binary files a/content/applications/finance/accounting/taxation/taxes/taxcloud/taxcloud04.png and /dev/null differ diff --git a/content/applications/finance/accounting/taxation/taxes/taxcloud/user-default-enter-default-account-id.png b/content/applications/finance/accounting/taxation/taxes/taxcloud/user-default-enter-default-account-id.png deleted file mode 100644 index fde8c5116..000000000 Binary files a/content/applications/finance/accounting/taxation/taxes/taxcloud/user-default-enter-default-account-id.png and /dev/null differ diff --git a/content/applications/finance/accounting/taxation/taxes/taxcloud/user-default-find-account-id.png b/content/applications/finance/accounting/taxation/taxes/taxcloud/user-default-find-account-id.png deleted file mode 100644 index 2ef439329..000000000 Binary files a/content/applications/finance/accounting/taxation/taxes/taxcloud/user-default-find-account-id.png and /dev/null differ diff --git a/content/applications/finance/accounting/taxation/taxes/taxcloud/user-default-search-field.png b/content/applications/finance/accounting/taxation/taxes/taxcloud/user-default-search-field.png deleted file mode 100644 index 7b40ef2fd..000000000 Binary files a/content/applications/finance/accounting/taxation/taxes/taxcloud/user-default-search-field.png and /dev/null differ diff --git a/content/applications/finance/accounting/taxation/taxes/taxcloud/user-default-select-field.png b/content/applications/finance/accounting/taxation/taxes/taxcloud/user-default-select-field.png deleted file mode 100644 index 588156c2d..000000000 Binary files a/content/applications/finance/accounting/taxation/taxes/taxcloud/user-default-select-field.png and /dev/null differ diff --git a/content/applications/finance/accounting/taxation/taxes/taxcloud/user-defaults-complete-configuration.png b/content/applications/finance/accounting/taxation/taxes/taxcloud/user-defaults-complete-configuration.png new file mode 100644 index 000000000..55228cad7 Binary files /dev/null and b/content/applications/finance/accounting/taxation/taxes/taxcloud/user-defaults-complete-configuration.png differ diff --git a/content/applications/finance/accounting/taxation/taxes/taxcloud/user-defaults-search-filters.png b/content/applications/finance/accounting/taxation/taxes/taxcloud/user-defaults-search-filters.png new file mode 100644 index 000000000..920aa0d7c Binary files /dev/null and b/content/applications/finance/accounting/taxation/taxes/taxcloud/user-defaults-search-filters.png differ diff --git a/content/applications/finance/accounting/taxation/taxes/taxcloud/user-defaults-search-more.png b/content/applications/finance/accounting/taxation/taxes/taxcloud/user-defaults-search-more.png new file mode 100644 index 000000000..6f767c3ea Binary files /dev/null and b/content/applications/finance/accounting/taxation/taxes/taxcloud/user-defaults-search-more.png differ