feat: add annual billing, free trial, upgrade/downgrade, and ACH invoice support

- Add monthly/annual billing toggle with 25% annual discount on pricing page
- Implement 14-day no-card free trial (server-side Stripe subscription creation)
- Enable upgrade/downgrade via Stripe Customer Portal
- Add admin-initiated ACH/invoice billing for enterprise customers
- Add billing card to Settings page with plan info and Manage Billing button
- Handle past_due status with read-only grace period access
- Add trial ending and trial expired email templates
- Add DB migration for billing_interval and collection_method columns
- Update ONBOARDING-AND-AUTH.md documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

frontend/src/pages/pricing/PricingPage.tsx

@@ -1,19 +1,21 @@
 import { useState } from 'react';
 import {
   Container, Title, Text, SimpleGrid, Card, Stack, Group, Badge,
-  Button, List, ThemeIcon, TextInput, Center, Alert,
+  Button, List, ThemeIcon, TextInput, Center, Alert, SegmentedControl, Box,
 } from '@mantine/core';
 import { IconCheck, IconX, IconRocket, IconStar, IconCrown, IconAlertCircle } from '@tabler/icons-react';
 import { useNavigate } from 'react-router-dom';
 import api from '../../services/api';
 import logoSrc from '../../assets/logo.png';
 
