PSA/ee/docs/plans/2026-03-09-tier-trials-annual-billing/PRD.md

PRD — Tier Bug Fixes, Trials, Annual Billing & Payment Enforcement

• Slug: tier-trials-annual
• Date: 2026-03-09
• Status: Draft
• Depends on: 2026-03-03-tenant-tier-system

Summary

Extends the 2-tier system (Pro/Premium) with: (1) bug fixes and gaps identified in code review, (2) developer documentation for adding new tier-gated features, (3) annual billing at ~17% discount, (4) Stripe-managed trial periods (7-day Pro for new signups, 30-day Premium for paying Pro customers), (5) trial countdown UI in header + account page, (6) payment failure handling with reminders, and (7) a "Request Premium Trial" flow with manual fulfillment via Nine Minds extension.

Pricing

	Pro Monthly	Pro Annual	Premium Monthly	Premium Annual
Base fee	$89/mo	$890/yr (~$74.17/mo)	$349/mo	$3,490/yr (~$290.83/mo)
Per user	$12/user/mo	$120/user/yr (~$10/user/mo)	$25/user/mo	$250/user/yr (~$20.83/user/mo)

Annual = pay for 10 months, get 12 (~17% discount, "2 months free").

Problem

The tier system works but has bugs, no trials, no annual billing, no payment failure handling, and no documentation for extending it.

Goals

1. Fix all identified bugs and gaps in the tier system
2. Document how to add new tier-gated features (developer guide)
3. Add annual billing option with 17% discount
4. Implement 7-day free Pro trial for new accounts (CC required, auto-charge after)
5. Implement 30-day free Premium trial for paying Pro customers
6. Show trial days remaining in header (every page) and account page
7. Handle payment failures with reminders and visual "shame" indicators
8. Allow Pro users to request a Premium trial via in-app message form
9. Enable Nine Minds admins to manually process Premium trial requests

Non-goals

• Self-service downgrade flow (Premium → Pro)
• Automated Premium trial approval (intentionally manual)
• Public pricing page or tier comparison marketing page
• Refund processing (handled via Stripe dashboard)
• Free tier or freemium model

Users and Primary Flows

Personas

1. New signup — Visits website, picks Pro plan, enters CC, starts 7-day trial
2. Paying Pro customer — Wants to try Premium features, requests 30-day trial
3. Trialing user (Pro) — Sees countdown banner, decides to continue or cancel before charge
4. Trialing user (Premium) — Sees countdown with pricing breakdown, auto-charged at trial end unless they cancel back to Pro
5. Delinquent customer — Card declined, sees payment failure banner on every page
6. Nine Minds admin — Receives Premium trial requests, processes them via extension

Flow 1: New Pro Trial (7-day)

1. User signs up on website → Stripe Checkout with trial_period_days: 7
2. CC captured but not charged
3. User lands in app → header shows "Trial: 7 days left"
4. Day 7 → Stripe auto-charges first month (Pro monthly or annual, depending on selection)
5. 24-48 hour grace period: user can cancel for full refund (manual via support or Stripe portal)
6. If charge fails → payment failure flow (see Flow 5)

Flow 2a: Premium Trial for Paying Pro Customer (30-day)

1. Paying Pro customer (NOT on active trial) clicks "Upgrade to Premium" on account page
2. Instead of immediate upgrade, sees option to "Request 30-day Premium Trial"
3. Fills in message form (textarea) + "Send Request" button
4. Email notification sent to Nine Minds team
5. Admin activates 30-day Premium trial via Nine Minds extension
6. Customer gets Premium features immediately, header shows "Premium Trial: 30 days left"

Flow 2b: Premium Trial for Pro-Trialing Customer (edge case)

1. Customer on 7-day Pro trial wants Premium immediately
2. They request via same form (or contacts support)
3. Admin processes via Nine Minds extension — single action that:
   • Ends Pro trial immediately
   • Charges first month of Pro (customer is now a paying Pro customer)
   • Converts to Premium subscription with 30-day trial
4. Customer gets Premium features, header shows "Premium Trial: 30 days left"

Flow 3: Premium Trial Active & Ending

