Skip to main content

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:

CaseClock startsLengthPhases
Widget installedcompanies.widget_installed_atcompanies.free_period_minutes (default 10)soft nudge (SoftNudgeBanner) while running → hard paywall (HardPaywallOverlay, "Your free session has ended.")
No widget, direct customer (!agency_id) — 8784dc51acompanies.created_atNO_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 — 6d57acecfwidget clock as aboveas aboveagency_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.

Copy mismatch

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_minutes for 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 in layouts/AppLayout.vue), store/app.js (graceEnd, hasActiveSubscription, isSubscriptionExpired).
  • Tests: backend/test/paywall-no-widget-grace.spec.js.