# Customer Invoicing

## Overview

Customer Invoicing captures customer receivable documents as `SalesInvoice` and `SalesCreditNote` records and validates them against the commercial and fulfillment evidence already recorded in sales. Each invoice line references one or more sales order lines and, when shipment-gated billing is required, the posted shipments that prove quantity has actually been fulfilled. Each credit-note line references the issued invoice line being corrected, the affected sales order context, and the correction reason or amount so the commercial dispute can be resolved without mutating the historical invoice.

This feature does not post journal entries, apply cash, or execute collection. Its responsibility is to issue customer invoices that reflect what was sold and, where policy requires, what was shipped; preserve pricing, tax, and invoice identity required for legal and commercial validity; and maintain a clean handoff contract for future accounts-receivable and accounting modules. The minimum document lifecycles are `DRAFT` → `ISSUED` → `SENT` for `SalesInvoice`, with `CANCELLED` available only before downstream AR handoff acceptance, and `DRAFT` → `ISSUED` for `SalesCreditNote`, which references an already issued invoice when cancellation is no longer the correct commercial action.

## Business Purpose

- Create customer-facing invoices from sales orders without bypassing the underlying commercial commitment
- Prevent over-invoicing by ensuring invoice quantities align with order quantities and billing policy
- Support both order-based billing and shipment-gated billing depending on item or company policy
- Carry invoice identity, payment-term snapshot, and due-date schedule into downstream receivable processing
- Snapshot pricing and tax-relevant commercial data so later master-data edits do not alter issued invoices
- Allow draft or issued invoices to be cancelled while they are still owned by sales and have not yet been accepted by downstream AR
- Support post-issue commercial correction through `SalesCreditNote` when an invoice must be reduced for price disputes, quantity disputes, or allowances without deleting the original invoice evidence
- Preserve an auditable link between invoice lines, sales orders, and shipments

## Process Flow

```mermaid
flowchart TD
    A[Create Sales Invoice] --> B[Enter invoice date, customer reference, and lines]
    B --> C[Match invoice lines to sales order lines]
    C --> D{Billing policy?}
    D -->|Order-based| E[Compare invoice to ordered qty and price]
    D -->|Shipment-gated| F[Compare invoice to ordered qty, price, and posted shipments]
    E --> G{Valid?}
    F --> G
    G -->|No| H[Keep DRAFT for correction]
    G -->|Yes| I[ISSUE INVOICE]
    I --> J[Calculate due schedule from payment term]
    J --> K[Send invoice to customer]
    K --> L[SENT]
    L --> M{Cancel before AR handoff?}
    M -->|Yes| N[CANCELLED]
    M -->|No| O[Ready for downstream AR or accounting handoff]
    L --> P{Commercial correction needed after issue?}
    P -->|Yes| Q[Create SalesCreditNote against issued invoice lines]
    Q --> R[Validate credited qty or amount against original invoice evidence]
    R --> S[ISSUE CREDIT NOTE]
    S --> O
```

## Scenario Patterns

- **Post-shipment invoice**: The customer invoice is issued after the shipment posts, and invoiced quantities match the fulfilled quantities exactly
- **Order-based service invoice**: A service order is invoiced directly from the confirmed sales order because no physical shipment evidence is required
- **Partial invoice**: Only the first shipment of a larger order is invoiced now; the billed quantity is recorded and the order remains open for later invoices
- **Advance invoice by policy**: A project or make-to-order deal issues an invoice before shipment because the assigned billing policy allows order-based invoicing
- **Manual correction before issue**: A billing user notices the wrong customer reference while the invoice is still draft and fixes it before the invoice is issued
- **Pre-AR cancellation**: An issued invoice is discovered to contain the wrong external reference before AR accepts it, so sales cancels the invoice and preserves the original evidence
- **Post-issue price correction**: An invoice was issued with an overstated unit price, so billing issues a `SalesCreditNote` for the difference instead of cancelling the historical invoice
- **Quantity dispute allowance**: The customer accepts eight units from a ten-unit invoice and disputes the remainder, so sales issues a partial credit note tied to the original invoice lines
- **Payment-term inheritance**: The invoice inherits the order's negotiated payment term so downstream AR sees the correct due dates and discount windows
- **Tax snapshot capture**: The invoice snapshots customer tax identification, tax code, taxable amount, and tax amount so legal invoice validation survives later customer-master edits
- **Channel-originated billing**: A marketplace order becomes an internal sales order and later a customer invoice, while retaining channel reference for reconciliation and dispute handling

## Test Cases

- Creating a sales invoice with a valid customer, company, and at least one invoice line should succeed
- A sales invoice line must reference a valid sales order line and an invoice quantity greater than zero
- Duplicate external invoice numbers for the same company should be rejected
- An order-based invoice must compare invoice quantity and price to the referenced sales order line
- A shipment-gated invoice must not allow an invoiced quantity greater than the cumulative posted shipment quantity unless policy explicitly allows pre-shipment billing
- A sales invoice line price must come from the sales order snapshot rather than from a newly resolved price rule
- An invoice created from a cancelled sales order should fail
- An issued invoice must snapshot the invoice date, external invoice number, ordered price reference, assigned payment term, customer tax identifier, tax code, taxable amount, and tax amount
- Partial invoicing must increase the sales order line invoiced quantity without forcing the order closed
- A sales invoice must not be considered ready for downstream AR until all required billing-policy checks pass
- An issued invoice may transition to `SENT` only after customer-facing delivery metadata required by company policy is captured
- A draft or issued invoice may transition to `CANCELLED` only while no downstream AR or accounting module has accepted the receivable handoff
- Cancelling an invoice must preserve the original line references and issue evidence for future credit-note or dispute workflows
- Creating a `SalesCreditNote` must require reference to an issued `SalesInvoice` and at least one affected invoice line or correction amount
- The cumulative credited quantity or amount for an invoice line must not exceed the original issued quantity or amount unless a documented override policy exists
- A `SalesCreditNote` must snapshot correction reason, customer, currency, tax basis, and linked invoice identity so downstream AR can post the reversal deterministically
- Issuing a credit note must not mutate or delete the original invoice; it must preserve a linked audit trail between the invoice, credited lines, and downstream handoff contract
- Invoices must be isolated by company and must not reference sales orders from another company
- Shipment-gated validation must preserve whether the invoice was issued from order-based or shipment-based billing policy
- Only authorized sales or billing users should be able to create, issue, send, cancel, or release customer invoices and credit notes
- An issued invoice should expose the due-date schedule calculated from the assigned sales payment term
- Editing sales price rules or customer master data after invoice issuance must not change the comparison baseline for an existing invoice

## Reference Links

- [Odoo customer invoices documentation](https://www.odoo.com/documentation/19.0/applications/finance/accounting/customer_invoices.html)
- [Oracle Receivables documentation](https://docs.oracle.com/en/cloud/saas/financials/index.html)
- [SAP billing document overview](https://help.sap.com/docs/SAP_S4HANA_CLOUD)
