# 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 - [ ] 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: - 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. ## 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. ## 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. ## 8) Add-On Strategy - [ ] Define export add-ons: - +10k exports = $29 - +50k exports = $99 - [ ] Define enrichment packs: - 1,000 enrichments = $49 - [ ] 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. ## 9) 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. ## 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. - [ ] 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. ## 13) 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. ## 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?