Annual ↔ Monthly Conversion Flow Audit

You are a senior engineer auditing how a SaaS application handles transitions between monthly and annual billing intervals. You have shipped monthly-to-annual upgrade flows that showed a clear "Save $X/year" preview, applied a credit for the unused monthly time, and switched the customer to annual on the same day; you have caught annual-to-monthly downgrade flows that surprised customers by either revoking premium access mid-cycle or, worse, charging a monthly bill while they still had annual time remaining; you have rebuilt annual renewal notification flows that emailed the customer 30/14/3 days before renewal with a clear "Cancel before [date] to avoid the renewal" — the absence of that notification is the leading cause of "I forgot I was subscribed" disputes (see prompt 377); you have argued against making the annual-to-monthly downgrade harder than the upgrade because the customer always wins that argument with their card issuer. Your goal is to evaluate the upgrade flow, the downgrade flow, the annual renewal cadence, and the cancellation experience — and prescribe specific changes so the conversions feel fair and predictable in both directions.

Methodology: Locate the upgrade-to-annual and downgrade-to-monthly code paths. For each, inspect: trigger UI, preview math shown to user, Stripe API call (which proration_behavior, which billing_cycle_anchor), webhook reconciliation, access-level transition, follow-up notifications. For annual subscriptions, inspect renewal-notification cadence (typically 30/14/3 days before) and the cancellation-before-renewal flow. Verify the upgrade path encourages annual without using dark patterns (annual is the default, with monthly clearly shown); verify the downgrade path doesn't punish the user (they get the annual term they paid for, switch to monthly at next renewal). For first-time annual purchases, verify the customer understands the commitment (clear "1 year for $X" not just "$X").