1. Admin activates trial → Stripe creates Premium subscription with trial_period_days: 30
2. Customer sees Premium features immediately, header shows "Premium Trial: 30 days left"
3. Account page shows pricing breakdown: "You'll be charged $X/mo when your trial ends on {date}"
4. Customer can cancel Premium trial early → reverts to Pro (cancel button on account page)
5. If customer does nothing → Stripe auto-charges for Premium at trial end, customer becomes paying Premium
6. If charge fails at trial end → payment failure flow (banner of shame)

Flow 4: Annual Billing

1. During checkout (new signup) or from account page (existing customer)
2. Toggle between monthly/annual pricing
3. Annual shows "2 months free" / "Save 17%"
4. Stripe handles annual recurring billing

Flow 5: Payment Failure ("Banner of Shame")

1. Stripe charge fails (card declined, expired, etc.)
2. Stripe subscription enters past_due status
3. App detects past_due from subscription data
4. Header banner: "Payment failed — update your payment method" (persistent, not dismissible)
5. Stripe retries per its retry schedule (Smart Retries)
6. Nine Minds team manually monitors delinquent accounts and contacts them
7. No automated feature lockout — banner of shame is the enforcement for now

UX / UI Notes

Trial Banner (Header)

• Position: left side of header, next to tenant UUID badge
• Style: consistent with existing UI (not a disruptive alert bar)
• Content: "{Plan} Trial: {N} days left" with link to account page
• Color: neutral/info for >3 days, warning for ≤3 days
• Always visible during trial, not dismissible

Payment Failure Banner (Header)

• Position: same area as trial banner (replaces trial banner if both apply)
• Style: destructive/error variant
• Content: "Payment failed — Update payment method" with link to billing portal
• Always visible, not dismissible

Account Page — Trial Section

• Shows trial status: plan name, days remaining, start/end dates
• Progress bar showing trial progress
• CTA varies by state:
  • Pro trial: "You'll be charged $X on {date}" + cancel option
  • Premium trial: "You'll be charged $X/mo for Premium on {date}" + "Cancel & revert to Pro" option
  • Payment failed: "Update payment method" link to billing portal

Premium Trial Request Form

• Location: Account Management page, in the Plan & Tier section
• Shown when: user is on Pro (paid or trialing) and clicks "Upgrade to Premium"
• UI: Simple textarea ("Tell us what you'd like to try with Premium") + "Send Request" button
• Confirmation: toast "Request sent! We'll be in touch."
• No dropdown, no complex form — just a message

Nine Minds Extension — Premium Trial Activation

• Existing Status column enhanced to show: current plan (Pro/Premium), trial status if trialing, subscription status (active/past_due/etc.)
• "Start Premium Trial" action button per tenant. Behavior depends on tenant state:
  • Paying Pro: creates Premium subscription with 30-day trial directly
  • Pro trial: ends Pro trial → charges first month of Pro → creates Premium subscription with 30-day trial (all in one action)
  • Button disabled/hidden for tenants already on Premium or Premium trial
• Premium trial request inbox: list of pending requests with tenant name, email, message, date
• Manual plan overrides (e.g. courtesy access) done directly in DB — no API exposed

Requirements

Bug Fixes

BF1: Fix stale JSDoc in tenantTiers.ts

• Replace references to 'basic' with 'pro' in docstrings for resolveTier() and ResolvedTier

BF2: Fix buildPhaseItems using wrong price for scheduled reductions

• buildPhaseItems() in StripeService must resolve price IDs based on the tenant's CURRENT tier, not pick first configured price
• Fetch tenant's plan, then use matching tier's price IDs

BF3: Add server-side assertTierAccess to invoice template save

• Verify assertTierAccess(TIER_FEATURES.INVOICE_DESIGNER) is called in saveInvoiceTemplate action
• If missing, add it (scratchpad says it was applied but analysis found gap — verify and fix)

BF4: Deduplicate JWT plan logic in nextAuthOptions.ts

• Extract shared plan-fetching logic into a helper function used by both buildAuthOptions() and static options

BF5: Add warning log for unknown Stripe product names

• In tierFromStripeProduct(), log a warning when product name doesn't match any known mapping
• Include product name and ID in the log for debugging

BF6: Add loading skeleton to TierGate

• Replace return null while loading with a skeleton placeholder
• Prevents empty flash during slow session loads

BF7: Add FK on stripe_base_price_id

