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.
• Implement workspace-scoped billing foundation storage for:
  • billing accounts
  • usage periods
  • usage counters
  • add-on purchases
  • add-on balances
• Add billing repository/service layers and minimal account-data integration.
• 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
• 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.
• Reuse a shared deep-research estimate path so entitlement cost estimation and batch creation use the same preview-derived basis.
• 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.
• Add a shared workspace-readiness matrix covering:
  • current ownership scope
  • target ownership scope
  • enforceability state
  • collaboration phase definitions
• Document the current collaboration phase as workspace billing with mostly personal data ownership.
• 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

• 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.
• 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

• 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.
• 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

• Choose billing provider (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.
• 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
• 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
• 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
• 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
• Add account redirect notices after Stripe return:
  • successful checkout/portal return confirmation
  • canceled or incomplete checkout messaging
  • failed or unresolved billing-return guidance
• 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:
  • 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) 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?