pguerrerox/leads4less
Public Access
1
0
Fork 0
Code Actions Wiki Activity

feat: launch Stripe billing flows with lifecycle hardening and analytics

Browse Source 
add Stripe checkout, portal, webhook ingestion, and idempotent event persistence

add billing lifecycle state (grace/sync/timeline/admin visibility) and stronger entitlement handling

add analytics event tracking and admin summary APIs plus account/pricing UI integration
This commit is contained in:
pguerrerox
2026-05-22 22:55:04 +00:00
parent 94b8c357b4
commit 5508e15da1
35 changed files with 2851 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files
TODO-pricing.md
+60 -27
View File
@@ -243,7 +243,7 @@
- [x] Add quota warning UX before hard exhaustion.
- [x] Keep migration-dependent collaboration messaging honest by surfacing included-but-not-ready capabilities as `Coming soon` instead of pretending they are fully live.
- [ ] Future note: the pricing comparison table should stay aligned with workspace-readiness decisions as collaboration and shared asset features move toward workspace ownership.
- [ ] Future note: upgrade CTAs are present, but actual checkout/subscription management should remain tied to the future payments integration step.
- [ ] Future note: upgrade CTAs are present, but actual checkout/subscription management should remain tied to the post-payments hardening step.
- [ ] Future note: pricing and account UX should keep users included, workspace limits, and collaboration-adjacent promises explicitly soft-gated until workspace-owned shared data and hard enforcement are ready.
- [ ] Future note: replace placeholder upgrade CTAs in the account billing UI with a real upgrade path, pricing-page jump, contact-sales flow, or explicit `coming soon` behavior before broader rollout.
@@ -262,32 +262,54 @@
- [ ] Future note: recurring feature add-ons should not be sold until the underlying capabilities and subscription management flows exist end-to-end.
## 10) Payments Integration
- [ ] Choose billing provider (likely Stripe).
- [ ] Map internal SKUs to external billing products/prices.
- [ ] Support subscriptions, annual billing, add-ons, and enterprise/manual invoicing.
- [ ] Define webhook handling for subscription state changes.
- [ ] Define downgrade, cancellation, retry, and grace-period behavior.
- [ ] Add internal admin visibility for billing state.
- [x] Choose billing provider (Stripe).
- [x] Map internal SKUs to external billing products/prices.
- [x] Support subscriptions, annual billing, add-ons, and enterprise/manual invoicing.
- [x] Define webhook handling for subscription state changes.
- [ ] Future note: Stripe is now the active integration path; keep the internal plan/add-on catalog as the canonical packaging source and treat Stripe price IDs as environment-specific mappings.
- [ ] Future note: the current customer-facing integration supports self-serve subscriptions, export-pack checkout, and the Stripe billing portal, while enterprise invoicing remains a manual sales workflow.
- [ ] Future note: webhook idempotency currently relies on the `billing_webhook_events` store; keep Stripe event processing centralized there as billing lifecycle coverage expands.
- [ ] Future note: post-payments hardening should tighten downgrade, cancellation, retry, and grace-period policy before broad rollout so Stripe portal actions and runtime entitlements stay aligned.
## 11) Founder / LTD Strategy
- [ ] Decide whether to launch founder LTD at all.
- [ ] If yes, define strict quantity cap (e.g. first 100-250 customers).
- [ ] Define founder SKUs:
- Founder Plan = $249 one-time
- Founder Pro = $499 one-time
- [ ] Ensure founder plans have monthly quotas and exclude unlimited compute/API.
- [ ] Define which future features are excluded from LTD plans.
## 11) Post-Payments Hardening & Admin Visibility
- [ ] Define explicit downgrade behavior:
- effective timing for scheduled vs immediate plan changes
- entitlement/usage treatment when the target plan is below current usage
- account messaging for pending downgrade state
- [x] Define explicit cancellation behavior:
- end-of-period vs immediate access policy
- post-cancellation account state and reactivation path
- handling for active add-on balances and usage windows
- [x] Define explicit payment retry and grace-period behavior:
- which Stripe states map to degraded vs blocked access
- grace-period duration and user-facing messaging
- when usage actions should warn, soft-block, or hard-block
- [x] Wire pricing-page CTAs to real billing actions:
- self-serve paid plans -> Stripe checkout
- active paid workspaces -> plan-change or billing-portal path
- enterprise plans -> contact-sales path
- [x] Add account redirect notices after Stripe return:
- successful checkout/portal return confirmation
- canceled or incomplete checkout messaging
- failed or unresolved billing-return guidance
- [x] Expand internal admin billing visibility for operational maintenance and debugging:
- show workspace billing summary with current plan, interval, status, renewal date, cancel-at-period-end, and trial/grace-period state
- show current usage period and counters for research, exports, add-ons, and remaining balances
- show recent Stripe/customer/subscription identifiers and latest webhook processing outcomes
- show recent billing timeline entries for checkout, subscription changes, payment failures, cancellations, and add-on purchases
- flag workspaces with stale billing sync, failed webhook processing, or status mismatches needing support follow-up
- document the minimum admin view(s) needed so support can verify billing state without direct database inspection
## 12) Analytics, Ops, and Revenue Instrumentation
- [ ] Track pricing-page conversion by plan.
- [ ] Track quota exhaustion events.
- [ ] Track upgrade triggers:
- [x] Track pricing-page conversion by plan.
- [x] Track quota exhaustion events.
- [x] Track upgrade triggers:
- export limit hit
- research limit hit
- feature-gate encounter
- [ ] Track add-on attach rate.
- [ ] Track plan mix, churn, expansion revenue, and annual conversion.
- [ ] Add internal dashboards for billing and usage health.
- [x] Track add-on attach rate.
- [x] Track plan mix, churn, expansion revenue, and annual conversion.
- [x] Add internal dashboards for billing and usage health.
## 13) Operational Enforcement Follow-Up
- [ ] Add queue prioritization by plan tier.
@@ -299,23 +321,34 @@
- [ ] Future note: export enforcement remains deferred until CSV/export generation moves to a backend endpoint.
- [ ] Future note: enrichment-route enforcement remains deferred until enrichment actions/routes are implemented.
## 14) Rollout Plan
## 14) Founder / LTD Strategy
- [ ] Decide whether to launch founder LTD at all.
- [ ] If yes, define strict quantity cap (e.g. first 100-250 customers).
- [ ] Define founder SKUs:
- Founder Plan = $249 one-time
- Founder Pro = $499 one-time
- [ ] Ensure founder plans have monthly quotas and exclude unlimited compute/API.
- [ ] Define which future features are excluded from LTD plans.
## 15) Rollout Plan
- [ ] Phase 1: finalize canonical plan definitions, presentation metadata boundaries, and entitlement model.
- [ ] Phase 2: implement usage ledger and backend enforcement.
- [ ] Phase 3: review workspace, user, and collaboration readiness before expanding team/workspace promises.
- [ ] Phase 4: update pricing page and account/billing UI based on the workspace/collaboration readiness decisions.
- [ ] Phase 5: finalize add-on strategy before wiring payment products.
- [ ] Phase 6: integrate payments and subscription lifecycle handling.
- [ ] Phase 7: decide and implement founder/LTD strategy only after the core subscription path is stable.
- [ ] Phase 7: harden post-payments lifecycle handling, wire real billing CTAs, and add pragmatic admin billing visibility before broader commercialization work.
- [ ] Phase 8: expand analytics, ops, and revenue instrumentation around the live billing and upgrade flows.
- [ ] Phase 9: launch collaboration, API, enrichment, and enterprise features as architecture matures.
- [ ] Phase 10: complete deferred operational enforcement work such as queue prioritization, throttling, and backend export enforcement when runtime scale justifies it.
- [ ] Phase 11: decide and implement founder/LTD strategy only after the app/site, billing lifecycle, admin/support visibility, analytics, and broader product maturity work are in place.
## Recommended Execution Order
- [ ] Next: `#10 Payments Integration`
- [ ] Then: `#11 Founder / LTD Strategy`
- [ ] Then: `#12 Analytics, Ops, and Revenue Instrumentation`
- [ ] Keep `#13 Operational Enforcement Follow-Up` deferred until async worker routing, backend exports, or higher-volume execution patterns make it necessary.
- [ ] Next: `#11 Post-Payments Hardening & Admin Visibility`
- [ ] Then: `#13 Analytics, Ops, and Revenue Instrumentation`
- [ ] Then: collaboration, API, enrichment, and enterprise feature maturation from `#15 Rollout Plan`
- [ ] Keep `#14 Operational Enforcement Follow-Up` deferred until async worker routing, backend exports, or higher-volume execution patterns make it necessary.
- [ ] Last: `#12 Founder / LTD Strategy` once the app/site, billing lifecycle, admin/support visibility, analytics, and broader product maturity work are in place.
## Open Questions
- [ ] Will research capacity be marketed as runs, credits, or both?