SEMANTIC BILLING
Subscription Lifecycle
Stripe owns the billing clock — subscription status, schedule triggers, renewal timing. Taking over the clock means managing when and how often customers are billed. Usage-based products add a wrinkle: threshold billing detects mid-cycle consumption spikes and triggers invoices.
subscription state determines when to collect
stripe.Subscription decides when periods start and end, when invoices are created, when charges fire. This coupling ripples through every billing problem. Taking over the clock is the single prerequisite for domain sovereignty.
Usage-based products (R2, Workers, etc.) bill at period end. Between billing cycles, a bad actor can consume arbitrarily large amounts with no payment validation. Monthly billing means up to 30 days of unvalidated consumption.
changes_calculator already solves WHAT — plans, quantities, prices, line items. The only gap is WHEN. Own the clock and every other domain can be built incrementally.
An OPE is a row in subs_object_products_element — an individual product component attached to a billable object (zone or account). Multiple OPEs compose a subscription.
Every other billing question — what to charge, how to collect, what credits to apply — depends on a single trigger: the billing period ended, generate an invoice. This domain takes over the clock.
When cumulative usage in the current period exceeds a configurable threshold, generate a mid-cycle invoice for actual consumption. Require immediate payment. If payment fails, suspend usage.
Threshold billing requires capabilities that don't exist yet: payment-gated entitlements (PDE), mid-cycle invoicing (Stripe migration), clean invoice semantics (Honest Invoicing), and usage anomaly detection. The sequencing is: PDE → Stripe migration → Honest Invoicing → threshold billing.
Own the billing clock and every other domain can be built incrementally.