[17.0][IMP] sale_advance_payment: option to allow overpayments

sale_advance_payment/README.rst

@@ -1,7 +1,3 @@
-.. image:: https://odoo-community.org/readme-banner-image
-   :target: https://odoo-community.org/get-involved?utm_source=readme
-   :alt: Odoo Community Association
-
 ====================
 Sale Advance Payment
 ====================
@@ -17,7 +13,7 @@ Sale Advance Payment
 .. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
     :target: https://odoo-community.org/page/development-status
     :alt: Beta
-.. |badge2| image:: https://img.shields.io/badge/license-AGPL--3-blue.png
+.. |badge2| image:: https://img.shields.io/badge/licence-AGPL--3-blue.png
     :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
     :alt: License: AGPL-3
 .. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fsale--workflow-lightgray.png?logo=github
@@ -35,6 +31,12 @@ Sale Advance Payment
 The module allows to add advance payments on sales and then use them on
 invoices.
 
+Additionally, it provides an optional feature to handle advance payments
+that exceed the order amount. This is particularly useful for e-commerce
+scenarios where tax calculations may differ between the external store
+and Odoo. When enabled, overpayments are partially reconciled, leaving
+the excess amount as customer credit.
+
 **Table of contents**
 
 .. contents::
@@ -45,14 +47,39 @@ Usage
 
 To use this module, you need to:
 
-- Go to a sale order.
-- Click on "Pay Sale Advance".
-- Select the Journal and specify the amount of the advanced payment.
-- "Make Advance Payment".
+-  Go to a sale order.
+-  Click on "Pay Sale Advance".
+-  Select the Journal and specify the amount of the advanced payment.
+-  "Make Advance Payment".
 
 When generating the invoice, the system displays the advanced payments,
 select those you want to add to the invoice.
 
+**Handling Overpayments:**
+
+By default, advance payments that exceed the invoice amount will be
+rejected. To enable partial reconciliation of overpayments:
+
+1. Go to *Settings > General Settings*
+2. Scroll to the *Accounting* section
+3. Check *Allow Advance Payments Exceeding Order Amount*
+4. Save the settings
+
+When enabled, advance payments larger than the order amount will be:
+
+-  Partially reconciled up to the invoice amount
+-  The excess amount remains as customer credit
+-  Useful for e-commerce integrations with tax calculation differences
+
+**Example Scenarios:**
+
+-  **E-commerce Integration**: Customer pays $120 but Odoo calculates
+   $100 due to tax differences
+-  **Prepayments**: Customer pays deposit that exceeds final invoice
+   amount
+-  **Currency Fluctuations**: Payment made in different currency with
+   rate variations
+
 Known issues / Roadmap
 ======================
 
@@ -81,11 +108,11 @@ Authors
 Contributors
 ------------
 
-- Omar Castiñeira Saaevdra <[email protected]>
-- Daniel Reis <[email protected]>
-- Nikul Chaudhary <[email protected]>
-- Manuel Regidor <[email protected]>
-- Urvisha Desai <[email protected]>
+-  Omar Castiñeira Saaevdra <[email protected]>
+-  Daniel Reis <[email protected]>
+-  Nikul Chaudhary <[email protected]>
+-  Manuel Regidor <[email protected]>
+-  Urvisha Desai <[email protected]>
 
 Maintainers
 -----------

sale_advance_payment/__manifest__.py

@@ -14,6 +14,7 @@
         "wizard/sale_advance_payment_wzd_view.xml",
         "views/sale_view.xml",
         "views/account_payment.xml",
+        "views/res_config_settings.xml",
         "security/ir.model.access.csv",
     ],
     "installable": True,

sale_advance_payment/models/__init__.py

@@ -1,3 +1,5 @@
 from . import payment
 from . import sale
 from . import account_move
+from . import res_config_settings
+from . import res_company

sale_advance_payment/models/account_move.py

@@ -7,15 +7,19 @@
 class AccountMove(models.Model):
     _inherit = "account.move"
 
-    def action_post(self):
+    def _post(self, soft=True):
         # Automatic reconciliation of payment when invoice confirmed.
