leads4less/TODO-pricing.md

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

• Update product messaging to emphasize:
  • local market intelligence
  • geographic prospecting
  • territory discovery
  • operational prospecting workflows
• Remove or reduce copy that frames the product as lead scraping or raw export tooling.
• Define a concise plan-comparison narrative for Starter, Growth, Pro, and Enterprise.
• 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

• Create a single source of truth for canonical plan definitions in code.
• Keep the canonical catalog separate from presentation metadata:
  • catalog = entitlements/commercial packaging data
  • presentation = pricing-card copy, marketing bullets, comparison-table labels
• Keep step #2 scoped to catalog/type design and pricing-page integration only.
• Define these initial SKUs:
  • starter_monthly
  • growth_monthly
  • pro_monthly
  • enterprise_custom
• Add annual counterparts with 20% discount support.
• Reserve type support for future founder/LTD SKUs without adding them to the active catalog yet.
• Add explicit catalog identity fields for each plan:
  • tier
  • billingInterval
  • isSelfServe
  • contactSalesRequired
• Include in each plan definition:
  • pricing
  • monthly usage limits
  • workspace/user limits
  • feature flags
  • queue priority / processing tier
  • add-on eligibility
• Treat workspace/user limits as commercial allowances first, not guaranteed enforceable constraints yet.
• Use customer-facing researchRunsPerMonth in the initial catalog and defer internal credit-ledger semantics to step #3.
• Add lightweight helper accessors around the catalog, for example:
  • getPlanByCode
  • getSelfServePlans
  • isAnnualPlan
  • getPlanDisplayMeta
• 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
• Add explicit listing semantics so public pricing visibility does not depend on billing interval.
• Add plan family / sibling linkage to support future annual toggles, plan switching, and analytics rollups.
• Reduce quantitative pricing bullet duplication by deriving core plan facts from structured catalog limits.
• 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

• Decide the internal usage model:
  • plan-based research runs, or
  • credit ledger with variable credit consumption per action
• Recommended default: use a credit system internally and simpler plan language externally.
• Keep the public catalog and pricing page centered on plan allowances, not internal billing mechanics.
• Define the research credit schedule, for example:
  • small local search = 1 credit
  • multi-radius query = 3-5 credits
  • enriched search = 10 credits
• Define export limits by plan:
  • Starter = 2,500/month
  • Growth = 15,000/month
  • Pro = 75,000/month
• Define what happens at limit exhaustion:
  • block
  • upgrade prompt
  • add-on purchase path
  • enterprise/contact sales path
• Implement a shared entitlement policy layer with:
  • usage resources/actions
  • plan-to-allowance translation helpers
  • action cost estimation helpers
  • pure entitlement decision helpers
• Separate capability gating from allowance checks in the entitlement layer.
• Add explicit allowance semantics so null does not silently mean allowed/unlimited.
• Add canonical action policy definitions for:
  • basic_search_run
  • deep_research_preview
  • deep_research_batch_run
  • csv_export
  • future enrichment_run
  • future api_request
• 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

• 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
• Starter
  • CSV export
  • map search
  • radius search
  • basic filters
  • exclude automations
  • exclude API access
  • exclude enrichments
  • exclude CRM integrations
  • exclude collaboration
• Growth
  • saved searches
  • territory mapping
  • advanced filtering
  • deduplication
  • export history
  • tagging & notes
  • faster processing
  • priority support
• Pro
  • shared lists
  • scheduled research
  • bulk exports
  • CRM integrations
  • webhooks/API
  • enrichment credits
  • collaboration features
• Enterprise
  • pooled or custom usage
  • SSO
  • SLA
  • white-labeling
  • onboarding / account management
  • dedicated infrastructure options
  • custom integrations
• Align feature-gate interpretation with entitlement action mappings in shared code.
• 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?