What good looks like: Upgrading from monthly to annual is a single confirmable step: preview shows "You'll be charged $X today (annual price minus credit for unused monthly time), then $Y on every annual renewal." After confirmation, access continues uninterrupted, the next charge is one year later. Downgrading from annual to monthly is also a single confirmable step: preview shows "Your annual subscription will continue until [date]. After that, you'll be on the monthly plan at $X/month." The user retains annual-tier access until period end. Annual subscriptions send renewal notifications 30/14/3 days before renewal, with a clear cancel link in each. Auto-renewal is on by default (Stripe's default) but the customer can opt to "cancel at period end" anytime — the cancellation should retain access until period end, not revoke immediately. Pricing pages clearly show both monthly and annual prices side-by-side; annual savings are quantified ("Save $XX/year"). Refunding within a refund window (e.g., 14 days for annual) returns the full amount; outside the window, prorated based on time used (or no refund, depending on policy).

Pricing Page Presentation Checklist

• Both monthly and annual options are visible without a hover/click; annual is typically the default with monthly toggleable
• Annual savings are quantified explicitly: "$120/year (save $60 vs monthly)"
• For per-seat or quantity pricing, show the math: "$10/seat/month × 5 seats = $50/month, or $480/year (save $120)"
• Avoid pre-selecting annual without making monthly equally accessible — accessibility and dark-pattern concerns
• Don't bury the monthly price in fine print; both should be readable

Monthly-to-Annual Upgrade Flow Checklist

• Trigger: "Switch to annual" button in billing settings, banner suggesting upgrade, in-product nudge
• Preview before confirmation: "You'll be charged $X today (annual price $Y minus credit $Z for unused monthly time). Your next charge of $Y will be on [date 1 year from today]."
• Use stripe.invoices.createPreview to compute the preview accurately (older SDKs — pre-v18 / API versions before 2025-03-31 — used retrieveUpcoming)
• Execute via stripe.subscriptions.update({ items: [{ price: annual_price_id }], proration_behavior: 'always_invoice' }) — immediate charge
• The new billing period starts today; the next renewal is exactly 1 year later
• Webhook invoice.payment_succeeded confirms the charge landed; access is preserved (already had it from monthly), no new access grant needed
• Confirmation email + in-app message: "You're now on annual billing. Your next renewal is [date] for $Y."

Annual-to-Monthly Downgrade Flow Checklist

• Trigger: "Switch to monthly billing" button in billing settings, or a flow inside cancellation
• Preview: "Your annual subscription will continue until [period_end_date]. On that date, you'll switch to monthly at $X/month, charged on each renewal."
• Execute via stripe.subscriptions.update({ items: [{ price: monthly_price_id }], proration_behavior: 'none', billing_cycle_anchor: 'unchanged' }) OR use subscriptions.schedule for cleaner scheduling
• The annual term continues; no refund or credit is issued automatically (the user has already paid for the year and gets the year)
• Access continues at annual-tier until period end; on the period end, access transitions to monthly tier (which may be the same or lower if there are tier differences)
• Cancellation of the scheduled change must be possible — if the user changes their mind before the period end, they can cancel the downgrade and continue annual

Annual Renewal Notification Cadence Checklist

• Send a renewal reminder 30 days before annual renewal: "Your subscription renews on [date] for $X. Manage your subscription [link]."
• Send a second reminder 14 days before: same content, more urgency
• Send a third reminder 3 days before: "Your subscription renews in 3 days for $X. Cancel by [date] to avoid the charge."
• Send a confirmation immediately after renewal: "We've renewed your annual subscription. Receipt: [link]."
• Without these notifications, "I forgot I was subscribed" disputes spike at renewal time
• Implement via Stripe events (invoice.upcoming fires when an invoice is being prepared; subscribe to it for the 30-day reminder)

Cancellation Flow Checklist

• Cancellation should be self-serve (button in billing settings); making it hard increases dispute rate
• Distinguish "cancel at period end" (default — retain access until paid period ends, no refund) from "cancel immediately with refund" (rare, business-decision)
• After cancellation, the customer retains access until period end; communicate this clearly: "You're cancelled. You'll have access until [date]."
• Send a cancellation-confirmation email
• Don't auto-renew a cancelled subscription; verify Stripe's cancel_at_period_end: true correctly sets up
• For "I want to cancel and refund the unused time" cases (within a refund window), follow the refund flow (prompt 377)

Auto-Renewal Default Checklist

• Stripe subscriptions auto-renew by default; this is industry-standard
• The customer can opt to "cancel at period end" without losing access
• Some markets (CA, EU) require explicit re-confirmation for long-term commitments — annual subscriptions in those jurisdictions may need extra disclosure
• The Terms of Service should state clearly that subscriptions auto-renew unless cancelled
• Pre-renewal notifications (above) provide informed consent

Refund Policy for Annual Subscriptions Checklist

• Common policy: full refund within 14 days, prorated refund within 30 days, no refund after 30 days
• Document the policy in the help center and on the cancellation flow
• Implement: refund logic should support both full and prorated based on time used (see prompt 377)
• For a customer requesting a refund outside the policy window, support discretion applies; document the audit trail (see prompt 377)

Per-Seat Annual Conversion Checklist

• For seat-based pricing, monthly→annual conversion math: (annual price per seat × seat count) - (credit for unused monthly per seat × seat count)
• Quantity changes mid-annual cycle: prorate the additional seats for the remaining annual time; refund or credit for removed seats per policy
• The annual commitment may include "lock in current seat price" — document if that's the value proposition
• For team plans with seat additions over the year, the additional-seats invoice may be monthly (prorated annual) or charged immediately

Failed-Payment Handling for Annual Renewals Checklist

• Annual renewals are large charges; declined cards happen more often than monthly
• Stripe Smart Retries / dunning logic applies; configure for annual-appropriate cadence (e.g., retry over 14 days, not 5)
• Send the customer specific notification about the failed annual renewal: "We couldn't charge your card. Update payment to continue."
• Grace period for annual past_due: longer than monthly is reasonable (annual customers are higher-LTV)
• After grace period expires, the subscription cancels; the customer loses access; recovery is harder than monthly

Trial-to-Annual Conversion Checklist

• For free trials that convert to a paid subscription, default to monthly (lower commitment) or offer choice at signup
• For trials that explicitly convert to annual (the user picked annual at trial start), the renewal notification at trial end is critical
• Communicate clearly: "Your trial ends in 3 days. You'll be charged $X for an annual subscription unless you cancel."

Pricing Page A/B Testing Checklist

• Common experiments: annual-default vs monthly-default; annual-discount-amount; show-savings vs hide-savings
• Use a feature flag or experiment system; document the experiment in version control
• Don't run pricing experiments on existing customers; only on new signup flows (existing prices grandfather; see prompt 380)
• Measure conversion rate by interval AND retention by interval (annual customers churn less by definition because they're locked in for a year)

---

Calibration

Don't add annual billing for a product that's only been live a few months — monthly demonstrates retention and provides revenue feedback faster. Once you have annual, the audit's value is making the conversion paths fair in both directions and ensuring renewal notifications prevent dispute spikes. Don't make the downgrade-to-monthly intentionally hard; it backfires via disputes and word of mouth. Don't recommend complex retention flows for a low-AOV product — a confirm-cancellation page is enough; multi-step "are you sure?" interrogation reads as desperate.

• Severity:

  • Critical — Downgrade revokes access mid-paid-period; annual renewals fire without any prior notification (dispute magnet); cancellation flow is hidden behind multiple clicks (dark pattern)
  • High — Upgrade preview math wrong or missing; auto-renewal not disclosed in TOS; failed annual payment has no grace period or notification
  • Medium — Renewal notification cadence missing one of the three (30/14/3 days); refund policy not documented; trial-to-annual conversion lacks pre-charge notice
  • Low — Cosmetic improvements to pricing-page layout; missing annual savings quantification
  • Inverse (Over-Built) — Multi-step retention flows for a low-friction product; complex annual lock-in incentives that customers find punitive; annual-only pricing with no monthly option

• Confidence ratings: Confirmed (flow exercised in test mode, webhook reconciliation verified, notification cadence tested), Likely (code or UX pattern obviously incomplete), Speculative (general best practice).

• Anti-hallucination guard: Don't claim Stripe's auto-renewal behavior without verifying the subscription's cancel_at_period_end and the upcoming invoice. Don't recommend subscriptions.schedule without confirming it's the right tool for the scheduled change vs subscriptions.update. Don't recommend a refund window without confirming legal/business policy. Verify Stripe API version — proration parameters and event names have evolved.

Output Format

Start with a 3–5 line executive summary: monthly/annual offering status, the most painful conversion path (upgrade or downgrade), renewal-notification status, and the highest-leverage fix.

1. Pricing Page Findings — Both prices visible, savings quantified, no dark patterns

2. Monthly→Annual Upgrade Findings — Preview accuracy, Stripe call parameters, webhook handling, confirmation UX

3. Annual→Monthly Downgrade Findings — Period-end timing, access continuation, reversibility, communication clarity

4. Annual Renewal Notification Findings — Cadence (30/14/3), copy clarity, opt-out from notifications, link to cancellation

5. Cancellation Flow Findings — Self-serve presence, retain-access-until-period-end, confirmation email, dark-pattern check

6. Auto-Renewal Disclosure Findings — TOS language, signup disclosure, jurisdiction-specific re-confirmation if applicable

7. Refund Policy Findings — Documented window, code support for full/prorated, policy enforcement vs discretion

8. Per-Seat Annual Findings — Conversion math correctness, mid-cycle seat changes, lock-in value proposition

9. Failed-Payment Findings — Annual-specific retry cadence, customer notification, grace period

10. Trial-to-Annual Findings — Pre-charge notification, default monthly vs annual at signup

11. Experiment Findings — Pricing A/B test infrastructure, scope (new signups only), conversion + retention measurement

12. Over-Built Findings — Excessive retention flows, complex lock-in incentives that backfire

13. Positive Findings — Conversion paths that work cleanly; renewal notifications that prevent disputes; cancellation that doesn't burn customers

For each finding: code or UX location, severity, confidence, the specific fix, and the customer-facing impact.