These cookies are required for the website to function properly. They ensure security, enable basic features like page navigation, and store user session data. You cannot disable these cookies.
- Subscription Billing
- Data model
The tables behind Subscription Billing
Subscription Billing ships with 23 tables, grouped here by the feature that uses them. Every record your team works with lives in one of them, and you can add fields and tables in Proto.
- Tables
- 23
- Features
- 6, plus shared settings
- Change it
- Add fields and tables in Proto
How the model is organised
Commercial basis
Users, Customers, billing products, price plans, price tiers and usage meters. Define customer identity, products, published price versions and meters.
Accepted subscriptions
Subscriptions, subscription changes and payment methods. Preserve accepted terms, effective changes and payment mandates.
Metering evidence
Usage events, usage aggregates and integration events. Keep usage events as append-only evidence and freeze each aggregate’s exact accepted input set.
Billing documents and corrections
Billing runs, Invoices, invoice lines, credit notes, credit lines, billing adjustments and billing adjustment applications. Prepare reviewed invoices, retain line calculations and link corrections to their original documents.
Collection and follow-up
Payment attempts, refund requests, dunning cases and dunning attempts. Preserve the distinct outcomes of payment attempts, refunds and collection follow-up.
Every table, by feature
- Plans and pricing4
- Subscription lifecycle5
- Usage metering7
- Invoices and proration10
- Payments and dunning7
- Billing operations and reporting7
- Shared and settings1
- Billing products
Product and service identity used by published price plans.
- Price plans
Versioned subscription terms; published price revisions are immutable.
Linked to Billing products, Usage meters, Users - Price tiers
Explicit contiguous usage bands inside one plan revision.
Linked to Price plans - Usage meters
Versioned event aggregation contract for one measurable product quantity.
- Customers
Entity-scoped billing accounts with reviewed terms and source identifiers.
- Subscriptions
Accepted customer terms and billing anchor; cancellation preserves prior invoices.
Linked to Customers, Price plans, Users - Subscription changes
Effective plan, quantity, pause or cancellation proposals, preserving prior terms.
Linked to Subscriptions, Price plans, Users - Price plans
Versioned subscription terms; published price revisions are immutable.
Linked to Billing products, Usage meters, Users - Payment methods
Provider-hosted payment tokens and accepted recurring mandates; no raw card details.
Linked to Customers
- Billing adjustments
Reviewed difference between a corrected rated source and the amounts already billed for the original line. Retain both evidence and signed delta.
Linked to Subscriptions, Invoice lines, Usage aggregates, Subscription changes - Billing adjustment applications
Per-document application of an approved signed correction; supports crediting original and earlier positive correction invoices without exceeding any line balance.
Linked to Billing adjustments, Invoice lines, Credit notes - Usage meters
Versioned event aggregation contract for one measurable product quantity.
- Usage events
Append-only metering evidence; repeated source identities cannot increase usage.
Linked to Subscriptions, Usage meters, Users - Usage aggregates
Frozen, explainable metered quantities for one subscription interval and run.
Linked to Subscriptions, Usage meters, Billing runs - Integration events
Verified inbound receipt and deduplication envelope for metering, tax and payments.
- Billing runs
One candidate invoice interval per subscription; reviewed inputs and retry identity.
Linked to Subscriptions, Users, Invoices, Billing adjustments
- Billing adjustments
Reviewed difference between a corrected rated source and the amounts already billed for the original line. Retain both evidence and signed delta.
Linked to Subscriptions, Invoice lines, Usage aggregates, Subscription changes - Billing adjustment applications
Per-document application of an approved signed correction; supports crediting original and earlier positive correction invoices without exceeding any line balance.
Linked to Billing adjustments, Invoice lines, Credit notes - Billing runs
One candidate invoice interval per subscription; reviewed inputs and retry identity.
Linked to Subscriptions, Users, Invoices, Billing adjustments - Invoices
Issued customer billing document; frozen lines, currency and tax evidence.
Linked to Customers, Subscriptions, Billing runs - Invoice lines
Frozen billed sources and net/tax/gross amounts.
Linked to Invoices, Usage aggregates, Subscription changes, Billing adjustments - Usage aggregates
Frozen, explainable metered quantities for one subscription interval and run.
Linked to Subscriptions, Usage meters, Billing runs - Subscription changes
Effective plan, quantity, pause or cancellation proposals, preserving prior terms.
Linked to Subscriptions, Price plans, Users - Credit notes
Independently reviewed correction to an issued invoice; cash refund is separate.
Linked to Invoices, Customers, Users - Credit lines
Explicit reference to the original billed line and remaining creditable amount.
Linked to Credit notes, Invoice lines - Refund requests
Independently reviewed refund instruction against an observed settled payment, preserving unknown outcomes.
Linked to Payment attempts, Credit notes, Users
- Payment methods
Provider-hosted payment tokens and accepted recurring mandates; no raw card details.
Linked to Customers - Payment attempts
Stable collection instruction and observed provider result, separate from invoice issue.
Linked to Invoices, Payment methods - Invoices
Issued customer billing document; frozen lines, currency and tax evidence.
Linked to Customers, Subscriptions, Billing runs - Dunning cases
Invoice follow-up state; communication never manufactures collection.
Linked to Invoices, Customers, Users - Dunning attempts
One scheduled notice or authorised payment retry with retained outcome.
Linked to Dunning cases, Payment attempts - Integration events
Verified inbound receipt and deduplication envelope for metering, tax and payments.
- Refund requests
Independently reviewed refund instruction against an observed settled payment, preserving unknown outcomes.
Linked to Payment attempts, Credit notes, Users
- Subscriptions
Accepted customer terms and billing anchor; cancellation preserves prior invoices.
Linked to Customers, Price plans, Users - Billing runs
One candidate invoice interval per subscription; reviewed inputs and retry identity.
Linked to Subscriptions, Users, Invoices, Billing adjustments - Usage aggregates
Frozen, explainable metered quantities for one subscription interval and run.
Linked to Subscriptions, Usage meters, Billing runs - Invoices
Issued customer billing document; frozen lines, currency and tax evidence.
Linked to Customers, Subscriptions, Billing runs - Credit notes
Independently reviewed correction to an issued invoice; cash refund is separate.
Linked to Invoices, Customers, Users - Payment attempts
Stable collection instruction and observed provider result, separate from invoice issue.
Linked to Invoices, Payment methods - Dunning cases
Invoice follow-up state; communication never manufactures collection.
Linked to Invoices, Customers, Users
Keys and references
Use customer and seller-entity scope on every relationship. Preserve provider event plus payload digest, subscription interval, published plan version and issued document identity. Corrections link to their original source; they do not erase it.
Migration order
- Verify users, customers, products and accepted commercial history.
- Publish reviewed price and meter versions.
- Reconcile subscriptions, effective changes and payment mandates.
- Import source usage and outstanding issued invoice history without charging again.
- Reconcile credits, settled payments, unresolved instructions and dunning before enabling automation.
Set up Subscription Billing your way.
Start free, then use Proto to change fields, steps and approvals before your team goes live.