Type: Domain Schema: billing Tables: 22 Primary source: documents/doc-24-billing-value-architecture.md Decisions: 5-8, 10, 22, 28, 55-76, 87, 90-93, 95, 106-108

Purpose

The billing module answers the financial stratum's core question: "Who pays, what did they buy, and how does economic activity flow through the platform?" It encompasses the full lifecycle of commercial engagement -- from product catalog and pricing through subscription management, invoice composition, and payment processing -- while maintaining the credit governance layer required for prepaid and promotional billing. Catalog shape is governed by plan_ladders and plan_ladder_tiers, which declare how plan products relate to one another as mutually exclusive alternatives without encoding capability (that lives in entitlement_sets) or pricing (that lives in prices). Cooperative-specific concerns (patronage attribution, cooperative member identity) have been extracted to the cooperative module (Decision 108); entitlement configuration (formerly product_entitlement_rules, now entitlement_set_rules within entitlement_sets) has been reassigned to the entitlements module (Decision 107) where its sole operational consumer resides. Products reference an entitlement set via entitlement_set_id to declare what capabilities they confer.

Tables

Table	Purpose
`billing_accounts`	Financial identity: the paying entity that owns subscriptions, accumulates charges, and anchors all downstream financial objects. Separates "who pays" from "who receives service."
`products`	Catalog entry describing what the cooperative sells. Carries name, type, and visibility but deliberately excludes pricing and entitlement mapping.
`prices`	Commercial terms for purchasing a product: amount, currency, billing schedule, trial period. Multiple prices per product enable migration without disruption.
`plan_ladders`	Named set of plan products declared mutually exclusive within a commercial domain. Catalog-shape construct; declares product alternatives without encoding capability or pricing.
`plan_ladder_tiers`	Ordered-membership junction placing plan products at ranked positions within a ladder. Supports multi-ladder bundle products via many-to-many.
`subscriptions`	Stateful recurring billing agreement. Primary invoice generator. Status governs pool provision lifecycle.
`subscription_items`	Line item within a subscription binding it to a specific price at a specific quantity. Each item produces one pool provision.
`subscription_changes`	Immutable audit trail of subscription lifecycle transitions with actor attribution and effective dating.
`purchases`	Completed one-time transaction. No recurring lifecycle. Creates pool provisions through the same mechanism as subscriptions.
`invoices`	Finalized billing document with address snapshot at issuance time. Immutability boundary at draft-to-open transition.
`invoice_line_items`	Atomic unit of invoice composition. Source of truth for invoice totals. Enables product-level patronage attribution.
`payments`	Local projection of payment processor outcomes. Records gross amount, processor fee, and settlement timing.
`payment_methods`	Provider-agnostic record of stored payment instruments. Thin, non-sensitive projection for display and dunning logic.
`refunds`	First-class partial or full return of money from a payment. Triggers patronage reversal workflow.
`disputes`	Chargeback or formal dispute against a payment. Business-critical dates and resolution status in `billing` schema; provider details in per-provider integration schemas.
`coupons`	Rule layer defining commercial reduction terms: type, percentage/amount, duration, product restrictions, redemption caps.
`promotion_codes`	Customer-facing redemption keys mapping to coupons. Enables per-channel attribution and multi-channel distribution.
`discounts`	Active state of a coupon applied to a billing relationship. Exclusive arc scoping to billing account, subscription, or line item.
`pending_charges`	Mutable pre-invoice financial obligations. The "missing middle" of the three-stage billing pipeline between raw inputs and frozen invoice outputs.
`pending_charge_usage_events`	Join table linking individual usage events to the pending charge that bills for them. Preserves usage event append-only semantics.
`credit_grants`	Discrete allocation of prepaid or promotional billing credits. Governed objects with priority, scope, expiration, and lifecycle.
`credit_transactions`	Immutable ledger entries recording balance movements against credit grants. Append-only; corrections via compensating transactions.

Quick Links

Model Reference -- DDL and table descriptions
Architecture -- Deep-dive documentation
Module Companion -- Decisions and open issues
Interfaces -- Cross-module dependencies