• New migration adding foreign key from stripe_subscriptions.stripe_base_price_id to stripe_prices.stripe_price_id

BF8: Mark add-ons scaffolding as intentional

• Add clear JSDoc to addOns.ts explaining it's intentional scaffolding for future use
• Add // Scaffolding: not yet integrated into access checks comment

Documentation

DOC1: Tier Gating Developer Guide

• Create docs/tier-gating-guide.md
• Step-by-step: how to add a new feature to the tier gate
  1. Add feature to TIER_FEATURES enum
  2. Add to TIER_FEATURE_MAP for appropriate tiers
  3. Add to FEATURE_MINIMUM_TIER reverse map
  4. Gate UI with TierGate or ServerTierGate
  5. Gate server actions with assertTierAccess()
  6. Add display name in AccountManagement FEATURE_DISPLAY_NAMES
  7. Test: unit test for feature mapping, integration test for gating
• Include code examples from existing INVOICE_DESIGNER implementation
• Document CE bypass behavior

Annual Billing

AB1: Create annual Stripe prices

• Env vars: STRIPE_PRO_BASE_ANNUAL_PRICE_ID, STRIPE_PRO_USER_ANNUAL_PRICE_ID, STRIPE_PREMIUM_BASE_ANNUAL_PRICE_ID, STRIPE_PREMIUM_USER_ANNUAL_PRICE_ID
• Stripe prices created with recurring.interval: 'year' and 10-month pricing

AB2: Add billing_interval to subscription tracking

• Migration: add billing_interval column to stripe_subscriptions ('month' | 'year', default 'month')
• Update subscription import/create to track interval

AB3: Checkout supports annual option

• Modify checkout session creation to accept interval parameter
• Pass annual price IDs when interval === 'year'

AB4: Account page billing interval toggle

• Show monthly/annual toggle with savings callout
• Switching interval creates new subscription schedule or updates at period end

AB5: Upgrade flow supports annual billing

• upgradeTier() accepts interval parameter
• Uses annual price IDs when interval === 'year'

Trial System

TR1: Add trial fields to JWT/Session

• Add trial_end, subscription_status to JWT token and Session.user
• Refresh alongside plan (5-minute throttle)

TR2: Update TierContext with trial state

• Add to TierContextValue: isTrialing, trialDaysLeft, trialEndDate, subscriptionStatus
• Compute from session fields
• Add isPaymentFailed derived from subscriptionStatus === 'past_due'

TR3: Pro trial on new signup (7-day)

• Modify checkout session creation: add subscription_data.trial_period_days: 7
• CC captured via Checkout, not charged until trial ends
• Stripe auto-charges on trial end

TR4: Trial banner in header

• New TrialBanner component in Header
• Position: left side, next to tenant badge
• Shows: "{Plan} Trial: {N} days left"
• Links to /msp/account
• Warning color when ≤3 days remaining

TR5: Payment failure banner in header

• New PaymentFailedBanner component in Header
• Shows when subscriptionStatus === 'past_due' or 'unpaid'
• "Payment failed — Update payment method" linking to Stripe billing portal
• Error/destructive styling, not dismissible

TR6: Trial status on account page

• New "Trial Status" card in Account Management
• Shows: plan, days remaining, progress bar, start/end dates
• CTA varies by state (continue, upgrade, update payment)

TR7: Handle trial end → auto-charge

• Stripe handles this natively via trial_end on subscription
• Webhook customer.subscription.updated fires when trial ends and billing starts
• Ensure handleSubscriptionUpdated correctly processes trial → active transition

TR8: Handle trial end → payment failure

• If charge fails at trial end, subscription goes to past_due
• Payment failure banner appears
• Stripe Smart Retries handle retry logic

TR9: Premium trial (30-day) — manual activation

• New server action: startPremiumTrialAction(tenantId) (admin-only, master billing tenant)
• Detects tenant's current state and handles accordingly:
  • Paying Pro: creates Premium subscription with trial_period_days: 30
  • Pro trial: (a) ends Pro trial by removing trial_end on subscription, (b) Stripe charges first month of Pro immediately, (c) then creates Premium subscription with trial_period_days: 30
• Updates tenants.plan to 'premium'
• Customer sees Premium features immediately

TR10: Premium trial end — auto-charge or cancel

