Skip to main content

Pastor upgrades chat plan

Persona​

A church on Starter Chat ($14.95/mo) for 3 months. Chatbot is working — 30+ prayer requests and 40+ visitor contacts monthly. Pastor now wants analytics, custom FAQs, and the Simulator to test the chatbot against scenarios. They want the "safe ladder" upgrade: same product family (chat), just more features.

Entry points​

  1. Billing section — /admin/[token]?tab=settings → Billing → "Upgrade Plan."
  2. Approaching limit email — "You're nearing your 200-message/month limit. Upgrade to Pro for 500/month."
  3. Limit exceeded banner — "You've reached your monthly limit. Upgrade to continue."
  4. Proactive upsell — "You're using [X]% of your message limit. Pro Chat includes 500 messages/month and analytics."

Click-through flow​

Steps​

  1. Open Billing section — Shows "Current Plan: Starter Chat — $14.95/mo," next billing date. "Upgrade Plan" button.

  2. Select Pro Chat — Pricing page highlights current plan. Pro Chat card shows "$34.95/mo" with 500 conversations, analytics, FAQ management, Simulator. "Upgrade to Pro" button.

  3. Stripe Checkout — Upgrade flow: subscriptions.update({ items: [{ id: <current_item_id>, price: <pro_price_id> }], proration_behavior: 'create_prorations' }). On success, webhook fires customer.subscription.updated.

  4. Webhook processing + plan update — processStripeEvent() calls updateSubscriptionTier(). Critical: premium_churches.plan is updated with raw Stripe key 'cwa_pro_chat' — NEVER the collapsed tier 'pro' from normalizePlanTier(). Writing the collapsed value breaks isProWebsitePlan(), PRO_WEBSITE_PLANS, and Website-tab gating. This was the P0 on 2026-04-17.

  5. Dashboard reflects new plan — Training tab reveals FAQs and Simulator sub-tabs (were hidden on Starter). Settings → Billing shows "Pro Chat — $34.95/mo." Message limit is now 500/month, resetting on next billing date.

Acceptance spec​

Canonical: knowledge/acceptance/pro-suite-chat.md

Pro Chat vs Starter Chat:

  • 500 responses/month (vs 200)
  • 35 tools (vs 12)
  • 4 agents (vs 2)
  • 50 FAQs (vs 0)
  • 5 uploaded documents (vs 0)
  • 30-day analytics (vs none)
  • 6 Simulator test paths (vs none)

Safe-ladder upgrades: Starter Chat → Pro Chat, Starter Chat → Suite Chat. Cross-family (Chat to Voice) returns 400 and requires cancelling and rebuying.

Success criteria​

  • Plan updates within 1 minute of Stripe success.
  • FAQs, Analytics, Simulator tabs appear without page reload.
  • Billing section shows "Current Plan: Pro Chat — $34.95/mo."
  • Service continues uninterrupted during upgrade.

Known failure modes​

  • Plan key collision. normalizePlanTier('cwa_pro_chat') returns 'pro' — if this is written to DB, queries checking plan IN ('cwa_pro_chat', ...) fail. Verify all writes to premium_churches.plan use raw Stripe keys. Source: memory/feedback_plan_tier_not_persisted.md.

  • Cross-family upgrade rejected with confusing error. Workaround: "Upgrading from Chat to Voice requires switching plans. Email support@churchwiseai.com for zero-downtime help." Tracked in GitHub issue FA-082.

  • Webhook loss on update. If customer.subscription.updated is dropped, Stripe succeeds but DB plan never updates. Verify idempotency check on event ID in stripe_webhook_inbox. Source: memory/project_stripe_webhook_inbox.md.

  • New features not gating properly. If tier-config.ts is cached, FAQ/Analytics tabs may not appear post-upgrade. Add revalidateTag('tier-config') after plan updates.