From adda59fe7f61a07ef796b4ea35e3000f582028ac Mon Sep 17 00:00:00 2001
From: Tobias Brunner <tobias.brunner@vshn.ch>
Date: Thu, 5 Jun 2025 10:58:12 +0200
Subject: [PATCH] add billing entity docs

---
 docs/modules/ROOT/nav.adoc                    |  1 +
 .../ROOT/pages/web-portal-billingentity.adoc  | 26 +++++++++++++++++++
 src/servala/core/models/organization.py       |  2 +-
 3 files changed, 28 insertions(+), 1 deletion(-)
 create mode 100644 docs/modules/ROOT/pages/web-portal-billingentity.adoc

diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index 447852e..cff0b83 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -4,6 +4,7 @@
 * xref:web-portal.adoc[]
 ** xref:web-portal-admin.adoc[Admin]
 ** xref:web-portal-controlplanes.adoc[Control-Planes]
+** xref:web-portal-billingentity.adoc[Billing Entities]
 
 * xref:web-portal-planning.adoc[]
 ** xref:user-stories.adoc[]
diff --git a/docs/modules/ROOT/pages/web-portal-billingentity.adoc b/docs/modules/ROOT/pages/web-portal-billingentity.adoc
new file mode 100644
index 0000000..cd7b662
--- /dev/null
+++ b/docs/modules/ROOT/pages/web-portal-billingentity.adoc
@@ -0,0 +1,26 @@
+= Web Portal Billing Entities
+
+Billing entities are used to connect an invoice address in Odoo to an organization in Servala.
+
+When creating a new organization, the billing information is required to be added.
+
+== Existing Billing Address
+
+With the email address of the currently logged-in user, Odoo is searched for existing `res.partner` records and presented in the dropdown.
+
+Search is done this way:
+
+* `res.partner` records created by a matching Odoo user.
+* User email matches an invoice address or contact address
+
+== New Billing Address
+
+When choosing to add a new billing address, two new records are created in the Odoo `res.partner` model:
+
+* A record with the field `company_type = company`
+* A record with the following field configuration:
+** `company_type = person`
+** `type = invoice`
+** `parent_id = company_id`
+
+The resulting database IDs are stored in the Servala portal database for referencing the records in Odoo.
diff --git a/src/servala/core/models/organization.py b/src/servala/core/models/organization.py
index 80e2d9e..8625203 100644
--- a/src/servala/core/models/organization.py
+++ b/src/servala/core/models/organization.py
@@ -148,7 +148,7 @@ class BillingEntity(ServalaModelMixin, models.Model):
     # Odoo IDs are nullable for creation, should never be null in practice
     # The company ID points at a record of type res.partner with company_type=company
     # The invoice ID points at a record of type res.partner with company_type=person,
-    # type=invoic, parent_id=company_id (the invoice address).
+    # type=invoice, parent_id=company_id (the invoice address).
     odoo_company_id = models.IntegerField(null=True)
     odoo_invoice_id = models.IntegerField(null=True)