feat(invoice): Store customer-specific invoice numbering on customer

When switching between org and customer invoice numbering, we need
to keep track of the number and use the correct one.

Author: Yopi

server/migrations/versions/2025-10-24-0915_add_invoice_next_number_to_customers.py

@@ -0,0 +1,33 @@
+"""add invoice_next_number to customers
+
+Revision ID: 8c9ef8060e95
+Revises: 9b0f38cdd25d
+Create Date: 2025-10-24 09:15:38.708186
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+# Polar Custom Imports
+
+# revision identifiers, used by Alembic.
+revision = "8c9ef8060e95"
+down_revision = "9b0f38cdd25d"
+branch_labels: tuple[str] | None = None
+depends_on: tuple[str] | None = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "customers",
+        sa.Column("invoice_next_number", sa.Integer(), nullable=True),
+    )
+    op.execute(
+        "UPDATE customers SET invoice_next_number = 1 WHERE invoice_next_number IS NULL"
+    )
+    op.alter_column("customers", "invoice_next_number", nullable=False)
+
+
+def downgrade() -> None:
+    op.drop_column("customers", "invoice_next_number")

server/polar/models/customer.py

@@ -13,6 +13,7 @@
     ColumnElement,
     ForeignKey,
     Index,
+    Integer,
     String,
     UniqueConstraint,
     Uuid,
@@ -136,6 +137,8 @@ class Customer(MetadataMixin, RecordModel):
         TIMESTAMP(timezone=True), nullable=True, default=None, index=True
     )
 
+    invoice_next_number: Mapped[int] = mapped_column(Integer, nullable=False, default=1)
+
     organization_id: Mapped[UUID] = mapped_column(
         Uuid,
         ForeignKey("organizations.id", ondelete="cascade"),

server/polar/order/service.py

@@ -578,7 +578,7 @@ async def _create_order_from_checkout(
 
         organization = checkout.organization
         invoice_number = await organization_service.get_next_invoice_number(
-            session, organization
+            session, organization, customer
         )
 
         repository = OrderRepository.from_session(session)
@@ -699,7 +699,7 @@ async def create_subscription_order(
             tax_rate = tax_calculation["tax_rate"]
 
         invoice_number = await organization_service.get_next_invoice_number(
-            session, subscription.organization
+            session, subscription.organization, customer
         )
 
         total_amount = subtotal_amount - discount_amount + tax_amount
@@ -791,7 +791,7 @@ async def create_trial_order(
 
         organization = subscription.organization
         invoice_number = await organization_service.get_next_invoice_number(
-            session, organization
+            session, organization, customer
         )
 
         repository = OrderRepository.from_session(session)
@@ -1344,7 +1344,7 @@ async def create_order_from_stripe(
         )
 
         invoice_number = await organization_service.get_next_invoice_number(
-            session, subscription.organization
+            session, subscription.organization, customer
         )
 
         repository = OrderRepository.from_session(session)

server/polar/organization/service.py

@@ -2,7 +2,7 @@
 from collections.abc import Sequence
 from datetime import UTC, datetime
 from enum import StrEnum
-from typing import Any
+from typing import TYPE_CHECKING, Any
 from uuid import UUID
 
 import structlog
@@ -16,6 +16,8 @@
 from polar.auth.models import AuthSubject
 from polar.checkout_link.repository import CheckoutLinkRepository
 from polar.config import Environment, settings
+from polar.customer.repository import CustomerRepository
+from polar.enums import InvoiceNumbering
 from polar.exceptions import PolarError, PolarRequestValidationError
 from polar.integrations.loops.service import loops as loops_service
 from polar.integrations.plain.service import plain as plain_service
@@ -44,6 +46,9 @@
 )
 from .sorting import OrganizationSortProperty
 
+if TYPE_CHECKING:
+    from polar.models import Customer
+
 log = structlog.get_logger()
 
 
@@ -361,17 +366,32 @@ async def get_next_invoice_number(
         self,
         session: AsyncSession,
         organization: Organization,
+        customer: "Customer",
     ) -> str:
-        invoice_number = f"{organization.customer_invoice_prefix}-{organization.customer_invoice_next_number:04d}"
-        repository = OrganizationRepository.from_session(session)
-        organization = await repository.update(
-            organization,
-            update_dict={
-                "customer_invoice_next_number": organization.customer_invoice_next_number
-                + 1
-            },
-        )
-        return invoice_number
+        match organization.invoice_numbering:
+            case InvoiceNumbering.customer:
+                customer_suffix = str(customer.id).split("-")[0].upper()
+                invoice_number = f"{organization.customer_invoice_prefix}-{customer_suffix}-{customer.invoice_next_number:04d}"
+                customer_repository = CustomerRepository.from_session(session)
+                await customer_repository.update(
+                    customer,
+                    update_dict={
+                        "invoice_next_number": customer.invoice_next_number + 1
+                    },
+                )
+                return invoice_number
+
+            case InvoiceNumbering.organization:
+                invoice_number = f"{organization.customer_invoice_prefix}-{organization.customer_invoice_next_number:04d}"
+                repository = OrganizationRepository.from_session(session)
+                organization = await repository.update(
+                    organization,
+                    update_dict={
+                        "customer_invoice_next_number": organization.customer_invoice_next_number
+                        + 1
+                    },
+                )
+                return invoice_number
 
     async def _after_update(
         self,

server/tests/order/test_service.py

@@ -13,7 +13,11 @@
 
 from polar.auth.models import AuthSubject
 from polar.checkout.eventstream import CheckoutEvent
-from polar.enums import PaymentProcessor, SubscriptionRecurringInterval
+from polar.enums import (
+    InvoiceNumbering,
+    PaymentProcessor,
+    SubscriptionRecurringInterval,
+)
 from polar.held_balance.service import held_balance as held_balance_service
 from polar.integrations.stripe.schemas import ProductType
 from polar.integrations.stripe.service import StripeService
@@ -3871,3 +3875,88 @@ async def test_customer_balance(
             await order_service.customer_balance(session, customer)
             == setup.expected_balance
         )
+
+
+@pytest.mark.asyncio
+class TestCustomerBasedInvoiceNumbering:
+    async def test_different_customers_different_invoice_numbers(
+        self,
+        save_fixture: SaveFixture,
+        session: AsyncSession,
+        organization: Organization,
+        product_one_time: Product,
+    ) -> None:
+        # Set organization to use customer-based invoice numbering
+        organization.order_settings = {
+            **organization.order_settings,
+            "invoice_numbering": InvoiceNumbering.customer,
+        }
+        await save_fixture(organization)
+
+        # Create two different customers
+        customer_1 = await create_customer(
+            save_fixture,
+            organization=organization,
+            email="[email protected]",
+            name="Customer 1",
+            stripe_customer_id="STRIPE_CUSTOMER_1",
+        )
+        customer_2 = await create_customer(
+            save_fixture,
+            organization=organization,
+            email="[email protected]",
+            name="Customer 2",
+            stripe_customer_id="STRIPE_CUSTOMER_2",
+        )
+
+        # Create checkout and order for customer 1
+        checkout_1 = await create_checkout(
+            save_fixture,
+            products=[product_one_time],
+            status=CheckoutStatus.confirmed,
+            customer=customer_1,
+        )
+        order_1 = await order_service.create_from_checkout_one_time(session, checkout_1)
+
+        # Create checkout and order for customer 2
+        checkout_2 = await create_checkout(
+            save_fixture,
+            products=[product_one_time],
+            status=CheckoutStatus.confirmed,
+            customer=customer_2,
+        )
+        order_2 = await order_service.create_from_checkout_one_time(session, checkout_2)
+
+        # Refresh to get the invoice numbers
+        await session.refresh(order_1)
+        await session.refresh(order_2)
+
+        # Both customers should have different invoice number sequences
+        # They should both start with the organization prefix but have customer-specific numbering
+        assert order_1.invoice_number is not None
+        assert order_2.invoice_number is not None
+        assert order_1.invoice_number != order_2.invoice_number
+
+        # Verify they both start with organization prefix
+        assert order_1.invoice_number.startswith(organization.customer_invoice_prefix)
+        assert order_2.invoice_number.startswith(organization.customer_invoice_prefix)
+
+        # Each customer should start at 0001
+        assert order_1.invoice_number.endswith("-0001")
+        assert order_2.invoice_number.endswith("-0001")
+
+        # Verify invoice numbers contain customer-specific suffix
+        customer_1_suffix = str(customer_1.id).split("-")[0].upper()
+        customer_2_suffix = str(customer_2.id).split("-")[0].upper()
+        assert customer_1_suffix in order_1.invoice_number
+        assert customer_2_suffix in order_2.invoice_number
+
+        # Verify format: PREFIX-CUSTOMER_SUFFIX-0001
+        assert (
+            order_1.invoice_number
+            == f"{organization.customer_invoice_prefix}-{customer_1_suffix}-0001"
+        )
+        assert (
+            order_2.invoice_number
+            == f"{organization.customer_invoice_prefix}-{customer_2_suffix}-0001"
+        )

server/tests/organization/test_service.py

@@ -10,9 +10,9 @@
 
 from polar.auth.models import AuthSubject
 from polar.config import Environment, settings
-from polar.enums import AccountType
+from polar.enums import AccountType, InvoiceNumbering
 from polar.exceptions import PolarRequestValidationError
-from polar.models import Organization, Product, User
+from polar.models import Customer, Organization, Product, User
 from polar.models.account import Account
 from polar.models.organization import OrganizationNotificationSettings
 from polar.models.organization_review import OrganizationReview
@@ -163,19 +163,111 @@ async def test_valid_with_none_subscription_settings(
 
 
 @pytest.mark.asyncio
-async def test_get_next_invoice_number(
+async def test_get_next_invoice_number_organization(
     session: AsyncSession,
     organization: Organization,
+    customer: Customer,
 ) -> None:
+    organization.order_settings = {
+        **organization.order_settings,
+        "invoice_numbering": InvoiceNumbering.organization,
+    }
     assert organization.customer_invoice_next_number == 1
 
     next_invoice_number = await organization_service.get_next_invoice_number(
-        session, organization
+        session, organization, customer
     )
 
     assert next_invoice_number == f"{organization.customer_invoice_prefix}-0001"
     assert organization.customer_invoice_next_number == 2
 
+    await session.refresh(customer)
+    assert customer.invoice_next_number == 1
+
+
+@pytest.mark.asyncio
+async def test_get_next_invoice_number_customer(
+    session: AsyncSession,
+    save_fixture: SaveFixture,
+    organization: Organization,
+    customer: Customer,
+) -> None:
+    await save_fixture(organization)
+
+    initial_org_counter = organization.customer_invoice_next_number
+    assert customer.invoice_next_number == 1
+
+    next_invoice_number = await organization_service.get_next_invoice_number(
+        session, organization, customer
+    )
+
+    customer_suffix = str(customer.id).split("-")[0].upper()
+    assert (
+        next_invoice_number
+        == f"{organization.customer_invoice_prefix}-{customer_suffix}-0001"
+    )
+    await session.commit()
+    await session.refresh(customer)
+    assert customer.invoice_next_number == 2
+
+    await session.refresh(organization)
+    assert organization.customer_invoice_next_number == initial_org_counter
+
+    await session.refresh(customer)
+
+    next_invoice_number = await organization_service.get_next_invoice_number(
+        session, organization, customer
+    )
+
+    assert (
+        next_invoice_number
+        == f"{organization.customer_invoice_prefix}-{customer_suffix}-0002"
+    )
+    await session.commit()
+    await session.refresh(customer)
+    assert customer.invoice_next_number == 3
+
+
+@pytest.mark.asyncio
+async def test_get_next_invoice_number_multiple_customers(
+    session: AsyncSession,
+    save_fixture: SaveFixture,
+    organization: Organization,
+    customer: Customer,
+) -> None:
+    await save_fixture(organization)
+
+    customer2 = Customer(
+        email="[email protected]",
+        organization=organization,
+    )
+    session.add(customer2)
+
+    invoice1 = await organization_service.get_next_invoice_number(
+        session, organization, customer
+    )
+    customer_suffix = str(customer.id).split("-")[0].upper()
+    await session.commit()
+    assert invoice1 == f"{organization.customer_invoice_prefix}-{customer_suffix}-0001"
+
+    invoice2 = await organization_service.get_next_invoice_number(
+        session, organization, customer2
+    )
+    customer2_suffix = str(customer2.id).split("-")[0].upper()
+    await session.commit()
+    assert invoice2 == f"{organization.customer_invoice_prefix}-{customer2_suffix}-0001"
+
+    invoice3 = await organization_service.get_next_invoice_number(
+        session, organization, customer
+    )
+    await session.commit()
+    assert invoice3 == f"{organization.customer_invoice_prefix}-{customer_suffix}-0002"
+
+    await session.refresh(customer)
+    await session.refresh(customer2)
+    assert customer.invoice_next_number == 3
+    assert customer2.invoice_next_number == 2
+
 
 @pytest.mark.asyncio
 class TestCheckReviewThreshold: