ADR-004: Billing Integration Strategy
Status: Deferred Owner: @bilal Date: 2025-12-06
Context
Organisations have a plan field (basic, premium, partner) but no mechanism to link to a payment provider, track subscription status, or handle plan changes.
Decision
Deferred — Add minimal schema hook now, full implementation when business model is finalised.
Immediate Change
ALTER TABLE organisations ADD COLUMN external_billing_id TEXT;
-- e.g., Stripe customer ID "cus_xxx"Future Schema (When Needed)
subscriptions— Track plan status (trialing, active, past_due, cancelled)billing_events— Webhook receipts from Stripeplan_features— Feature flags per plan (max_properties, api_access, etc.)
Integration Pattern
Stripe Webhook → Edge Function → billing_events table
→ Update subscriptions
→ Update organisations.plan
Open Questions
- Which payment provider? (Stripe assumed)
- Metered vs flat-rate billing?
- Free trial period?
- What happens on payment failure?
Consequences
Positive
- Minimal schema change now
- No coupling to specific provider
- Can implement when business model finalised
Negative
organisations.plancan drift from actual subscription status until implemented