feat(billing): add monthly billing cycle option for Team and Enterprise seats

Implement monthly billing alongside existing annual billing per the
spec changelog 2026-03-26. Users now select monthly or annual billing
at checkout, with cycle-specific Stripe prices resolved from env vars.

Backend:
- Add pricing constants for both cycles (Teams /, Enterprise /)
- Add BillingCycle type with DB/API/Stripe boundary mapping
- Replace product.default_price lookup with explicit getPriceIdForPlanAndCycle
- Populate billing_cycle column from Stripe subscription interval
- Add changeBillingCycle/cancelBillingCycleChange endpoints via Stripe
  subscription schedules (takes effect at renewal, no proration)
- Expand schedule on subscription retrieval for pending change detection

Frontend:
- Add Monthly/Annual pill toggle with Save 17% badge to UpgradeTrialDialog
- Dynamic PlanCard billing label (Billed monthly/Billed annually)
- Switch to Monthly/Annual button in SubscriptionQuickActions
- BillingCycleChangeDialog with cost comparison and effective date
- Pending cycle change banner in SubscriptionOverviewCard with cancel

Tests:
- 3 tests for billing_cycle tracking (monthly, yearly, null fallback)
- 2 tests for billingCycle schema validation on checkout endpoint

Author: jeanduplessis

.env.test

@@ -34,6 +34,10 @@ WORKOS_API_KEY=invalid-mock-workos-key
 WORKOS_CLIENT_ID=invalid-mock-workos-client-id
 STRIPE_TEAMS_SUBSCRIPTION_PRODUCT_ID='STRIPE_TEAMS_SUBSCRIPTION_PRODUCT_ID'
 STRIPE_ENTERPRISE_SUBSCRIPTION_PRODUCT_ID='STRIPE_ENTERPRISE_SUBSCRIPTION_PRODUCT_ID'
+STRIPE_TEAMS_MONTHLY_PRICE_ID='price_test_teams_monthly'
+STRIPE_TEAMS_ANNUAL_PRICE_ID='price_test_teams_annual'
+STRIPE_ENTERPRISE_MONTHLY_PRICE_ID='price_test_enterprise_monthly'
+STRIPE_ENTERPRISE_ANNUAL_PRICE_ID='price_test_enterprise_annual'
 USER_DEPLOYMENTS_API_BASE_URL=''
 USER_DEPLOYMENTS_API_AUTH_KEY=''
 SESSION_INGEST_WORKER_URL=''

.plans/monthly-billing-plan.md

@@ -155,14 +155,41 @@ Changes to `PlanCard`:
    - For annual: "Billed annually ($180/yr)" / "($720/yr)"
    - For monthly: "Billed monthly"
 
-### Step 7: Update the subscription overview to show billing cycle correctly
+### Step 7: Update the subscription overview for pending cycle changes
 
 **File**: `src/components/organizations/subscription/SubscriptionOverviewCard.tsx`
 
-The overview card already displays `formatBillingInterval()` from the Stripe
-subscription's `price.recurring.interval` — this should work for both
-monthly and annual subscriptions without changes. Verify it renders correctly
-for monthly subscriptions.
+The overview card derives "Next Payment" amount and "Billing Cycle" label
+from `subscription.items[0]`. That reflects the _current_ cycle, which is
+wrong when a billing cycle change is scheduled — e.g., a monthly→annual
+switch would still show the monthly price and "Monthly" label even though
+the next invoice will charge the annual rate.
+
+When a schedule is active (`subscription.schedule` is non-null), the card
+must read phase-2 of the schedule to show accurate upcoming-cycle data:
+
+1. **Detect pending schedule**: Check `subscription.schedule`. When truthy,
+   fetch the schedule via `client.subscriptionSchedules.retrieve(scheduleId)`
+   (or expand it on the subscription fetch — see below).
+2. **Extract phase-2 data**: Read `schedule.phases[1]` to get the upcoming
+   price ID, quantity, and start date.
+3. **Override display values**: When a pending cycle change exists:
+   - **Next Payment** should show the phase-2 price × quantity, not the
+     current line item amount.
+   - **Billing Cycle** should show the upcoming interval (e.g., "Annual"
+     instead of "Monthly") with a qualifier like "(starting {date})".
+   - Alternatively, show both: current cycle with a banner/annotation
+     indicating the upcoming change.
+4. **API support**: The `get` query on the subscription router currently
+   returns the raw Stripe subscription. Either:
+   - **(a)** Expand `schedule` on the subscription retrieve call
+     (`expand: ['schedule']`) so the frontend has phase data, or
+   - **(b)** Add a separate query/field that returns pending schedule info.
+     Option (a) is simpler since it's one Stripe call with an expand.
+
+For subscriptions _without_ a pending schedule, the current
+`formatBillingInterval()` logic works correctly for both monthly and annual
+intervals — no changes needed there.
 
 ### Step 8: Implement billing cycle change endpoint
 
