IMP] finance avatax doc peer edits

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

@@ -2,14 +2,13 @@
 AvaTax integration
 ==================
 
-Avalara's *AvaTax* is a cloud-based tax software that delivers the latest sales and use
-tax calculations to Odoo's sales and invoicing flow when the customer makes a purchase. *AvaTax* tax
-calculation is supported in every United Nations charted country. This includes inter-boarder
-transactions as well.
+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 in every United Nations charted country, including inter-border
+transactions.
 
 .. important::
-   Use of AvaTax for your company is only available for companies with locations in the United
-   States and Canada.
+   AvaTax is only available for databases/companies with locations in the United States and Canada.
 
 *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
@@ -29,18 +28,21 @@ Avalara provides the following services:
 .. important::
    Some limitations exist in Odoo while using AvaTax for tax calculation:
 
-   Point of Sale is not supported but it most cases a dynamic tax calculation model (like AvaTax) is
-   not necessary because the delivery address is always static, the store or restaurant itself.
+   - AvaTax is not supported in Odoo *Point of Sale*, 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.
+   - AvaTax and Odoo use the company address and not the warehouse address.
 
-   Exercise tax is not supported. This includes tabacco/vape taxes, fuel taxes, and other specific
-   industries.
+   - Exercise tax is not supported. This includes tabacco/vape taxes, fuel taxes, and other specific
+     industries.
 
 .. seealso::
    Avalara's support documents: `About AvaTax
    <https://community.avalara.com/support/s/document-item?language=en_US&bundleId=dqa1657870670369_dqa1657870670369&topicId=About_AvaTax.html&_LANG=enus>`_
 
+Set up on AvaTax (onboarding)
+=============================
+
 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
 <https://www.avalara.com/us/en/get-started.html>`_
@@ -49,20 +51,15 @@ connect with Avalara to purchase a license: `Avalara: Let's Talk
    Upon account setup, take note of the AvaTax :guilabel:`Account ID`. This will be needed in the
    :ref:`Odoo setup <avatax/credentials>`. In Odoo this number is the :guilabel:`API ID`.
 
-Set up on AvaTax (onboarding)
-=============================
-
- First `create a basic company profile
+ Then, `create a basic company profile
  <https://community.avalara.com/support/s/document-item?bundleId=dqa1657870670369_dqa1657870670369&topicId=Create_a_Basic_company_profile.html&_LANG=enus>`_.
 
 Create basic company profile
 ----------------------------
 
-Gather some key information about the business. Things that are necessary for the next step are:
-where the company collects tax, products and service that the company sells and where each is sold,
-and finally which customer are exempt from tax, if any.
-
-Follow the Avalara documentation for creating a 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 your company information
    <https://community.avalara.com/support/s/document-item?bundleId=dqa1657870670369_dqa1657870670369&topicId=Add_your_company_information.html&_LANG=enus>`_.
@@ -80,23 +77,27 @@ Follow the Avalara documentation for creating a basic company profile:
 Connect to AvaTax
 =================
 
-Following creating the basic company profile in Avalara, a connection to AvaTax **must** be made.
-This step is necessary to connect Odoo to AvaTax and vice-versa.
+After creating the basic company profile in Avalara, connect to AvaTax. This step links Odoo and
+AvaTax bidirectionally.
 
 Navigate to either Avalara's `sandbox <https://sandbox.admin.avalara.com/>`_ or `production
 <https://admin.avalara.com/>`_ environment. This will depend on which type of Avalara account the
 company would like to integrate.
 
 .. seealso::
-   Avalara's documentation on `sandbox vs production environments
+   `Sandbox vs production environments in Avalara
    <https://knowledge.avalara.com/bundle/fzc1692293626742/page/sandbox-vs-production.html>`_.
 
-Login to create the :guilabel:`Licence Key`. Go to :menuselection:`Settings --> License and API
-Keys`. Click :guilabel:`Generate Licence Key`.
+Log in to create the :guilabel:`License Key`. Go to :menuselection:`Settings --> License and API
+Keys`. Click :guilabel:`Generate License Key`.
 
