feat: add billing foundation and entitlement enforcement
- add workspace-scoped billing storage, usage tracking, and add-on catalog - enforce plan entitlements for search and deep research routes - expand pricing and account UI around billing state, usage, and upgrades
This commit is contained in:
pguerrerox
+118
-60
@@ -161,54 +161,115 @@
|
||||
- [ ] Future note: revisit the fallback `coming_soon` state for unavailable or unmapped features before broad UI rollout so hidden vs upgrade vs future behavior stays intentional.
|
||||
|
||||
## 5) Billing & Data Model Design
|
||||
- [ ] Design subscription/account state separately from the canonical plan catalog.
|
||||
- [ ] Keep billing-provider identifiers out of the canonical catalog until payments integration work begins.
|
||||
- [ ] Design subscription state storage for current plan, billing interval, and status.
|
||||
- [ ] Design a monthly usage ledger for:
|
||||
- [x] Design subscription/account state separately from the canonical plan catalog.
|
||||
- [x] Keep billing-provider identifiers out of the canonical catalog until payments integration work begins.
|
||||
- [x] Design subscription state storage for current plan, billing interval, and status.
|
||||
- [x] Design a monthly usage ledger for:
|
||||
- research credits/runs
|
||||
- exports
|
||||
- enrichments
|
||||
- API usage (future)
|
||||
- [ ] Design add-on purchases and remaining balances.
|
||||
- [ ] Define renewal/reset behavior for monthly quotas.
|
||||
- [ ] Define annual billing behavior and renewal terms.
|
||||
- [ ] Define LTD handling with monthly quotas and non-unlimited usage.
|
||||
- [x] Design add-on purchases and remaining balances.
|
||||
- [x] Define renewal/reset behavior for monthly quotas.
|
||||
- [x] Define annual billing behavior and renewal terms.
|
||||
- [x] Define LTD handling with monthly quotas and non-unlimited usage.
|
||||
- [x] Implement workspace-scoped billing foundation storage for:
|
||||
- billing accounts
|
||||
- usage periods
|
||||
- usage counters
|
||||
- add-on purchases
|
||||
- add-on balances
|
||||
- [x] Add billing repository/service layers and minimal account-data integration.
|
||||
- [x] Keep step `#5` foundation-only:
|
||||
- no Stripe/webhook integration yet
|
||||
- no route enforcement yet
|
||||
- no full billing UI rollout yet
|
||||
- [ ] Future note: `remaining = 0` for `not_available` resources is intentional and should stay aligned with entitlement semantics.
|
||||
- [ ] Future note: expired billing periods should fail closed for current usage-window resolution until subscription lifecycle automation can advance billing periods reliably.
|
||||
- [ ] Future note: consider exposing `usagePeriodId` later if enforcement, debugging, or admin tooling needs period-level traceability.
|
||||
- [ ] Future note: add transactional workflows around billing-account updates, usage updates, and add-on purchase/balance mutations once real payment flows are introduced.
|
||||
- [ ] Future note: `plan_code` is currently unconstrained text in the database; keep application-side validation strict unless a later migration adds stronger DB validation.
|
||||
- [ ] Future note: usage ownership is workspace-scoped in storage, but current operational enforcement is still catching up to that model.
|
||||
|
||||
## 6) Enforcement Architecture
|
||||
- [ ] Create a centralized entitlement/usage policy service on the backend.
|
||||
- [ ] Ensure all high-cost actions check entitlements before execution.
|
||||
- [ ] Start with enforcement on:
|
||||
- research routes
|
||||
- export routes
|
||||
- enrichment routes (future)
|
||||
- [ ] Add queue prioritization by plan tier.
|
||||
- [ ] Add throttling/fair-usage controls.
|
||||
- [ ] Add clear API responses for quota exhaustion and upgrade flows.
|
||||
- [x] Create a centralized entitlement/usage policy service on the backend.
|
||||
- [x] Ensure all high-cost actions check entitlements before execution.
|
||||
- [x] Start with enforcement on:
|
||||
- [x] research routes
|
||||
- [x] Bootstrap new and existing workspaces into a usable pre-payments Starter billing state so enforcement does not hard-block all chargeable actions before subscriptions exist.
|
||||
- [x] Reuse a shared deep-research estimate path so entitlement cost estimation and batch creation use the same preview-derived basis.
|
||||
- [x] Add clear API responses for quota exhaustion and upgrade flows.
|
||||
- [ ] Future note: the current enforcement slice should be treated as the core entitlement/runtime gate, not the full operational control layer.
|
||||
- [ ] Future note: the default Starter bootstrap is a pre-payments usability policy and should be revisited when real subscription lifecycle automation is implemented.
|
||||
|
||||
## 7) Workspace, User, and Collaboration Readiness
|
||||
- [ ] Review whether current data ownership is sufficiently workspace-scoped for plan promises.
|
||||
- [ ] Identify gaps between current user-scoped data model and promised team/workspace packaging.
|
||||
- [ ] Document which catalog limits can be enforced immediately versus only represented commercially at launch.
|
||||
- [ ] Define how to enforce:
|
||||
- users included
|
||||
- workspace limits
|
||||
- shared assets/lists
|
||||
- collaboration permissions
|
||||
- [ ] Decide whether some collaboration features need phased rollout rather than immediate sale.
|
||||
- [x] Review whether current data ownership is sufficiently workspace-scoped for plan promises.
|
||||
- [x] Identify gaps between current user-scoped data model and promised team/workspace packaging.
|
||||
- [x] Document which catalog limits can be enforced immediately versus only represented commercially at launch.
|
||||
- [x] Define how to enforce:
|
||||
- [x] users included
|
||||
- [x] workspace limits
|
||||
- [x] shared assets/lists
|
||||
- [x] collaboration permissions
|
||||
- [x] Decide whether some collaboration features need phased rollout rather than immediate sale.
|
||||
- [x] Add a shared workspace-readiness matrix covering:
|
||||
- current ownership scope
|
||||
- target ownership scope
|
||||
- enforceability state
|
||||
- collaboration phase definitions
|
||||
- [x] Document the current collaboration phase as workspace billing with mostly personal data ownership.
|
||||
- [x] Define the migration target for workspace ownership of:
|
||||
- `search_jobs`
|
||||
- `deep_research_batches`
|
||||
- `businesses`
|
||||
- `search_job_results`
|
||||
- [ ] Future note: before true collaboration is sold as real runtime behavior, core domain entities need `workspace_id` ownership and repository/query updates.
|
||||
- [ ] Future note: users included and workspace limits should remain soft-gated until multi-workspace UX and shared data ownership mature.
|
||||
- [ ] Future note: shared lists, tagging/notes, and collaboration permissions should not be treated as hard-enforceable features until the workspace migration is complete.
|
||||
|
||||
## 8) Add-On Strategy
|
||||
- [ ] Define export add-ons:
|
||||
## 8) Pricing Page & Account UX
|
||||
- [x] Build pricing page from canonical plan definitions instead of hardcoded copy.
|
||||
- [x] Derive pricing-card and comparison-table content from presentation metadata layered on top of the canonical catalog.
|
||||
- [x] Add plan comparison table.
|
||||
- [x] Add annual/monthly toggle.
|
||||
- [x] Add upgrade CTAs and contact-sales CTA.
|
||||
- [x] Add account/billing page showing:
|
||||
- [x] current plan
|
||||
- [x] billing interval
|
||||
- [x] usage this month
|
||||
- [x] remaining quota
|
||||
- [x] available add-ons
|
||||
- [x] upgrade options
|
||||
- [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: 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.
|
||||
|
||||
## 9) Add-On Strategy
|
||||
- [x] Define export add-ons:
|
||||
- +10k exports = $29
|
||||
- +50k exports = $99
|
||||
- [ ] Define enrichment packs:
|
||||
- [x] Define enrichment packs:
|
||||
- 1,000 enrichments = $49
|
||||
- [ ] Reserve future add-ons for:
|
||||
- [x] Reserve future add-ons for:
|
||||
- AI prospecting assistant
|
||||
- white-label / agency tools
|
||||
- higher API capacity
|
||||
- [ ] Decide whether add-ons are one-time, monthly recurring, or both.
|
||||
- [x] Decide whether add-ons are one-time, monthly recurring, or both.
|
||||
- [ ] Future note: launch active add-ons should stay limited to one-time export packs until enrichment delivery and payments lifecycle handling are live.
|
||||
- [ ] Future note: recurring feature add-ons should not be sold until the underlying capabilities and subscription management flows exist end-to-end.
|
||||
|
||||
## 9) Founder / LTD Strategy
|
||||
## 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.
|
||||
|
||||
## 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:
|
||||
@@ -217,29 +278,6 @@
|
||||
- [ ] Ensure founder plans have monthly quotas and exclude unlimited compute/API.
|
||||
- [ ] Define which future features are excluded from LTD plans.
|
||||
|
||||
## 10) Pricing Page & Account UX
|
||||
- [ ] Build pricing page from canonical plan definitions instead of hardcoded copy.
|
||||
- [ ] Derive pricing-card and comparison-table content from presentation metadata layered on top of the canonical catalog.
|
||||
- [ ] Add plan comparison table.
|
||||
- [ ] Add annual/monthly toggle.
|
||||
- [ ] Add upgrade CTAs and contact-sales CTA.
|
||||
- [ ] Add account/billing page showing:
|
||||
- current plan
|
||||
- billing interval
|
||||
- usage this month
|
||||
- remaining quota
|
||||
- available add-ons
|
||||
- upgrade options
|
||||
- [ ] Add quota warning UX before hard exhaustion.
|
||||
|
||||
## 11) 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.
|
||||
|
||||
## 12) Analytics, Ops, and Revenue Instrumentation
|
||||
- [ ] Track pricing-page conversion by plan.
|
||||
- [ ] Track quota exhaustion events.
|
||||
@@ -251,13 +289,33 @@
|
||||
- [ ] Track plan mix, churn, expansion revenue, and annual conversion.
|
||||
- [ ] Add internal dashboards for billing and usage health.
|
||||
|
||||
## 13) Rollout Plan
|
||||
## 13) Operational Enforcement Follow-Up
|
||||
- [ ] Add queue prioritization by plan tier.
|
||||
- [ ] Add throttling/fair-usage controls.
|
||||
- [ ] Add export-route enforcement once CSV/export generation moves to a backend endpoint.
|
||||
- [ ] Add enrichment-route enforcement once enrichment actions/routes are implemented.
|
||||
- [ ] Future note: queue prioritization is deferred until async worker routing or higher-volume queued execution becomes an active runtime path.
|
||||
- [ ] Future note: throttling/fair-usage controls are deferred until higher-volume execution patterns require operational protection.
|
||||
- [ ] 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
|
||||
- [ ] Phase 1: finalize canonical plan definitions, presentation metadata boundaries, and entitlement model.
|
||||
- [ ] Phase 2: implement usage ledger and backend enforcement.
|
||||
- [ ] Phase 3: update pricing page and account/billing UI.
|
||||
- [ ] Phase 4: integrate payments and subscription lifecycle handling.
|
||||
- [ ] Phase 5: launch add-ons and annual billing.
|
||||
- [ ] Phase 6: launch collaboration, API, enrichment, and enterprise features as architecture matures.
|
||||
- [ ] 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 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Open Questions
|
||||
- [ ] Will research capacity be marketed as runs, credits, or both?
|
||||
|
||||
Reference in New Issue
Block a user