diff --git a/content/applications/finance/accounting/taxes/avatax.rst b/content/applications/finance/accounting/taxes/avatax.rst index 255061342..5de628447 100644 --- a/content/applications/finance/accounting/taxes/avatax.rst +++ b/content/applications/finance/accounting/taxes/avatax.rst @@ -1,80 +1,404 @@ :show-content: ================== -Avatax integration +AvaTax integration ================== -Avatax is a tax calculation provider that can be integrated in Odoo. +Avalara's *AvaTax* is a cloud-based tax software. Integrating *AvaTax* with Odoo provides real-time +and region-specific tax calculations when users sell, purchase, and invoice items in Odoo. *AvaTax* +tax calculation is supported with every United Nations charted country, including inter-border +transactions. + +.. important:: + *AvaTax* is only available for integration with databases/companies that have locations in the + United States and Canada. This means the fiscal position/country of a database can only be set to + the United States or Canada. For more information, reference this documentation: + :ref:`avatax/fiscal_country`. + +*AvaTax* accounts for location-based tax rates for each state, county, and city. It improves +remittance accuracy by paying close attention to laws, rules, jurisdiction boundaries, and special +circumstances (like, tax holidays, and product exemptions). Companies who integrate with *AvaTax* +can maintain control of tax-calculations in-house with this simple :abbr:`API (application +programming interface)` integration. + +.. important:: + Some limitations exist in Odoo while using *AvaTax* for tax calculation: + + - *AvaTax* is **not** supported in Odoo's *Point of Sale* app, because a dynamic tax calculation + model is excessive for transactions within a single delivery address, such as stores or + restaurants. + - *AvaTax* and Odoo use the company address and **not** the warehouse address. + - Exercise tax is **not** supported. This includes tobacco/vape taxes, fuel taxes, and other + specific industries. + +.. seealso:: + Avalara's support documents: `About AvaTax + `_ + +Set up on AvaTax +================ + +To use *AvaTax*, an account with Avalara is required for the setup. If one has not been set up yet, +connect with Avalara to purchase a license: `Avalara: Let's Talk +`_. + +.. tip:: + Upon account setup, take note of the *AvaTax* :guilabel:`Account ID`. This will be needed in the + :ref:`Odoo setup `. In Odoo, this number is the :guilabel:`API ID`. + +Then, `create a basic company profile +`_. + +Create basic company profile +---------------------------- + +Collect essential business details for the next step: locations where tax is collected, +products/services sold (and their sales locations), and customer tax exemptions, if applicable. +Follow the Avalara documentation for creating a basic company profile: + +#. `Add company information + `_. +#. `Tell us where the company collects and pays tax + `_. +#. `Verify jurisdictions and activate the company + `_. +#. `Add other company locations for location-based filing + `_. +#. `Add a marketplace to the company profile + `_. + +.. _avatax/create_avalara_credentials: + +Connect to AvaTax +----------------- + +After creating the basic company profile in Avalara, connect to *AvaTax*. This step links Odoo and +*AvaTax* bidirectionally. + +Navigate to either Avalara's `sandbox `_ or `production +`_ environment. This will depend on which type of Avalara account the +company would like to integrate. + +.. seealso:: + `Sandbox vs production environments in Avalara + `_. + +Log in to create the :guilabel:`License Key`. Go to :menuselection:`Settings --> License and API +Keys`. Click :guilabel:`Generate License Key`. + +.. note:: + A warning appears stating: `If your business app is connected to Avalara solutions, the + connection will be broken until you update the app with the new license key. This action cannot + be undone.` + + Generating a new license key breaks the connection with existing business apps using the *AvaTax* + integration. Make sure to update these apps with the new license key. + +If this will be the first :abbr:`API (application programming interface)` integration being made +with *AvaTax* and Odoo, then click :guilabel:`Generate license key`. + +If this is an additional license key, ensure the previous connection can be broken. There is +**only** one license key associated with each of the Avalara sandbox and production accounts. + +.. important:: + Copy this key to a safe place. It is **strongly encouraged** to backup the license key for future + reference. This key cannot be retrieved after leaving this screen. + +Odoo configuration +================== + +Before using *AvaTax*, there are some additional configurations in Odoo to ensure tax calculations +are made accurately. + +Verify that the Odoo database contains necessary data. The country initially set up in the database +determines the fiscal position, and aids *AvaTax* in calculating accurate tax rates. + +.. _avatax/fiscal_country: + +Fiscal country +-------------- + +To set the :guilabel:`Fiscal Country`, navigate to :menuselection:`Accounting app --> Configuration +--> Settings`. + +.. seealso:: + :doc:`../../fiscal_localizations` + +Under the :guilabel:`Taxes` section, set the :guilabel:`Fiscal Country` feature to :guilabel:`United +States` or :guilabel:`Canada`. Then, click :guilabel:`Save`. + +Company settings +---------------- + +All companies operating under the Odoo database should have a full and complete address listed in +the settings. Navigate to the :menuselection:`Settings app`, and under the :guilabel:`Companies` +section, ensure there is only one company operating the Odoo database. Click :guilabel:`Update Info` +to open a separate page to update company details. + +If there are multiple companies operating in the database, click :guilabel:`Manage Companies` to +load a list of companies to select from. Update company information by clicking into the specific +company. + +Database administrators should ensure that the :guilabel:`Street...`, :guilabel:`Street2...`, +:guilabel:`City`, :guilabel:`State`, :guilabel:`ZIP`, and :guilabel:`Country` are all updated for +the companies. + +This ensures accurate tax calculations and smooth end-of-year accounting operations. + +.. seealso:: + - :doc:`../../../general/companies` + - :doc:`../get_started` + +Module installation +------------------- + +Next, ensure that the Odoo *AvaTax* module is installed. To do so, navigate to the +:menuselection:`Apps application`. In the :guilabel:`Search...` bar, type in `avatax`, and press +:kbd:`Enter`. The following results populate: + +.. list-table:: + :header-rows: 1 + :widths: 25 25 50 + + * - Name + - Technical name + - Description + * - :guilabel:`Avatax` + - `account_avatax` + - Default *AvaTax* module. This module adds the base *AvaTax* features for tax calculation. + * - :guilabel:`Avatax for SO` + - `account_avatax_sale` + - Includes the information needed for tax calculation on sales orders in Odoo. + * - :guilabel:`Avatax for Subscriptions` + - `account_avatax_sale_subscription` + - This module includes the features required for tax calculation on subscriptions in Odoo. + * - :guilabel:`Account Avatax - Ecommerce` + - `website_sale_account_avatax` + - Includes tax calculation features for the checkout process on Odoo eCommerce. + * - :guilabel:`Account AvaTax - Ecommerce - Delivery` + - `website_sale_delivery_avatax` + - Includes tax calculation features for the delivery process on Odoo eCommerce. + +Click the :guilabel:`Install` button on the module labeled :guilabel:`Avatax`: `account_avatax`. +Doing so installs the following modules: + +- :guilabel:`Avatax`: `account_avatax` +- :guilabel:`Avatax for SO`: `account_avatax_sale` +- :guilabel:`Account Avatax - Ecommerce`: `website_sale_account_avatax` + +Should *AvaTax* be needed for Odoo *Subscriptions*, or for delivery tax in Odoo *eCommerce*, then +install those modules individually by clicking on :guilabel:`Install`. .. _avatax/credentials: -Credential configuration -======================== +Odoo AvaTax settings +-------------------- -To integrate Avatax with Odoo, go to :menuselection:`Accounting --> Configuration --> Settings --> -Taxes` and add your Avatax credentials in the :guilabel:`Avatax` section. - -.. tip:: - If you do not yet have credentials, click on :guilabel:`How to Get Credentials`. +To integrate the *AvaTax* :abbr:`API (application programming interface)` with Odoo, go to +:menuselection:`Accounting app --> Configuration --> Settings` section. The :guilabel:`AvaTax` +fields in the :guilabel:`Taxes` section is where the *AvaTax* configurations are made and the +credentials are entered in. .. image:: avatax/avatax-configuration-settings.png :align: center - :alt: Configure Avatax settings + :alt: Configure AvaTax settings -.. _avatax/tax-mapping: +Prerequisites +~~~~~~~~~~~~~ + +First, select the :guilabel:`Environment` in which the company wishes to use *AvaTax* in. It can +either be :guilabel:`Sandbox` or :guilabel:`Production`. + +.. seealso:: + For help determining which *AvaTax* environment to use (either :guilabel:`Production` or + :guilabel:`Sandbox`), visit: `Sandbox vs Production environments + `_. + +Credentials +~~~~~~~~~~~ + +Now, the credentials can be entered in. The *AvaTax* :guilabel:`Account ID` should be entered in the +:guilabel:`API ID` field, and the :guilabel:`License Key` should be entered in the :guilabel:`API +Key` field. + +.. important:: + The :guilabel:`Account ID` can be found by logging into the *AvaTax* portal (`sandbox + `_ or `production `_). In the + upper-right corner, click on the initials of the user and :guilabel:`Account`. The + :guilabel:`Account ID` is listed first. + + To access the :guilabel:`License Key` see this documentation: + :ref:`avatax/create_avalara_credentials`. + +For the :guilabel:`Company Code` field, enter the Avalara company code for the company being +configured. Avalara interprets this as `DEFAULT`, if it is not set. The :guilabel:`Company Code` can +be accessed in the Avalara management portal. + +First, log into the *AvaTax* portal (`sandbox `_ or `production +`_). Then, navigate to :menuselection:`Settings --> Manage Companies`. +The :guilabel:`Company Code` value is located in the row of the :guilabel:`Company` in the +:guilabel:`Company Code` column. + +.. image:: avatax/company-code.png + :align: center + :alt: AvaTax company code highlighted on the company details page. + +Transaction options +~~~~~~~~~~~~~~~~~~~ + +There are two transactional settings in the Odoo *AvaTax* settings that can be configured: +:guilabel:`Use UPC` and :guilabel:`Commit Transactions`. + +If the checkbox next to :guilabel:`Use UPC` is ticked, the transactions will use Universal Product +Codes (UPC), instead of custom defined codes in Avalara. Consult a certified public accountant (CPA) +for specific guidance. + +Should the :guilabel:`Commit Transactions` checkbox be ticked, then, the transactions in the Odoo +database will be committed for reporting in *AvaTax*. + +Address validation +~~~~~~~~~~~~~~~~~~ + +The *Address Validation* feature ensures that the most up-to-date address by postal standards is set +on a contact in Odoo. This is important to provide accurate tax calculations for customers. + +.. important:: + The :guilabel:`Address Validation` feature only works with partners/customers in North America. + +Additionally, tick the checkbox next to the :guilabel:`Address validation` field. + +.. important:: + For accurate tax calculations, it is best practice to enter a complete address for the contacts + saved in the database. However, *AvaTax* can still function by implementing a best effort attempt + using only the :guilabel:`Country`, :guilabel:`State`, and :guilabel:`Zip code`. These are the + three minimum required fields. + +:guilabel:`Save` the settings to implement the configuration. + +.. tip:: + Manually :guilabel:`Validate` the address by navigating to the :menuselection:`Contacts app`, and + selecting a contact. Now that the *AvaTax* module has been configured on the database, a + :guilabel:`Validate` button appears directly below the :guilabel:`Address`. + + Click :guilabel:`Validate`, and a pop-up window appears with a :guilabel:`Validated Address` and + :guilabel:`Original Address` listed. If the :guilabel:`Validated Address` is the correct mailing + address for tax purposes, click :guilabel:`Save Validated`. + + .. image:: avatax/validate-address.png + :align: center + :alt: Validate address pop-up window in Odoo with "Save Validated" button and "Validated + Address" highlighted. + +.. warning:: + All previously-entered addresses for contacts in the Odoo database will need to be validated + using the manually validate process outlined above. Addresses are not automatically validated if + they were entered previously. This only occurs upon tax calculation. + +Test connection +~~~~~~~~~~~~~~~ + +After entering all the above information into the *AvaTax* setup on Odoo, click :guilabel:`Test +connection`. This ensures the :guilabel:`API ID` and :guilabel:`API KEY` are correct, and a +connection is made between Odoo and the *AvaTax* application programming interface (API). + +Sync parameters +~~~~~~~~~~~~~~~ + +Upon finishing the configuration and settings of the *AvaTax* section, click the :guilabel:`Sync +Parameters` button. This action synchronizes the exemption codes from *AvaTax*. + +.. _avatax/fiscal_positions: + +Fiscal position +--------------- + +Next, navigate to :menuselection:`Accounting app --> Configuration --> Accounting: Fiscal +Positions`. A :guilabel:`Fiscal Position` is listed named, :guilabel:`Automatic Tax Mapping +(AvaTax)`. Click it to open *AvaTax's* fiscal position configuration page. + +Here, ensure that the :guilabel:`Use AvaTax API` checkbox is ticked. + +Optionally, tick the checkbox next to the field labeled: :guilabel:`Detect Automatically`. Should +this option be ticked, then, Odoo will automatically apply this :guilabel:`Fiscal Position` for +transactions in Odoo. + +Enabling :guilabel:`Detect Automatically` also makes specific parameters, such as :guilabel:`VAT +required`, :guilabel:`Foreign Tax ID`, :guilabel:`Country Group`, :guilabel:`Country`, +:guilabel:`Federal States`, or :guilabel:`Zip Range` appear. Filling these parameters filters the +:guilabel:`Fiscal Position` usage. Leaving them blank ensures all calculations are made using this +:guilabel:`Fiscal Position`. + +.. warning:: + Should the :guilabel:`Detect Automatically` checkbox not be ticked, each customer will need to + have the :guilabel:`Fiscal Position` set on their :guilabel:`Sales and Purchase` tab of the + contact record. To do so, navigate to :menuselection:`Sales app --> Order --> Customers`, or + :menuselection:`Contacts app --> Contacts`. Then, select a customer or contact to set the fiscal + position on. + + Navigate to the :guilabel:`Sales and Purchase` tab, and down to the section labeled, + :guilabel:`Fiscal Position`. Set the :guilabel:`Fiscal Position` field to the fiscal position + for the customer. + +.. seealso:: + :doc:`fiscal_positions` + +AvaTax accounts +~~~~~~~~~~~~~~~ + +Upon selecting the checkbox option for :guilabel:`Use AvaTax API` a new :guilabel:`AvaTax` tab +appears. Click into this tab to reveal two different settings. + +The first setting is the :guilabel:`AvaTax Invoice Account`, while the second is, :guilabel:`AvaTax +Refund Account`. Ensure both accounts are set for smooth end-of-year record keeping. Consult a +certified public accountant (CPA) for specific guidance on setting both accounts. + +Click :guilabel:`Save` to implement the changes. Tax mapping -=========== +----------- -The Avatax integration is available on Sale Orders and Invoices with the included Avatax fiscal +The *AvaTax* integration is available on sale orders and invoices with the included *AvaTax* fiscal position. +Product category mapping +~~~~~~~~~~~~~~~~~~~~~~~~ + Before using the integration, specify an :guilabel:`Avatax Category` on the product categories. +Navigate to :menuselection:`Inventory app --> Configuration --> Product Categories`. Select the +product category to add the :guilabel:`AvaTax Category` to. In the :guilabel:`AvaTax Category` +field, select a category from the drop-down menu, or :guilabel:`Search More...` to open the complete +list of options. .. image:: avatax/avatax-category.png :align: center - :alt: Specify Avatax Category on products + :alt: Specify AvaTax Category on products. -Avatax Categories may be overridden or set on individual products as well. +Product mapping +~~~~~~~~~~~~~~~ + +*AvaTax* Categories may be set on individual products, as well. To set the :guilabel:`Avatax +Category` navigate to :menuselection:`Inventory app --> Products --> Products`. Select the product +to add the :guilabel:`Avatax Category` to. Under the :guilabel:`General Information` tab, on the +far-right, is a selector field labeled: :guilabel:`Avatax Category`. Finally, click the drop-down +menu, and select a category, or :guilabel:`Search More...` to find one that is not listed. + +.. note:: + If both the product, and its category, have an :guilabel:`AvaTax Category` set, the product's + :guilabel:`AvaTax Category` takes precedence. .. image:: avatax/override-avatax-product-category.png :align: center - :alt: Override product categories as needed + :alt: Override product categories as needed. -.. _avatax/address-mapping: - -Address validation -================== - -Manually validate customer addresses by clicking the :guilabel:`Validate address` link in the -customer form view. - -.. image:: avatax/validate-customer-address.png - :align: center - :alt: Validate customer addresses - -If preferred, choose to keep the newly validated address or the original address in the wizard that -pops up. - -.. image:: avatax/choose-customer-address.png - :align: center - :alt: Address validation wizard - -.. _avatax/tax-calculation: - -Tax calculation -=============== - -Automatically calculate taxes on Odoo quotations and invoices with Avatax by confirming the -documents. Alternatively, calculate the taxes manually by clicking the :guilabel:`Compute taxes -using Avatax` button while these documents are in draft mode. - -Use the :guilabel:`Avalara Code` field that's available on customers, quotations, and invoices to -cross-reference data in Odoo and Avatax. +.. important:: + Mapping an :guilabel:`AvaTax Category` on either the *Product* or *Product Category* should be + completed for every *Product* or *Product Category*, depending the route that is chosen. .. seealso:: - :doc:`fiscal_positions` - :doc:`avatax/avatax_use` + - `US Tax Compliance: Avatax elearning video + `_ .. toctree:: :titlesonly: diff --git a/content/applications/finance/accounting/taxes/avatax/choose-customer-address.png b/content/applications/finance/accounting/taxes/avatax/choose-customer-address.png deleted file mode 100644 index 284c29b6f..000000000 Binary files a/content/applications/finance/accounting/taxes/avatax/choose-customer-address.png and /dev/null differ diff --git a/content/applications/finance/accounting/taxes/avatax/company-code.png b/content/applications/finance/accounting/taxes/avatax/company-code.png new file mode 100644 index 000000000..ab937ba0c Binary files /dev/null and b/content/applications/finance/accounting/taxes/avatax/company-code.png differ diff --git a/content/applications/finance/accounting/taxes/avatax/validate-address.png b/content/applications/finance/accounting/taxes/avatax/validate-address.png new file mode 100644 index 000000000..db1e75569 Binary files /dev/null and b/content/applications/finance/accounting/taxes/avatax/validate-address.png differ diff --git a/content/applications/finance/accounting/taxes/avatax/validate-customer-address.png b/content/applications/finance/accounting/taxes/avatax/validate-customer-address.png deleted file mode 100644 index b17abe81d..000000000 Binary files a/content/applications/finance/accounting/taxes/avatax/validate-customer-address.png and /dev/null differ