-A warning will display 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.`
+.. note::
+   A warning will display 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. Ensure to update these apps with the new license key.
 
 Should this be the first :abbr:`API (application programming interface)` integration being made with
 AvaTax and Odoo, then click :guilabel:`Generate license key`.
@@ -105,41 +106,38 @@ Should this be an additional license key then, ensure the previous connection ca
 is **only** one license key associated with each of the Avalara sandbox and production accounts.
 
 Copy this key to a safe place. It is strongly encouraged to *download*, *print*, *copy and paste*,
-or *write* down the license key for future reference. This key is un-retrievable after leaving this
-screen.
+or *write* down the license key for future reference. This key cannot be retrieved after leaving
+this screen.
 
 Configuration in Odoo
 =====================
 
 Before using AvaTax there are some additional configurations in Odoo to ensure tax calculations are
 made accurately.
 
-Ensure that the company has data set up in the Odoo database. When the database or company is
-initially set up, a country is set. This country sets the fiscal position and helps *AvaTax*
-calculate the correct tax rates.
-
-.. seealso::
-   Refer to this documentation for more information: :doc:`../../fiscal_localizations`.
+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.
 
 Fiscal country
 --------------
 
-First, ensure that the :guilabel:`Fiscal Country` is set. To set it, navigate to,
-:menuselection:`Accounting --> Configuration --> Settings --> Fiscal Localization`.
-:guilabel:`Fiscal Localization` is located under the :guilabel:`Taxes` section.
+
+To set the :guilabel:`Fiscal Country`, navigate to :menuselection:`Accounting app --> Configuration
+--> Settings`.
 
 .. seealso::
    - :doc:`../../fiscal_localizations`
 
-For AvaTax this setting needs to be set to either :guilabel:`United States` or :guilabel:`Canada`.
+Under the :guilabel:`Taxes` section, set the :guilabel:`Fiscal Country` feature to :guilabel:`United
+States` or :guilabel:`Canada`.
 
 Company settings
 ----------------
 
 All companies operating under the Odoo database should have a full and complete address listed in
-the settings. Navigate to :menuselection:`Settings App --> Companies`. Should there only be one
-company operating the Odoo database, click :guilabel:`Update Info` to update the reliant contact
-information for the company.
+the settings. Navigate to :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.
 
 Should there be multiple companies operating in the database, click :guilabel:`Manage Companies` to
 load a list of companies to select from. Update customer information by clicking into the specific
@@ -149,12 +147,18 @@ Database administrators should ensure that the :guilabel:`Street...`, :guilabel:
 :guilabel:`City`, :guilabel:`State`, :guilabel:`ZIP`, and :guilabel:`Country` are all updated for
 the companies.
 
+This will ensure 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 :menuselection:`Apps
-application --> Search...` bar and then type in `avatax`. Press enter and the following results will
-populate:
+application. In the :guilabel:`Search...` bar, type in `avatax`. Press enter and the following
+results populate:
 
 - :guilabel:`Avatax`: `account_avatax`
 - :guilabel:`Avatax for SO`: `account_avatax_sale`
@@ -172,7 +176,7 @@ This will install the following modules:
 - :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`. Additionally, in Brazil two
+install those modules individually by clicking on :guilabel:`Install`. Additionally, in Brazil, two
 separate *AvaTax* modules need to be installed. See the list above for these modules.
 
 .. _avatax/credentials:
@@ -181,8 +185,9 @@ Odoo AvaTax settings
 ====================
 
 To integrate the *AvaTax* :abbr:`API (application programming interface)` with Odoo, go to
