# TODO: LocaleScope Pricing & Packaging Design ## Goals - [ ] Position LocaleScope as a local market intelligence platform, not a scraper/export commodity. - [ ] Align pricing, packaging, product capabilities, and billing enforcement to a single plan model. - [ ] Protect infrastructure with quotas, credits, throttling, and priority processing. - [ ] Preserve room for future AI, enrichment, API, collaboration, and enterprise expansion. ## 1) Product & Marketing Alignment - [x] Update product messaging to emphasize: - local market intelligence - geographic prospecting - territory discovery - operational prospecting workflows - [x] Remove or reduce copy that frames the product as lead scraping or raw export tooling. - [x] Define a concise plan-comparison narrative for Starter, Growth, Pro, and Enterprise. - [x] Make Growth the obvious value anchor in pricing page design and copy. - [ ] Decide whether to update historical/internal naming artifacts separately: - `CHANGELOG.md` historical branding references - `package.json` package name ## 2) Canonical Plan Definitions - [x] Create a single source of truth for canonical plan definitions in code. - [x] Keep the canonical catalog separate from presentation metadata: - catalog = entitlements/commercial packaging data - presentation = pricing-card copy, marketing bullets, comparison-table labels - [x] Keep step `#2` scoped to catalog/type design and pricing-page integration only. - [x] Define these initial SKUs: - `starter_monthly` - `growth_monthly` - `pro_monthly` - `enterprise_custom` - [x] Add annual counterparts with 20% discount support. - [x] Reserve type support for future founder/LTD SKUs without adding them to the active catalog yet. - [x] Add explicit catalog identity fields for each plan: - `tier` - `billingInterval` - `isSelfServe` - `contactSalesRequired` - [x] Include in each plan definition: - pricing - monthly usage limits - workspace/user limits - feature flags - queue priority / processing tier - add-on eligibility - [x] Treat workspace/user limits as commercial allowances first, not guaranteed enforceable constraints yet. - [x] Use customer-facing `researchRunsPerMonth` in the initial catalog and defer internal credit-ledger semantics to step `#3`. - [x] Add lightweight helper accessors around the catalog, for example: - `getPlanByCode` - `getSelfServePlans` - `isAnnualPlan` - `getPlanDisplayMeta` - [x] Expand shared billing/account types only enough to support future plan display: - current plan code nullable - billing interval nullable - billing status/message - no real subscription persistence yet - [x] Add explicit listing semantics so public pricing visibility does not depend on billing interval. - [x] Add plan family / sibling linkage to support future annual toggles, plan switching, and analytics rollups. - [x] Reduce quantitative pricing bullet duplication by deriving core plan facts from structured catalog limits. - [x] Encode internal feature readiness notes for marketed-but-not-yet-enforced capabilities. - [ ] Follow-up recommendation: clarify whether `getPlanByCode` should stay active-catalog-only or be renamed to make reserved-code behavior explicit. - [ ] Follow-up recommendation: revisit whether `planFamily` should remain separate from `tier` or be consolidated later. - [ ] Follow-up recommendation: consider moving shared plan price/period formatting helpers into the billing domain once account and pricing UI expand. - [ ] Follow-up recommendation: extend readiness modeling beyond feature flags if later steps need readiness for support, processing, or add-on availability. ## 3) Packaging & Entitlement Model - [x] Decide the internal usage model: - plan-based research runs, or - credit ledger with variable credit consumption per action - [x] Recommended default: use a credit system internally and simpler plan language externally. - [x] Keep the public catalog and pricing page centered on plan allowances, not internal billing mechanics. - [x] Define the research credit schedule, for example: - small local search = 1 credit - multi-radius query = 3-5 credits - enriched search = 10 credits - [x] Define export limits by plan: - Starter = 2,500/month - Growth = 15,000/month - Pro = 75,000/month - [x] Define what happens at limit exhaustion: - block - upgrade prompt - add-on purchase path - enterprise/contact sales path - [x] Implement a shared entitlement policy layer with: - usage resources/actions - plan-to-allowance translation helpers - action cost estimation helpers - pure entitlement decision helpers - [x] Separate capability gating from allowance checks in the entitlement layer. - [x] Add explicit allowance semantics so `null` does not silently mean allowed/unlimited. - [x] Add canonical action policy definitions for: - `basic_search_run` - `deep_research_preview` - `deep_research_batch_run` - `csv_export` - future `enrichment_run` - future `api_request` - [x] Keep step `#3` policy-only: - no DB persistence yet - no route enforcement yet - no billing-provider integration yet - [ ] Future note: `evaluateActionEntitlement()` is policy-only and later steps must provide real remaining-usage inputs from subscription/account state. - [ ] Future note: missing readiness metadata currently implies `launch_ready`; keep readiness annotations current as new gated features are added. - [ ] Future note: `api_requests` and `enrichments` are modeled ahead of full product implementation; do not treat them as launch-ready by default. - [ ] Future note: deep research costing should stay aligned with preview-derived estimates and should not diverge into a second billing algorithm. - [ ] Future note: export policy is defined, but reliable export enforcement requires a future backend export endpoint. - [ ] Future note: usage subject remains `user` until workspace-scoped ownership and pooled usage are ready. - [ ] Future note: `territoryMapping` currently carries deep-research capability semantics and may need a dedicated capability later if gating becomes more granular. ## 4) Feature Gates by Plan - [x] Implement a shared feature-gate interpreter layer that resolves feature state by plan using: - plan feature flags - feature readiness metadata - self-serve vs enterprise upgrade paths - [x] Starter - [x] CSV export - [x] map search - [x] radius search - [x] basic filters - [x] exclude automations - [x] exclude API access - [x] exclude enrichments - [x] exclude CRM integrations - [x] exclude collaboration - [x] Growth - [x] saved searches - [x] territory mapping - [x] advanced filtering - [x] deduplication - [x] export history - [x] tagging & notes - [x] faster processing - [x] priority support - [x] Pro - [x] shared lists - [x] scheduled research - [x] bulk exports - [x] CRM integrations - [x] webhooks/API - [x] enrichment credits - [x] collaboration features - [x] Enterprise - [x] pooled or custom usage - [x] SSO - [x] SLA - [x] white-labeling - [x] onboarding / account management - [x] dedicated infrastructure options - [x] custom integrations - [x] Align feature-gate interpretation with entitlement action mappings in shared code. - [x] Keep step `#4` shared-policy only: - no broad UI rollout yet - no backend route enforcement yet - no usage-ledger coupling yet - [ ] Future note: make upgrade recommendations readiness-aware so users are not prompted to upgrade into tiers where the target feature is still `coming_soon`. - [ ] Future note: consolidate action ↔ feature mapping into one canonical source shared by `entitlements.ts` and `feature-gates.ts` to avoid drift between UI gating and backend action policy. - [ ] Future note: for Enterprise plans, included-but-not-ready features should usually resolve to `coming_soon` instead of `contact_sales`. - [ ] 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 - [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) - [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 - [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 - [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) 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 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. ## 9) Add-On Strategy - [x] Define export add-ons: - +10k exports = $29 - +50k exports = $99 - [x] Define enrichment packs: - 1,000 enrichments = $49 - [x] Reserve future add-ons for: - AI prospecting assistant - white-label / agency tools - higher API capacity - [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. ## 10) Payments Integration - [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) 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 - [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 - [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. - [ ] 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) 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: 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: `#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? - [ ] Which collaboration/team features are truly launch-ready? - [ ] Should workspace limits be hard-enforced at launch or soft-gated initially? - [ ] Which add-ons launch on day one vs later? - [ ] Is founder/LTD part of launch or a separate campaign? - [ ] What exact enterprise triggers require custom sales instead of self-serve? - [ ] Which plan data belongs in the canonical catalog versus presentation metadata?