Billing And Invoicing

Billing manages customer or party invoices, payments, credit notes, write-offs, and receivables aging. The current implementation is operational and GL-integrated for invoice issue, payment, credit-note, and write-off flows.

Current Scope

Billing supports:

• Draft invoice creation with one or more invoice lines.
• Approval-aware invoice create and update operations with activity-log entries.
• Invoice issue through the GL posting engine.
• Payment application against posted invoices.
• Credit notes against posted invoices.
• Invoice write-offs against posted invoices with outstanding balances.
• Receivables aging by as-of date, client, and business unit.
• Invoice detail views with lines, payments, credit notes, and GL posting status.

GL Integration

Billing posts through the domain GL engine, not direct journal inserts.

The active posting rules are:

• BILLING.INVOICE.ISSUE: debits receivable and credits revenue plus output tax where applicable.
• BILLING.INVOICE.PAYMENT: debits cash, bank, mobile money, or wallet accounts and credits receivable.
• BILLING.CREDIT_NOTE: debits revenue plus output tax and credits receivable.
• BILLING.WRITE_OFF: debits write-off expense and credits receivable.

The procedure layer resolves fallback COAs using system tags such as:

• SERVICE_RECEIVABLE, RECEIVABLE, AR_CONTROL, TRADE_RECEIVABLE
• SERVICE_REVENUE, PRODUCT_REVENUE
• OUTPUT_TAX_PAYABLE, TAX_PAYABLE
• CASH_AT_HAND, CASH_IN_TILL
• MOBILE_MONEY_ACCOUNT, MOBILE_MONEY
• BANK_CURRENT_ACCOUNT, BANK_CURRENT
• LOAN_WRITEOFF_EXPENSE, WRITEOFF, EXPENSE, OPERATING_EXPENSE

The callback dispatcher finalizes billing records after GL posting:

• BILLING.INVOICE_ISSUE.POSTED
• BILLING.INVOICE_ISSUE.REJECTED
• BILLING.INVOICE_PAYMENT.POSTED
• BILLING.INVOICE_PAYMENT.REJECTED
• BILLING.CREDIT_NOTE.POSTED
• BILLING.CREDIT_NOTE.REJECTED
• BILLING.WRITE_OFF.POSTED
• BILLING.WRITE_OFF.REJECTED

Event Integration

Events can carry billing charge context through event charge lines. Event charge detail views already show linked billing invoice information when a charge has been invoiced.

The current boundary is:

• Events define billable event types and charge policies.
• Billing owns invoice creation, balance calculation, payment, and credit-note lifecycle.
• GL owns posting and callback finalization.

Communication And Notifications

The communication module has templates, messages, outbox, SMS credits, and desktop SMS infrastructure. Billing posted callbacks enqueue approved SMS templates when the invoice is linked to a client with a valid phone number.

Registered billing templates:

• BILLING_INVOICE_ISSUED_SMS_V1
• BILLING_PAYMENT_POSTED_SMS_V1
• BILLING_CREDIT_NOTE_POSTED_SMS_V1
• BILLING_WRITE_OFF_POSTED_SMS_V1
• BILLING_OVERDUE_REMINDER_SMS_V1

Invoice issue, payment, credit-note, and write-off notifications are queued only after successful GL posting. Notification failures are non-blocking and cannot reject an otherwise valid GL posting. The overdue reminder template is registered but requires a scheduler policy to determine reminder timing and frequency.

Reporting

Billing has an operational aging endpoint and four generic report-catalog definitions. Catalog reports use the standard reporting runner, export, preset, and scheduling infrastructure.

Operational reporting:

• GET /api/billing/aging
• Procedure: get_billing_aging_report
• Filters: as_of_date, client_id, business_unit_id_filter

Catalog reports:

• BILLING_AGING: reconstructs open balances from posted invoices, payments, credit notes, and write-offs as of the requested date.
• BILLING_INVOICE_REGISTER: invoice totals, status, approval status, balance, and GL state.
• BILLING_PAYMENT_REGISTER: payment channel, reference, amount, and GL posting state.
• BILLING_RECEIVABLE_RECONCILIATION: compares base-currency billing receivables with summed daily GL movements through the as-of date by business unit and receivable COA.

The reconciliation deliberately retains raw GL signs. A negative asset balance or missing receivable tag is shown as an exception instead of being converted with ABS().

Permissions

Implemented billing permissions include:

• VIEW_BILLING_INVOICES
• CREATE_BILLING_INVOICE
• UPDATE_BILLING_INVOICE
• APPLY_BILLING_PAYMENT
• CREATE_BILLING_CREDIT_NOTE
• WRITE_OFF_BILLING_INVOICE
• VIEW_BILLING_AGING

Remaining Implementation Gaps

• Add the overdue-reminder scheduler and tenant-configurable reminder timing/frequency policy.
• Add reversal lifecycles for posted billing payments, credit notes, and write-offs. Reversals must use GL reversal callbacks rather than direct status or balance edits.
• Extend receivable reconciliation to optional customer subledger detail where billing products require customer-level subledgers.