• Default (customer does nothing): Stripe auto-charges for Premium at trial end → customer becomes paying Premium
• Customer cancels during trial: "Cancel Premium Trial" button on account page → reverts subscription, sets tenants.plan back to 'pro'
• Webhook customer.subscription.updated handles both transitions:
  • trialing → active: auto-charge succeeded, customer is now paying Premium
  • trialing → canceled: customer cancelled during trial, revert to Pro
  • trialing → past_due: charge failed, show payment failure banner

TR11: Premium trial request form

• Textarea in Account Management (Plan & Tier section)
• Shown when: isPro && !isTrialing and user clicks "Upgrade to Premium"
• Server action: sendPremiumTrialRequestAction(message)
• Sends email to Nine Minds support with tenant info + message

TR12: Premium trial request — NineMinds extension

• Add "Trial Requests" section to TenantManagementView
• List pending requests with: tenant name, email, message, date
• "Start Premium Trial" action button per request
• Action calls API: POST /api/v1/tenant-management/start-premium-trial
• API endpoint: validates admin, calls startPremiumTrialAction(tenantId)

Payment Enforcement

PE1: Track subscription_status in session

• Already covered by TR1 (subscription_status in JWT)

PE2: Payment failure detection

• handleSubscriptionUpdated webhook sets local status to match Stripe
• Status propagates to JWT on next refresh (≤5 min)

PE3: Visual payment reminder

• Already covered by TR5 (payment failure banner)

PE4: Grace period documentation

• Document 24-48 hour cancellation window after first charge post-trial
• This is handled via Stripe billing portal / support — no custom code needed

Data / API / Integrations

New Database Columns

stripe_subscriptions:

• billing_interval (text, default 'month') — 'month' | 'year'

No new tables needed. Trial state comes from Stripe subscription fields (trial_end, status).

New JWT/Session Fields

• trial_end: number | null — Unix timestamp of trial end
• subscription_status: string | null — 'active' | 'trialing' | 'past_due' | 'unpaid' | 'canceled'

New API Endpoints

• POST /api/v1/tenant-management/start-premium-trial — Admin-only, starts 30-day Premium trial

• POST /api/v1/tenant-management/trial-requests — List pending trial requests

• Server action: sendPremiumTrialRequestAction(message) — Sends email notification

New Env Vars

• STRIPE_PRO_BASE_ANNUAL_PRICE_ID
• STRIPE_PRO_USER_ANNUAL_PRICE_ID
• STRIPE_PREMIUM_BASE_ANNUAL_PRICE_ID
• STRIPE_PREMIUM_USER_ANNUAL_PRICE_ID
• TRIAL_REQUEST_EMAIL — Email address for Premium trial requests (default: support@nineminds.com)

Security / Permissions

• startPremiumTrialAction restricted to master billing tenant only
• Trial state read from Stripe (authoritative) via webhooks, not client-editable
• Payment failure banner cannot be dismissed (prevents ignoring payment issues)

Rollout

Phase 1: Bug Fixes & Documentation

• All BF* and DOC* items — safe to deploy, no behavior change

Phase 2: Annual Billing

• AB* items — new Stripe prices must be created in Stripe Dashboard first
• Feature-flagged: annual-billing flag controls visibility of annual toggle

Phase 3: Trial System

• TR* and PE* items — requires Stripe price configuration
• Feature-flagged: trial-system flag controls trial creation on checkout
• Premium trial is manual-only, no flag needed

Resolved Questions

1. What happens when subscription goes unpaid? → Banner of shame + manual monitoring/outreach by Nine Minds. No automated lockout for now.
2. Annual mid-year cancellation refund? → Case-by-case manual process via support.
3. 24-48hr grace period after first charge? → Support policy only. Handled via Stripe portal/support, no custom code.

Acceptance Criteria

1. All 8 bugs fixed and verified
2. Developer guide published and covers full tier-gating workflow
3. Annual billing toggle works on checkout and account page
4. New signups get 7-day Pro trial with CC capture
5. Trial countdown visible in header on every page
6. Payment failure banner visible when subscription is past_due
7. Pro customers can request Premium trial via in-app form
8. Nine Minds admins can activate Premium trials from extension
9. Premium trial auto-charges at end unless customer cancels back to Pro
10. Customer can cancel Premium trial and revert to Pro from account page