-:menuselection:`Accounting --> Configuration --> Settings --> Taxes --> AvaTax` section. This is
-where the *AvaTax* some configurations will be made and the credentials will be entered in.
+:menuselection:`Accounting --> 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
@@ -191,10 +196,7 @@ where the *AvaTax* some configurations will be made and the credentials will be
 Prerequisites
 -------------
 
-Before the credentials are entered in, tick the checkbox to the right of the :guilabel:`AvaTax`
-title to activate the feature.
-
-Next, select the :guilabel:`Environment` that the company wishes to use AvaTax in. It can either be
+First, select the :guilabel:`Environment` that the company wishes to use AvaTax in. It can either be
 :guilabel:`Sandbox` or :guilabel:`Production`.
 
 .. seealso::
@@ -209,7 +211,7 @@ Now, the credentials can be entered in. The AvaTax :guilabel:`Account ID` will b
 :guilabel:`API ID` field and the :guilabel:`License Key` will be entered in the :guilabel:`API Key`
 field.
 
-.. tip::
+.. important::
    The :guilabel:`Account ID` can be found by logging into the AvaTax portal (`sandbox
    <https://sandbox.admin.avalara.com/>`_ or `production <https://admin.avalara.com/>`_). In the
    upper-right corner are the initials of the user and :guilabel:`Account`, click into this icon.
@@ -218,6 +220,19 @@ field.
    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
+<https://sandbox.admin.avalara.com/>`_ or `production <https://admin.avalara.com/>`_). 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
 -------------------
 
@@ -234,13 +249,16 @@ 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 in North America.
+   The :guilabel:`Address Validation` feature only works with partners 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
+   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.
@@ -258,7 +276,7 @@ Additionally, tick the checkbox next to the :guilabel:`Address validation` field
 
    .. image:: avatax/validate-address.png
       :align: center
-      :alt: Validate address pop-up window in Odoo with save validated button and validated address
+      :alt: Validate address pop-up window in Odoo with "Save Validated" button and "Validated Address"
             highlighted.
 
 .. warning::
@@ -270,26 +288,28 @@ Sync parameters
 ---------------
 
 Upon finishing the configuration and settings of the AvaTax section click the :guilabel:`Sync
-Parameters`. This action will synchronize the exemption codes from AvaTax.
+Parameters` button. This action will synchronize the exemption codes from AvaTax.
 
 .. _avatax/fiscal_positions:
 
 Fiscal position
 ===============
 
-Next, navigate to :menuselection:`Configuration --> Accounting --> Fiscal Positions`. A new
-:guilabel:`Fiscal Position` is listed called :guilabel:`Automatic Tax Mapping (AvaTax)`. Click on
-this :guilabel:`Fiscal Position`.
+Next, navigate to :menuselection:`Accounting app --> Configuration --> Accounting: Fiscal
+Positions`. A :guilabel:`Fiscal Position` is listed called :guilabel:`Automatic Tax Mapping
+(AvaTax)`. Click it to open AvaTax's fiscal position configuration page.
 
-Ensure that the :guilabel:`Use AvaTax API` checkbox is ticked.
+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.
 
-Specific parameters, such as :guilabel:`VAT required`, :guilabel:`Foreign Tax ID`,
-:guilabel:`Country Group`, :guilabel:`Country`, :guilabel:`Federal States`, or :guilabel:`Zip Range`
-can be specified below this checkbox.
+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 this parameters will filter the
+:guilabel:`Fiscal Position` usage. Leaving them blank will ensure all calculations are made using
+this :guilabel:`Fiscal Position`.
 
 .. warning::
    Should the :guilabel:`Detect Automatically` checkbox not be ticked, then each *Customer* will
@@ -303,7 +323,7 @@ can be specified below this checkbox.
    for the customer.
 
    .. seealso::
-      - :doc:`fiscal_positions`
+      :doc:`fiscal_positions`
 
 AvaTax accounts
 ---------------
@@ -328,9 +348,9 @@ Product category mapping
 
 Before using the integration, specify an :guilabel:`Avatax Category` on the product categories.
 Navigate to :menuselection:`Inventory --> Configuration --> Product Categories`. Select the product
-category to add the :guilabel:`AvaTax Category` to. Finally next to the field labeled
-:guilabel:`AvaTax Category`, click the drop-down menu and select a category, or :guilabel:`Search
-More...` to find one that isn't connected.
+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
@@ -339,12 +359,15 @@ More...` to find one that isn't connected.
 Product mapping
 ---------------
 
-AvaTax Categories may be overridden or 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.
+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 AvaTax Category set, the product's AvaTax Category
+   takes precedence.
 
 .. image:: avatax/override-avatax-product-category.png
    :align: center