AI Rules for Subscription Billing

AI Builds Subscriptions That Leak Revenue

AI generates subscription billing with: no trial management (free trial starts but never converts or expires), no proration (upgrading mid-cycle charges the full new price instead of the prorated difference), no dunning (failed payment cancels the subscription immediately with no recovery attempt), no plan change handling (downgrade takes effect immediately instead of at period end), and no usage tracking (flat-rate only, no metered or usage-based options). Each gap is a revenue leak or a customer experience failure.

Modern subscription billing is: trial-managed (automatic conversion to paid with grace periods and reminders), prorated (mid-cycle plan changes charge or credit the correct amount), dunning-enabled (failed payments trigger email sequences that recover 20-40% of churned revenue), lifecycle-aware (upgrades immediate, downgrades at period end), and usage-flexible (flat-rate, metered, per-seat, or hybrid pricing models). AI generates none of these.

These rules cover: plan management and pricing models, trial-to-paid conversion, proration on plan changes, dunning for failed payments, usage-based metered billing, and subscription analytics.

Rule 1: Plan Management and Pricing Architecture

The rule: 'Define plans in Stripe (not in your code): Product + Price objects in Stripe Dashboard or API. Each plan has: a product (what the customer gets), one or more prices (monthly, annual, per-seat), and feature entitlements (which features each plan unlocks). Your database stores: the Stripe subscription ID, the current plan identifier, and the subscription status. Stripe is the source of truth for billing; your database is the source of truth for feature access.'

For feature entitlements: 'Map plans to features in your application: const PLAN_FEATURES = { free: { maxProjects: 3, maxRulesets: 5, apiAccess: false }, pro: { maxProjects: 50, maxRulesets: 100, apiAccess: true }, enterprise: { maxProjects: Infinity, maxRulesets: Infinity, apiAccess: true } }. Check entitlements on every feature access: if (user.plan.maxProjects <= user.projectCount) throw new PlanLimitError(). The entitlement map is the bridge between billing (Stripe) and product (your app).'

AI generates: hardcoded plan logic scattered across the codebase. Changing the Pro plan from 50 to 100 projects requires finding and updating every check. With a centralized entitlement map: change one value, every feature gate respects it. Adding a new plan: add one entry to the map. Zero code changes in feature gates.

• Plans defined in Stripe: Product + Price objects, not hardcoded in application
• Stripe is billing source of truth; your DB is feature access source of truth
• Centralized entitlement map: plan → features, one definition, all gates respect it
• Multiple prices per plan: monthly ($19), annual ($190), per-seat ($10/user/month)
• New plan = new map entry, zero changes to feature gate code

Rule 2: Trial-to-Paid Conversion

The rule: 'Configure trials in Stripe: subscription_data: { trial_period_days: 14 }. Stripe handles: trial start (no charge), trial end (automatic charge), and trial expiry (subscription cancelled if no payment method). Your application handles: trial countdown display ("7 days remaining"), upgrade prompts ("Add a payment method to continue after trial"), and grace period (1-3 days after trial ends before restricting access — give the user time to add a payment method).'

For the conversion funnel: 'Day 1: welcome email with key features to try. Day 7 (halfway): engagement email highlighting features they have not tried. Day 12 (2 days before end): urgency email — "Your trial ends in 2 days. Add a payment method to keep your data." Day 14 (trial end): if payment method on file, charge automatically. If no payment method: grace period (3 days), daily reminder, then restrict to free plan. Never delete user data on trial expiry — downgrade to free, preserve data, let them upgrade later.'

AI generates: a 14-day trial with no reminders, no grace period, and immediate data deletion on expiry. User forgets about the trial, comes back on day 16, data is gone. With proper trial management: the user received 3 reminder emails, had a 3-day grace period, and their data is preserved on the free plan. They upgrade on day 20 with zero data loss. The trial converts instead of alienating.

Rule 3: Proration on Plan Changes

The rule: 'On upgrade: charge the prorated difference immediately (user pays only for the remaining days at the higher rate). On downgrade: apply at the end of the current billing period (user keeps the higher plan until they have used what they paid for). Stripe handles proration automatically: stripe.subscriptions.update(subId, { items: [{ price: newPriceId }], proration_behavior: "create_prorations" }). The invoice shows: credit for unused time on the old plan + charge for remaining time on the new plan.'

