Billing Database

Why This Exists

This document defines conceptual database responsibilities for the Billing Domain. It does not define physical SQL implementation.

Owner

The owner is the Chief Product Officer and Enterprise Architect.

Business Value

Billing storage must protect commercial evidence, subscription state, invoices, payments, entitlements, limits, and audit records.

Conceptual Tables Or Collections

Table or collection	Responsibility
billing_accounts	Billing account identity, organization reference, currency, tax context, and status.
billing_contacts	Billing contact references and communication preferences where Billing-owned.
billing_plans	Plan code, name, status, description, and version.
billing_plan_limits	Plan limits by usage unit, quantity, period, and enforcement behavior.
billing_plan_entitlements	Entitlement packages granted by plan.
billing_subscriptions	Subscription plan, status, cycle, dates, renewal, and cancellation references.
billing_trials	Trial period, status, conversion state, and linked subscription.
billing_entitlements	Effective entitlement grants by subscription.
billing_usage_records	Usage measurements by unit, period, source, and subscription.
billing_invoices	Invoice number, account, amount, currency, due date, status, and issue date.
billing_invoice_line_items	Charges, discounts, credits, taxes, and adjustments.
billing_payments	Payment attempts, provider references, amount, status, and timestamps.
billing_payment_failures	Failure reasons, retry count, recovery status, and next action.
billing_renewals	Renewal schedule, status, renewal invoice, and outcome.
billing_cancellations	Cancellation request, reason, effective date, and status.
billing_provider_callbacks	Raw or referenced provider callback records and processing status.
billing_audit_log	Audit records for subscription, invoice, payment, entitlement, and cancellation changes.

Indexing Considerations

Billing should support indexes for:

• organization_id.
• billing_account_id.
• subscription_id.
• plan_code.
• subscription_status.
• invoice_number.
• invoice_status.
• payment_status.
• provider_reference.
• renewal_date.
• created_at.

Audit Requirements

Audit logging is required for:

• Plan changes.
• Subscription creation and status changes.
• Entitlement changes.
• Invoice issuance, voiding, and crediting.
• Payment callback processing.
• Payment failure recovery decisions.
• Renewal and cancellation actions.

Provider Data Handling

Payment provider callback records should be retained with enough metadata to prove processing decisions. Sensitive payment instrument data should not be stored unless explicitly required and governed by security and compliance standards.