[REM] accounting: multiple payments

Removing redundant page (see task) See PR https://github.com/odoo/documentation/pull/6645 taskid-3466400
[IMP] localization: spain missing reports
2024-01-11 10:27:47 +01:00 · 2024-01-09 13:52:02 +00:00 · 2024-01-07 02:40:31 +01:00 · 2024-01-05 15:42:56 +00:00 · 2024-01-04 16:15:26 +00:00 · 2024-01-04 16:15:23 +00:00
633 changed files with 115758 additions and 79939 deletions
@@ -86,12 +86,13 @@ static: $(HTML_BUILD_DIR)/_static/style.css

 # Called by runbot for the ci/documentation_guideline check.
 test:
-	@python tests/main.py $(SOURCE_DIR)/administration $(SOURCE_DIR)/applications $(SOURCE_DIR)/contributing $(SOURCE_DIR)/developer $(SOURCE_DIR)/services redirects
+	@python tests/main.py $(SOURCE_DIR)/administration $(SOURCE_DIR)/applications $(SOURCE_DIR)/contributing $(SOURCE_DIR)/developer redirects

 # Similar as `test`, but called only manually by content reviewers to trigger extra checks.
 review:
-	@read -p "Enter content path: " path; read -p "Enter max line length (default: 100): " line_length; \
+	@read -p "Enter relative content path: " path; read -p "Enter max line length (default: 100): " line_length; \
 	if [ -z "$$path" ]; then echo "Error: Path cannot be empty"; exit 1; fi; \
+	if echo $$path | grep -q 'content/'; then path=`echo $$path | sed 's|content/||'`; fi; \
 	if [ -z "$$line_length" ]; then line_length=100; fi; \
 	export REVIEW=1; \
 	python tests/main.py --max-line-length=$$line_length $(SOURCE_DIR)/$$path
@@ -211,6 +211,7 @@ sphinx.transforms.i18n.docname_to_domain = (
 # is populated. If a version is passed to `versions` but is not listed here, it will not be shown.
 versions_names = {
    'master': "Master",
+    '17.0': "Odoo 17",
    'saas-16.4': "Odoo Online",
    'saas-16.3': "Odoo Online",
    'saas-16.2': "Odoo Online",
@@ -219,7 +220,6 @@ versions_names = {
    'saas-15.2': "Odoo Online",
    '15.0': "Odoo 15",
    '14.0': "Odoo 14",
-    '13.0': "Odoo 13",
 }

 # The language names that should be shown in the language switcher, if the config option `languages`
@@ -310,7 +310,7 @@ in ``/etc/nginx/sites-enabled/odoo.conf`` set:
    proxy_send_timeout 720s;

    # Add Headers for odoo proxy mode
-    proxy_set_header X-Forwarded-Host $host;
+    proxy_set_header X-Forwarded-Host $http_host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP $remote_addr;
@@ -25,13 +25,13 @@ To get started, go to `Microsoft's Azure Portal <https://portal.azure.com/>`_. L
 :guilabel:`Microsoft Outlook Office 365` account if there is one, otherwise log in with the
 personal :guilabel:`Microsoft account`. A user with administrative access to the Azure Settings
 will need to connect and perform the following configuration. Next, navigate to the section
-labeled :guilabel:`Manage Azure Active Directory`.
+labeled :guilabel:`Manage Microsoft Entra ID` (formally *Azure Active Directory*).

 Now, click on :guilabel:`Add (+)`, located in the top menu, and then select :guilabel:`App
 registration`. On the :guilabel:`Register an application` screen, rename the :guilabel:`Name` to
 `Odoo` or something recognizable. Under the :guilabel:`Supported account types` section select
-:guilabel:`Accounts in any organizational directory (Any Azure AD directory - Multitenant) and
-personal Microsoft accounts (e.g. Skype, Xbox)`.
+:guilabel:`Accounts in any organizational directory (Any Microsoft Entra ID directory - Multitenant)
+and personal Microsoft accounts (e.g. Skype, Xbox)`.

 Under the :guilabel:`Redirect URL` section, select :guilabel:`Web` as the platform, and then input
 `https://<odoo base url>/microsoft_outlook/confirm` in the :guilabel:`URL` field. The Odoo base URL
@@ -30,8 +30,8 @@ Upgrade
 Trigger a database upgrade.

 .. seealso::
-   For more information about the upgrade process, check out the :doc:`Odoo Online upgrade
-   documentation <../upgrade/odoo_online>`.
+   For more information about the upgrade process, check out the :ref:`Odoo Online upgrade
+   documentation <upgrade/request-test-database>`.

 .. _odoo_online/duplicate:

@@ -129,6 +129,5 @@ users, click :guilabel:`Add more users`.
 To remove users, select them and click :guilabel:`Remove`.

 .. seealso::
-   - :doc:`../../applications/general/users/manage_users`
-   - :doc:`../../applications/general/users/delete_account`
-
+   - :doc:`/applications/general/users/manage_users`
+   - :doc:`/applications/general/users/odoo_account`
@@ -1,3 +1,4 @@
+:hide-page-toc:

 .. _supported_versions:

@@ -16,9 +17,6 @@ Odoo provides support and bug fixing **for the 3 last major versions** of Odoo.
   - Online versions are *not* released for Odoo.sh and On-Premise installations.
   - Online versions are listed below as *SaaS*.

-What's the support status of my Odoo?
-=====================================
-
 This matrix shows the support status of every version.

 **Major releases are in bold type.**
@@ -33,6 +31,12 @@ This matrix shows the support status of every version.
     - On-Premise
     - Release date
     - End of support
+   * - **Odoo 17.0**
+     - |green|
+     - |green|
+     - |green|
+     - November 2023
+     - November 2026 (planned)
   * - Odoo saas~16.4
     - |green|
     - N/A
@@ -62,7 +66,7 @@ This matrix shows the support status of every version.
     - |green|
     - |green|
     - October 2022
-     - October 2025 (planned)
+     - November 2025 (planned)
   * - Odoo saas~15.2
     - |red|
     - N/A
@@ -80,21 +84,27 @@ This matrix shows the support status of every version.
     - |green|
     - |green|
     - October 2021
-     - October 2024 (planned)
+     - November 2024 (planned)
   * - **Odoo 14.0**
-     - |green|
-     - |green|
-     - |green|
+     - |red|
+     - |red|
+     - |red|
     - October 2020
-     - November 2023 (planned)
+     - November 2023
   * - **Odoo 13.0**
     - |red|
     - |red|
     - |red|
     - October 2019
     - October 2022
+   * - Older versions
+     - |red|
+     - |red|
+     - |red|
+     - Before 2019
+     - Before 2022

-.. note::
+.. admonition:: Legend

    |green| Supported version

@@ -102,7 +112,9 @@ This matrix shows the support status of every version.

    N/A Never released for this platform

-    🏁 Future version, not released yet
+.. important::
+   Even though we don't support older versions, you can always `upgrade from any version
+   <https://upgrade.odoo.com/>`_.

 .. |green| raw:: html

@@ -111,14 +123,3 @@ This matrix shows the support status of every version.
 .. |red| raw:: html

   <span class="text-danger" style="font-size: 32px; line-height: 0.5">●</span>
-
-I run an older version of Odoo/OpenERP/TinyERP
-==============================================
-
-Odoo 12.0, 11.0, 10.0, 9.0, and 8.0 are not supported anymore, on any platform.
-
-OpenERP 7.0, 6.1, 6.0 and 5.0 are not supported anymore, on any platform.
-
-TinyERP 4.0, 3.0, 2.0 and 1.0 are not supported anymore, on any platform.
-
-Even though we don't support older versions, you can always `upgrade from any version <https://upgrade.odoo.com/>`_.
@@ -295,7 +295,7 @@ Upgrade
 Available for production and staging branches for valid projects.

 .. seealso::
-    :doc:`Upgrade - Odoo.sh <../../upgrade/odoo_sh>`
+    :doc:`Upgrade documentation <../../upgrade>`

 .. _odoosh-gettingstarted-branches-tabs-settings:

@@ -1,226 +1,373 @@
-:show-content:
-
-.. |assistance-contact| replace::
-   If you need Odoo assistance on this matter, please get in touch with your Odoo Account Manager or
-   our `Sales department`_.
-.. _Sales department: mailto:sales@odoo.com
-
 =======
 Upgrade
 =======

-.. toctree::
-   :titlesonly:
+An upgrade is the process of moving your database from an older version to a newer :doc:`supported
+version <maintain/supported_versions>` (e.g., Odoo 14.0 to Odoo 16.0). Frequently upgrading is
+essential as each version comes with new and improved features, bug fixes, and security patches.

-   upgrade/odoo_online
-   upgrade/odoo_sh
-   upgrade/on_premise
-   upgrade/faq
+.. _upgrade_faq/rolling_release:

-An upgrade is switching to a newer version of Odoo (e.g., Odoo 14.0 to Odoo 15.0).
+.. spoiler:: Automatic upgrades: Odoo Online's Rolling Release process
+
+   The Rolling Release process allows Odoo Online customers to upgrade their database directly from
+   a message prompt sent to the database administrator as soon as a new version is released. The
+   invitation to upgrade is only sent if no issues are detected during the automatic tests.
+
+   .. image:: upgrade/rr-upgrade-message.png
+      :alt: The upgrade message prompt on the top right of the database
+
+   It is strongly recommended to manually :ref:`test the upgrade first <upgrade/test_your_db>`.
+   Clicking :guilabel:`I want to test first` redirects to `the database manager
+   <https://www.odoo.com/my/databases/>`_, where it is possible to request an upgraded test database
+   and check it for any discrepancies.
+
+   It is **not** recommended to click :guilabel:`Upgrade Now` without testing first, as it
+   immediately triggers the live production database upgrade.
+
+   If the Rolling Release process detects an issue with the upgrade, it will be deactivated until
+   the issue is resolved.

 An upgrade does not cover:

-* Changing :ref:`editions <upgrade-faq/editions-change>` (i.e., Community to Enterprise edition)
-* Switching :ref:`hosting type <upgrade-faq/hosting-types-switch>` (i.e., On-Premise to Odoo Online
-  or Odoo.sh)
-* Migration from another ERP to Odoo
+  - Downgrading to a previous version of Odoo
+  - :doc:`Switching editions <maintain/enterprise>` (e.g., from Community to Enterprise)
+  - :doc:`Changing hosting type </administration/maintain/hosting_changes>` (e.g., from on-premise
+    to Odoo Online)
+  - Migrating from another ERP to Odoo

-.. note:: |assistance-contact|
+.. warning::
+   If your database contains a **custom module**, you must first upgrade its source code to be
+   compatible with the new version of Odoo **before upgrading**.
+.. TODOUPG : once the page for developers is published, uncomment and link
+.. :doc:`first upgrade its source code </developer/reference/upgrade>`

-.. seealso::
-   - :ref:`upgrade/sla`

-.. _upgrade/process-workflow:
+Upgrading in a nutshell
+-----------------------

-Process workflow
-================
+#. Request an upgraded test database (see :ref:`obtaining an upgraded test database
+   <upgrade/request-test-database>`).

-The upgrade process in a nutshell:
+#. Thoroughly test the upgraded database (see :ref:`testing the new version of the database
+   <upgrade/test_your_db>`).

-#. You create a test upgrade request.
-#. Odoo processes the request automatically by running the database through an upgrade script, which
-   takes between 20 and 120 minutes.
-#. Odoo delivers a test database.
-#. You test your database for possible discrepancies (see :ref:`upgrade/test-guidance`).
-#. If there are any discrepancies, you report them to the Upgrade support team via the help portal
-   (see :ref:`upgrade/test-assistance`).
-#. We fix the issues and send you a new test database.
-#. Once you have completed the testing and are happy with the result, you decide on a date and time
-   when you stop users from accessing Odoo, freeze all data entries, and create an upgrade request
-   for the production upgrade.
-#. Odoo delivers the production database through the automated process.
-#. You restore it in your Production environment a few short hours later and continue working on the
-   newly upgraded database (this is done automatically on Odoo Online).
+#. Report any issue encountered during the testing to Odoo via the `support page
+   <https://odoo.com/help?stage=migration>`__.

-.. seealso::
-   - :doc:`Upgrade process for Odoo Online <upgrade/odoo_online>`
-   - :doc:`Upgrade process for Odoo.sh <upgrade/odoo_sh>`
-   - :doc:`Upgrade process for On-Premise <upgrade/on_premise>`
+#. (If applicable) : upgrade the source code of your custom module to be compatible with the new
+   version of Odoo.

-.. _upgrade/testing-phase:
+#. Once all issues are resolved and you are confident that the upgraded database can be used as
+   your main database without any issues, plan the upgrade of your production database.

-Testing
-=======
+#. Request the upgrade for the production database, rendering it unavailable for the time it takes
+   to complete the process (see :ref:`upgrading the production database <upgrade/upgrade-prod>`).

-This phase allows you to review an upgraded version of your database without affecting your
-production database in any way. We suggest that you run the test upgrade process at least once, but
-you can do it as many times as you need (one at a time).
+#. Report any issue encountered during the upgrade to Odoo via the `support page
+   <https://odoo.com/help?stage=post_upgrade>`__.

-Once you receive your upgraded test database, check that all data, processes, and functionality are
-still correct and working as expected.
+.. TODOUPG: Once the page for developers is published, put this at 4)
+.. (see :ref:`upgrading customizations <upgrade/upgrading_customizations>`).

-If you do find discrepancies, :ref:`report your issues <upgrade/test-assistance>` and :ref:`request
-a new test database <upgrade/test-db-request>` when the reported issues are fixed in the upgrade
-script.
+.. _upgrade/request-test-database:

-If you do not find any discrepancies, you can move on to the upgrade of your production database.
-
-.. important::
-   A test database is only intended for testing and remains completely unrelated to your present or
-   future production database. Any data you add, or changes you make, will not be reflected in your
-   upgraded production database.
-
-.. note::
-   Test databases are neutered and features are disabled to prevent them from having an impact on
-   the production database:
-
-   #. The serial number of the database is modified (to prevent it from sending information as if it
-      was the production database).
-   #. The :ref:`base URL of the database <domain-name/web-base-url>` is reset to
-      ``http://localhost:8069`` and the email domain to ``localhost``.
-   #. Scheduled actions are disabled (the calendar synchronization, the bank statement
-      synchronization, the planned automated actions, the fetching of incoming mail servers, etc.).
-   #. Outgoing mail servers are disabled by archiving the existing ones and adding a
-      fake/non-working one.
-   #. Payment providers and delivery carriers are reset to test environment.
-   #. Accounting localization Electronic Data Interchange (EDI) services are disabled.
-   #. A system parameter is set to tell the database has been neutered.
-
-.. _upgrade/test-db-request:
-
-Request a test database
-=======================
-
-Follow the instructions available per hosting type on the `website form
-<https://upgrade.odoo.com>`_ and select *Testing* purpose.
-
-.. image:: upgrade/test-purpose.png
-   :align: center
-   :alt: Selection of the "Testing" purpose in the upgrade form on Odoo
-
-.. _upgrade/test-guidance:
-
-Test guidance
-=============
-
-Every business and organization has its own operational needs and has to test its specific Odoo
-database individually. We recommend you look at `the test scenario
-<https://docs.google.com/document/d/1ypNs7JKPOsjNbKpdiKFH7Al6g6whZ9jr7f7duAQ5E1w/>`_ for further
-information.
-
-.. todo:: change link "test scenario" once the related doc is published
-
-.. _upgrade/test-assistance:
-
-Assistance
----------
-
-If you encounter an issue in the **test database**, please get in touch with Odoo Upgrade Support
-via the `Odoo Support page <https://www.odoo.com/help>`_.
-
-Under the *Ticket Description* section, select *An issue related to my upgrade* ticket type.
-
-   .. image:: upgrade/test-assistance.png
-      :align: center
-      :alt: Selection of "An issue related to my upgrade" as Ticket Type in the support form on Odoo
-
-   .. warning::
-      If you choose another *Ticket Description* type, the request will be redirected to another
-      team. This will slow down the processing and response time.
-
-Please provide as much detail as you can (i.e., videos and screenshots to illustrate your issue).
-This will avoid clarifying questions and speed up the resolution process significantly.
-
-.. note::
-   * The purpose of the test phase is not to correct existing data or configurations in your
-     database.
-   * |assistance-contact|
-
-.. _upgrade/steps-production:
-
-The production launch
-=====================
-
-The production upgrade request is when you decide to upgrade your current database with all your
-production data (invoices, VAT returns, inventories, current orders) to a new version of your
-choice.
-
-After your :ref:`tests <upgrade/testing-phase>` are completed to your satisfaction, submit the
-request to upgrade your production database via our `website form <https://upgrade.odoo.com>`_.
-Select *Production* purpose.
-
-.. important::
-   Going into production without first testing may lead to:
-
-   - business interruptions (e.g., no longer having the possibility to validate an action)
-   - poor customer experiences (e.g., an eCommerce website that does not work correctly)
-
-.. _upgrade/production-assistance:
-
-Assistance
----------
-
-If you encounter issues or problems in the **production database**, please get in touch with **Odoo
-Support**:
-
-#. Connect to our `Odoo Support page <https://www.odoo.com/help>`_.
-#. Under the *Ticket Description* section, select the appropriate type related to your issue but
-   **do not select** the option *An issue related to my upgrade*.
-
-   .. note::
-      After upgrading to production, the support will be provided by the Support team instead of the
-      Upgrade team.
-
-#. Please provide as much detail as you can (i.e., videos and screenshots to illustrate your issue).
-   This will avoid clarifying questions and speed up the resolution process significantly.
-
-   .. warning::
-      If you choose *An issue related to my upgrade* as ticket type, the request will be redirected
-      to another team than the support one and will slow down the processing and response time.
-
-.. _upgrade/assistance:
-
-Help
-====
-
-.. _upgrade/contact:
-
-Contact our upgrade service support
+Obtaining an upgraded test database
 -----------------------------------

