Billing
Model Stripe-backed products, prices, plans, entitlements, usage, and customer billing state.
Kernia billing is centered on Stripe import plus application entitlements. Stripe owns products, prices, checkout, portals, invoices, and subscription webhooks. Kernia stores the imported catalog, maps prices to internal plans and features, and exposes check and track APIs for product enforcement.
Stripe catalog import
Use /stripe/catalog/sync to import products and prices from Stripe into Kernia. Imported records should be reviewed before they are mapped to plans.
/api/auth/stripe/catalog/syncPulls Stripe products and prices into Kernia billing tables.
Features
Features describe what the application can enforce: boolean access, metered usage, seats, non-consumable quantities, included grants, reset periods, and optional overage behavior.
{
"key": "messages",
"kind": "metered",
"included": 10000,
"resetPeriod": "month",
"allowOverage": false
}Plans and prices
A plan maps one or more Stripe prices to a set of plan features. A single product can have monthly and annual prices that share the same entitlement set.
Customer state
Billing customer state connects a Kernia user or organization to a Stripe customer and subscription. Webhooks should be the source of truth for subscription status.
/api/auth/billing/customerReturns customer id, subscription state, active plan, and billing portal availability.
Check and track
/api/auth/billing/checkChecks whether a user or organization has access to a feature and returns remaining balance where relevant.
/api/auth/billing/trackRecords usage and updates entitlement balance for metered features.
Usage events
Track usage at the point where the product action succeeds. Do not count failed actions unless the product explicitly bills attempts.
Webhooks
Stripe webhooks should update subscription rows, billing customer state, period boundaries, and entitlement resets. Tests should use signed mock webhook events.
Demo coverage
The SaaS demo should show current plan, imported products/prices, mapped features, check output, usage history, portal link creation, and webhook health.