@@ -219,10 +246,17 @@ it later.
 
 Add a "Switch to Monthly/Annual" action in the subscription management UI:
 
-1. Show the action only for owners/billing managers.
-2. If a schedule is active on the subscription, show "Pending: switching to
-   {cycle} at next renewal" with a "Cancel" button.
-3. On click, call the `changeBillingCycle` mutation.
+1. Show the action only for owners/billing managers with an active
+   subscription that has no pending cancellation.
+2. If a schedule is active on the subscription (detected via the expanded
+   schedule data from Step 7), show a "Pending: switching to {cycle} on
+   {date}" banner with a "Cancel" button that calls
+   `cancelBillingCycleChange`.
+3. Hide the "Switch" action while a schedule is already pending (one
+   change at a time).
+4. On click, call the `changeBillingCycle` mutation. The target cycle is
+   the opposite of the current one (derived from
+   `subscription.items[0].price.recurring.interval`).
 
 ### Step 10: Update email notifications
 
@@ -282,7 +316,7 @@ needed.
 | `src/routers/organizations/organization-subscription-router.ts`          | Modify      | Add `billingCycle` to checkout input; add `changeBillingCycle` and `cancelBillingCycleChange` mutations   |
 | `src/components/organizations/UpgradeTrialDialog.tsx`                    | Modify      | Add billing cycle toggle, dynamic pricing                                                                 |
 | `src/components/organizations/subscription/PlanCard.tsx`                 | Modify      | Accept `billingCycle` prop, dynamic label                                                                 |
-| `src/components/organizations/subscription/SubscriptionOverviewCard.tsx` | Modify      | Show pending cycle change indicator                                                                       |
+| `src/components/organizations/subscription/SubscriptionOverviewCard.tsx` | Modify      | Read phase-2 schedule data for pending cycle changes; override Next Payment and Billing Cycle display     |
 | `.env.test` / `.env.example`                                             | Modify      | Add new price ID env vars                                                                                 |
 | Test files (3-4 files)                                                   | Modify      | Add billing cycle test cases                                                                              |
 
@@ -304,7 +338,16 @@ needed.
    cycle change is scheduled, we should release the schedule first. The
    cancel handler should check for and release active schedules.
 
-4. **Promotion codes / discounts**: The checkout already supports
+4. **Overview card shows stale data during pending schedule**: Until the
+   schedule takes effect, `subscription.items[0]` reflects the current
+   cycle's price and interval. Without expanding the schedule and reading
+   phase-2, the "Next Payment" and "Billing Cycle" fields will be wrong.
+   Step 7 addresses this, but it requires either expanding the schedule on
+   the subscription retrieve call or making a second Stripe API call. The
+   expand approach adds no extra latency but increases response payload
+   size.
+
+5. **Promotion codes / discounts**: The checkout already supports
    `allow_promotion_codes: true`. Monthly prices may have different
    promotion code eligibility in Stripe. This is a Stripe configuration
    concern, not a code concern.

plans/monthly-billing-plan.md

@@ -390,6 +390,26 @@ export function useStopOrganizationSubscriptionCancellation() {
   );
 }
 