-Should you have any more questions about the upgrade, do not hesitate to send a message to `Odoo
-Upgrade Team <mailto:upgrade@odoo.com>`_. We will be happy to answer it as soon as possible.
+The `Upgrade page <https://upgrade.odoo.com/>`_ is the main platform for requesting an upgraded
+database. However, depending on the hosting type, you can upgrade from the command line
+(on-premise), the `Odoo Online database manager <https://odoo.com/my/databases>`_, or your `Odoo.sh
+project <https://odoo.sh/project>`_.

-.. _upgrade/supported-versions:
+.. note::
+   The Upgrade platform follows the same `Privacy Policy <https://www.odoo.com/privacy>`_ as the
+   other Odoo.com services. Visit the `General Data Protection Regulation page
+   <https://www.odoo.com/gdpr>`_ to learn more about how Odoo handles your data and privacy.

-Supported versions
------------------
+.. tabs::

-Please note that Odoo provides support and bug fixing only for the three last major versions of
-Odoo.
+   .. group-tab:: Odoo Online

-This is a factor to take into consideration before upgrading. If you are on an older version, we
-suggest you to prefer the most recent version to benefit from longer support (before having to
-upgrade again).
+      Odoo Online databases can be manually upgraded via the `database manager
+      <https://odoo.com/my/databases>`_.
+
+      The database manager displays all databases associated with the user's account. Databases
+      not on the most recent version of Odoo display an arrow in a circle icon next to their name,
+      indicating that they can be upgraded.
+
+      .. image:: upgrade/databases-page.png
+         :alt: The database manager with an upgrade button next to the name of a database.
+
+      Click the **arrow in a circle** icon to start the upgrade process. In the popup, fill in:
+
+      - The **version** of Odoo you want to upgrade to, usually the latest version
+      - The **email** address that should receive the link to the upgraded database
+      - The :guilabel:`Purpose` of the upgrade, which is automatically set to :guilabel:`Test` for
+        your first upgrade request
+
+      .. image:: upgrade/upgrade-popup.png
+         :alt: The "Upgrade your database" popup.
+
+      The :guilabel:`Upgrade in progress` tag is displayed next to the database name until
+      completion. Once the process succeeds, an email containing a link to the upgraded test
+      database is sent to the address provided. The database can also be accessed from the database
+      manager by clicking the dropdown arrow before the database name.
+
+      .. image:: upgrade/access-upgraded-db.png
+         :alt: Clicking the menu arrow displays the upgraded test database.
+
+   .. group-tab:: Odoo.sh
+
+      Odoo.sh is integrated with the upgrade platform to simplify the upgrade process.
+
+      .. image:: upgrade/odoo-sh-staging.png
+         :alt: Odoo.sh project and tabs
+
+      The **latest production daily automatic backup** is then sent to the `upgrade platform
+      <https://upgrade.odoo.com>`_.
+
+      Once the upgrade platform is done upgrading the backup and uploading it on the branch, it is
+      put in a **special mode**: each time a **commit is pushed** on the branch, a **restore
+      operation** of the upgraded backup and an **update of all the custom modules** occur. This
+      allows you to test your custom modules on a pristine copy of the upgraded database. The log
+      file of the upgrade process can be found in your newly upgraded staging build by going to
+      :file:`~/logs/upgrade.log`.
+
+      .. note::
+         In databases where custom modules are installed, their source code
+         must be up-to-date with the target version of Odoo before the upgrade
+         can be performed. If there are none, the "update on commit" mode is
+         skipped, the upgraded database is built as soon as it is transferred from the upgrade
+         platform, and the upgrade mode is exited.
+
+         .. TODOUPG : once the page for developers is published, uncomment
+         .. Check out the :doc:`upgrade for developers'
+         .. documentation </developer/reference/upgrade>` for more information. In
+         .. addition, if a module is not needed after an upgrade, :ref:`you can
+         .. remove customizations <upgrade/remove_customizations>`.
+
+   .. group-tab:: On-premise
+
+      The standard upgrade process can be initiated by entering the following command line on the
+      machine where the database is hosted:
+
+      .. code-block:: console
+
+         $ python <(curl -s https://upgrade.odoo.com/upgrade) test -d <your db name> -t <target version>
+
+      The following command can be used to display the general help and the main commands:
+
+      .. code-block:: console
+
+         $ python <(curl -s https://upgrade.odoo.com/upgrade) --help
+
+      An upgraded test database can also be requested via the `Upgrade page
+      <https://upgrade.odoo.com/>`_.
+
+      .. note::
+         - For security reasons, only the person who submitted the upgrade request can download it.
+         - For storage reasons, the database's copy is submitted without a filestore to the upgrade
+           server. Therefore, the upgraded database does not contain the production filestore.
+         - Before restoring the upgraded database, its filestore must be merged with the production
+           filestore to be able to perform tests in the same conditions as it would be in the new
+           version.
+         - The upgraded database contains:
+
+           - A `dump.sql` file containing the upgraded database
+           - A `filestore` folder containing files extracted from in-database records into
+             attachments (if there are any) and new standard Odoo files from the targeted Odoo
+             version (e.g., new images, icons, payment provider's logos, etc.).
+             This is the folder that should be merged with the production filestore
+             in order to get the full upgraded filestore.
+
+.. note::
+   You can request multiple test databases if you wish to test an upgrade more than once.
+
+.. _upgrade/upgrade_report:
+
+.. note::
+   When an upgrade request is completed, an upgrade report is attached to the successful upgrade
+   email, and it becomes available in the Discuss app for users who are part of the "Administration
+   / Settings" group. This report provides important information about the changes introduced by
+   the new version.
+
+.. _upgrade/test_your_db:
+
+Testing the new version of the database
+---------------------------------------
+
+It is essential to spend some time testing the upgraded test database to ensure that you are not
+stuck in your day-to-day activities by a change in views, behavior, or an error message once the
+upgrade goes live.
+
+.. note::
+   Test databases are neutralized, and some features are disabled to prevent them from impacting the
+   production database:
+
+   #. Scheduled actions are disabled.
+   #. Outgoing mail servers are disabled by archiving the existing ones and adding a fake one.
+   #. Payment providers and delivery carriers are reset to the test environment.
+   #. Bank synchronization is disabled. Should you want to test the synchronization, contact your
+      bank synchronization provider to get sandbox credentials.
+
+Testing as many of your business flows as possible is strongly recommended to ensure they are
+working correctly and to get more familiar with the new version.
+
+.. admonition:: Basic test checklist
+
+   - Are there views that are deactivated in your test database but active in your production
+     database?
+   - Are your usual views still displayed correctly?
+   - Are your reports (invoice, sales order, etc.) correctly generated?
+   - Are your website pages working correctly?
+   - Are you able to create and modify records? (sales orders, invoices, purchases, users, contacts,
+     companies, etc.)
+   - Are there any issues with your mail templates?
+   - Are there any issues with saved translations?
+   - Are your search filters still present?
+   - Can you export your data?
+
+.. spoiler:: Example of end-to-end testing
+
+   - Checking a random product in your product catalog and comparing its test and production data to
+     verify everything is the same (product category, selling price, cost price, vendor, accounts,
+     routes, etc.).
+   - Buying this product (Purchase app).
+   - Confirming the reception of this product (Inventory app).
+   - Checking if the route to receive this product is the same in your production database
+     (Inventory app).
+   - Selling this product (Sales app) to a random customer.
+   - Opening your customer database (Contacts app), selecting a customer (or company), and checking
+     its data.
+   - Shipping this product (Inventory app).
+   - Checking if the route to ship this product is the same as in your production database
+     (Inventory app).
+   - Validating a customer invoice (Invoicing or Accounting app).
+   - Crediting the invoice (issuing a credit note) and checking if it behaves as in your production
+     database.
+   - Checking your reports' results (Accounting app).
+   - Randomly checking your taxes, currencies, bank accounts, and fiscal year (Accounting app).
+   - Making an online order (Website apps) from the product selection in your shop until the
+     checkout process and checking if everything behaves as in your production database.
+
+   This list is **not** exhaustive. Extend the example to your other apps based on your use of Odoo.
+
+If you face an issue while testing your upgraded test database, you can request the assistance of
+Odoo via the `support page <https://odoo.com/help?stage=migration>`__ by selecting the option
+related to testing the upgrade. In any case, it is essential to report any
+problem encountered during the testing to fix it before upgrading your production database.
+
+You might encounter significant differences with standard views, features, fields, and models during
+testing. Those changes cannot be reverted on a case-by-case basis. However, if a change introduced
+by a new version breaks a customization, it is the responsibility of the maintainer of your custom
+module to make it compatible with the new version of Odoo.
+
+.. tip::
+   Do not forget to test:
+
+   - Integrations with external software (EDI, APIs, etc.)
+   - Workflows between different apps (online sales with eCommerce, converting a lead all the way to
+     a sales order, delivery of products, etc.)
+   - Data exports
+   - Automated actions
+   - Server actions in the action menu on form views, as well as by selecting multiple records on
+     list views
+
+.. _upgrade/upgrade-prod:
+
+Upgrading the production database
+---------------------------------
+
+Once the :ref:`tests <upgrade/test_your_db>` are completed and you are confident that the upgraded
+database can be used as your main database without any issues, it is time to plan the go-live day. It
+can be planned in coordination with Odoo's upgrade support analysts, reachable via the `support page
+<https://odoo.com/help>`__.
+
+Your production database will be unavailable during its upgrade. Therefore, we recommend planning
+the upgrade at a time when the use of the database is minimal.
+
+As the standard upgrade scripts and your database are constantly evolving, it is also recommended
+to frequently request another upgraded test database to ensure that the upgrade process is
+still successful, especially if it takes a long time to finish. Fully rehearsing the upgrade
+process the day before upgrading the production database is also recommended.
+
+.. important::
+   - Going into production without first testing may lead to:
+
+     - Users failing to adjust to the changes and new features
+     - Business interruptions (e.g., no longer having the possibility to validate an action)
+     - Poor customer experience (e.g., an eCommerce website that does not work correctly)
+
+The process of upgrading a production database is similar to upgrading a test database with a few
+exceptions.
+
+.. tabs::
+
+   .. group-tab:: Odoo Online
+
+      The process is similar to :ref:`obtaining an upgraded test database
+      <upgrade/request-test-database>`, except for the purpose option, which must be set to
+      :guilabel:`Production` instead of :guilabel:`Test`.
+
+      .. warning::
+         Once the upgrade is requested, the database will be unavailable until the upgrade is
+         finished. Once the process is completed, it is impossible to revert to the previous
+         version.
+
+   .. group-tab:: Odoo.sh
+
+      The process is similar to :ref:`obtaining an upgraded test database
+      <upgrade/request-test-database>` on the :guilabel:`Production` branch.
+
+      .. image:: upgrade/odoo-sh-prod.png
+         :alt: View from the upgrade tab
+
+      The process is **triggered as soon as a new commit is made** on the branch. This
+      allows the upgrade process to be synchronized with the deployment of the custom modules'
+      upgraded source code.
+      If there are no custom modules, the upgrade process is triggered immediately.
+
+      .. important::
+         The database is unavailable throughout the process. If anything goes wrong, the platform
+         automatically reverts the upgrade, as it would be for a regular update. In case of success,
+         a backup of the database before the upgrade is created.
+
+      The update of your custom modules must be successful to complete the entire upgrade process.
+      Make sure the status of your staging upgrade is :guilabel:`successful` before trying it in
+      production.
+   .. TODOUPG : once the page for developers is published, uncomment
+   .. More information on how to upgrade your custom modules can be found in the :ref:`upgrading customizations documentation <upgrade/upgrading_customizations>`.
+
+   .. group-tab:: On-premise
+
+      The command to upgrade a database to production is similar to the one of upgrading a test
+      database except for the argument `test`, which must be replaced by `production`:
+
+      .. code-block:: console
+
+         $ python <(curl -s https://upgrade.odoo.com/upgrade) production -d <your db name> -t <target version>
+
+      An upgraded production database can also be requested via the `Upgrade page
+      <https://upgrade.odoo.com/>`_.
+      Once the database is uploaded, any modification to your production database will **not** be
+      present on your upgraded database. This is why we recommend not using it during the upgrade
+      process.
+
+      .. important::
+         When requesting an upgraded database for production purposes, the copy is submitted without
+         a filestore. Therefore, the upgraded database filestore must be merged with the production
+         filestore before deploying the new version.
+
+In case of an issue with your production database, you can request the assistance of Odoo via the
+`support page <https://odoo.com/help?stage=post_upgrade>`__ by selecting the option related to
+the upgrade in production.

-.. seealso::
-   :doc:`maintain/supported_versions`

 .. _upgrade/sla:

 Service-level agreement (SLA)
-=============================
+-----------------------------

 With Odoo Enterprise, upgrading a database to the most recent version of Odoo is **free**, including
 any support required to rectify potential discrepancies in the upgraded database.
@@ -230,7 +377,7 @@ Information about the upgrade services included in the Enterprise Licence is ava
 upgrade services you can expect.

 Upgrade services covered by the SLA
-----------------------------------
+===================================

 Databases hosted on Odoo's cloud platforms (Odoo Online and Odoo.sh) or self-hosted (On-Premise) can
 benefit from upgrade services at all times for:
@@ -245,7 +392,7 @@ Upgrade services are limited to the technical conversion and adaptation of a dat
 modules and data) to make it compatible with the version targeted by the upgrade.

 Upgrade services not covered by the SLA
---------------------------------------
+=======================================

 The following upgrade-related services are **not** included:

@@ -256,9 +403,6 @@ The following upgrade-related services are **not** included:
  <studio/automated-actions/action>`; and
 - **training** on using the upgraded version's features and workflows.

-.. note:: |assistance-contact|
-
 .. seealso::
-   - :doc:`Upgrade FAQ <upgrade/faq>`
   - :doc:`Odoo.sh documentation <odoo_sh>`
   - :doc:`Supported Odoo versions <maintain/supported_versions>`
@@ -1,228 +0,0 @@
-.. |assistance-contact| replace::
-   If you need Odoo assistance on this matter, please get in touch with your Odoo Account Manager or
-   our `Sales department`_.
-.. _Sales department: mailto:sales@odoo.com
-
-===
-FAQ
-===
-
-.. _upgrade-faq/why:
-
-Why upgrade
-===========
-
-* You benefit from the latest features of the :ref:`new major version
-  <upgrade-faq/release-notes>` released by Odoo.
-* If you are in an :ref:`unsupported version <upgrade/supported-versions>`, you get a new version
-  with support.
-
-.. _upgrade-faq/when:
-
-When to upgrade
-===============
-
-Whenever you want. You can make your upgrade request as soon as a new version is released or when
-your version turns unsupported, and you still wish to enjoy support.
-
-.. _upgrade-faq/availability:
-
-Availability of the new version
-===============================
-
-As soon as Odoo announces the release of a new major version, you can create a test upgrade request
-to try the latest version. Please note that at this point, the upgrade scripts will only have been
-tested with demo data. Please report any issue you might encounter while testing via the `Odoo
-Support page <https://www.odoo.com/help>`_ and make sure to be happy with your test version before
-requesting the upgrade of your database in production.
-
-.. _upgrade-faq/duration:
-
-Duration of the upgrade
-=======================
-
-It is impossible to give time estimates for every upgrade request.
-
-In general, the "smaller" the database, the quickest the upgrade request is completed. A single-user
-database that uses only CRM will be processed faster than a multi-company, multi-user database that
-uses Accounting, Sales, Purchase, and Manufacturing.
-
-You can expect the time it takes for the platform to upgrade the test database to be similar to the
-production upgrade.
-
-.. _upgrade-faq/project:
-
-Duration of the upgrade project
-------------------------------
-
-It depends on the user involvement (the time spent on testing, reporting problems, etc.) and the
-issues encountered that might need to be addressed by our technical team.
-
-So, in a nutshell, what can impact your upgrade lead time?
-
-* Source & targeted versions
-* Installed apps
-* Volume of data
-* Amount of customization (models, fields, methods, workflows, reports, website, etc.)
-* Installation of new apps or configuration changes after the start of the test phase
-* User commitment
-
-.. _upgrade-faq/custom-modules:
-
-Upgrade of the custom modules
-=============================
-
-As stated in our :doc:`/legal/terms/enterprise`, section :ref:`charges_standard`, this optional
-service is subject to additional fees.
-
-Depending on your situation, the custom code could be upgraded by our services, by one of our
-partners, or you can do it yourself.
-
-.. note:: |assistance-contact|
-
-.. _upgrade-faq/upgrade-or-migration:
-
-Upgrade or Migration
-====================
-
-An upgrade is switching to a newer version of Odoo, while a migration reflects the change of
-:ref:`editions <upgrade-faq/editions-change>` or change of :ref:`hosting type
-<upgrade-faq/hosting-types-switch>`.
-
-.. note:: |assistance-contact|
-
-.. _upgrade-faq/editions-change:
-
-Editions change (from Community to Enterprise)
-==============================================
-
-The upgrade always returns an Enterprise edition of Odoo, whether the database you sent was a
-community or enterprise edition. It is required to have an enterprise subscription to upgrade.
-
- .. note::
-    If you need assistance on this matter,  please contact us via the `Odoo Support page
-    <https://www.odoo.com/help>`_.
-
-.. seealso::
-   - `Editions <https://www.odoo.com/page/editions>`_
-
-.. _upgrade-faq/hosting-types-switch:
-
-Switching the hosting types (On-premise vs. Odoo Online vs. Odoo.sh)
-====================================================================
-
-An upgrade does not cover a change of `Hosting types <https://www.odoo.com/page/hosting-types>`_.
-
-Open the following link to get :doc:`more information about how to change your hosting type
-<../maintain/hosting_changes>`.
-
-.. note:: |assistance-contact|
-
-.. _upgrade-faq/upgrade-report:
-
-The Upgrade Report
-==================
-
-When an upgrade request completes successfully (test or production), you receive an email
-notification about it that includes an 'Upgrade Report'. This report is also sent to you via the
-Discuss app. It contains valuable information regarding changes that occurred during the upgrade.
-While it serves as a guide to possible issues to look out for, it is not an exhaustive list. It
-remains imperative that you test the upgraded database thoroughly and report any discrepancies you
-might find, before you decide to upgrade your production database.
-
-.. _upgrade-faq/custom-views:
-
-Custom views
-============
-
-During the upgrade, some custom views might get disabled for technical reasons. Therefore they might
-have to be fixed after the upgrade. The :ref:`Upgrade Report <upgrade-faq/upgrade-report>` that is
-generated after the upgrade is available in the Discuss app, and lists all the custom views that
-might be impacted by this.
-
-.. _upgrade-faq/release-notes:
-
-Release Notes by version
-========================
-
-Open our `Release Note <https://www.odoo.com/page/release-notes>`_ page to get a summary of the new
-features and improvements made in each version.
-
-How long is my test available for
-=================================
-
-An Odoo Online test database is available for one month by default. We can extend this trial period
-upon request. For Odoo.sh or on-premise, there is no restriction.
-
-How many tests to perform before upgrading to production?
-=========================================================
-
-As many as needed. When you are comfortable with the database, run a last test upgrade 48 hours
-before requesting your production upgrade and test your workflows one last time.
-
-How to/Where to report upgrade issues?
-======================================
-
-If you encounter issues during the upgrade process, please contact the Odoo Support through the
-`Odoo Support page <https://www.odoo.com/help>`_.
-
- To report an issue discovered during the testing phase, please select **An issue related to my
-  upgrade (test phase)**.
- To report an issue discovered post-upgrade, please select **An issue related to my upgrade
-  (production)**.
-
-Upgrading to production
-=======================
-
-Once you have completed testing and are happy with the result, you decide on a date and time when
-you stop users from accessing Odoo, freeze all data entries, and create an upgrade request for the
-production upgrade.
-
-How is my data handled in the Upgrade Platform?
-===============================================
-
-The Odoo Upgrade platform uses the same Privacy Policy as the rest of Odoo.com services.
-
-Your data is hosted on servers that follow our security guidelines, namely:
-
- SSL - All web connections to client instances are protected with 256-bit SSL encryption
-  (HTTPS with a 2048-bit modulus SSL certificate), and running behind Grade A SSL stacks. All our
-  certificate chains are using SHA-2 already.
- Safe System - Our servers are running recent Linux distribution with up-to-date security patches,
-  with firewall and intrusion countermeasures (not disclosed for obvious reasons).
-
-Servers are located at the same locations as our Cloud providers with the following services:
-
- Restricted perimeter, physically accessed by authorized data center employees only
- Physical access control with security badges or biometrical security
- Security cameras monitoring the data center locations 24/7
- Security personnel on-site 24/7
-
-The uploaded and migrated databases uploaded to the Upgrade platform are kept for up to 3 months and
-are permanently deleted following that period.
-
-You can learn more about privacy and data handling at Odoo by visiting our `General Data Protection
-Regulation page <https://www.odoo.com/gdpr>`_.
-
-Rolling Release (applicable to Odoo Online databases)
-=====================================================
-
-This feature allows customers to upgrade their database directly from a message prompt sent to the
-database administrator as soon as the new version is released. Odoo first tests the upgrade to the
-next version. The rolling release upgrade option is displayed if the automated tests are successful.
-The message offers two options:
-
-#. To 'Upgrade Now', which immediately triggers the upgrade of your live production database.
-
-#. To take you to your `database manager <https://www.odoo.com/my/databases/>`_ where you can
-   `request an upgraded test database <https://upgrade.odoo.com/#online/>`_ and check the upgraded
-   test database for any discrepancies.
-
-When you choose to proceed with the production upgrade directly, make sure all users have saved
-their work and are logged out. The upgrade takes approximately 15 minutes. During this time your
-database is unreachable. If you notice any problem after the upgrade, please report it via the `Odoo
-Support page <https://www.odoo.com/help>`_.
-
-.. note::
-   If you are using the Website or Studio app, we recommend you always do a test upgrade before
-   upgrading your production instance.
@@ -1,92 +0,0 @@
-===========
-Odoo Online
-===========
-
-Odoo databases can be manually upgraded directly from the main Odoo website. To upgrade an Odoo
-database, navigate to the `database manager <https://www.odoo.com/my/databases>`_ page and sign in.
-
-The database manager page displays all of the Odoo databases associated with the user's account. Any
-databases that are not already on the most recent version of Odoo display an **arrow in a circle**
-icon next to the database name, indicating that the database can be upgraded.
-
-.. image:: odoo_online/databases-page.png
-   :align: center
-   :alt: The database manager page with an upgrade button next to the name of a database.
-
-.. important::
-   - If the database's version is **lower** than the latest major release: the database must be
-     upgraded within two months. After these two months, an automatic upgrade is initiated.
-   - If the database's version is **equal** to or **higher** than the latest major release:
-     you can disregard the invitation to upgrade, as the database probably would not benefit from
-     new features every two months.
-
-If a database is *not* on the latest online version, its administrator should receive an invitation
-to upgrade on the database's dashboard, displayed as an **arrow in a circle**.
-
-.. image:: odoo_online/database-notification.png
-   :alt: Invitation to upgrade on the database dashboard.
-
-.. note::
-   Versions that are not supported anymore become deprecated and must be updated to avoid
-   security issues. It is recommended to initiate the upgrade yourself and not wait for the
-   automatic upgrade, as the former method allows you to request a test upgrade of the database to
-   check for any discrepancies.
-
-Test database
-=============
-
-Click on the **arrow in a circle** icon to start the upgrade process. On the :guilabel:`Upgrade your
-database` pop-up, select the version of Odoo that the platform will be upgraded to. In the
-:guilabel:`Email to notify` field, enter an email address that will receive email notifications
-about the database upgrade.
-
-There is also a :guilabel:`Purpose` section on the pop-up that is used to specify the reason for the
-upgrade. However, at this stage of the process, the only selectable option is :guilabel:`Test`, as
-Odoo requires users to create a test copy of the upgraded database before converting the actual
-database.
-
-.. image:: odoo_online/upgrade-pop-up.png
-   :align: center
-   :alt: The "Upgrade your database" pop-up.
-
-After filling out the form, click the :guilabel:`Upgrade` button. The pop-up disappears and the
-database being upgraded shows a red :guilabel:`Upgrade in progress` tag next to its name. An email
-confirming that the upgrade is in progress is also sent to the email address specified on the
-pop-up.
-
-.. image:: odoo_online/upgrade-in-progress.png
-   :align: center
-   :alt: The "Upgrade in progress" tag next to the database name.
-
-Once the upgrade is complete, a new test database appears on the `database manager
-<https://www.odoo.com/my/databases>`_ page. To access the test database, click the drop-down arrow
-(:guilabel:`⯆`) to the left of the main database's name. Doing so makes the test version appear
-below it. Finally, click the green :guilabel:`Connect` button on the right side of the test
-version's row to go to the database.
-
-.. image:: odoo_online/test-database.png
-   :align: center
-   :alt: A test database on the database manager page.
-
-Except for being on the newer version of Odoo, the test database is an exact copy of the one being
-upgraded. It is important to do extensive testing in this database to ensure that the upgrade has
-not altered or corrupted any data, and that all workflows still proceed as expected.
-
-Production database
-===================
-
-After confirming the integrity of the new version, return to the `database manager
-<https://www.odoo.com/my/databases>`_ page. Once again, click on the **arrow in a circle** icon next
-to the database being upgraded. The :guilabel:`Upgrade your database` pop-up appears as before,
-except that there is now a :guilabel:`Production` option under the :guilabel:`Purpose` section.
-
-Select the :guilabel:`Production` option and then click :guilabel:`Upgrade` to begin the upgrade
-process. As before, a notification email is sent to the email address provided and a red
-:guilabel:`Upgrade in progress` tag appears next to the name of the database.
-
-The production database is then taken offline and will be upgraded automatically. The time it takes
-to upgrade the production database should be similar to the time that was necessary to upgrade the
-test database. Make sure to inform database users of the scheduled downtime.
-
-After the upgrade is finished, the :guilabel:`Upgrade in progress` tag disappears and the database
-is upgraded to the version specified.
@@ -1,132 +0,0 @@
-=======
-Odoo.sh
-=======
-
-.. _upgrade/odoo_sh/overview:
-
-Overview
-========
-
-Odoo.sh is integrated with the upgrade platform to make the upgrade process easier.
-
-.. note::
-   The :guilabel:`Upgrade` tab is available in the branches view. It is only available for valid
-   projects with a valid production build.
-
-.. image:: odoo_sh/odoo-sh-menu.png
-   :align: center
-   :alt: Click on the upgrade menu
-
-The suggested upgrade steps on Odoo.sh are:
-
-#. On a :guilabel:`Development` branch, upgrade your custom modules to keep them compatible with the
-   new version and thoroughly **test them**.
-#. Switch that branch to the :guilabel:`Staging` branch, **upgrade** the last daily production
-   backup and **test it**. Write upgrade scripts if necessary.
-#. Trigger the production upgrade from your :guilabel:`Production` branch and sit tight.
-
-.. seealso::
-   - :doc:`../../administration/upgrade`
-   - :doc:`Upgrade FAQ <../upgrade/faq>`
-   - :doc:`Introduction to Odoo.sh <../odoo_sh/overview/introduction>`
-
-.. _upgrade/odoo_sh/custom-modules:
-
-Upgrade your custom modules
-===========================
-
-The first step is to upgrade your custom modules to keep them compatible with the new version. Fork
-your :guilabel:`Production` branch in the :guilabel:`Development` stage, then go to the settings of
-your :guilabel:`Development` branch and select the Odoo version you target. If needed, modify your
-code to be compatible with the new version. Make sure to **test** your features are still working
-correctly.
-
-.. note::
-   Depending on your contract, the upgrade of your custom modules can be done by yourself, by your
-   Partner or by Odoo (if you hold a subscription including maintenance of customizations).
-
-.. _upgrade/odoo_sh/testing-phase:
-
-Upgrade your database on a staging branch
-=========================================
-
-Take the upgraded development branch and drag & drop it to :guilabel:`Staging`.
-
-Go to the :guilabel:`Upgrade` tab and select the :guilabel:`target version`. Then, click on
-:guilabel:`Test Upgrade`.
-
-.. image:: odoo_sh/odoo-sh-staging.png
-   :align: center
-   :alt: Odoo.sh project and tabs
-
-The **latest production daily automatic backup** is sent to the
-`upgrade platform <https://www.upgrade.odoo.com>`_ to start the upgrade test process.
-
-.. note::
-   You can follow the upgrade process by going to the :guilabel:`Upgrade` menu of your
-   :guilabel:`Production` branch.
-
-When the upgraded backup is ready on the `upgrade platform <https://www.upgrade.odoo.com>`_, it is
-automatically downloaded back to your project.
-
-The branch is now in a **special mode**: each time a **commit is pushed** on the branch, a
-**restore operation** of the upgraded backup occurs, and an **update of all the custom modules**
-happens. This allows you to quickly iterate on your custom modules upgrade scripts. The log file of
-the upgrade process can be found at :file:`~/logs/upgrade.log` in your newly upgraded staging build.
-
-.. note::
-   - The **special upgrade mode** is automatically closed after 30 days.
-   - It may happen that custom modules are no longer needed after an upgrade. Custom modules in the
-     upgraded database are set to be updated. If the modules are missing in the code, the update
-     fails, thus failing the whole process. An empty module with a manifest and possibly some custom
-     upgrade script are necessary to clean up the database. The complete removal of the module has
-     to be handled afterwards.
-
-Functionally test your upgraded database
-========================================
-
-Now that the test upgraded database is available on your staging branch, **thoroughly test it** and
-make sure everything runs as it's supposed to. Once you are satisfied with the result, you are ready
-to upgrade your production database.
-
-Production upgrade
-==================
-
-Once you are happy with your testing, you can start the process on the :guilabel:`Production`
-branch.
-
-On your :guilabel:`Production` branch, go to the :guilabel:`Upgrade` tab, select the
-:guilabel:`targeted version` and click on the :guilabel:`start Upgrade` button.
-
-.. image:: odoo_sh/odoo-sh-prod.png
-   :align: center
-   :alt: View from the upgrade tab
-
-The actual process is **triggered as soon as you push a new commit** in your branch. Make sure you
-are pushing code that is compatible with the new version. For example by merging the code from your
-upgraded staging branch.
-
-.. note::
-   You can see the progress of the upgrade by going to the :guilabel:`Upgrade` tab of the main
-   branch.
-
-.. image:: odoo_sh/odoo-sh-progress.png
-   :align: center
-   :alt: View showing the progress of the upgrade
-
-.. important::
-   Your database is unavailable throughout the process.
-
-.. note::
-   If anything goes wrong, the platform automatically reverts the upgrade, the same as it would be
-   for a regular update. In case of success, a backup is always made.
-
-The update of your custom modules must be successful to complete the entire upgrade process. Make
-sure the status of your staging upgrade is :guilabel:`successful` before trying it in production.
-
-.. note::
-   It may happen that custom modules are no longer needed after an upgrade. Custom modules in the
-   upgraded database are set to be updated. If the modules are missing in the code, the update
-   fails, thus failing the whole process. An empty module with a manifest and possibly some custom
-   upgrade script are necessary to clean up the database. The complete removal of the module has to
-   be handled afterwards.
@@ -1,76 +0,0 @@
-==========
-On-Premise
-==========
-
-Test upgrade request
-====================
-
-There are two ways to create your upgrade request.
-
-Upgrade request via command line
--------------------------------
-
-For technically-advanced users and partners, the upgrade process can be initiated via the following
-command line on the server where the database is hosted:
-
-:command:`python <(curl -s https://upgrade.odoo.com/upgrade) test -d <your db name> -t
-<target version>`
-
-The above command creates the database dump, sends it to the upgrade platform, and initiates the
-automated upgrade process. During the upgrade, you can follow the live logs on your screen.
-Once the upgrade process is completed successfully, the upgraded database is restored onto the
-server (as a duplicate test database).
-
-Upgrade request via the Odoo Upgrade Portal
-------------------------------------------
-
-#. Download a recent copy of your database and select the option :guilabel:`pg_dump custom format
-   (without filestore)`.
-#. Upload this dump file at https://upgrade.odoo.com and select *Testing* as the aim.
-   Odoo performs the automated upgrade process. Once it is completed, you receive an email with a
-   link to download the upgrade database dump file.
-#. Import the upgraded database into your on-premise environment and manually test all processes and
-   workflows.
-
-.. note::
-   - For security reasons, only the person who submitted the upgrade request is able to download it.
-   - Any problem found during testing should be reported via the `helpdesk
-     <https://odoo.com/help>`_.
-   - For storage reasons, the copy of your database is submitted without a filestore to the upgrade
-     server. Therefore, the upgraded database does not contain the production filestore.
-   - Before restoring the upgraded database, its filestore must be merged with the production
-     filestore to be able to perform tests in the same conditions as it would be in the new version.
-   - The upgraded database contains:
-
-      - A `dump.sql` file containing the upgraded database.
-      - A `filestore` folder containing files that were extracted from in-database records into
-        attachments (if there are any) and new standard Odoo files from the targeted Odoo version
-        (like new images, icons, payment provider's logos, etc.). This is the folder that should be
-        merged with the production filestore in order to get the full upgraded filestore.
-
-Upgrade your production database
-================================
-
-Once you have completed the testing successfully, you can proceed to upgrade your live database in
-production. Download your upgraded database from the link in the email and import it onto your live
-environment.
-
-.. important::
-   - Same as in the test phase, when requesting an upgrade for production purposes, the copy of your
-     database is submitted without a filestore.
-   - Therefore, the upgraded database filestore must be merged with the production filestore before
-     deploying the new version.
-
-Custom modules (if applicable)
-==============================
-
-The upgrade of a database that contains custom modules is a two-step process.
-
-#. The standard upgrade is done when your upgrade request is completed.
-#. Your custom modules also need to be upgraded to keep them compatible with the new version.
-
-Depending on your contract, the upgrade of your custom modules can be done
-
-#. by yourself.
-#. by your Partner.
-#. by Odoo (if you hold a subscription to 'Maintenance of Customizations').
@@ -106,9 +106,9 @@ If your connection with the proxy is disconnected, you can reconnect with the pr
 :guilabel:`Fetch Account` button.

 .. note::
-   This disconnection can be caused by the Odoo support. In this case, please contact the `support
-   <https://www.odoo.com/help>`_ directly with your client id or the reference of the error listed
-   in the chatter.
+   If you are unable to reconnect using the :guilabel:`Fetch Account` button, please contact the
+   `support <https://www.odoo.com/help>`_ directly with your client id or the reference of the error
+   listed in the chatter.

 .. _MigrationOnlineSync:

@@ -236,3 +236,4 @@ the material has been shipped to the customer.
   customer_invoices/electronic_invoicing
   customer_invoices/snailmail
   customer_invoices/epc_qr_code
+   customer_invoices/incoterms
@@ -0,0 +1,46 @@
+=========
+Incoterms
+=========
+
+:abbr:`Incoterms (International Commercial Terms)` are standardized trade terms used in
+international transactions to define the rights and responsibilities of buyers and sellers. They
+establish the obligations related to the delivery of goods, the transfer of risks, and the
+distribution of costs between the parties involved. Incoterms specify important details, such as the
+point at which the risk and costs transfer from the seller to the buyer, the responsibility for
+transportation, insurance, customs clearance, and other relevant aspects of the transaction.
+
+.. note::
+   By default, all 11 Incoterms are available in Odoo:
+
+   - **EXW**: Ex works
+   - **FCA**: Free carrier
+   - **FAS**: Free alongside ship
+   - **FOB**: Free on board
+   - **CFR**: Cost and freight
+   - **CIF**: Cost, insurance and freight
+   - **CPT**: Carriage paid to
+   - **CIP**: Carriage and insurance paid to
+   - **DPU**: Delivered at place unloaded
+   - **DAP**: Delivered at place
+   - **DDP**: Delivered duty paid
+
+.. seealso::
+   :doc:`../reporting/intrastat`
+
+.. _incoterms/invoices:
+
+Define an Incoterm
+==================
+
+To define an Incoterm manually, create an invoice or bill, click the :guilabel:`Other Info` tab, and
+select the :guilabel:`Incoterm`.
+
+.. _incoterms/default:
+
+Default Incoterm configuration
+==============================
+
+You can set a default Incoterm rule to **automatically** populate the Incoterm field on all newly
+created invoices and bills. Under :menuselection:`Accounting/Invoicing --> Configuration -->
+Settings`, scroll down to the :guilabel:`Customer Invoices` section, and select an Incoterm in the
+:guilabel:`Default Incoterm` field.
@@ -187,7 +187,8 @@ Send yourself a sample invoice by email to make sure everything is correctly con
   * :doc:`get_started/chart_of_accounts`
   * :doc:`bank/bank_synchronization`
   * :doc:`../fiscal_localizations`
-   * `Odoo Tutorials: Accounting Basics <https://www.odoo.com/r/lsZ>`_
+   * `Odoo Tutorials: Accounting and Invoicing - Getting started [video]
+     <https://www.odoo.com/slides/slide/getting-started-1692>`_

 .. toctree::
   :titlesonly:
@@ -1,167 +1,439 @@
-=================================
-Inventory average price valuation
-=================================
+===============================
+Average price on returned goods
+===============================

-As stated in the :doc:`inventory valuation page
-</applications/inventory_and_mrp/inventory/management/reporting/inventory_valuation_config>`,
-one of the possible costing method you can use in perpetual stock
-valuation, is the average cost.
+.. |AVCO| replace:: :abbr:`AVCO (Average Cost Valuation)`

-This document answers to one recurrent question for companies using that
-method to make their stock valuation: how does a shipping returned to
-its supplier impact the average cost and the accounting entries? This
-document is **only** for the specific use case of a perpetual valuation (as
-opposed to the periodic one) and in average price costing method (as
-opposed to standard of FIFO).
+.. _inventory/avg_cost/definition:

-Definition of average cost
-==========================
+*Average cost valuation* (AVCO) is an inventory valuation method that evaluates cost based on the
+total cost of goods bought or produced during a period, divided by the total number of items
+on-hand. Inventory valuation is used to:

-The average cost method calculates the cost of ending inventory and cost
-of goods sold on the basis of weighted average cost per unit of
-inventory.
+- reflect the value of a company's assets;
+- keep track of the amount of unsold goods;
+- account for monetary value in goods that have yet to generate profit;
+- report on flow of goods throughout the quarter.

-The weighted average cost per unit is calculated using the following
-formula:
+Because |AVCO| uses the weighted average to evaluate the cost, it is a good fit for companies that
+sell only a few different products in large quantities. In Odoo, this costing analysis is
+*automatically updated* each time products are received.

- When new products arrive in a warehouse, the new average cost is
-  recomputed as:
+Thus, when shipments are returned to their supplier, Odoo automatically generates accounting entries
+to reflect the change in inventory valuation. However, Odoo does **not** automatically update the
+|AVCO| calculation, because :ref:`this can potentially create inconsistencies with inventory
+valuation <inventory/avg_price/leaving_inventory>`.

-.. image:: avg_price_valuation/avg01.png
+.. note::
+   This document addresses a specific use case for theoretical purposes. Navigate :ref:`here
+   <inventory/inventory_valuation_config>` for instructions on how to set up and use |AVCO| in Odoo.
+
+.. seealso::
+   - :ref:`Using inventory valuation <inventory/reporting/using_inventory_val>`
+   - :ref:`Other inventory valuation methods <inventory/inventory_valuation_config/costing_methods>`
+
+Configuration
+=============
+
+To use average cost inventory valuation on a product, navigate to :menuselection:`Inventory -->
+Configuration --> Product Categories` and select the category that will be using |AVCO|. On the
+product category page, set :guilabel:`Costing Method` to `Average Cost (AVCO)` and
+:guilabel:`Inventory Valuation` to `Automated`.
+
+.. seealso::
+   :ref:`Inventory valuation configuration <inventory/inventory_valuation_config>`
+
+Using average cost valuation
+============================
+
+The average cost method adjusts the inventory valuation when products are received in the warehouse.
+This section explains how it works, but if the explanation is unnecessary, skip to the :ref:`return
+to supplier use case <inventory/avg_cost/return>` section.
+
+.. _inventory/avg_cost/formula:
+
+Formula
+-------
+
+When new products arrive, the new average cost for each product is recomputed using the formula:
+
+.. math::
+   Avg~Cost = \frac{(Old~Qty \times Old~Avg~Cost) + (Incoming~Qty \times Purchase~Price)}{Final~Qty}
+
+- **Old Qty**: product count in stock before receiving the new shipment;
+- **Old Avg Cost**: calculated average cost for a single product from the previous inventory
+  valuation;
+- **Incoming Qty**: count of products arriving in the new shipment;
+- **Purchase Price**: estimated price of products at the reception of products (since vendor bills
+  may arrive later). The amount includes not only the price for the products, but also added costs,
+  such as shipping, taxes, and :ref:`landed costs <inventory/reporting/landed_costs>`. At reception
+  of the vendor bill, this price is adjusted;
+- **Final Qty**: quantity of on-hand stock after the stock move.
+
+.. _inventory/avg_cost/definite_rule:
+
+.. important::
+   When products leave the warehouse, the average cost **does not** change. Read about why the
+   average cost valuation is **not** adjusted :ref:`here <inventory/avg_price/leaving_inventory>`.
+
+.. _inventory/avg_cost/math_table:
+
+Compute average cost
+--------------------
+
+To understand how the average cost of a product changes with each shipment, consider the following
+table of warehouse operations and stock moves. Each is a different example of how the average cost
+valuation is affected.
+
+--------------------------------+---------------+-------------------+---------------+------------+
+| Operation                      | Incoming Value| Inventory Value   | Qty On Hand   | Avg Cost   |
+================================+===============+===================+===============+============+
+|                                |               | $0                | 0             | $0         |
+--------------------------------+---------------+-------------------+---------------+------------+
+| Receive 8 tables at $10/unit   | 8 * $10       | $80               | 8             | $10        |
+--------------------------------+---------------+-------------------+---------------+------------+
+| Receive 4 tables at $16/unit   | 4 * $16       | $144              | 12            | $12        |
+--------------------------------+---------------+-------------------+---------------+------------+
+| Deliver 10 tables              | -10 * $12     | $24               | 2             | $12        |
+--------------------------------+---------------+-------------------+---------------+------------+
+
+.. _inventory/avg_cost/ex-1:
+
+.. exercise::
+   Ensure comprehension of the above computations by reviewing the "Receive 8 tables at $10/unit"
+   example.
+
+   Initially, the product stock is 0, so all values are $0.
+
+   In the first warehouse operation, `8` tables are received at `$10` each. The average cost is
+   calculated using the :ref:`formula <inventory/avg_cost/formula>`:
+
+   .. math::
+      Avg~Cost = \frac{0 + 8 \times $10}{8} = \frac{$80}{8} = $10
+
+   - Since the *incoming quantity* of tables is `8` and the *purchase price* for each is `$10`,
+   - The inventory value in the numerator is evaluated to `$80`;
+   - `$80` is divided by the total amount of tables to store, `8`;
+   - `$10` is the average cost of a single table from the first shipment.
+
+   To verify this in Odoo, in the *Purchase* app, order `8` quantities of a new product, `Table`,
+   with no previous stock moves, for `$10` each.
+
+   In the table's :guilabel:`Product Category` field in the :guilabel:`General Information` tab of
+   the product form, click the :guilabel:`➡️ (arrow)` icon, to open an :guilabel:`External Link` to
+   edit the product category. Set the :guilabel:`Costing Method` to `Average Cost (AVCO)` and
+   :guilabel:`Inventory Valuation` to `Automated`.
+
+   Then, return to the purchase order. Click :guilabel:`Confirm Order`, and click :guilabel:`Receive
+   Products` to confirm receipt.
+
+   Next, check the inventory valuation record generated by the product reception by navigating to
+   :menuselection:`Inventory --> Reporting --> Inventory Valuation`. Select the drop-down for
+   `Table`, and view the :guilabel:`Total Value` column for the *valuation layer* (:dfn:`inventory
+   valuation at a specific point in time = on-hand quantity * unit price`). The 8 tables in-stock
+   are worth $80.
+
+   .. image:: avg_price_valuation/inventory-val-8-tables.png
+      :align: center
+      :alt: Show inventory valuation of 8 tables in Odoo.
+
+.. tip::
+   When the product category's :guilabel:`Costing Method` is set to :guilabel:`AVCO`, then the
+   average cost of a product is also displayed on the :guilabel:`Cost` field, under the
+   :guilabel:`General Information` tab, on the product page itself.
+
+Product delivery (use case)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For outgoing shipments, :ref:`outbound products have no effect on the average cost valuation
+<inventory/avg_cost/definite_rule>`. Although the average cost valuation is not recalculated, the
+inventory value still decreases because the product is removed from stock and delivered to the
+customer location.
+
+.. exercise::
+   To demonstrate that the average cost valuation is not recalculated, examine the "Deliver 10
+   tables" example.
+
+   .. math::
+      Avg~Cost = \frac{12 \times $12 + (-10) \times $12}{12-10} = \frac{24}{2} = $12
+
+   #. Because 10 tables are being sent out to customers, the *incoming quantity* is `-10`. The
+      previous average cost (`$12`) is used in lieu of a vendor's *purchase price*;
+   #. The *incoming inventory value* is `-10 * $12 = -$120`;
+   #. The old *inventory value* (`$144`) is added to the *incoming inventory value* (`-$120`), so
+      `$144 + -$120 = $24`;
+   #. Only `2` tables remain after shipping out `10` tables from `12`. So the current *inventory
+      value* (`$24`) is divided by the on-hand quantity (`2`);
+   #. `$24 / 2 = $12`, which is the same average cost as the previous operation.
+
+   To verify this in Odoo, sell `10` tables in the *Sales* app, validate the delivery, and then
+   review the inventory valuation record by going to in :menuselection:`Inventory --> Reporting -->
+   Inventory Valuation`. In the topmost valuation layer, delivering `10` tables reduces the
+   product's value by `-$120`.
+
+   **Note**: What is not represented in this stock valuation record is the revenue made from this
+   sale, so this decrease is not a loss to the company.
+
+   .. image:: avg_price_valuation/inventory-val-send-10-tables.png
+      :align: center
+      :alt: Show how deliveries decrease inventory valuation.
+
+.. _inventory/avg_cost/return:
+
+Return items to supplier (use case)
+===================================
+
+Because the price paid to suppliers can differ from the price the product is valued at with the
+|AVCO| method, Odoo handles returned items in a specific way.
+
+#. Products are returned to suppliers at the original purchase price, but;
+#. The internal cost valuation remains unchanged.
+
+The above :ref:`example table <inventory/avg_cost/math_table>` is updated as follows:
+
+--------------------------------+---------------+-------------------+---------------+------------+
+| Operation                      | Qty*Avg Cost  | Inventory Value   | Qty On Hand   | Avg Cost   |
+================================+===============+===================+===============+============+
+|                                |               | $24               | 2             | $12        |
+--------------------------------+---------------+-------------------+---------------+------------+
+| Return 1 table bought at $10   | -1 * $12      | $12               | 1             | $12        |
+--------------------------------+---------------+-------------------+---------------+------------+
+
+In other words, returns to vendors are perceived by Odoo as another form of a product exiting the
+warehouse. To Odoo, because the table is valued at $12 per unit, the inventory value is reduced by
+`$12` when the product is returned; the initial purchase price of `$10` is unrelated to the table's
+average cost.
+
+.. example::
+   To return a single table that was purchased for `$10`, navigate to the receipt in the *Inventory*
+   app for the :ref:`8 tables purchased in Exercise 1 <inventory/avg_cost/ex-1>` by going to the
+   :guilabel:`Inventory Overview`, clicking on :guilabel:`Receipts`, and selecting the desired
+   receipt.
+
+   Then, click :guilabel:`Return` on the validated delivery order, and modify the quantity to `1` in
+   the reverse transfer window. This creates an outgoing shipment for the table. Select
+   :guilabel:`Validate` to confirm the outgoing shipment.
+
+   Return to :menuselection:`Inventory --> Reporting --> Inventory Valuation` to see how the
+   outgoing shipment decreases the inventory value by $12.
+
+   .. image:: avg_price_valuation/inventory-valuation-return.png
+      :align: center
+      :alt: Inventory valuation for return.
+
+.. _inventory/avg_price/leaving_inventory:
+
+Eliminate stock valuation errors in outgoing products
+-----------------------------------------------------
+
+Inconsistencies can occur in a company's inventory when the average cost valuation is recalculated
+on outgoing shipments.
+
+To demonstrate this error, the table below displays a scenario in which 1 table is shipped to a
+customer and another is returned to a supplier at the purchased price.
+
+------------------------------------------+---------------+-------------------+---------------+------------+
+| Operation                                | Qty*Price     | Inventory Value   | Qty On Hand   | Avg Cost   |
+==========================================+===============+===================+===============+============+
+|                                          |               | $24               | 2             | $12        |
+------------------------------------------+---------------+-------------------+---------------+------------+
+| Ship 1 product to customer               | -1 \* $12     | $12               | 1             | $12        |
+------------------------------------------+---------------+-------------------+---------------+------------+
+| Return 1 product initially bought at $10 | -1 \* $10     | **$2**            | **0**         | $12        |
+------------------------------------------+---------------+-------------------+---------------+------------+
+
+In the final operation above, the final inventory valuation for the table is `$2` even though there
+are `0` tables left in stock.
+
+.. admonition:: Correct method
+
+   Use the average cost to value the return. This does not mean the company gets $12 back for a $10
+   purchase; the item returned for $10 is valued internally at $12. The inventory value change
+   represents a product worth $12 no longer being accounted for in company assets.
+
+Anglo-Saxon accounting
+======================
+
+In addition to using |AVCO|, companies that use **Anglo-Saxon accounting** also keep a holding
+account that tracks the amount to be paid to vendors. Once a vendor delivers an order, **inventory
+value** increases based on the vendor price of the products that have entered the stock. The holding
+account (called **stock input**) is credited and only reconciled once the vendor bill is received.
+
+.. seealso::
+   - :ref:`Anglo-Saxon vs. Continental <inventory/inventory_valuation_config/accounting>`
+
+The table below reflects journal entries and accounts. The *stock input* account stores the money
+intended to pay vendors when the vendor bill has not yet been received. To balance accounts when
+returning products that have a price difference between the price the product is **valued at** and
+the price it was bought for, a *price difference* account is created.
+
+.. _inventory/avg_price/price-table:
+
+-----------------------------------------+---------------+--------------+-------------------+---------------+------------+
+| Operation                               | Stock Input   | Price Diff   | Inventory Value   | Qty On Hand   | Avg Cost   |
+=========================================+===============+==============+===================+===============+============+
+|                                         |               |              | $0                | 0             | $0         |
+-----------------------------------------+---------------+--------------+-------------------+---------------+------------+
+| Receive 8 tables at $10                 | ($80)         |              | $80               | 8             | $10        |
+-----------------------------------------+---------------+--------------+-------------------+---------------+------------+
+| Receive vendor bill $80                 | $0            |              | $80               | 8             | $10        |
+-----------------------------------------+---------------+--------------+-------------------+---------------+------------+
+| Receive 4 tables at $16                 | ($64)         |              | $144              | 12            | $12        |
+-----------------------------------------+---------------+--------------+-------------------+---------------+------------+
+| Receive vendor bill $64                 | $0            |              | $144              | 12            | $12        |
+-----------------------------------------+---------------+--------------+-------------------+---------------+------------+
+| Deliver 10 tables to customer           | $0            |              | $24               | 2             | $12        |
+-----------------------------------------+---------------+--------------+-------------------+---------------+------------+
+| Return 1 table initially bought at $10  | **$10**       | **$2**       | **$12**           | 1             | $12        |
+-----------------------------------------+---------------+--------------+-------------------+---------------+------------+
+| Receive vendor refund $10               | $0            | $2           | $12               | 1             | $12        |
+-----------------------------------------+---------------+--------------+-------------------+---------------+------------+
+
+Product reception
+-----------------
+
+Summary
+~~~~~~~
+
+At product reception, Odoo ensures companies can pay for goods that were purchased by preemptively
+moving an amount matching the price of received goods into the :doc:`liability account
+</applications/finance/accounting/get_started/cheat_sheet>`, **Stock Input**. Then, once the bill
+has been received, the amount in the holding account is transferred to *Accounts Payable*. Transfers
+into this account means the bill has been paid. **Stock Input** is reconciled once the vendor bill
+is received.
+
+Inventory valuation is a method of calculating how much each in-stock product is worth internally.
+Since there is a difference between the price the product is **valuated at** and the price the
+product was actually **purchased for**, the **Inventory Valuation** account is unrelated to the
+crediting and debiting operations of the **Stock Input** account.
+
+To conceptualize all this, follow the breakdown below.
+
+Accounts balanced at received products
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In this example, a company starts with zero units of a product, `table`, in stock. Then, 8 tables
+are received from the vendor:
+
+#. The **Stock Input** account stores `$80` of credit owed to the vendor. The amount in this account
+   is unrelated to the inventory value.
+#. `$80` worth of tables came **in** (**debit** the *Inventory Value* account `$80`), and
+#. `$80` must be paid **out** for received goods (**credit** the *Stock Input* account `$80`).
+
+In Odoo
+*******
+
+Odoo generates an accounting journal entry when shipments that use |AVCO| costing method are
+received. Configure a :guilabel:`Price Difference Account` by selecting the :guilabel:`➡️ (arrow)`
+icon next to the :guilabel:`Product Category` field on the product page.
+
+Under :guilabel:`Account Properties`, create a new :guilabel:`Price Difference Account` by typing in
+the name of the account and clicking :guilabel:`Create and Edit`. Then set the account
+:guilabel:`Type` as `Expenses`, and click :guilabel:`Save`.
+
+.. image:: avg_price_valuation/create-price-difference.png
   :align: center
+   :alt: Create price difference account.

- When products leave the warehouse: the average cost **does not** change
+Then, receive the shipment in the *Purchase* app or *Inventory* app, and navigate to the
+:menuselection:`Accounting app --> Accounting --> Journal Entries`. In the list, find the
+:guilabel:`Reference` that matches the warehouse reception operation for the relevant product.

-Defining the purchase price
---------------------------
+.. image:: avg_price_valuation/search-for-entry-of-tables.png
+   :align: center
+   :alt: Show accounting entry of 8 tables from the list.

-The purchase price is estimated at the reception of the products (you
-might not have received the vendor bill yet) and reevaluated at the
-reception of the vendor bill. The purchase price includes the cost you
-pay for the products, but it may also includes additional costs, like
-landed costs.
+Click on the line for 8 tables. This accounting journal entry shows that when the 8 tables were
+received, the `Stock Valuation` account increased by `$80`. Conversely, the **Stock Input** account
+(set as `Stock Interim (Received)` account by default) is credited `$80`.

-Average cost example
-====================
+.. image:: avg_price_valuation/accounting-entry-8-tables.png
+   :align: center
+   :alt: Debit stock valuation and credit stock input 80 dollars.

-+-----------------------------+---------------+-------------------+---------------+------------+
-| Operation                   | Delta Value   | Inventory Value   | Qty On Hand   | Avg Cost   |
-+=============================+===============+===================+===============+============+
-|                             |               | $0                | 0             | $0         |
-+-----------------------------+---------------+-------------------+---------------+------------+
-| Receive 8 Products at $10   | +8\*$10       | $80               | 8             | $10        |
-+-----------------------------+---------------+-------------------+---------------+------------+
-| Receive 4 Products at $16   | +4\*$16       | $144              | 12            | $12        |
-+-----------------------------+---------------+-------------------+---------------+------------+
-| Deliver 10 Products         | -10\*$12      | $24               | 2             | $12        |
-+-----------------------------+---------------+-------------------+---------------+------------+
-+-----------------------------+---------------+-------------------+---------------+------------+
+Accounts balanced at received vendor bill
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-At the beginning, the Avg Cost is set to 0 set as there is no product in
-the inventory. When the first reception is made, the average cost
-becomes logically the purchase price.
+In this example, a company starts with zero units of a product, table, in stock. Then, 8 tables are
+received from the vendor. When the bill is received from vendor for 8 tables:

-At the second reception, the average cost is updated because the total
-inventory value is now ``$80 + 4*$16 = $144``. As we have 12 units on
-hand, the average price per unit is ``$144 / 12 = $12``.
+#. Use `$80` in the **Stock Input** account to pay the bill. This cancels out and the account now
+   holds `$0`.
+#. Debit **Stock Input** `$80` (to reconcile this account).
+#. Credit **Accounts payable** `$80`. This account stores the amount the company owes others, so
+   accountants use the amount to write checks to vendors.

-By definition, the delivery of 10 products does not change the average
-cost. Indeed, the inventory value is now $24 as we have only 2 units
-remaining of each ``$24 / 2 = $12``.
+In Odoo
+*******

-Purchase return use case
-========================
+Once the vendor requests payment, navigate to the :menuselection:`Purchase app --> Orders -->
+Purchase` and select the :abbr:`PO (Purchase Order)` for 8 tables. Inside the :abbr:`PO (Purchase
+Order)`, select :guilabel:`Create Bill`.

-In case of a product returned to its supplier after reception, the
-inventory value is reduced using the average cost formulae (not at the
-initial price of these products!).
+Switch to the :guilabel:`Journal Items` tab to view how `$80` is transferred from the holding
+account, `Stock Interim (Received)` to `Accounts Payable`. :guilabel:`Confirm` the bill to record
+the payment to the vendor.

-Which means that the above table will be updated as follow:
+.. image:: avg_price_valuation/receive-8-table-bill.png
+   :align: center
+   :alt: Show bill linked to the purchase order for 8 tables.

-+-----------------------------------------------+---------------+-------------------+---------------+------------+
-| Operation                                     | Delta Value   | Inventory Value   | Qty On Hand   | Avg Cost   |
-+===============================================+===============+===================+===============+============+
-|                                               |               | $24               | 2             | $12        |
-+-----------------------------------------------+---------------+-------------------+---------------+------------+
-| Return of 1 Product initially bought at $10   | -1\*$12       | $12               | 1             | $12        |
-+-----------------------------------------------+---------------+-------------------+---------------+------------+
+On product delivery
+-------------------

-Explanation: counter example
----------------------------
+In the :ref:`above example table <inventory/avg_price/price-table>`, when 10 products are delivered
+to a customer, the **Stock Input** account is untouched because there are no new products coming in.
+To put it simply:

-Remember the definition of **Average Cost**, saying that we do not update
-the average cost of a product leaving the inventory. If you break this
-rule, you may lead to inconsistencies in your inventory.
+#. **Inventory valuation** is credited `$120`. Subtracting from inventory valuation represents
+   `$120` worth of products exiting the company.
+#. Debit **Accounts Receivable** to record revenue from the sale.

-As an example, here is the scenario when you deliver one piece to the
-customer and return the other one to your supplier (at the cost you
-purchased it). Here is the operation:
+.. image:: avg_price_valuation/sell-10-tables.png
+   :align: center
+   :alt: Show journal items linked to sale order.

-+-----------------------------------------------+---------------+-------------------+---------------+------------+
-| Operation                                     | Delta Value   | Inventory Value   | Qty On Hand   | Avg Cost   |
-+===============================================+===============+===================+===============+============+
-|                                               |               | $24               | 2             | $12        |
-+-----------------------------------------------+---------------+-------------------+---------------+------------+
-| Customer Shipping 1 product                   | -1\*$12       | $12               | 1             | $12        |
-+-----------------------------------------------+---------------+-------------------+---------------+------------+
-| Return of 1 Product initially bought at $10   | -1\*$10       | **$2**            | **0**         | $12        |
-+-----------------------------------------------+---------------+-------------------+---------------+------------+
+.. spoiler:: Understand Anglo-Saxon expensing

-As you can see in this example, this is not correct: an inventory
-valuation of $2 for 0 pieces in the warehouse.
+   In the accounting journal entry invoicing a customer for 10 tables, the accounts **Product
+   Sales**, **Tax Received**, and **Accounts Receivable** all pertain to the sale of the product.
+   **Accounts Receivable** is the account where the customer payment will be received.

-The correct scenario should be to return the goods at the current
-average cost:
+   Anglo-Saxon accounting recognizes the cost of goods sold (COGS) once the sale is made. So, up
+   until the product is sold, scrapped, or returned, costs of keeping the product in stock are not
+   accounted for. The **Expense** account is debited `$120` to log the costs of storing 10 tables
+   during this period of time.

-+-----------------------------------------------+---------------+-------------------+---------------+------------+
-| Operation                                     | Delta Value   | Inventory Value   | Qty On Hand   | Avg Cost   |
-+===============================================+===============+===================+===============+============+
-|                                               |               | $24               | 2             | $12        |
-+-----------------------------------------------+---------------+-------------------+---------------+------------+
-| Customer Shipping 1 product                   | -1\*$12       | $12               | 1             | $12        |
-+-----------------------------------------------+---------------+-------------------+---------------+------------+
-| Return of 1 Product initially bought at $10   | -1\*$12       | **$0**            | **0**         | $12        |
-+-----------------------------------------------+---------------+-------------------+---------------+------------+
+On product return
+-----------------

-On the other hand, using the average cost to value the return ensure a
-correct inventory value at all times.
+In the :ref:`above example table <inventory/avg_price/price-table>`, when returning 1 product to a
+vendor purchased at `$10`, a company expects `$10` in the **Accounts Payable** account from the
+vendor. However, **Stock Input** account must be debited `$12` because the average cost is `$12` at
+the time of the return. The missing `$2` is accounted for in the :guilabel:`Price Difference
+Account`, which is set up in the product's :guilabel:`Product Category`.

-Further thoughts on anglo saxon mode
------------------------------------
+.. note::
+   Behavior of *price difference accounts* varies from localization. In this case, the account is
+   intended to store differences between vendor price and *automated* inventory valuation methods.

-For people in using the **anglo saxon accounting** principles, there is
-another concept to take into account: the stock input account of the
-product, which is intended to hold at any time the value of vendor bills
-to receive. So the stock input account will increase on reception of
-incoming shipments and will decrease when receiving the related vendor
-bills.
+Summary:

-Back to our example, we see that when the return is valued at the
-average price, the amount booked in the stock input account is the
-original purchase price:
+#. Debit **Stock Input** account `$10` to move the table from stock to stock input. This move is to
+   indicate that the table is to be processed for an outgoing shipment.
+#. Debit **Stock Input** an additional `$2` to account for the **Price Difference**.
+#. Credit **Stock Valuation** `$12` because the item is leaving the stock.

-+-----------------------------------------------+---------------+--------------+-------------------+---------------+------------+
-| Operation                                     | stock input   | price diff   | Inventory Value   | Qty On Hand   | Avg Cost   |
-+===============================================+===============+==============+===================+===============+============+
-|                                               |               |              | $0                | 0             | $0         |
-+-----------------------------------------------+---------------+--------------+-------------------+---------------+------------+
-| Receive 8 Products at $10                     | ($80)         |              | $80               | 8             | $10        |
-+-----------------------------------------------+---------------+--------------+-------------------+---------------+------------+
-| Receive vendor bill $80                       | $0            |              | $80               | 8             | $10        |
-+-----------------------------------------------+---------------+--------------+-------------------+---------------+------------+
-| Receive 4 Products at $16                     | ($64)         |              | $144              | 12            | $12        |
-+-----------------------------------------------+---------------+--------------+-------------------+---------------+------------+
-| Receive vendor bill $64                       | $0            |              | $144              | 12            | $12        |
-+-----------------------------------------------+---------------+--------------+-------------------+---------------+------------+
-| Deliver 10 Products                           | $0            |              | $24               | 2             | $12        |
-+-----------------------------------------------+---------------+--------------+-------------------+---------------+------------+
-| Return of 1 Product initially bought at $10   | **$10**       | **$2**       | **$12**           | 1             | $12        |
-+-----------------------------------------------+---------------+--------------+-------------------+---------------+------------+
-| Receive vendor refund $10                     | $0            | $2           | $12               | 1             | $12        |
-+-----------------------------------------------+---------------+--------------+-------------------+---------------+------------+
+.. image:: avg_price_valuation/expensing-price-difference-account.png
+   :align: center
+   :alt: 2 dollar difference expensed in Price Difference account.

-This is because the vendor refund will be made using the original
-purchase price, so to zero out the effect of the return in the stock
-input in last operation, we need to reuse the original price. The price
-difference account located on the product category is used to book the
-difference between the average cost and the original purchase price.
+Once the vendor's refund is received,
+
+#. Credit **Stock Input** account `$10` to reconcile the price of the table.
+#. Debit **Accounts Payable** `$10` to have the accountants collect and register the payment in
+   their journal.
+
+.. image:: avg_price_valuation/return-credit-note.png
+   :align: center
+   :alt: Return to get 10 dollars back.
@@ -3,48 +3,37 @@ Chart of accounts
 =================

 The **chart of accounts (COA)** is the list of all the accounts used to record financial
-transactions in the general ledger of an organization.
+transactions in the general ledger of an organization. The chart of accounts can be found under
+:menuselection:`Accounting-->Configuration-->Chart of Accounts`.

-The accounts are usually listed in the order of appearance in the financial reports. Most of the
-time, they are listed as follows :
+When browsing your chart of accounts, you can sort the accounts by :guilabel:`Code`,
+:guilabel:`Account Name`, or :guilabel:`Type`, but other options are available in the drop-down menu
+:guilabel:`(⋮)`.

- Balance Sheet accounts:
-
-  - Assets
-  - Liabilities
-  - Equity
-
- Profit & Loss:
-
-  - Income
-  - Expense
-
-When browsing your chart of accounts, you can filter the accounts by number, in the left column, and
-also group them by :guilabel:`Account Type`.
-
-.. image:: chart_of_accounts/chart-of-accounts.png
-   :align: center
+.. image:: chart_of_accounts/chart-of-accounts-sort.png
   :alt: Group the accounts by type in Odoo Accounting

 Configuration of an account
 ===========================

-The country you select at the creation of your database (or additional company on your database)
-determines which **fiscal localization package** is installed by default. This package includes a
-standard chart of accounts already configured according to the country's regulations. You can use
-it directly or set it according to your company's needs.
+The country you select during the creation of your database (or additional company in your database)
+determines which :doc:`fiscal localization package <../../fiscal_localizations>` is installed by
+default. This package includes a standard chart of accounts already configured according to the
+country's regulations. You can use it directly or set it according to your company's needs.
+
+To create a new account, go to :menuselection:`Accounting-->Configuration-->Chart of Accounts`,
+click :guilabel:`Create`, and fill in (at the minimum) the required fields
+(:guilabel:`Code, Account Name, Type`).

 .. warning::
   It is not possible to modify the **fiscal localization** of a company once a journal entry has
   been posted.

-To create a new account, go to :menuselection:`Accounting --> Configuration --> Chart of Accounts`,
-click on :guilabel:`Create`, and fill out the form.
-
 Code and name
 -------------

-Each account is identified by its **code** and **name**, which also indicates the account's purpose.
+Each account is identified by its :guilabel:`Code` and :guilabel:`Name`, which also indicate the
+account's purpose.

 .. _chart-of-account/type:

@@ -59,7 +48,7 @@ Correctly configuring the **account type** is critical as it serves multiple pur
 - Generate opening entries

 To configure an account type, open the :guilabel:`Type` field's drop-down selector and select the
-right type among the following list:
+corresponding type from the following list:

 +---------------+--------------+-------------------------+
 | Report        | Category     | Account Types           |
@@ -104,29 +93,31 @@ right type among the following list:
 Assets, deferred expenses, and deferred revenues automation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-Some **account types** display a new field **to automate** the creation of :ref:`assets
-<assets-automation>` entries, :ref:`deferred expenses <deferred-expenses-automation>` entries,
-and :ref:`deferred revenues <deferred-revenues-automation>` entries.
+Some **account types** can **automate** the creation of :ref:`assets <assets-automation>` entries,
+:ref:`deferred expenses <deferred-expenses-automation>` entries, and
+:ref:`deferred revenues <deferred-revenues-automation>` entries. To **automate** entries, click
+:guilabel:`Setup` on an account line and go to the :guilabel:`Automation` tab.

-You have three choices for the :guilabel:`Automation` field:
+You have three choices for the :guilabel:`Automation` tab:

 #. :guilabel:`No`: this is the default value. Nothing happens.
 #. :guilabel:`Create in draft`: whenever a transaction is posted on the account, a draft entry is
-   created, but not validated. You must first fill out the corresponding form.
-#. :guilabel:`Create and validate`: you must also select a **model**. Whenever a transaction is
-   posted on the account, an entry is created and immediately validated.
+   created but not validated. You must first fill out the corresponding form.
+#. :guilabel:`Create and validate`: you must also select a :guilabel:`Deferred Expense Model`.
+   Whenever a transaction is posted on the account, an entry is created and immediately validated.

 Default taxes
 -------------

-Select a **default tax** that will be applied when this account is chosen for a product sale or
-purchase.
+In the :guilabel:`Setup` menu of an account, select a **default tax** to be applied when this
+account is chosen for a product sale or purchase.

 Tags
 ----

-Some accounting reports require **tags** to be set on the relevant accounts. By default, you can
-choose among the tags that are used by the *Cash Flow Statement*.
+Some accounting reports require **tags** to be set on the relevant accounts. To add a tag, under
+:guilabel:`Setup`, click the :guilabel:`Tags` field and select an existing tag or :guilabel:`Create`
+a new one.

 Account groups
 --------------
@@ -134,31 +125,29 @@ Account groups
 **Account groups** are useful to list multiple accounts as *sub-accounts* of a bigger account and
 thus consolidate reports such as the **Trial Balance**. By default, groups are handled automatically
 based on the code of the group. For example, a new account `131200` is going to be part of the group
-`131000`.
+`131000`. You can attribute a specific group to an account in the :guilabel:`Group` field under
+:guilabel:`Setup`.

 Create account groups manually
------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 .. note::
   Regular users should not need to create account groups manually. The following section is only
   intended for rare and advanced use cases.

-To create a new account group, :ref:`developer mode <developer-mode>` and head to
-:menuselection:`Accounting app --> Configuration --> Account Groups`. Here, create a new group and
-enter the :guilabel:`name, code prefix, and company` to which that group account should be
-available. Note that you must enter the same code prefix in both :guilabel:`From` and :guilabel:`to`
-fields.
+To create a new account group, activate :ref:`developer mode <developer-mode>` and head to
+:menuselection:`Accounting app-->Configuration-->Account Groups`. Here, create a new group and enter
+the :guilabel:`name, code prefix, and company` to which that group account should be available. Note
+that you must enter the same code prefix in both :guilabel:`From` and :guilabel:`to` fields.

 .. image:: chart_of_accounts/account-groups.png
-   :align: center
   :alt: Account groups creation.

-To display your **Trial Balance** report with your account groups, go to :menuselection:`Accounting
-app-->Reporting-->Trial Balance`, then open the :guilabel:`Options` menu and select
-:guilabel:`Hierarchy and Subtotals`.
+To display your **Trial Balance** report with your account groups, go to
+:menuselection:`Accounting-->Reporting-->Trial Balance`, then open the :guilabel:`Options` menu and
+select :guilabel:`Hierarchy and Subtotals`.

-.. image:: chart_of_accounts/trial-balance.png
-   :align: center
+.. image:: chart_of_accounts/chart-of-accounts-groups.png
   :alt: Account Groups in the Trial Balance in Odoo Accounting

 Allow reconciliation
@@ -171,15 +160,18 @@ For example, an invoice paid with a credit card can be marked as :guilabel:`paid
 its payment. Therefore, the account used to record credit card payments needs to be configured as
 **allowing reconciliation**.

-To do so, check the :guilabel:`Allow Reconciliation` box in the account's settings, and save.
+To do so, check the :guilabel:`Allow Reconciliation` box in the account's settings, and
+:guilabel:`Save`; or enable the button from the chart of accounts view.
+
+.. image:: chart_of_accounts/chart-of-accounts-reconciliation.png
+   :alt: Allow reconciliation for accounts in Odoo Accounting

 Deprecated
 ----------

 It is not possible to delete an account once a transaction has been recorded on it. You can make
-them unusable by using the **Deprecated** feature.
-
-To do so, check the :guilabel:`Deprecated` box in the account's settings, and save.
+them unusable by using the **Deprecated** feature: check the :guilabel:`Deprecated` box in the
+account's settings, and :guilabel:`Save`.

 .. seealso::
   * :doc:`cheat_sheet`
@@ -4,15 +4,15 @@
 Payments
 ========

-In Odoo, payments can either be linked automatically to an invoice or bill or be stand-alone records
-for use at a later date.
+In Odoo, payments can either be automatically linked to an invoice or bill or be stand-alone records
+for use at a later date:

-If a payment is **linked to an invoice or bill**, it reduces the amount due of the invoice. You can
-have multiple payments related to the same invoice.
+- If a payment is **linked to an invoice or bill**, it reduces/settles the amount due of the
+  invoice. You can have multiple payments related to the same invoice.

-If a payment is **not linked to an invoice or bill**, the customer has an outstanding credit with
-your company, or your company has an outstanding debit with a vendor. You can use those outstanding
-amounts to reduce unpaid invoices/bills.
+- If a payment is **not linked to an invoice or bill**, the customer has an outstanding credit with
+  your company, or your company has an outstanding debit with a vendor. You can use those
+  outstanding amounts to reduce/settle unpaid invoices/bills.

 .. seealso::
   - :doc:`Internal transfers <payments/internal_transfers>`
@@ -23,69 +23,64 @@ amounts to reduce unpaid invoices/bills.
 Registering payment from an invoice or bill
 ===========================================

-When clicking on :guilabel:`Register payment` in a customer invoice or vendor bill, it generates a
-new journal entry and changes the amount due according to the amount of the payment. The counterpart
-is reflected in an outstanding receipts or payments account. At this point, the customer invoice or
-vendor bill is marked as :guilabel:`In payment`. Then, when the outstanding account is reconciled
-with a bank statement line, the invoice or vendor bill changes to the :guilabel:`Paid` status.
+When clicking :guilabel:`Register payment` in a customer invoice or vendor bill, it generates a new
+journal entry and changes the amount due according to the payment amount. The counterpart is
+reflected in an :ref:`outstanding <bank/outstanding-accounts>` **receipts** or **payments** account.
+At this point, the customer invoice or vendor bill is marked as :guilabel:`In payment`. Then, when
+the outstanding account is reconciled with a bank statement line, the invoice or vendor bill changes
+to the :guilabel:`Paid` status.

 The information icon near the payment line displays more information about the payment. You can
-access additional information, such as the related journal, by clicking on :guilabel:`View`.
+access additional information, such as the related journal, by clicking :guilabel:`View`.

 .. image:: payments/information-icon.png
-   :alt: See detailed information of a payment
+   :alt: See detailed information of a payment.

 .. note::
-   - The customer invoice or vendor bill should be in the status :guilabel:`Posted` to register the
+   - The customer invoice or vendor bill must be in the :guilabel:`Posted` status to register the
     payment.
-   - When clicking on :guilabel:`Register payment`, you can select the amount to pay and make a
-     partial or full payment.
-   - If your main bank account is set as :ref:`outstanding account
-     <bank/outstanding-accounts>`, and the payment is made in Odoo (not related to a
-     bank statement), invoices and bills are directly registered in the status :guilabel:`Paid`.
-   - If you unreconciled a payment, it still appears in your books but is no longer linked to the
+   - If you unreconcile a payment, it still appears in your books but is no longer linked to the
     invoice.
   - If you (un)reconcile a payment in a different currency, a journal entry is automatically
     created to post the currency exchange gains/losses (reversal) amount.
   - If you (un)reconcile a payment and an invoice having cash basis taxes, a journal entry is
     automatically created to post the cash basis tax (reversal) amount.

-.. seealso::
-   - :doc:`bank/reconciliation`
+.. tip::
+   - If your main bank account is set as an :ref:`outstanding account
+     <bank/outstanding-accounts>`, and the payment is registered in Odoo (not through a related
+     bank statement), invoices and bills are directly registered as :guilabel:`Paid`.

 Registering payments not tied to an invoice or bill
 ===================================================

-When a new payment is registered via the menu :menuselection:`Customers / Vendors --> Payments`, it
-is not directly linked to an invoice or bill. Instead, the account receivable or the account payable
-are matched with the outstanding account until they are manually matched with their related invoice
-or bill.
+When a new payment is registered via :menuselection:`Customers / Vendors --> Payments` menu, it is
+not directly linked to an invoice or bill. Instead, the account receivable or the account payable is
+matched with the **outstanding account** until it is manually matched with its related invoice or
+bill.

 Matching invoices and bills with payments
 -----------------------------------------

-A blue banner appears when you validate a new invoice or bill and there is an outstanding payment
-for this specific customer or vendor. It can easily be matched from the invoice or the bill by
-clicking on :guilabel:`ADD` under :guilabel:`Outstanding Credits` or :guilabel:`Outstanding Debits`.
+A blue banner appears when you validate a new invoice/bill and an **outstanding payment** exists for
+this specific customer or vendor. It can easily be matched from the invoice or bill by clicking
+:guilabel:`ADD` under :guilabel:`Outstanding Credits` or :guilabel:`Outstanding Debits`.

 .. image:: payments/add-option.png
-   :alt: Shows the ADD option to reconcile an invoice or a bill with a payment
+   :alt: Shows the ADD option to reconcile an invoice or a bill with a payment.

-The invoice or bill is now marked as :guilabel:`In payment` until it is reconciled with the bank
-statement.
-
-.. seealso::
-   - :doc:`bank/reconciliation`
+The invoice or bill is now marked as :guilabel:`In payment` until it is reconciled with its
+corresponding bank statement.

 Batch payment
 -------------

 Batch payments allow you to group different payments to ease :doc:`reconciliation
-<bank/reconciliation>`. They are also useful when you deposit checks to the bank or
-for SEPA Payments. To do so, go to :menuselection:`Accounting --> Customers --> Batch Payments` or
-:menuselection:`Accounting --> Vendors --> Batch Payments`. In the list view of payments, you can
-select several payments and group them in a batch by clicking on :menuselection:`Action --> Create
-Batch Payment`.
+<bank/reconciliation>`. They are also useful when you deposit :doc:`checks <payments/checks>` to the
+bank or for :doc:`SEPA payments <payments/pay_sepa>`. To do so, go to :menuselection:`Accounting -->
+Customers --> Batch Payments` or :menuselection:`Accounting --> Vendors --> Batch Payments`. In the
+list view of payments, you can select and group several payments in a batch by clicking
+:menuselection:`Action --> Create Batch Payment`.

 .. seealso::
  - :doc:`payments/batch`
@@ -97,36 +92,50 @@ Payments matching
 -----------------

 The :guilabel:`Payments matching` tool opens all unreconciled customer invoices or vendor bills and
-gives you the opportunity to process them all one by one, doing the matching of all their payments
-and invoices at once. You can reach this tool from the :menuselection:`Accounting Dashboard -->
-Customer Invoices / Vendor Bills`, and click on :guilabel:`⋮` and select :guilabel:`Payments
-Matching`, or by going to :menuselection:`Accounting --> Reconciliation`.
+allows you to process them individually, matching all payments and invoices in one place. You can
+reach this tool from the :menuselection:`Accounting Dashboard --> Customer Invoices / Vendor Bills`,
+click the drop-down menu button (:guilabel:`⋮`), and select :guilabel:`Payments Matching`, or go to
+:menuselection:`Accounting --> Accounting --> Reconciliation`.
+
+.. image:: payments/payments-journal.png
+   :alt: Payments matching menu in the drop-down menu.

 .. note::
-   During the :doc:`reconciliation <bank/reconciliation>`, if the sum of the debits
-   and credits does not match, there is a remaining balance. This either needs to be reconciled at a
-   later date or needs to be written off directly.
+   During the :doc:`reconciliation <bank/reconciliation>`, if the sum of the debits and credits does
+   not match, there is a remaining balance. This either needs to be reconciled at a later date or
+   needs to be written off directly.

 Batch payments matching
 -----------------------

-To reconcile several outstanding payments or invoices at once, for a specific customer or vendor,
-the batch reconciliation feature can be used. Go to :menuselection:`Accounting --> Reporting -->
-Aged Receivable / Aged Payable`. You now see all transactions that have not been reconciled yet, and
-when you select a customer or vendor, the :guilabel:`Reconcile` option is displayed.
+You can use the batch reconciliation feature to reconcile several outstanding payments or invoices
+simultaneously for a specific customer or vendor. Go to :menuselection:`Accounting --> Reporting -->
+Aged Receivable / Aged Payable`. You can see all transactions that have not been reconciled yet for
+that partner, and when you select a customer or vendor, the :guilabel:`Reconcile` option is
+displayed.

 .. image:: payments/reconcile-option.png
-   :alt: See the reconcile option
+   :alt: See the reconcile option.
+
+Registering a partial payment
+=============================
+
+To register a **partial payment**, click :guilabel:`Register payment` from the related invoice or
+bill, and enter the amount received or paid. Upon entering the amount, a prompt appears to decide
+whether to :guilabel:`Keep open` the invoice or bill, or :guilabel:`Mark as fully paid`. Select
+:guilabel:`Keep open` and click :guilabel:`Create payment`. The invoice or bill is now marked as
+:guilabel:`Partial`. Select :guilabel:`Mark as fully paid` if you wish to settle the invoice or bill
+with a difference in the amount.
+
+.. image:: payments/payment-difference.png
+   :alt: Partial payment of an invoice or bill.

 Reconciling payments with bank statements
 =========================================

 Once a payment has been registered, the status of the invoice or bill is :guilabel:`In payment`. The
-next step is to reconcile it with the related bank statement line to have the transaction finalized
-and the invoice or bill marked as :guilabel:`Paid`.
-
-.. seealso::
-   - :doc:`bank/reconciliation`
+next step is :doc:`reconciling <bank/reconciliation>` it with the related bank statement line to
+have the transaction finalized and the invoice or bill marked as :guilabel:`Paid`.

 .. toctree::
   :titlesonly:
@@ -139,5 +148,4 @@ and the invoice or bill marked as :guilabel:`Paid`.
   payments/internal_transfers
   payments/pay_sepa
   payments/pay_checks
-   payments/multiple
   payments/forecast
@@ -1,53 +0,0 @@
-=========================
-Pay several bills at once
-=========================
-
-Odoo offers the possibility of grouping multiple bills' payments into one, facilitating the
-reconciliation process.
-
-.. seealso::
-   - :doc:`/applications/inventory_and_mrp/purchase/manage_deals/manage`
-   - :doc:`/applications/finance/accounting/bank/reconciliation`
-
-Group payments
-==============
-
-To register the payment of multiple bills at once, go to :menuselection:`Accounting app -->
-Vendors --> Bills`. Then, select the bills you wish to register a payment for by **ticking** the
-boxes next to the bills. When done, either click :guilabel:`Register Payment` or
-:menuselection:`Action --> Register Payment`.
-
-.. image:: multiple/register-payment-button.png
-   :align: center
-   :alt: Register payment button.
-
-.. note::
-   Payments can only be registered for :guilabel:`posted` bills.
-
-When registering the payments, a **pop-up window** appears. From here, you can either create
-**separate payments** for each bill all at once by clicking :guilabel:`Create Payment`, *or* create
-one payment by combining **all** bills' payments. To **combine** all payments, tick the
-:guilabel:`Group Payments` box.
-
-.. note::
-   The :guilabel:`Group Payments` option only appears when selecting two or more bills.
-
-.. image:: multiple/multiple-group-payments.png
-   :align: center
-   :alt: Group payments options when registering a payment.
-
-When selecting :guilabel:`Group Payments`, the :guilabel:`amount, currency, date and memo` are all
-set automatically, but you can modify them according to your needs.
-
-Partial group payments with cash discounts
------------------------------------------
-
-In case of **partial group payments with cash discounts**, you can follow the steps found on the
-:doc:`cash discount documentation page
-</applications/finance/accounting/customer_invoices/cash_discounts>`. Make sure to
-apply the :doc:`payment terms
-</applications/finance/accounting/customer_invoices/payment_terms>` to the **bills**
-*instead* of the invoices.
-
-.. seealso::
-   :doc:`/applications/finance/accounting/customer_invoices/payment_terms`
@@ -13,14 +13,15 @@ Activate checks payment methods
 -------------------------------

 To activate the checks payment method, go to :menuselection:`Accounting --> Configuration -->
-Checks`, there you can activate the payment method as well as set up the :guilabel:`Check Layout`.
-Once activated the :guilabel:`Checks` setting, the feature is automatically setup for your
-:guilabel:`Outgoing Payments`.
+Settings`, and scroll down to the :guilabel:`Vendor Payments` section. There, you can activate the
+payment method as well as set up the :guilabel:`Check Layout`.

 .. note::
-   Some countries require specific modules to print checks; such modules may be installed by
-   default. For instance, the :guilabel:`U.S. Checks Layout` module is required to print U.S.
-   checks.
+   - Once the :guilabel:`Checks` setting is activated, the **Checks** payment method is
+     automatically set up in the :guilabel:`Outgoing Payments` tabs of **bank** journals.
+   - Some countries require specific modules to print checks; such modules may be installed by
+     default. For instance, the :guilabel:`U.S. Checks Layout` module is required to print U.S.
+     checks.

 Compatible check stationery for printing checks
 ===============================================
@@ -7,9 +7,8 @@ Reporting
 Main reports available
 ======================

-Besides the reports created specifically in each localisation module, a
-few very useful **generic** and **dynamic reports** are available for all
-countries :
+Odoo includes **generic** and **dynamic** reports available for all countries, regardless of the
+:doc:`localization package <../../finance/fiscal_localizations>` installed:

 -  **Balance Sheet**
 -  **Profit and Loss**
@@ -19,136 +18,136 @@ countries :
 -  **Aged Receivable**
 -  **Cash Flow Statement**
 -  **Tax Report**
-  **Bank Reconciliation**

-You can annotate every reports to print them and report to your adviser.
-Export to xls to manage extra analysis. Drill down in the reports to see
-more details (payments, invoices, journal items, etc.).
+Reports can be **annotated, printed, and drilled down** to see details (payments, invoices,
+journal items, etc.) by clicking the **down** arrow. Reports can also be exported to **PDF** or
+**XLSX** format by clicking :guilabel:`PDF` or :guilabel:`XLSX` at the top of the page.

-You can also compare values with another period. Choose how many periods
-you want to compare the chosen time period with. You can choose up to 12
-periods back from the date of the report if you don't want to use the
-default **Previous 1 Period** option.
+.. image:: reporting/reporting-annotate.png
+   :alt: Annotate reports.
+
+You can compare values across periods by using the :guilabel:`Comparison` menu and selecting the
+periods you want to compare.
+
+.. image:: reporting/reporting-comparison.png
+   :alt: Comparison menu to compare time periods.

 .. _reporting/balance-sheet:

 Balance Sheet
 -------------

-The **Balance Sheet** shows a snapshot of the assets, liabilities and equity
-of your organisation as at a particular date.
+The **Balance Sheet** shows a snapshot of your organization's assets, liabilities, and equity at a
+particular date.

-.. image:: reporting/main_reports09.png
+.. image:: reporting/reporting-balance-sheet.png
+   :alt: Balance sheet report of Odoo.
+
+.. _reporting/profit-and-loss:

 Profit and Loss
 ---------------

-The **Profit and Loss** report (or **Income Statement**) shows your
-organisation's net income, by deducting expenses from revenue for the
-report period.
+The **Profit and Loss** report (or **Income Statement**) shows your company's net income by
+deducting expenses from revenue for the reporting period.

-.. image:: reporting/main_reports10.png
+.. image:: reporting/reporting-profit-and-loss.png
+   :alt: Profit and Loss report of Odoo
+
+.. _reporting/executive-summary:

 Executive Summary
 -----------------

-The **Executive Summary** allows for a quick look at all the important
-figures you need to run your company.
+The **Executive Summary** allows a quick look at all the important figures to run your company.

-In very basic terms, this is what each of the items in this section is
-reporting :
+In basic terms, this is what each item in the following section reports:

 - **Performance:**
    - **Gross profit margin:**
-        The contribution each individual sale made
-        by your business less any direct costs needed to make those sales
-        (things like labour, materials, etc).
+        The contribution of all sales made by your business **minus** any direct costs needed to
+        make those sales (labor, materials, etc.).
    - **Net profit margin:**
-        The contribution each individual sale made by
-        your business less any direct costs needed to make those sales,
-        as well as any fixed overheads your company has (things like
-        rent, electricity, taxes you need to pay as a result of those
-        sales).
-    - **Return on investment (p.a.):**
-        The ratio of net profit made, to the
-        amount of assets the company used to make those profits.
+        The contribution of all sales made by your business **minus** any direct costs needed to
+        make those sales *and* fixed overheads your company has (electricity, rent, taxes
+        to be paid as a result of those sales, etc.).
+    - **Return on investment (per annum):**
+        The ratio of net profit made to the amount of assets the company used to make those profits.
 - **Position:**
-    - **Average debtor days:**
-        The average number of days it takes your
-        customers to pay you (fully), across all your customer invoices.
-    - **Average creditor days:**
-        The average number of days it takes you to
-        pay your suppliers (fully) across all your bills.
-    - **Short term cash forecast:**
-        How much cash is expected in or out of
-        your organisation in the next month i.e. balance of your **Sales
-        account** for the month less the balance of your **Purchases account**
-        for the month.
+    - **Average debtors days:**
+        The average number of days it takes your customers to (fully) pay you across all your
+        customer invoices.
+    - **Average creditors days:**
+        The average number of days it takes you to (fully) pay your suppliers across all your bills.
+    - **Short-term cash forecast:**
+        How much cash is expected in or out of your business in the next month, i.e., the balance of
+        your **Sales account** for the month **minus** the balance of your **Purchases account** for
+        the month.
    - **Current assets to liabilities:**
-        Also referred to as **current ratio**, this is the ratio
-        of current assets (assets that could be
-        turned into cash within a year) to the current liabilities
-        (liabilities which will be due in the next year). This is
-        typically used as as a measure of a company's ability to service
-        its debt.
+        Also referred to as **current ratio**, this is the ratio of current assets (:dfn:`assets
+        that could be turned into cash within a year`) to the current liabilities (:dfn:`liabilities
+        that will be due in the next year`). It is typically used to measure a company's ability to
+        service its debt.

-.. image:: reporting/main_reports01.png
+.. image:: reporting/reporting-executive-summary.png
+   :alt: Executive summary report in Odoo.
+
+.. _reporting/general-ledger:

 General Ledger
 --------------

-The **General Ledger Report** shows all transactions from all accounts for a
-chosen date range. The initial summary report shows the totals for each
-account and from there you can view a detailed transaction report or any
-exceptions. This report is useful for checking every transaction that
-occurred during a certain period of time.
+The **General Ledger Report** shows all transactions from all accounts for a chosen date range. The
+initial summary report shows each account's totals; from here, you can view a detailed transaction
+report or any exceptions. This report helps check every transaction that occurred during a specific
+period.

-.. image:: reporting/main_reports05.png
+.. image:: reporting/reporting-general-ledger.png
+   :alt: General Ledger report in Odoo.

 .. _reporting/aged-payable:

 Aged Payable
 ------------

-Run the **Aged Payable Details** report to display information on individual
-bills, credit notes and overpayments owed by you, and how long these
-have gone unpaid.
+Run the **Aged Payable Details** report to display information on individual bills, credit notes,
+and overpayments you owe and how long these have gone unpaid.

-.. image:: reporting/main_reports02.png
+.. image:: reporting/reporting-aged-payable.png
+   :alt: Aged Payable report in Odoo.

 .. _reporting/aged-receivable:

 Aged Receivable
 ---------------

-The **Aged Receivables** report shows the sales invoices that were awaiting
-payment during a selected month and several months prior.
+The **Aged Receivables** report shows the sales invoices awaiting payment during a selected month
+and several months prior.

-.. image:: reporting/main_reports07.png
+.. image:: reporting/reporting-aged-receivable.png
+   :alt: Aged Receivable report in Odoo.
+
+.. _reporting/cash-flow-statement:

 Cash Flow Statement
 -------------------

-The **Cash Flow Statement** shows how changes in balance sheet accounts and
-income affect cash and cash equivalents, and breaks the analysis down to
-operating, investing and financing activities.
+The **Cash Flow Statement** shows how changes in balance sheet accounts and income affect cash and
+cash equivalents and breaks the analysis down to operating, investing, and financing activities.

-.. image:: reporting/main_reports03.png
+.. image:: reporting/reporting-cash-flow-statement.png
+   :alt: Cash Flow Statement report in Odoo.

 .. _reporting/tax-report:

 Tax Report
 ----------

-This report allows you to see the **net** and **tax amounts** for all the taxes
-grouped by type (sale/purchase).
+This report allows you to see the **net** and **tax amounts** for all the taxes grouped by type
+(sale/purchase).

-.. image:: reporting/main_reports04.png
-
-Bank Reconciliation
-------------------
-
-.. image:: reporting/main_reports06.png
+.. image:: reporting/reporting-tax-report.png
+   :alt: Tax report in Odoo.

 .. toctree::
   :titlesonly:
@@ -17,6 +17,9 @@ collects data on:
   legislation <http://data.europa.eu/eli/reg/2019/2152/2022-01-01>`_, preferring instead
   *intra-Union trade in goods statistics*.

+.. seealso::
+   :doc:`../customer_invoices/incoterms`
+
 .. _intrastat/general-configuration:

 General configuration
@@ -23,12 +23,12 @@ Odoo API key
 ------------

 You can create Odoo external API keys either :ref:`for a single database <silverfin/api-singledb>`
-(hosting: Odoo Online, On-premise, and Odoo.sh) or :ref:`for multiple databases managed by a user
+(hosting: Odoo Online, On-premise, and Odoo.sh) or :ref:`for all databases managed by a single user
 <silverfin/api-multipledb>` (hosting: Odoo Online).

 .. important::
   - These API keys are personal and provide full access to your user account. Store it securely.
-   - You can copy the API key only at its creation, and you cannot retrieve it later.
+   - You can copy the API key only at its creation. It is not possible to retrieve it later.
   - If you need it again, create a new API key (and delete the old one).

 .. seealso::
@@ -36,15 +36,15 @@ You can create Odoo external API keys either :ref:`for a single database <silver

 .. _silverfin/api-singledb:

-One key per database
-~~~~~~~~~~~~~~~~~~~~
+Per database
+~~~~~~~~~~~~

-To create a new API key valid for a single database, click on the user menu, then on
-:guilabel:`My Profile`. Under the :guilabel:`Account Security` tab, click on :guilabel:`New API
-key`, confirm your password, give a descriptive name to your new key, and copy the new API key.
+To add an API key to a **single** database, connect to the database, enable the :ref:`developer
+mode <developer-mode>`, click on the user menu, and then :guilabel:`My Profile` /
+:guilabel:`Preferences`. Under the :guilabel:`Account Security` tab, click on :guilabel:`New API
+Key`, confirm your password, give a descriptive name to your new key, and copy the API key.

 .. image:: silverfin/api-key-db.png
-   :align: center
   :alt: creation of an Odoo external API key for a database

 .. seealso::
@@ -52,15 +52,18 @@ key`, confirm your password, give a descriptive name to your new key, and copy t

 .. _silverfin/api-multipledb:

-One key for multiple databases (fiduciaries)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+For all databases (fiduciaries)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-To create a new API key valid for all the databases of a single user **(the easiest for
-fiduciaries)**, navigate to `Odoo's website <https://www.odoo.com>`_  and sign in with your
-administrator account. Next, open `your account security settings in developer mode
+To add an API key to **all** databases managed by a single user at the same time **(the easiest
+method for fiduciaries)**, navigate to `Odoo's website <https://www.odoo.com>`_  and sign in with
+your administrator account. Next, open `your account security settings in developer mode
 <https://www.odoo.com/my/security?debug=1>`_, click on :guilabel:`New API Key`, confirm your
 password, give a descriptive name to your new key, and copy the new API key.

+.. tip::
+   Open the `database manager <https://www.odoo.com/my/databases>`_ to view all databases that will
+   be linked to the single API key.
+
 .. image:: silverfin/api-key-user.png
-   :align: center
   :alt: creation of an Odoo external API key for an Odoo user
@@ -3,109 +3,114 @@ Fiscal positions (tax and account mapping)
 ==========================================

 Default taxes and accounts are set on products and customers to create new transactions on the fly.
-However, you might have to use different taxes and record the transactions on different accounts,
-according to your customers' and providers' localizations and business types.
+However, depending on the customers' and providers' localization and business type, using different
+taxes and accounts for a transaction might be necessary.

-**Fiscal Positions** allow you to create *sets of rules* to automatically adapt the taxes and the
-accounts used for a transaction.
+**Fiscal positions** allow the creation of rules to adapt the taxes and accounts used for a
+transaction automatically.

-.. image:: fiscal_positions/fiscal-positions-intra-community.png
-   :align: center
-   :alt: Example: Belgian to Intra-Community tax mapping with Fiscal Positions in Odoo Accounting
-
-They can be applied in various ways:
-
- :ref:`automatically applied, based on some rules <fiscal_positions/automatic>`
- :ref:`manually applied on a transaction <fiscal_positions/partner>`
- :ref:`assigned to a partner, on its contact form <fiscal_positions/transaction>`
+They can be applied :ref:`automatically <fiscal_positions/automatic>`, :ref:`manually
+<fiscal_positions/manual>`, or :ref:`assigned to a partner <fiscal_positions/partner>`.

 .. note::
-   A few Fiscal Positions are already preconfigured on your database, as part of your :ref:`fiscal
-   localization package <fiscal_localizations/packages>`.
+   Several default fiscal positions are available as part of your :ref:`fiscal localization
+   package <fiscal_localizations/packages>`.

 Configuration
 =============

-Tax and Account Mapping
+ .. _fiscal_positions/mapping:
+
+Tax and account mapping
 -----------------------

-To edit or create a Fiscal Position, go to :menuselection:`Accounting --> Configuration --> Fiscal
-Positions`, and open the entry you want to modify or click on *Create*.
+To edit or create a fiscal position, go to :menuselection:`Accounting --> Configuration --> Fiscal
+Positions`, and open the entry to modify or click on :guilabel:`New`.

 The mapping of taxes and accounts is based on the default taxes and accounts defined in the
-products' forms.
+product form.

- To map to another tax or account, fill out the right column (**Tax to Apply**/**Account to Use
-  Instead**).
- To remove a tax, rather than replacing it with another, leave the field **Tax to Apply** empty.
- To replace a tax with multiple other taxes, add multiple lines with the same **Tax on Product**.
+- To map to another tax or account, fill out the right column (:guilabel:`Tax to Apply`/
+  :guilabel:`Account to Use Instead`).
+
+.. image:: fiscal_positions/fiscal-positions-tax-mapping.png
+   :align: center
+   :alt: Example of a fiscal position's tax mapping
+
+.. image:: fiscal_positions/fiscal-positions-account-mapping.png
+   :align: center
+   :alt: Example of a fiscal position's account mapping
+
+- To remove a tax, leave the field :guilabel:`Tax to Apply` empty.
+- To replace a tax with several other taxes, add multiple lines using the same :guilabel:`Tax on
+  Product`.

 .. note::
   The mapping only works with *active* taxes. Therefore, make sure they are active by going to
   :menuselection:`Accounting --> Configuration --> Taxes`.

+Application
+===========
+
 .. _fiscal_positions/automatic:

 Automatic application
 ---------------------

-You can configure your Fiscal Positions to be applied automatically, following a set of conditions.
+To automatically apply a fiscal position following a set of conditions, go to
+:menuselection:`Accounting --> Configuration --> Fiscal Positions`, open the fiscal position to
+modify, and tick :guilabel:`Detect Automatically`.

-To do so, open the Fiscal Position you want to modify and click on **Detect Automatically**. You can
-configure a few conditions:
+From there, several conditions can be activated:

- **VAT Required**: The VAT number *must* be indicated in the customer's contact form.
- **Country Group** / **Country**: The Fiscal Position is applied to these countries.
+- :guilabel:`VAT Required`: the customer's VAT number must be present on their contact form.
+- :guilabel:`Country Group` and :guilabel:`Country`: the fiscal position is only applied to the
+  selected country or country group.

 .. image:: fiscal_positions/fiscal-positions-automatic.png
   :align: center
-   :alt: Example of settings to apply a Fiscal Position automatically
+   :alt: Example of a fiscal position automatic application settings

 .. note::
-   Taxes on **eCommerce orders** are automatically updated once the visitor has logged in or filled
+   Taxes on **eCommerce orders** are automatically updated once the customer has logged in or filled
   out their billing details.

 .. important::
-   The Fiscal Positions' **sequence** - the order in which they are arranged - defines which
-   Fiscal Position to apply if the conditions are met in multiple Fiscal Positions.
+   The fiscal positions' **sequence** defines which fiscal position is applied if all conditions
+   set on multiple fiscal positions are met simultaneously.

-   For example, if the first Fiscal Position targets *country A*, and the second Fiscal Position
-   targets a *Country Group* that also comprises *country A*, only the first Fiscal Position will be
-   applied to customers from *country A*.
+   For example, suppose the first fiscal position in a sequence targets *country A* while the second
+   fiscal position targets a *country group* that comprises *country A*. In that case, only the
+   first fiscal position will be applied to customers from *country A*.

-.. _fiscal_positions/application:
+.. _fiscal_positions/manual:

-Application
-===========
+Manual application
+------------------
+
+To manually select a fiscal position, open a sales order, invoice, or bill, go to the
+:guilabel:`Other Info` tab and select the desired :guilabel:`Fiscal Position` before adding product
+lines.
+
+.. image:: fiscal_positions/fiscal-positions-manual.png
+   :align: center
+   :alt: Selection of a fiscal position on a sales order, invoice, or bill

 .. _fiscal_positions/partner:

-Assign a Fiscal Position to a partner
-------------------------------------
+Assign to a partner
+-------------------

-You can manually define which Fiscal Position must be used by default for a specific partner.
+To define which fiscal position must be used by default for a specific partner, go to
+:menuselection:`Accounting --> Customers --> Customers`, select the partner, open the
+:guilabel:`Sales & Purchase` tab, and select the :guilabel:`Fiscal Position`.

-To do so, open the partner's contact form, go to the **Sales & Purchase** tab, edit the **Fiscal
-Position** field, and click on *Save*.
-
-.. image:: fiscal_positions/fiscal-positions-partner.png
+.. image:: fiscal_positions/fiscal-positions-customer.png
   :align: center
-   :alt: Selection of a Fiscal Position on a Sales Order / Invoice / Bill in Odoo Accounting
-
-.. _fiscal_positions/transaction:
-
-Choose Fiscal Positions manually on Sales Orders, Invoices, and Bills
---------------------------------------------------------------------
-
-To manually select which Fiscal Position to use for a new Sales Order, Invoice, or Bill, go to the
-**Other Info** tab and select the right **Fiscal Position** *before* adding product lines.
-
-.. image:: fiscal_positions/fiscal-positions-transaction.png
-   :align: center
-   :alt: Selection of a Fiscal Position on a Sales Order / Invoice / Bill in Odoo Accounting
+   :alt: Selection of a fiscal position on a customer

 .. seealso::

  * :doc:`../taxes`
-  * :doc:`taxcloud` (decommissioning TaxCloud integration in Odoo 17+)
+  * :doc:`taxcloud`
  * :doc:`B2B_B2C`
@@ -4,15 +4,16 @@ Colombia

 .. |DIAN| replace:: :abbr:`DIAN (Dirección de Impuestos y Aduanas Nacionales)`

-Odoo's Colombian localization package provides accounting, fiscal and legal features in Colombia
-such as chart of accounts, taxes and electronic invoicing.
+Odoo's Colombian localization package provides accounting, fiscal, and legal features for databases
+in Colombia – such as chart of accounts, taxes, and electronic invoicing.

-In addition, we have a series of videos covering how to start from scratch, configuration, main
-workflows, and specific use cases.
+In addition, a series of videos on the subject is also available. These videos cover how to start
+from scratch, set up configurations, complete common workflows, and provide in-depth looks at some
+specific use cases as well.

 .. seealso::
-   `Odoo Colombian localization videos
-   <https://www.youtube.com/playlist?list=PL1-aSABtP6ABxZshems3snMjx7bj_7ZsZ>`_.
+   `Smart Tutorial - Colombian Localization
+   <https://www.odoo.com/slides/smart-tutorial-localizacion-de-colombia-132>`_.

 .. _colombia/configuration:

@@ -36,74 +37,78 @@ localization:
     - `l10n_co`
     - Default :ref:`fiscal localization package <fiscal_localizations/packages>`. This module adds
       the base accounting features for the Colombian localization: chart of accounts, taxes,
-       withholdings, identification document type.
+       withholdings, and identification document type.
   * - :guilabel:`Colombian - Accounting Reports`
     - `l10n_co_reports`
     - Includes accounting reports for sending certifications to suppliers for withholdings applied.
   * - :guilabel:`Electronic invoicing for Colombia with Carvajal`
     - `l10n_co_edi`
-     - This module includes the features that are required for the integration with Carvajal and
-       generates the electronic invoices and support document related to the vendor bills based on
+     - This module includes the features required for integration with Carvajal, and
+       generates the electronic invoices and support documents related to the vendor bills, based on
       |DIAN| regulations.
   * - :guilabel:`Colombian - Point of Sale`
     - `l10n_co_pos`
-     - Includes Point of Sale Receipt for Colombian Localization.
+     - Includes Point of Sale receipts for Colombian localization.

 .. note::
-   When a database is created from scratch selecting :guilabel:`Colombia` as the country, Odoo
-   automatically installs the base modules *Colombia - Accounting* and *Colombia - Accounting
-   Reports*.
+   When `Colombia` is selected for a company's :guilabel:`Fiscal Localization`, Odoo automatically
+   installs certain modules.

 Company configuration
 ---------------------

-To configure your company information, go to the :menuselection:`Contacts` app and search for your
-company. Alternatively, activate :ref:`developer mode <developer-mode>` and navigate to
+To configure your company information, go to the :menuselection:`Contacts` app, and search for your
+company.
+
+Alternatively, activate :ref:`developer mode <developer-mode>` and navigate to
 :menuselection:`General Setting --> Company --> Update Info --> Contact`. Then, edit the contact
-form to configure the following information:
+form and configure the following information:

 - :guilabel:`Company Name`.
- :guilabel:`Address`: Including :guilabel:`City`, :guilabel:`Department` and :guilabel:`Zip Code`.
- :guilabel:`Tax ID`: When it is a `NIT`, it must have the *verification digit* at the end of the ID
-  followed by a hyphen (`-`).
+- :guilabel:`Address`: Including :guilabel:`City`, :guilabel:`Department` and :guilabel:`ZIP` code.
+- :guilabel:`Identification Number`: Select the :guilabel:`Identification Type` (`NIT`, `Cédula de
+  Ciudadanía`, `Registro Civil`, etc.). When the :guilabel:`Identification Type` is `NIT`, the
+  :guilabel:`Identification Number` **must** have the *verification digit* at the end of the ID
+  prefixed by a hyphen (`-`).

 Next, configure the :guilabel:`Fiscal Information` in the :guilabel:`Sales & Purchase` tab:

 - :guilabel:`Obligaciones y Responsabilidades`: Select the fiscal responsibility for the company
-  (:guilabel:`O-13` Gran Contribuyente, :guilabel:`O-15` Autorretenedor, :guilabel:`O-23` Agente de
-  retención IVA, :guilabel:`O-47` Regimen de tributación simple, :guilabel:`R-99-PN` No Aplica).
+  (`O-13` Gran Contribuyente, `O-15` Autorretenedor, `O-23` Agente de retención IVA, `O-47` Regimen
+  de tributación simple, `R-99-PN` No Aplica).
 - :guilabel:`Gran Contribuyente`: If the company is *Gran Contribuyente* this option should be
  selected.
- :guilabel:`Fiscal Regimen`: Select the Tribute Name for the company (:guilabel:`IVA`,
-  :guilabel:`INC`, :guilabel:`IVA e INC`, :guilabel:`No Aplica`)
+- :guilabel:`Fiscal Regimen`: Select the Tribute Name for the company (`IVA`, `INC`, `IVA e INC`,
+  or `No Aplica`)
 - :guilabel:`Commercial Name`: If the company uses a specific commercial name, and it needs to be
  displayed in the invoice.

 Carjaval credentials configuration
 ----------------------------------

-Once the modules installed, the user credentials must be configured in order to connect with
-Carvajal Web Service. Navigate to :menuselection:`Accounting --> Configuration --> Settings` and
-scroll to the :guilabel:`Colombian Electronic Invoicing` section. Then, fill in the required
-configuration information provided by Carvajal:
+Once the modules are installed, the user credentials **must** be configured, in order to connect
+with Carvajal Web Service. To do so, navigate to :menuselection:`Accounting --> Configuration -->
+Settings` and scroll to the :guilabel:`Colombian Electronic Invoicing` section. Then, fill in the
+required configuration information provided by Carvajal:

- :guilabel:`Username` and :guilabel:`Password`: Correspond to the username and password provided
-  by Carvajal to the company.
+- :guilabel:`Username` and :guilabel:`Password`: Username and password (provided by Carvajal) to the
+  company.
 - :guilabel:`Company Registry`: Company's NIT number *without* the verification code.
- :guilabel:`Account ID`: Company ID followed by `_01`.
- :guilabel:`Colombia Template Code`: Select one of the two available templates (:guilabel:`CGEN03`
-  or :guilabel:`CGNE04`) to be used in the PDF format of the electronic invoice.
+- :guilabel:`Account ID`: Company's NIT number followed by `_01`.
+- :guilabel:`Colombia Template Code`: Select one of the two available templates (`CGEN03` or
+  `CGNE04`) to be used in the PDF format of the electronic invoice.
+
+Enable the :guilabel:`Test mode` checkbox to connect with the Carvajal testing environment.
+
+Once Odoo and Carvajal are fully configured and ready for production, deactivate the :guilabel:`Test
+mode` checkbox to use the production database.

 .. image:: colombia/carvajal-configuration.png
+   :align: center
   :alt: Configure credentials for Carvajal web service in Odoo.

-.. note::
-   Check the :guilabel:`Test mode` checkbox to connect with the Carvajal testing environment. Once
-   Odoo and Carvajal are fully configured and ready for production, uncheck the :guilabel:`Test
-   mode` checkbox to use the production database.
-
 .. important::
-   :guilabel:`Test mode` must be used **only** on replicated databases, **not** the production
+   :guilabel:`Test mode` must **only** be used on duplicated databases, **not** the production
   environment.

 Report data configuration
@@ -112,8 +117,17 @@ Report data configuration
 Report data can be defined for the fiscal section and bank information of the PDF as part of the
 configurable information sent in the XML.

-Navigate to :menuselection:`Accounting --> Configuration --> Settings` and scroll to the
-:guilabel:`Colombian Electronic Invoicing` section.
+Navigate to :menuselection:`Accounting --> Configuration --> Settings`, and scroll to the
+:guilabel:`Colombian Electronic Invoicing` section, in order to find the :guilabel:`Report
+Configuration` fields. Here the header information for each report type can be configured.
+
+- :guilabel:`Gran Contribuyente`
+- :guilabel:`Tipo de Régimen`
+- :guilabel:`Retenedores de IVA`
+- :guilabel:`Autorretenedores`
+- :guilabel:`Resolución Aplicable`
+- :guilabel:`Actividad Económica`
+- :guilabel:`Bank Information`

 .. _colombia/master-data:

@@ -123,67 +137,85 @@ Master data configuration
 Partner
 ~~~~~~~

+Partner contacts can be created in the *Contacts* app. To do so, navigate to
+:menuselection:`Contacts`, and click the :guilabel:`Create` button.
+
+Then, name the contact, and using the radio buttons, select the contact type, either
+:guilabel:`Individual` or :guilabel:`Company`.
+
+Complete the full :guilabel:`Address`, including the :guilabel:`City`, :guilabel:`State`, and
+:guilabel:`ZIP` code. Then, complete the identification and fiscal information.
+
 Identification information
 **************************

-Document types defined by the |DIAN| are available on the partner form as part of the Colombian
-localization. Colombian partners must have their :guilabel:`Identification Number` (VAT) and
-:guilabel:`Document Type` set.
+Identification types, defined by the |DIAN|, are available on the partner form, as part of the
+Colombian localization. Colombian partners **must** have their :guilabel:`Identification Number`
+(VAT) and :guilabel:`Document Type` set.

 .. tip::
   When the :guilabel:`Document Type` is `NIT`, the :guilabel:`Identification Number` needs to be
-   configured in Odoo, including the *verification digit*; Odoo splits this number when the data to
-   is sent to the third party.
+   configured in Odoo, including the *verification digit at the end of the ID, prefixed by a hyphen
+   (`-`)*.

 Fiscal information
 ******************

-The partner's responsibility codes (section 53 in the RUT document) are included as part of the
-electronic invoicing module, as it is required by the |DIAN|.
+The partner's responsibility codes (section 53 in the :abbr:`RUT (Registro único tributario)`
+document) are included as part of the electronic invoicing module, as it is required by the |DIAN|.

 The required fields can be found under :menuselection:`Partner --> Sales & Purchase Tab --> Fiscal
-Information`:
+Information section`:

 - :guilabel:`Obligaciones y Responsabilidades`: Select the fiscal responsibility for the company
-  (:guilabel:`O-13` Gran Contribuyente, :guilabel:`O-15` Autorretenedor, :guilabel:`O-23` Agente de
-  retención IVA, :guilabel:`O-47` Regimen de tributación simple, :guilabel:`R-99-PN` No Aplica).
+  (`O-13` Gran Contribuyente, `O-15` Autorretenedor, `O-23` Agente de retención IVA, `O-47` Regimen
+  de tributación simple, or `R-99-PN` No Aplica).
 - :guilabel:`Gran Contribuyente`: If the company is *Gran Contribuyente* this option should be
  selected.
- :guilabel:`Fiscal Regimen`: Select the Tribute Name for the company (:guilabel:`IVA`,
-  :guilabel:`INC`, :guilabel:`IVA e INC`, :guilabel:`No Aplica`)
+- :guilabel:`Fiscal Regimen`: Select the tribute name for the company (`IVA`, `INC`, `IVA e INC`, or
+  `No Aplica`)
 - :guilabel:`Commercial Name`: If the company uses a specific commercial name, and it needs to be
  displayed in the invoice.

 Products
 ~~~~~~~~

-In addition to adding general information (in the :guilabel:`General Information` tab) on the
-product form, either the :guilabel:`UNSPSC Category`, :guilabel:`Barcode`, or :guilabel:`Internal
-Reference` field must also be configured.
+To manage products, navigate to :menuselection:`Accounting --> Customers --> Products`, then click
+on a product.
+
+When adding general information on the product form, it is required that either the
+:guilabel:`UNSPSC Category` (:guilabel:`Accounting` tab), or :guilabel:`Internal Reference`
+(:guilabel:`General Information` tab) field is configured. Be sure to :guilabel:`Save` the product
+once configured.

 Taxes
 ~~~~~

-If sales transactions include products with taxes, the :guilabel:`Value Type` field in the
-:guilabel:`Advanced Options` tab needs to be configured per tax. To do so, go to
-:menuselection:`Accounting --> Configuration --> Taxes`, and select the related tax.
+To create or modify taxes, go to :menuselection:`Accounting --> Configuration --> Taxes`, and select
+the related tax.

-Retention tax types (:guilabel:`ICA`, :guilabel:`IVA`, :guilabel:`Fuente`) are also included. This
-configuration is used to display taxes in the invoice PDF correctly.
+If sales transactions include products with taxes, the :guilabel:`Value Type` field in the
+:guilabel:`Advanced Options` tab needs to be configured per tax. Retention tax types
+(:guilabel:`ICA`, :guilabel:`IVA`, :guilabel:`Fuente`) are also included. This configuration is used
+to display taxes correctly in the invoice PDF.

 .. image:: colombia/retention-tax-types.png
+   :align: center
   :alt: The ICA, IVA and Fuente fields in the Advanced Options tab in Odoo.

+.. _co-journals:
+
 Sales journals
 ~~~~~~~~~~~~~~

-.. _co-journals:
-
 Once the |DIAN| has assigned the official sequence and prefix for the electronic invoice resolution,
-the sales journals related to the invoice documents must be updated in Odoo. To do so, navigate to
-:menuselection:`Accounting --> Configuration --> Journals`.
+the sales journals related to the invoice documents **must** be updated in Odoo. To do so, navigate
+to :menuselection:`Accounting --> Configuration --> Journals`, and select an existing sales journal,
+or create a new one with the :guilabel:`Create` button.

-Configure the following data in the :guilabel:`Advanced Settings` tab:
+On the sales journal form, input the :guilabel:`Journal Name`, :guilabel:`Type`, and set a unique
+:guilabel:`Short Code` in the :guilabel:`Journals Entries` tab. Then, configure the following data
+in the :guilabel:`Advanced Settings` tab:

 - :guilabel:`Electronic invoicing`: Enable :guilabel:`UBL 2.1 (Colombia)`.
 - :guilabel:`Invoicing Resolution`: Resolution number issued by |DIAN| to the company.
@@ -193,32 +225,31 @@ Configure the following data in the :guilabel:`Advanced Settings` tab:
 - :guilabel:`Range of Numbering (maximum)`: Last authorized invoice number.

 .. note::
-   The sequence and resolution of the journal must match the one configured in Carvajal and the
+   The sequence and resolution of the journal **must** match the one configured in Carvajal and the
   |DIAN|.

 Invoice sequence
 ****************

-The invoice sequence and prefix must be correctly configured when the first document is created.
+The invoice sequence and prefix **must** be correctly configured when the first document is created.

 .. note::
-   Odoo automatically assigns a prefix and sequence to the following documents.
+   Odoo automatically assigns a prefix and sequence to the following invoices.

 Purchase journals
 *****************

-Once the |DIAN| has assigned the official sequence and prefix for the support document related to
+Once the |DIAN| has assigned the official sequence and prefix for the *support document* related to
 vendor bills, the purchase journals related to their supporting documents need to be updated in
 Odoo. The process is similar to the configuration of the :ref:`sales journals <co-journals>`.

 Chart of accounts
 *****************

-The :doc:`chart of accounts
-</applications/finance/accounting/get_started/chart_of_accounts>` is installed by default as part of
-the localization module, the accounts are mapped automatically in taxes, default account payable,
-and default account receivable. The chart of accounts for Colombia is based on the PUC (Plan Unico
-de Cuentas).
+The :doc:`chart of accounts </applications/finance/accounting/get_started/chart_of_accounts>` is
+installed by default as part of the localization module, the accounts are mapped automatically in
+taxes, default account payable, and default account receivable. The chart of accounts for Colombia
+is based on the PUC (Plan Unico de Cuentas).

 .. _colombia/workflows:

@@ -228,18 +259,38 @@ Main workflows
 Electronic invoices
 -------------------

+The following is a breakdown of the main workflow for electronic invoices with the Colombian
+localization:
+
+#. Sender creates an invoice.
+#. Electronic invoice provider generates the legal XML file.
+#. Electronic invoice provider creates the CUFE (Invoice Electronic Code) with the electronic
+   signature.
+#. Electronic invoice provider sends a notification to |DIAN|.
+#. |DIAN| validates the invoice.
+#. |DIAN| accepts or rejects the invoice.
+#. Electronic invoice provider generates the PDF invoice with a QR code.
+#. Electronic invoice provider sends invoice to the acquirer.
+#. Acquirer sends a receipt of acknowledgement, and accepts or rejects the invoice.
+#. Sender downloads a :file:`.zip` file with the PDF and XML.
+
+.. image:: colombia/workflow-electronic-invoice.png
+   :align: center
+   :alt: Electronic invoice workflow for Colombian localization.
+
 .. _colombia/invoice-creation:

 Invoice creation
 ~~~~~~~~~~~~~~~~

 .. note::
-   The functional workflow taking place before an invoice validation does not alter the main changes
-   introduced with the electronic invoice.
+   The functional workflow taking place before an invoice validation does **not** alter the main
+   changes introduced with the electronic invoice.

 Electronic invoices are generated and sent to both the |DIAN| and customer through Carvajal's web
-service integration. These documents can be created from your sales order or manually. Go to
-:menuselection:`Accounting --> Customers --> Invoices` and configure:
+service integration. These documents can be created from your sales order or manually generated. To
+create a new invoice, go to :menuselection:`Accounting --> Customers --> Invoices`, and select
+:guilabel:`Create`. On the invoice form configure the following fields:

 - :guilabel:`Customer`: Customer's information.
 - :guilabel:`Journal`: Journal used for electronic invoices.
@@ -259,9 +310,10 @@ invoice is then processed asynchronously by the E-invoicing service UBL 2.1 (Col
 also displayed in the chatter.

 .. image:: colombia/invoice-sent.png
+   :align: center
   :alt: Carvajal XML invoice file in Odoo chatter.

-The :guilabel:`Electronic Invoice Name` field is now displayed in the :guilabel:`EDI Documents` tab
+The :guilabel:`Electronic Invoice Name` field is now displayed in the :guilabel:`EDI Documents` tab,
 with the name of the XML file. Additionally, the :guilabel:`Electronic Invoice Status` field is
 displayed with the initial value :guilabel:`To Send`. To process the invoice manually, click on the
 :guilabel:`Process Now` button.
@@ -271,7 +323,7 @@ displayed with the initial value :guilabel:`To Send`. To process the invoice man
 Reception of legal XML and PDF
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-The electronic invoice vendor (Carvajal) receives the XML file and proceeds to validate its
+The electronic invoice vendor (Carvajal) receives the XML file, and proceeds to validate its
 structure and information.

 After validating the electronic invoice, proceed to generate a legal XML which includes a digital
@@ -279,10 +331,11 @@ signature and a unique code (CUFE), a PDF invoice that includes a QR code and th
 generated. If everything is correct the :guilabel:`Electronic Invoicing` field value changes to
 :guilabel:`Sent`.

-A ZIP containing the legal electronic invoice in XML format and the invoice in PDF format is
-downloaded and displayed in the invoice chatter:
+A :file:`.zip` containing the legal electronic invoice (in XML format) and the invoice in (PDF
+format) is downloaded and displayed in the invoice chatter:

 .. image:: colombia/invoice-zip.png
+   :align: center
   :alt: ZIP file displayed in the invoice chatter in Odoo.

 The electronic invoice status changes to :guilabel:`Accepted`.
@@ -292,7 +345,7 @@ Credit notes

 The process for credit notes is the same as for invoices. To create a credit note with reference to
 an invoice, go to :menuselection:`Accounting --> Customers --> Invoices`. On the invoice, click
-:guilabel:`Add Credit Note` and complete the following information:
+:guilabel:`Add Credit Note`, and complete the following information:

 - :guilabel:`Credit Method`: Select the type of credit method.

@@ -316,7 +369,7 @@ Debit notes

 The process for debit notes is similar to credit notes. To create a debit note with reference to an
 invoice, go to :menuselection:`Accounting --> Customers --> Invoices`. On the invoice, click the
-:guilabel:`Add Debit Note` button and complete the following information:
+:guilabel:`Add Debit Note` button, and enter the following information:

 - :guilabel:`Reason`: Type the reason for the debit note.
 - :guilabel:`Debit note date`: Select the specific options.
@@ -331,7 +384,7 @@ Support document for vendor bills
 ---------------------------------

 With master data, credentials, and the purchase journal configured for support documents related to
-vendor bills, you can start using support documents.
+vendor bills, you can start using *support documents*.

 Support documents for vendor bills can be created from your purchase order or manually. Go to
 :menuselection:`Accounting --> Vendors --> Bills` and fill in the following data:
@@ -372,6 +425,7 @@ Commerce (ICA) tax. The report can be found under :menuselection:`Accounting -->
 Colombian Statements --> Certificado de Retención en ICA`.

 .. image:: colombia/ica-report.png
+   :align: center
   :alt: Certificado de Retención en ICA report in Odoo Accounting.

 Certificado de Retención en IVA
@@ -382,6 +436,7 @@ can be found under :menuselection:`Accounting --> Reporting --> Colombian Statem
 de Retención en IVA`.

 .. image:: colombia/iva-report.png
+   :align: center
   :alt: Certificado de Retención en IVA report in Odoo Accounting.

 Certificado de Retención en la Fuente
@@ -392,4 +447,5 @@ be found under :menuselection:`Accounting --> Reporting --> Colombian Statements
 Retención en Fuente`.

 .. image:: colombia/fuente-report.png
+   :align: center
   :alt: Certificado de Retención en Fuente report in Odoo Accounting.
--- a/Show More
+++ b/Show More