-        res = super().action_post()
-        sale_order = self.mapped("line_ids.sale_line_ids.order_id")
-        if sale_order and self.invoice_outstanding_credits_debits_widget is not False:
-            json_invoice_outstanding_data = (
-                self.invoice_outstanding_credits_debits_widget.get("content", [])
+        res = super()._post(soft=soft)
+        for invoice in self:
+            # Get Advance Payment Account Moves
+            sale_orders = invoice.mapped("line_ids.sale_line_ids.order_id")
+            advance_payment_moves = sale_orders.account_payment_ids.move_id
+            # Get reconcilable payments JSON data
+            widget_json = invoice.invoice_outstanding_credits_debits_widget or {}
+            can_reconcile_lines = filter(
+                lambda x: x.get("move_id") in advance_payment_moves.ids,
+                widget_json.get("content", []),
             )
-            for data in json_invoice_outstanding_data:
-                if data.get("move_id") in sale_order.account_payment_ids.move_id.ids:
-                    self.js_assign_outstanding_line(line_id=data.get("id"))
+            for line in can_reconcile_lines:
+                invoice.js_assign_outstanding_line(line_id=line.get("id"))
         return res

sale_advance_payment/models/res_company.py

@@ -0,0 +1,15 @@
+# Copyright 2025 Open Source Integrators
+# License AGPL-3.0 or later (http://www.gnu.org/licenses/agpl).
+
+from odoo import fields, models
+
+
+class ResCompany(models.Model):
+    _inherit = "res.company"
+
+    allow_advance_overpayment = fields.Boolean(
+        string="Allow Advance Payments Exceeding Order Amount",
+        help="If checked, advance payments larger than the order amount will be "
+        "allowed. Useful for e-commerce scenarios where tax calculations may "
+        "differ between the store and Odoo.",
+    )

sale_advance_payment/models/res_config_settings.py

@@ -0,0 +1,17 @@
+# Copyright 2025 Open Source Integrators
+# License AGPL-3.0 or later (http://www.gnu.org/licenses/agpl).
+
+from odoo import fields, models
+
+
+class ResConfigSettings(models.TransientModel):
+    _inherit = "res.config.settings"
+
+    allow_advance_overpayment = fields.Boolean(
+        string="Allow Advance Payments Exceeding Order Amount",
+        help="If checked, advance payments larger than the order amount will be "
+        "allowed. Useful for e-commerce scenarios where tax calculations may "
+        "differ between the store and Odoo.",
+        related="company_id.allow_advance_overpayment",
+        readonly=False,
+    )

sale_advance_payment/readme/DESCRIPTION.md

@@ -1,2 +1,8 @@
 The module allows to add advance payments on sales and then use them on
 invoices.
+
+Additionally, it provides an optional feature to handle advance payments
+that exceed the order amount. This is particularly useful for e-commerce
+scenarios where tax calculations may differ between the external store
+and Odoo. When enabled, overpayments are partially reconciled, leaving
+the excess amount as customer credit.

sale_advance_payment/readme/USAGE.md

@@ -7,3 +7,24 @@ To use this module, you need to:
 
 When generating the invoice, the system displays the advanced payments,
 select those you want to add to the invoice.
+
+**Handling Overpayments:**
+
+By default, advance payments that exceed the invoice amount will be rejected.
+To enable partial reconciliation of overpayments:
+
+1. Go to *Settings > General Settings*
+2. Scroll to the *Accounting* section
+3. Check *Allow Advance Payments Exceeding Order Amount*
+4. Save the settings
+
+When enabled, advance payments larger than the order amount will be:
+- Partially reconciled up to the invoice amount
+- The excess amount remains as customer credit
+- Useful for e-commerce integrations with tax calculation differences
+
+**Example Scenarios:**
+
+- **E-commerce Integration**: Customer pays $120 but Odoo calculates $100 due to tax differences
+- **Prepayments**: Customer pays deposit that exceeds final invoice amount
+- **Currency Fluctuations**: Payment made in different currency with rate variations

sale_advance_payment/static/description/index.html

@@ -3,7 +3,7 @@
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 <meta name="generator" content="Docutils: https://docutils.sourceforge.io/" />
-<title>README.rst</title>
+<title>Sale Advance Payment</title>
 <style type="text/css">
 
 /*
@@ -360,23 +360,23 @@
 </style>
 </head>
 <body>
-<div class="document">
+<div class="document" id="sale-advance-payment">
+<h1 class="title">Sale Advance Payment</h1>
 
-
-<a class="reference external image-reference" href="https://odoo-community.org/get-involved?utm_source=readme">
-<img alt="Odoo Community Association" src="https://odoo-community.org/readme-banner-image" />
-</a>
-<div class="section" id="sale-advance-payment">
-<h1>Sale Advance Payment</h1>
 <!-- !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !! This file is generated by oca-gen-addon-readme !!
 !! changes will be overwritten.                   !!
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !! source digest: sha256:14d1192bf1791b33d1a15e824c608d675b53b30c405560a19cf213768a3a630f
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -->
-<p><a class="reference external image-reference" href="https://odoo-community.org/page/development-status"><img alt="Beta" src="https://img.shields.io/badge/maturity-Beta-yellow.png" /></a> <a class="reference external image-reference" href="http://www.gnu.org/licenses/agpl-3.0-standalone.html"><img alt="License: AGPL-3" src="https://img.shields.io/badge/license-AGPL--3-blue.png" /></a> <a class="reference external image-reference" href="https://github.com/OCA/sale-workflow/tree/17.0/sale_advance_payment"><img alt="OCA/sale-workflow" src="https://img.shields.io/badge/github-OCA%2Fsale--workflow-lightgray.png?logo=github" /></a> <a class="reference external image-reference" href="https://translation.odoo-community.org/projects/sale-workflow-17-0/sale-workflow-17-0-sale_advance_payment"><img alt="Translate me on Weblate" src="https://img.shields.io/badge/weblate-Translate%20me-F47D42.png" /></a> <a class="reference external image-reference" href="https://runboat.odoo-community.org/builds?repo=OCA/sale-workflow&amp;target_branch=17.0"><img alt="Try me on Runboat" src="https://img.shields.io/badge/runboat-Try%20me-875A7B.png" /></a></p>
+<p><a class="reference external image-reference" href="https://odoo-community.org/page/development-status"><img alt="Beta" src="https://img.shields.io/badge/maturity-Beta-yellow.png" /></a> <a class="reference external image-reference" href="http://www.gnu.org/licenses/agpl-3.0-standalone.html"><img alt="License: AGPL-3" src="https://img.shields.io/badge/licence-AGPL--3-blue.png" /></a> <a class="reference external image-reference" href="https://github.com/OCA/sale-workflow/tree/17.0/sale_advance_payment"><img alt="OCA/sale-workflow" src="https://img.shields.io/badge/github-OCA%2Fsale--workflow-lightgray.png?logo=github" /></a> <a class="reference external image-reference" href="https://translation.odoo-community.org/projects/sale-workflow-17-0/sale-workflow-17-0-sale_advance_payment"><img alt="Translate me on Weblate" src="https://img.shields.io/badge/weblate-Translate%20me-F47D42.png" /></a> <a class="reference external image-reference" href="https://runboat.odoo-community.org/builds?repo=OCA/sale-workflow&amp;target_branch=17.0"><img alt="Try me on Runboat" src="https://img.shields.io/badge/runboat-Try%20me-875A7B.png" /></a></p>
 <p>The module allows to add advance payments on sales and then use them on
 invoices.</p>
+<p>Additionally, it provides an optional feature to handle advance payments
+that exceed the order amount. This is particularly useful for e-commerce
+scenarios where tax calculations may differ between the external store
+and Odoo. When enabled, overpayments are partially reconciled, leaving
+the excess amount as customer credit.</p>
 <p><strong>Table of contents</strong></p>
 <div class="contents local topic" id="contents">
 <ul class="simple">
@@ -392,7 +392,7 @@ <h1>Sale Advance Payment</h1>
 </ul>
 </div>
 <div class="section" id="usage">
-<h2><a class="toc-backref" href="#toc-entry-1">Usage</a></h2>
+<h1><a class="toc-backref" href="#toc-entry-1">Usage</a></h1>
 <p>To use this module, you need to:</p>
 <ul class="simple">
 <li>Go to a sale order.</li>
@@ -402,31 +402,55 @@ <h2><a class="toc-backref" href="#toc-entry-1">Usage</a></h2>
 </ul>
 <p>When generating the invoice, the system displays the advanced payments,
 select those you want to add to the invoice.</p>
+<p><strong>Handling Overpayments:</strong></p>
+<p>By default, advance payments that exceed the invoice amount will be
+rejected. To enable partial reconciliation of overpayments:</p>
+<ol class="arabic simple">
+<li>Go to <em>Settings &gt; General Settings</em></li>
+<li>Scroll to the <em>Accounting</em> section</li>
+<li>Check <em>Allow Advance Payments Exceeding Order Amount</em></li>
+<li>Save the settings</li>
+</ol>
+<p>When enabled, advance payments larger than the order amount will be:</p>
+<ul class="simple">
+<li>Partially reconciled up to the invoice amount</li>
+<li>The excess amount remains as customer credit</li>
+<li>Useful for e-commerce integrations with tax calculation differences</li>
+</ul>
+<p><strong>Example Scenarios:</strong></p>
+<ul class="simple">
+<li><strong>E-commerce Integration</strong>: Customer pays $120 but Odoo calculates
+$100 due to tax differences</li>
+<li><strong>Prepayments</strong>: Customer pays deposit that exceeds final invoice
+amount</li>
+<li><strong>Currency Fluctuations</strong>: Payment made in different currency with
+rate variations</li>
+</ul>
 </div>
 <div class="section" id="known-issues-roadmap">
-<h2><a class="toc-backref" href="#toc-entry-2">Known issues / Roadmap</a></h2>
+<h1><a class="toc-backref" href="#toc-entry-2">Known issues / Roadmap</a></h1>
 <p>Split several computed values in separate fields (mls, advance_amount,
 amount_residual). This allows a better comprehension of logic, and a
 better inheritance possibility.</p>
 </div>
 <div class="section" id="bug-tracker">
-<h2><a class="toc-backref" href="#toc-entry-3">Bug Tracker</a></h2>
+<h1><a class="toc-backref" href="#toc-entry-3">Bug Tracker</a></h1>
 <p>Bugs are tracked on <a class="reference external" href="https://github.com/OCA/sale-workflow/issues">GitHub Issues</a>.
 In case of trouble, please check there if your issue has already been reported.
 If you spotted it first, help us to smash it by providing a detailed and welcomed
 <a class="reference external" href="https://github.com/OCA/sale-workflow/issues/new?body=module:%20sale_advance_payment%0Aversion:%2017.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**">feedback</a>.</p>
 <p>Do not contact contributors directly about support or help with technical issues.</p>
 </div>
 <div class="section" id="credits">
-<h2><a class="toc-backref" href="#toc-entry-4">Credits</a></h2>
+<h1><a class="toc-backref" href="#toc-entry-4">Credits</a></h1>
 <div class="section" id="authors">
-<h3><a class="toc-backref" href="#toc-entry-5">Authors</a></h3>
+<h2><a class="toc-backref" href="#toc-entry-5">Authors</a></h2>
 <ul class="simple">
 <li>Comunitea</li>
 </ul>
 </div>
 <div class="section" id="contributors">
-<h3><a class="toc-backref" href="#toc-entry-6">Contributors</a></h3>
+<h2><a class="toc-backref" href="#toc-entry-6">Contributors</a></h2>
 <ul class="simple">
 <li>Omar Castiñeira Saaevdra &lt;<a class="reference external" href="mailto:omar&#64;comunitea.com">omar&#64;comunitea.com</a>&gt;</li>
 <li>Daniel Reis &lt;<a class="reference external" href="mailto:dreis&#64;opensourceintegrators.com">dreis&#64;opensourceintegrators.com</a>&gt;</li>
@@ -436,7 +460,7 @@ <h3><a class="toc-backref" href="#toc-entry-6">Contributors</a></h3>
 </ul>
 </div>
 <div class="section" id="maintainers">
-<h3><a class="toc-backref" href="#toc-entry-7">Maintainers</a></h3>
+<h2><a class="toc-backref" href="#toc-entry-7">Maintainers</a></h2>
 <p>This module is maintained by the OCA.</p>
 <a class="reference external image-reference" href="https://odoo-community.org">
 <img alt="Odoo Community Association" src="https://odoo-community.org/logo.png" />
@@ -449,6 +473,5 @@ <h3><a class="toc-backref" href="#toc-entry-7">Maintainers</a></h3>
 </div>
 </div>
 </div>
-</div>
 </body>
 </html>

sale_advance_payment/tests/__init__.py

@@ -1 +1,2 @@
 from . import test_sale_advance_payment
+from . import test_advance_overpayment