Free Session, Paywall & Trials
Audience: Sales / Finance / Support (engineers for the technical section) · Where in app: dashboard paywall banners/overlay; Packages & Billing → Select Plan · Plan availability: self-serve direct customers
There is no automatic trial subscription on signup. A new self-serve tenant evaluates the product through a short free session enforced by a client-side paywall; to keep going they buy a package, which may itself carry a Stripe trial. (Older copy and this page's previous version described an automatic "7-day trial with no card" — that is not how the code works.)
The free-session paywall
GET /company/paywall-status (CompanyController.paywallStatus, company looked up by user_id — i.e. the web owner) computes the phase server-side; usePaywallStatus.js renders it and schedules a timer to re-fetch exactly when the clock runs out (no polling).
"Active subscription" = a SubscriptionModel row with subscription_status in active / trialing — the welcome wallet row (welcome_wallet: true, see Wallet) never counts. With none:
| Case | Clock starts | Length | Phases |
|---|---|---|---|
| Widget installed | companies.widget_installed_at | companies.free_period_minutes (default 10) | soft nudge (SoftNudgeBanner) while running → hard paywall (HardPaywallOverlay, "Your free session has ended.") |
No widget, direct customer (!agency_id) — 8784dc51a | companies.created_at | NO_WIDGET_GRACE_MINUTES = 30 (fixed, not per company) | hard paywall only (the PaywallInstallBanner "Your widget isn't installed yet" is the nudge) |
| No widget, agency client | — | — | never paywalled here (billed by the agency) |
Agency's own site, self-serve agency, no agency plan — 6d57acecf | widget clock as above | as above | agency_plan_needed: true → same phases in agency mode (below) |
Before 8784dc51a a direct customer who never installed the widget (e.g. phone agents only) was never asked to pay.
Response fields: paywall_clock_started_at, paywall_clock_minutes, no_widget_grace, widget_installed(_at), minutes_since_install, visitor_count_since_install, soft_nudge_active, hard_paywall_active, free_period_minutes, grace_period_claimed, has_active_subscription. The frontend times the switch from paywall_clock_started_at + paywall_clock_minutes (falling back to widget_installed_at / free_period_minutes for older backends).
Agency own-site paywall (6d57acecf, frontend 05e656c5): agency_plan_needed is true when the company is its agency's own site (agency_self_account), the agency is self-serve (agencies.self_serve_signup_at, set only by the "I'm an agency" signup paths together with trial: true, trial_duration: 7) and it has no active, unexpired agency_subscriptions row; the own site is then treated as unpaid. Because the no-widget grace excludes anything with agency_id, it only starts once the widget is installed. Agencies made by conversion don't carry self_serve_signup_at, so it never applies to them. GET /companies?self_account=1 backs the portal's My website switch.
Overlay copy (HardPaywallOverlay.vue): with visitors since install ("live proof", real sessions) — "Your widget is working · N on your site now", "N people have visited your site". Business mode: CTA Start my free trial and see them / Start my free trial straight to packages-checkout for the plan they registered with (registered_package_id / register_pkg), else the popular trial plan, else the cheapest; line "N days free, then $X/month for <plan>." + Compare plans; the no-proof branch still says "Your free session has ended." / "Start your 7-day free trial…". Direct owners who can self-convert also get "Setting this up for clients? Convert to an agency account" (see Agency overview). Agency mode: "That's what each of your clients will see. Choose your agency plan…" (or "Your demo site is ready"), Choose my agency plan → agency portal agency-portal-setup?step=plan, "Your first plan starts with a 7-day free trial." (agency.trial_duration while trial && !trial_activated_at). SoftNudgeBanner has matching agency copy ("N visitors have already landed on your demo site…").
Exemptions: partner demo accounts (partner_certification_enabled and never bought a non-free subscription) — see Certification. The overlay also stays hidden on the packages/checkout/cards routes and during an active call or open chat.
One-time grace claim
POST /company/claim-grace-period resets widget_installed_at to now and sets companies.grace_period_claimed: true — a fresh free session, once per company. Refused if already claimed or the widget isn't installed. The overlay's "Just installed? Claim your free N-minute session" link is hidden when no_widget_grace is true (there is no install to restart from); its label uses free_period_minutes, not minutes since install (4a0812b0).
free_period_minutes is a super-admin per-company setting (CompanyController admin endpoint; stripped from tenant $sets along with grace_period_claimed). It is the paywall session length — not a pool of free AI-voice minutes.
Buying a plan / package trials
The paywall CTAs go to Packages & Billing (views/packages/Index.vue). Since 4a0812b0 that page no longer advertises a trial: header "Choose your plan" / "Pick a package to get started — cancel anytime", button Select Plan (or Change Plan), price "/mo", and the "How your trial works" sidebar is gone.
Trials are per package: PackageModel.free_trial === 'yes' with trial_limit days (Stripe trial_period_days, default 7 in StripeService) and optional trial_without_card. Checkout (Checkout.vue) shows "N-day free trial · Cancel anytime" and sends trial: true only for a tenant with no existing subscription; SubscriptionController honours it only when the package allows. The subscription row then has is_trial: true.
The overlay's no-visitors branch still says "Start your 7-day free trial" and its plan line falls back to 7 days when the picked plan has no trial, while the packages page dropped all trial copy. Whether a trial exists depends on the package picked.
Post-expiry grace (frontend)
store/app.js graceEnd(sub) keeps access after expiry_date regardless of status (active, past_due, …): 7 days for direct customers (covers Stripe's retry window), 3 hours for agency clients (3777038c; a client's expiry is the agency period end + 30 min, so a declined agency payment locks clients ~3.5 h after the period ends). is_trial subscriptions are handled separately (isTrialExpired).
Once locked, agency clients — owners and members — go to inform-agency (2e3d4f2c): "Subscription Expired … managed by <agency>" (agency name from agencyBranding, fallback "your provider"); owners are forwarded to packages-agency-billing when the agency takes payment online (can_pay / live billing), members stay (they lack invoices.getAll, which previously bounced them dashboard ↔ billing forever — 3e34543c). The expired banner reads "Contact <agency> to renew your account subscription and keep using all features." (41e6828c). The router re-reads the subscription once before locking a client who just paid (a7ab9c47).
Behaviors & edge cases
- When a subscription lapses the identity-graph subscription gate trips → the AI sees only the current session. See /subsystems/identity-graph.
- Add-on purchases need an active subscription.
- Sales-led extensions: a super admin can raise
free_period_minutesfor a company.
Technical implementation
- Backend:
CompanyController.paywallStatus/claimGracePeriod(routes/CompanyRoutes.js),SubscriptionController(package trial),StripeService(trial_period_days). - Models:
companies.free_period_minutes,companies.grace_period_claimed,companies.widget_installed_at,SubscriptionModel.is_trial,PackageModel.free_trial/trial_limit/trial_without_card. - Frontend:
composables/usePaywallStatus.js,components/paywall/{SoftNudgeBanner,HardPaywallOverlay,PaywallInstallBanner,CelebrationOverlay}.vue(mounted inlayouts/AppLayout.vue),store/app.js(graceEnd,hasActiveSubscription,isSubscriptionExpired). - Tests:
backend/test/paywall-no-widget-grace.spec.js.