+type BillingInterval = 'month' | 'year';
+
 const plans = [
   {
     id: 'starter',
     name: 'Starter',
-    price: '$29',
-    period: '/month',
+    monthlyPrice: 29,
+    annualPrice: 261, // 29 * 12 * 0.75
     description: 'For small communities getting started',
     icon: IconRocket,
     color: 'blue',
@@ -29,8 +31,8 @@ const plans = [
   {
     id: 'professional',
     name: 'Professional',
-    price: '$79',
-    period: '/month',
+    monthlyPrice: 79,
+    annualPrice: 711, // 79 * 12 * 0.75
     description: 'For growing HOAs that need full features',
     icon: IconStar,
     color: 'violet',
@@ -47,8 +49,8 @@ const plans = [
   {
     id: 'enterprise',
     name: 'Enterprise',
-    price: 'Custom',
-    period: '',
+    monthlyPrice: 0,
+    annualPrice: 0,
     description: 'For large communities and management firms',
     icon: IconCrown,
     color: 'orange',
@@ -64,29 +66,53 @@ const plans = [
   },
 ];
 
+function formatPrice(plan: typeof plans[0], interval: BillingInterval) {
+  if (plan.externalUrl) return { display: 'Custom', sub: '' };
+  if (interval === 'year') {
+    const monthly = (plan.annualPrice / 12).toFixed(2);
+    return {
+      display: `$${monthly}`,
+      sub: `/mo billed annually ($${plan.annualPrice}/yr)`,
+    };
+  }
+  return { display: `$${plan.monthlyPrice}`, sub: '/month' };
+}
+
 export function PricingPage() {
   const navigate = useNavigate();
   const [loading, setLoading] = useState<string | null>(null);
   const [error, setError] = useState('');
   const [email, setEmail] = useState('');
   const [businessName, setBusinessName] = useState('');
+  const [billingInterval, setBillingInterval] = useState<BillingInterval>('month');
+
+  const handleStartTrial = async (planId: string) => {
+    if (!email.trim()) {
+      setError('Email address is required to start a trial');
+      return;
+    }
+    if (!businessName.trim()) {
+      setError('HOA / Business name is required to start a trial');
+      return;
+    }
 
-  const handleSelectPlan = async (planId: string) => {
     setLoading(planId);
     setError('');
     try {
-      const { data } = await api.post('/billing/create-checkout-session', {
+      const { data } = await api.post('/billing/start-trial', {
         planId,
-        email: email || undefined,
-        businessName: businessName || undefined,
+        billingInterval,
+        email: email.trim(),
+        businessName: businessName.trim(),
       });
-      if (data.url) {
-        window.location.href = data.url;
+      if (data.subscriptionId) {
+        // Navigate to pending page with subscription ID for polling
+        navigate(`/onboarding/pending?session_id=${data.subscriptionId}`);
       } else {
-        setError('Unable to create checkout session');
+        setError('Unable to start trial');
       }
     } catch (err: any) {
-      setError(err.response?.data?.message || 'Failed to start checkout');
+      setError(err.response?.data?.message || 'Failed to start trial');
     } finally {
       setLoading(null);
     }
@@ -104,20 +130,48 @@ export function PricingPage() {
         </Text>
       </Stack>
 
-      {/* Optional pre-capture fields */}
+      {/* Monthly / Annual Toggle */}
+      <Center mb="xl">
+        <Box pos="relative">
+          <SegmentedControl
+            value={billingInterval}
+            onChange={(val) => setBillingInterval(val as BillingInterval)}
+            data={[
+              { label: 'Monthly', value: 'month' },
+              { label: 'Annual', value: 'year' },
+            ]}
+            size="md"
+            radius="xl"
+          />
+          {billingInterval === 'year' && (
+            <Badge
+              color="green"
+              variant="filled"
+              size="sm"
+              style={{ position: 'absolute', top: -10, right: -40 }}
+            >
+              Save 25%
+            </Badge>
+          )}
+        </Box>
+      </Center>
+
+      {/* Pre-capture fields (required for trial) */}
       <Center mb="xl">
         <Group>
           <TextInput
-            placeholder="Email address"
+            placeholder="Email address *"
             value={email}
             onChange={(e) => setEmail(e.currentTarget.value)}
             style={{ width: 220 }}
+            required
           />
           <TextInput
-            placeholder="HOA / Business name"
+            placeholder="HOA / Business name *"
             value={businessName}
             onChange={(e) => setBusinessName(e.currentTarget.value)}
             style={{ width: 220 }}
+            required
           />
         </Group>
       </Center>
@@ -129,87 +183,101 @@ export function PricingPage() {
       )}
 
       <SimpleGrid cols={{ base: 1, sm: 2, lg: 3 }} spacing="lg">
-        {plans.map((plan) => (
-          <Card
-            key={plan.id}
-            withBorder
-            shadow={plan.popular ? 'lg' : 'sm'}
-            radius="md"
-            p="xl"
-            style={plan.popular ? {
-              border: '2px solid var(--mantine-color-violet-5)',
-              position: 'relative',
-            } : undefined}
-          >
-            {plan.popular && (
-              <Badge
-                color="violet"
-                variant="filled"
-                style={{ position: 'absolute', top: -10, right: 20 }}
-              >
-                Most Popular
-              </Badge>
-            )}
+        {plans.map((plan) => {
+          const price = formatPrice(plan, billingInterval);
+          return (
+            <Card
+              key={plan.id}
+              withBorder
+              shadow={plan.popular ? 'lg' : 'sm'}
+              radius="md"
+              p="xl"
+              style={plan.popular ? {
+                border: '2px solid var(--mantine-color-violet-5)',
+                position: 'relative',
+              } : undefined}
+            >
+              {plan.popular && (
+                <Badge
+                  color="violet"
+                  variant="filled"
+                  style={{ position: 'absolute', top: -10, right: 20 }}
+                >
+                  Most Popular
+                </Badge>
+              )}
+
+              <Stack gap="md">
+                <Group>
+                  <ThemeIcon size="lg" color={plan.color} variant="light" radius="md">
+                    <plan.icon size={20} />
+                  </ThemeIcon>
+                  <div>
+                    <Text fw={700} size="lg">{plan.name}</Text>
+                    <Text size="xs" c="dimmed">{plan.description}</Text>
+                  </div>
+                </Group>
 
-            <Stack gap="md">
-              <Group>
-                <ThemeIcon size="lg" color={plan.color} variant="light" radius="md">
-                  <plan.icon size={20} />
-                </ThemeIcon>
                 <div>
-                  <Text fw={700} size="lg">{plan.name}</Text>
-                  <Text size="xs" c="dimmed">{plan.description}</Text>
+                  <Group align="baseline" gap={4}>
+                    <Text fw={800} size="xl" ff="monospace" style={{ fontSize: plan.externalUrl ? 28 : 36 }}>
+                      {plan.externalUrl ? 'Request Quote' : price.display}
+                    </Text>
+                  </Group>
+                  {price.sub && (
+                    <Text size="xs" c="dimmed" mt={2}>
+                      {price.sub}
+                    </Text>
+                  )}
+                  {!plan.externalUrl && billingInterval === 'year' && (
+                    <Text size="xs" c="dimmed" td="line-through" mt={2}>
+                      ${plan.monthlyPrice}/mo without annual discount
+                    </Text>
+                  )}
                 </div>
-              </Group>
 
-              <Group align="baseline" gap={4}>
-                <Text fw={800} size="xl" ff="monospace" style={{ fontSize: plan.externalUrl ? 28 : 36 }}>
-                  {plan.externalUrl ? 'Request Quote' : plan.price}
-                </Text>
-                {plan.period && <Text size="sm" c="dimmed">{plan.period}</Text>}
-              </Group>
+                <List spacing="xs" size="sm" center>
+                  {plan.features.map((f, i) => (
+                    <List.Item
+                      key={i}
+                      icon={
+                        <ThemeIcon
+                          size={20}
+                          radius="xl"
+                          color={f.included ? 'teal' : 'gray'}
+                          variant={f.included ? 'filled' : 'light'}
+                        >
+                          {f.included ? <IconCheck size={12} /> : <IconX size={12} />}
+                        </ThemeIcon>
+                      }
+                    >
+                      <Text c={f.included ? undefined : 'dimmed'}>{f.text}</Text>
+                    </List.Item>
+                  ))}
+                </List>
 
-              <List spacing="xs" size="sm" center>
-                {plan.features.map((f, i) => (
-                  <List.Item
-                    key={i}
-                    icon={
-                      <ThemeIcon
-                        size={20}
-                        radius="xl"
-                        color={f.included ? 'teal' : 'gray'}
-                        variant={f.included ? 'filled' : 'light'}
-                      >
-                        {f.included ? <IconCheck size={12} /> : <IconX size={12} />}
-                      </ThemeIcon>
-                    }
-                  >
-                    <Text c={f.included ? undefined : 'dimmed'}>{f.text}</Text>
-                  </List.Item>
-                ))}
-              </List>
-
-              <Button
-                fullWidth
-                size="md"
-                color={plan.color}
-                variant={plan.popular ? 'filled' : 'light'}
-                loading={!plan.externalUrl ? loading === plan.id : false}
-                onClick={() =>
-                  plan.externalUrl
-                    ? window.open(plan.externalUrl, '_blank', 'noopener')
-                    : handleSelectPlan(plan.id)
-                }
-              >
-                {plan.externalUrl ? 'Request Quote' : 'Get Started'}
-              </Button>
-            </Stack>
-          </Card>
-        ))}
+                <Button
+                  fullWidth
+                  size="md"
+                  color={plan.color}
+                  variant={plan.popular ? 'filled' : 'light'}
+                  loading={!plan.externalUrl ? loading === plan.id : false}
+                  onClick={() =>
+                    plan.externalUrl
+                      ? window.open(plan.externalUrl, '_blank', 'noopener')
+                      : handleStartTrial(plan.id)
+                  }
+                >
+                  {plan.externalUrl ? 'Request Quote' : 'Start Free Trial'}
+                </Button>
+              </Stack>
+            </Card>
+          );
+        })}
       </SimpleGrid>
 
       <Text ta="center" size="sm" c="dimmed" mt="xl">
-        All plans include a 14-day free trial. No credit card required to start.
+        All plans include a 14-day free trial. No credit card required.
       </Text>
     </Container>
   );

frontend/src/pages/settings/SettingsPage.tsx

@@ -1,11 +1,11 @@
-import { useState } from 'react';
+import { useState, useEffect } from 'react';
 import {
   Title, Text, Card, Stack, Group, SimpleGrid, Badge, ThemeIcon, Divider,
-  Tabs, Button, Switch,
+  Tabs, Button, Switch, Loader,
 } from '@mantine/core';
 import {
   IconBuilding, IconUser, IconSettings, IconShieldLock,
-  IconFingerprint, IconLink, IconLogout,
+  IconFingerprint, IconLink, IconLogout, IconCreditCard,
 } from '@tabler/icons-react';
 import { notifications } from '@mantine/notifications';
 import { useAuthStore } from '../../stores/authStore';
@@ -15,10 +15,39 @@ import { PasskeySettings } from './PasskeySettings';
 import { LinkedAccounts } from './LinkedAccounts';
 import api from '../../services/api';
 
+interface SubscriptionInfo {
+  plan: string;
+  planName: string;
+  billingInterval: string;
+  status: string;
+  collectionMethod: string;
+  trialEndsAt: string | null;
+  currentPeriodEnd: string | null;
+  cancelAtPeriodEnd: boolean;
+}
+
+const statusColors: Record<string, string> = {
+  active: 'green',
+  trial: 'blue',
+  past_due: 'orange',
+  archived: 'red',
+  suspended: 'red',
+};
+
 export function SettingsPage() {
   const { user, currentOrg } = useAuthStore();
   const { compactView, toggleCompactView } = usePreferencesStore();
   const [loggingOutAll, setLoggingOutAll] = useState(false);
+  const [subscription, setSubscription] = useState<SubscriptionInfo | null>(null);
+  const [subLoading, setSubLoading] = useState(true);
+  const [portalLoading, setPortalLoading] = useState(false);
+
+  useEffect(() => {
+    api.get('/billing/subscription')
+      .then(({ data }) => setSubscription(data))
+      .catch(() => { /* billing not configured or no subscription */ })
+      .finally(() => setSubLoading(false));
+  }, []);
 
   const handleLogoutEverywhere = async () => {
     setLoggingOutAll(true);
@@ -32,6 +61,31 @@ export function SettingsPage() {
     }
   };
 
+  const handleManageBilling = async () => {
+    setPortalLoading(true);
+    try {
+      const { data } = await api.post('/billing/portal');
+      if (data.url) {
+        window.location.href = data.url;
+      }
+    } catch {
+      notifications.show({ message: 'Unable to open billing portal', color: 'red' });
+    } finally {
+      setPortalLoading(false);
+    }
+  };
+
+  const formatInterval = (interval: string) => {
+    return interval === 'year' ? 'Annual' : 'Monthly';
+  };
+
+  const formatDate = (iso: string | null) => {
+    if (!iso) return null;
+    return new Date(iso).toLocaleDateString('en-US', {
+      year: 'numeric', month: 'short', day: 'numeric',
+    });
+  };
+
   return (
     <Stack>
       <div>
@@ -63,6 +117,73 @@ export function SettingsPage() {
           </Stack>
         </Card>
 
+        {/* Billing / Subscription */}
+        <Card withBorder padding="lg">
+          <Group mb="md">
+            <ThemeIcon color="teal" variant="light" size={40} radius="md">
+              <IconCreditCard size={24} />
+            </ThemeIcon>
+            <div>
+              <Text fw={600} size="lg">Billing</Text>
+              <Text c="dimmed" size="sm">Subscription and payment</Text>
+            </div>
+          </Group>
+          {subLoading ? (
+            <Group justify="center" py="md"><Loader size="sm" /></Group>
+          ) : subscription ? (
+            <Stack gap="xs">
+              <Group justify="space-between">
+                <Text size="sm" c="dimmed">Plan</Text>
+                <Group gap={4}>
+                  <Badge variant="light">{subscription.planName}</Badge>
+                  <Badge variant="light" color="gray" size="sm">{formatInterval(subscription.billingInterval)}</Badge>
+                </Group>
+              </Group>
+              <Group justify="space-between">
+                <Text size="sm" c="dimmed">Status</Text>
+                <Badge
+                  color={statusColors[subscription.status] || 'gray'}
+                  variant="light"
+                >
+                  {subscription.status === 'past_due' ? 'Past Due' : subscription.status}
+                  {subscription.cancelAtPeriodEnd ? ' (Canceling)' : ''}
+                </Badge>
+              </Group>
+              {subscription.trialEndsAt && subscription.status === 'trial' && (
+                <Group justify="space-between">
+                  <Text size="sm" c="dimmed">Trial Ends</Text>
+                  <Text size="sm" fw={500}>{formatDate(subscription.trialEndsAt)}</Text>
+                </Group>
+              )}
+              {subscription.currentPeriodEnd && subscription.status !== 'trial' && (
+                <Group justify="space-between">
+                  <Text size="sm" c="dimmed">Current Period Ends</Text>
+                  <Text size="sm" fw={500}>{formatDate(subscription.currentPeriodEnd)}</Text>
+                </Group>
+              )}
+              {subscription.collectionMethod === 'send_invoice' && (
+                <Group justify="space-between">
+                  <Text size="sm" c="dimmed">Payment</Text>
+                  <Badge variant="light" color="cyan" size="sm">Invoice / ACH</Badge>
+                </Group>
+              )}
+              <Button
+                variant="light"
+                color="teal"
+                size="sm"
+                leftSection={<IconCreditCard size={16} />}
+                onClick={handleManageBilling}
+                loading={portalLoading}
+                mt="xs"
+              >
+                Manage Billing
+              </Button>
+            </Stack>
+          ) : (
+            <Text size="sm" c="dimmed">No active subscription</Text>
+          )}
+        </Card>
+
         {/* User Profile */}
         <Card withBorder padding="lg">
           <Group mb="md">
@@ -108,7 +229,7 @@ export function SettingsPage() {
             </Group>
             <Group justify="space-between">
               <Text size="sm" c="dimmed">Version</Text>
-              <Badge variant="light">2026.03.17</Badge>
+              <Badge variant="light">2026.03.18</Badge>
             </Group>
             <Group justify="space-between">
               <Text size="sm" c="dimmed">API</Text>