+export function useChangeBillingCycle() {
+  const trpc = useTRPC();
+  const onSuccess = useInvalidateAllOrganizationData();
+  return useMutation(
+    trpc.organizations.subscription.changeBillingCycle.mutationOptions({
+      onSuccess,
+    })
+  );
+}
+
+export function useCancelBillingCycleChange() {
+  const trpc = useTRPC();
+  const onSuccess = useInvalidateAllOrganizationData();
+  return useMutation(
+    trpc.organizations.subscription.cancelBillingCycleChange.mutationOptions({
+      onSuccess,
+    })
+  );
+}
+
 export function useUpdateOrganizationSeatCount() {
   const trpc = useTRPC();
   const onSuccess = useInvalidateAllOrganizationData();

src/app/api/organizations/hooks.ts

@@ -4,10 +4,12 @@ import { useState } from 'react';
 import { Dialog, DialogContent, DialogTitle } from '@/components/ui/dialog';
 import { PlanCard } from './subscription/PlanCard';
 import { Button } from '@/components/Button';
-import type { OrganizationPlan } from '@/lib/organizations/organization-types';
+import type { BillingCycle, OrganizationPlan } from '@/lib/organizations/organization-types';
 import {
-  TEAM_SEAT_PRICE_MONTHLY_USD,
-  ENTERPRISE_SEAT_PRICE_MONTHLY_USD,
+  TEAM_SEAT_PRICE_MONTHLY_BILLED_MONTHLY_USD,
+  TEAM_SEAT_PRICE_MONTHLY_BILLED_ANNUALLY_USD,
+  ENTERPRISE_SEAT_PRICE_MONTHLY_BILLED_MONTHLY_USD,
+  ENTERPRISE_SEAT_PRICE_MONTHLY_BILLED_ANNUALLY_USD,
 } from '@/lib/organizations/constants';
 import {
   useOrganizationSubscriptionLink,
@@ -53,8 +55,18 @@ export function UpgradeTrialDialog({
   container,
 }: UpgradeTrialDialogProps) {
   const [selectedPlan, setSelectedPlan] = useState<OrganizationPlan>(currentPlan);
+  const [billingCycle, setBillingCycle] = useState<BillingCycle>('annual');
   const [isPurchasing, setIsPurchasing] = useState(false);
 
+  const teamPrice =
+    billingCycle === 'monthly'
+      ? TEAM_SEAT_PRICE_MONTHLY_BILLED_MONTHLY_USD
+      : TEAM_SEAT_PRICE_MONTHLY_BILLED_ANNUALLY_USD;
+  const enterprisePrice =
+    billingCycle === 'monthly'
+      ? ENTERPRISE_SEAT_PRICE_MONTHLY_BILLED_MONTHLY_USD
+      : ENTERPRISE_SEAT_PRICE_MONTHLY_BILLED_ANNUALLY_USD;
+
   const { data: orgData } = useOrganizationWithMembers(organizationId);
   const subscriptionLink = useOrganizationSubscriptionLink();
   const hog = usePostHog();
@@ -70,6 +82,7 @@ export function UpgradeTrialDialog({
     hog?.capture('trial_upgrade_purchase_clicked', {
       organizationId,
       selectedPlan,
+      billingCycle,
       seatCount: orgData.members.length,
     });
 
@@ -79,6 +92,7 @@ export function UpgradeTrialDialog({
         seats: orgData.members.length,
         cancelUrl: window.location.href,
         plan: selectedPlan,
+        billingCycle,
       });
 
       if (result.url) {
@@ -106,11 +120,47 @@ export function UpgradeTrialDialog({
             </p>
           </div>
 
+          {/* Billing Cycle Toggle */}
+          <div className="flex items-center justify-center gap-3">
+            <div className="inline-flex rounded-lg bg-muted p-1">
+              <button
+                type="button"
+                onClick={() => setBillingCycle('monthly')}
+                className={`rounded-md px-5 py-1.5 text-sm font-medium transition-all ${
+                  billingCycle === 'monthly'
+                    ? 'bg-blue-600 text-white'
+                    : 'text-muted-foreground hover:text-foreground'
+                }`}
+              >
+                Monthly
+              </button>
+              <button
+                type="button"
+                onClick={() => setBillingCycle('annual')}
+                className={`rounded-md px-5 py-1.5 text-sm font-medium transition-all ${
+                  billingCycle === 'annual'
+                    ? 'bg-blue-600 text-white'
+                    : 'text-muted-foreground hover:text-foreground'
+                }`}
+              >
+                Annual
+              </button>
+            </div>
+            <span
+              className={`rounded-full border border-green-400/30 bg-green-400/10 px-2.5 py-0.5 text-xs font-semibold text-green-400 transition-opacity ${
+                billingCycle === 'annual' ? 'opacity-100' : 'opacity-30'
+              }`}
+            >
+              Save 17%
+            </span>
+          </div>
+
           {/* Plan Cards */}
           <div className="flex justify-center gap-4">
             <PlanCard
               plan="teams"
-              pricePerMonth={TEAM_SEAT_PRICE_MONTHLY_USD}
+              pricePerMonth={teamPrice}
+              billingCycle={billingCycle}
               features={TEAMS_FEATURES}
               isSelected={selectedPlan === 'teams'}
               currentPlan={currentPlan}
@@ -119,7 +169,8 @@ export function UpgradeTrialDialog({
 
             <PlanCard
               plan="enterprise"
-              pricePerMonth={ENTERPRISE_SEAT_PRICE_MONTHLY_USD}
+              pricePerMonth={enterprisePrice}
+              billingCycle={billingCycle}
               features={ENTERPRISE_FEATURES}
               isSelected={selectedPlan === 'enterprise'}
               currentPlan={currentPlan}