For the user experience: 'Before confirming the plan change, show the proration preview: "Upgrading to Pro: you will be charged $12.50 today (prorated for 15 remaining days). Your next full charge of $19.00 will be on April 29." Stripe API: stripe.invoices.retrieveUpcoming({ subscription: subId, subscription_items: [{ price: newPriceId }] }) returns the upcoming invoice with proration line items. Show this to the user before they confirm.'

AI generates: upgrade charges the full monthly price immediately, regardless of where in the billing cycle the user is. User upgrades on day 28 of a 30-day cycle: pays full price for 2 days of the higher plan. Next month: charged again. The user feels overcharged and churns. Proration: the user pays $1.27 for 2 days, then $19.00 for the next full month. Fair, transparent, and churn-preventing.

Rule 4: Dunning for Failed Payment Recovery

The rule: 'When a renewal payment fails, do not cancel immediately. Dunning sequence: Day 0 (payment fails): send email — "Your payment failed. Update your card to keep your subscription." Include a direct link to the payment update page. Day 3: reminder email with more urgency. Day 7: final warning — "Your subscription will be downgraded in 7 days." Day 14: downgrade to free plan, send notification. Throughout: Stripe Smart Retries automatically retries the charge on days 1, 3, 5, 7.'

For the payment update flow: 'Stripe Customer Portal: redirect users to a Stripe-hosted page where they can update their payment method, view invoices, and manage their subscription. Or use Stripe Elements to embed a card update form in your app. The dunning email links directly to the update page — one click from email to card entry. Every additional click between the email and the card form reduces recovery rate. Make the path frictionless.'

AI generates: invoice.payment_failed webhook triggers immediate subscription cancellation. The user is locked out. They had a temporary card issue (expired card, insufficient funds after payday). With dunning: Stripe retries automatically, the user gets reminder emails, updates their card on day 5, subscription continues uninterrupted. 20-40% of failed payments are recovered with dunning. Without it: 0% recovery, 100% involuntary churn.

• Never cancel on first payment failure — dunning recovers 20-40% of failed charges
• Stripe Smart Retries: automatic retry on days 1, 3, 5, 7 with intelligent timing
• Email sequence: day 0 (alert), day 3 (reminder), day 7 (warning), day 14 (downgrade)
• Direct link to payment update: one click from email to card entry form
• Stripe Customer Portal: hosted page for card update, invoice history, plan management

Rule 5: Usage-Based and Metered Billing

The rule: 'For usage-based pricing (API calls, storage, compute time), use Stripe metered billing: create a metered price (billing_scheme: "metered"), report usage via the API (stripe.subscriptionItems.createUsageRecord), and Stripe calculates the charge at the end of the billing period. Your application: tracks usage in real-time (Redis counter or database), reports usage to Stripe periodically (hourly or daily), and enforces usage limits before the billing cycle ends.'

For hybrid pricing: 'Combine flat-rate base + metered overage: Pro plan = $19/month includes 10,000 API calls. Usage beyond 10,000: $0.002 per call. Implementation: flat-rate subscription for the base, metered subscription item for the overage. Track usage, subtract the included amount, report only the overage to Stripe. Display in the dashboard: "API calls: 8,247 / 10,000 included. $0 overage this month." Transparency prevents billing surprises.'

AI generates: flat-rate pricing only, or usage tracking with no billing integration (track usage but never charge for it). The flat-rate user at 100,000 API calls pays the same as the user at 100 calls — unsustainable. Metered billing: heavy users pay proportionally, light users pay less, and the business model scales with customer usage. Stripe handles the invoicing; your app handles the tracking.

Complete Subscription Billing Rules Template

Consolidated rules for subscription billing.

• Plans in Stripe, entitlements in your app — centralized feature map, not scattered checks
• Trial management: reminders at day 7/12/14, grace period, downgrade not delete on expiry
• Proration: immediate on upgrade (charge difference), period-end on downgrade (use what you paid)
• Preview proration before confirming: show exact charge and next billing date
• Dunning sequence: 4 emails over 14 days + Stripe Smart Retries — recover 20-40% of failures
• One-click payment update from dunning email — minimize friction to recover
• Metered billing for usage: report usage to Stripe, invoice calculated at period end
• Hybrid: flat base + metered overage — dashboard shows usage vs included amount