---
name: saas-billing-collections
description: Design, reconcile, and safely operate SaaS billing, subscriptions, usage metering, invoices, taxes, payments, refunds, credits, dunning, collections, affiliates, WHMCS, Invoice Ninja, Stripe, and Paywise integrations. Use for Lunexor hosting products, usage-based billing, overdue invoices, payment reconciliation, invoice documents, customer synchronization, and collection handover workflows.
compatibility: Financial reads should use restricted keys. Charges, refunds, credits, invoice sending, subscription changes, and collection handovers require explicit authorization, idempotency keys, dry runs, and post-action reconciliation.
license: Apache-2.0
---

# SaaS billing and collections

Financial state is distributed across the product database, payment provider, invoice system, tax documents and collection provider. Reconcile before mutating.

## Required workflow

1. Identify customer, legal entity, currency, tax jurisdiction, subscription, invoice and provider IDs.
2. Read current state from every relevant system.
3. Compare amounts, dates, line items, taxes, credits, payments, refunds and external references.
4. Explain discrepancies before proposing a write.
5. Generate a dry run with exact monetary effects and document changes.
6. Require an idempotency key tied to the business event.
7. Execute the smallest authorized operation.
8. Re-read provider and local state, then reconcile ledger and document records.
9. Record an audit event without payment credentials or unnecessary personal data.

## Usage-based billing

Define meter name, unit, aggregation window, source event, deduplication key, late-arrival policy, corrections, rounding, price version and customer-visible explanation. Do not derive billable usage from unstable dashboard aggregates when immutable source events exist.

## Invoice generation

Validate legal numbering, seller and customer identity, service period, tax treatment, currency, due date, payment reference and immutable PDF/archive requirements. Regeneration must not silently replace an issued legal document; use correction or credit-note workflows.

## Dunning and collections

Before handover:

- confirm the invoice is due, unpaid and not disputed;
- reconcile partial payments, credits and refunds;
- verify reminder and delay dates;
- create or resolve the debtor record;
- attach the correct invoice document;
- present exact principal, fees and currency;
- require confirmation before release to collections;
- store the external claim identifier and status.

## Permission separation

Use separate gates for `billing-read`, `invoice-create`, `invoice-send`, `subscription-write`, `refund`, `credit`, `payment-capture`, `collections-draft` and `collections-release`. A normal router deployment should expose read-only tools only.

## Output

Return customer and transaction identifiers, reconciled amounts in the original currency, discrepancies, dry-run effects, idempotency key, required capability, action status, resulting documents or external IDs, post-action reconciliation and remaining financial or legal review.