What This Template Is For
Billing is the feature that ships once and breaks for years. Every other feature on your roadmap earns revenue only if billing works correctly. Yet most product teams treat billing as an engineering problem and hand it off with a one-page spec that says "integrate with Stripe."
The reality is that billing logic touches every part of the product: plan changes, seat additions, proration, failed payments, refunds, tax compliance, invoicing, and dunning. Each of these has edge cases that, if unspecified, will be decided by whichever engineer picks up the ticket. Those implicit decisions become implicit policy, and implicit policy becomes customer complaints.
This template helps you specify billing and subscription features with enough precision to prevent the most common billing bugs. It covers pricing model definition, payment flow design, upgrade and downgrade logic, proration rules, failed payment handling, and invoicing requirements. Use it alongside the pricing tier template for pricing structure design and the Product-Led Growth Handbook for self-serve billing strategy.
The monthly recurring revenue glossary entry explains MRR calculation conventions that this spec references. The expansion metrics template tracks the revenue outcomes of the billing flows you define here.
When to Use This Template
- When building billing from scratch. Specify the full system before writing code to avoid costly rework.
- When migrating billing providers. Document existing logic so you can verify parity after migration.
- When adding a new pricing model. Seat-based, usage-based, or hybrid pricing each introduces new billing flows.
- When expanding internationally. New tax jurisdictions, currencies, and payment methods create billing complexity.
- When billing bugs are recurring. If customers report incorrect charges more than once a quarter, the spec is incomplete.
How to Use This Template
Step 1: Define the Pricing Model
Document every plan, its price, billing interval, and what is included. Be explicit about units (per seat, per 1,000 API calls, per GB). Ambiguity in pricing definitions causes ambiguity in invoices.
Step 2: Map Payment Flows
Diagram every path from "user decides to pay" to "payment confirmed." Include new subscriptions, upgrades, downgrades, add-ons, and renewals. Each flow should have a clear trigger, success state, and failure state.
Step 3: Specify Proration Rules
Define exactly how mid-cycle plan changes are calculated. Proration math is the number one source of billing disputes. Document whether you prorate to the day, to the second, or not at all.
Step 4: Define Edge Cases
Failed payments, expired cards, chargebacks, refund policies, dunning sequences. These scenarios are rare individually but collectively they affect 5-15% of your subscriber base each month.
Step 5: Specify Invoice and Receipt Requirements
Define what appears on every invoice: line items, tax breakdown, company details, payment method summary. Many customers need invoices for expense reports and tax compliance.
The Template
Pricing Model Definition
| Field | Value |
|---|---|
| Product name | [Product name] |
| Billing provider | [Stripe / Chargebee / Recurly / etc.] |
| Supported currencies | [USD, EUR, GBP, etc.] |
| Tax handling | [Provider-managed / custom / none] |
| Billing intervals | [Monthly / Annual / Both] |
| Annual discount | [X% off monthly price] |
| Trial period | [N days / None] |
Plan Definitions
| Plan | Monthly Price | Annual Price | Seats Included | Overage per Seat | Usage Limits | Key Features |
|---|---|---|---|---|---|---|
| Free | $0 | $0 | [N] | N/A | [Limits] | [Features] |
| [Starter] | $[X]/mo | $[X]/yr | [N] | $[X]/seat/mo | [Limits] | [Features] |
| [Pro] | $[X]/mo | $[X]/yr | [N] | $[X]/seat/mo | [Limits] | [Features] |
| [Enterprise] | Custom | Custom | Custom | Custom | Custom | [Features] |
Payment Flows
New Subscription Flow
| Step | Action | System Behavior | Success State | Failure State |
|---|---|---|---|---|
| 1 | User selects plan | Display plan details and pricing | Plan selected | N/A |
| 2 | User enters payment method | Validate card / ACH / payment method | Payment method saved | Show validation error, retry |
| 3 | System creates subscription | Charge first period, create subscription in billing provider | Subscription active, receipt emailed | See Failed Payment Flow |
| 4 | System provisions access | Grant plan-level permissions | Access granted | Retry provisioning, alert ops |
| 5 | System sends confirmation | Email receipt + welcome content | Delivered | Queue for retry |
Upgrade Flow
| Step | Action | System Behavior | Proration | Effective |
|---|---|---|---|---|
| 1 | User selects higher plan | Show price difference and prorated amount | [Immediate / Next cycle] | [Immediate / Next cycle] |
| 2 | System calculates proration | [Credit remaining days on old plan, charge remaining days on new plan] | [Formula] | [Immediate] |
| 3 | System charges difference | Charge prorated amount to payment method on file | [Amount] | [Immediate] |
| 4 | System updates access | Grant new plan permissions immediately | N/A | [Immediate] |
Downgrade Flow
| Step | Action | System Behavior | Proration | Effective |
|---|---|---|---|---|
| 1 | User selects lower plan | Show what will change, effective date | [Credit / No credit] | [End of current period] |
| 2 | System schedules change | Mark subscription for downgrade at renewal | [None / Credit applied to balance] | [Renewal date] |
| 3 | Access continues | User retains current plan until period ends | N/A | [Current period] |
| 4 | System applies downgrade | Reduce permissions, charge new plan rate | N/A | [Renewal date] |
Cancellation Flow
| Step | Action | System Behavior | Refund | Access |
|---|---|---|---|---|
| 1 | User requests cancellation | Show retention offer (if applicable) | N/A | N/A |
| 2 | User confirms cancellation | Schedule cancellation at period end | [None / Prorated / Full month] | Retains until period end |
| 3 | Period ends | Downgrade to Free or deactivate account | N/A | [Free plan / Read-only / Locked] |
Proration Rules
| Scenario | Calculation | Example |
|---|---|---|
| Upgrade mid-cycle | (New daily rate - Old daily rate) x remaining days | Pro ($49/mo) to Business ($99/mo) on day 15 of 30: ($3.30 - $1.63) x 15 = $25.05 |
| Downgrade mid-cycle | [Credit remaining days at old rate, apply to balance / No proration] | [Define] |
| Seat added mid-cycle | Seat price x (remaining days / total days in period) | Add seat at $10/mo on day 10 of 30: $10 x (20/30) = $6.67 |
| Seat removed mid-cycle | [Credit remaining days / No credit until renewal] | [Define] |
| Annual to monthly | [No proration, switch at renewal / Prorated refund of annual] | [Define] |
| Monthly to annual | [Charge annual minus credit for remaining monthly days] | [Define] |
Failed Payment Handling
| Event | Timing | Action | Customer Communication | Access Impact |
|---|---|---|---|---|
| First failure | Day 0 | Retry charge in 24 hours | Email: "Payment failed, please update card" | None |
| Second failure | Day 1 | Retry charge in 48 hours | Email: "Payment still failing" + in-app banner | None |
| Third failure | Day 3 | Retry charge in 72 hours | Email: "Action required" + in-app modal | [None / Read-only] |
| Fourth failure | Day 7 | Final retry | Email: "Account will be restricted" | [Read-only / Feature restriction] |
| Grace period ends | Day 14 | Cancel subscription | Email: "Subscription cancelled" | [Free plan / Locked / Data retained for X days] |
Invoice Requirements
| Field | Required | Source |
|---|---|---|
| Invoice number | Yes | Sequential, auto-generated |
| Invoice date | Yes | Charge date |
| Company name | Yes | Account billing details |
| Company address | Yes | Account billing details |
| Tax ID (VAT/EIN) | If provided | Account billing details |
| Line items | Yes | Plan name, quantity, unit price, total |
| Subtotal | Yes | Sum of line items |
| Tax amount | If applicable | Tax rate x subtotal |
| Total | Yes | Subtotal + tax |
| Payment method | Yes | Last 4 digits of card / bank name |
| Payment status | Yes | Paid / Pending / Failed |
Billing Spec Checklist
- ☐ Defined all plans with exact pricing and included features
- ☐ Documented new subscription payment flow
- ☐ Documented upgrade flow with proration rules
- ☐ Documented downgrade flow with effective dates
- ☐ Documented cancellation flow with retention step
- ☐ Specified proration calculation for every mid-cycle change
- ☐ Defined failed payment retry schedule and access impact
- ☐ Specified dunning email sequence content and timing
- ☐ Defined invoice fields and format requirements
- ☐ Documented tax handling approach and supported jurisdictions
- ☐ Specified refund policy and process
- ☐ Tested all flows with billing provider sandbox
- ☐ Reviewed with finance for revenue recognition compliance
Filled Example: B2B Collaboration SaaS
Plan Definitions
| Plan | Monthly | Annual | Seats | Overage | Storage | Key Features |
|---|---|---|---|---|---|---|
| Free | $0 | $0 | 3 | N/A | 1 GB | Basic boards, 5 integrations |
| Team | $12/seat/mo | $10/seat/mo (billed annually) | 5 min | $12/seat/mo | 50 GB | Unlimited boards, 50 integrations, SSO |
| Business | $24/seat/mo | $20/seat/mo (billed annually) | 10 min | $24/seat/mo | 500 GB | Advanced reporting, audit log, custom fields |
Proration Example: Team to Business Upgrade
Account: 8 seats on Team monthly ($96/mo). Upgrades to Business on day 12 of a 30-day cycle.
- Remaining days: 18
- Daily rate (Team, 8 seats): $96 / 30 = $3.20/day
- Daily rate (Business, 8 seats): $192 / 30 = $6.40/day
- Credit for unused Team days: 18 x $3.20 = $57.60
- Charge for Business days: 18 x $6.40 = $115.20
- Prorated charge: $115.20 - $57.60 = $57.60
- Next full renewal: $192.00 on next billing date
Dunning Sequence Results (Q4 2025)
| Stage | Accounts Reached | Recovered | Recovery Rate |
|---|---|---|---|
| Email 1 (Day 0) | 342 | 198 | 57.9% |
| Email 2 + Banner (Day 1) | 144 | 52 | 36.1% |
| Email 3 + Modal (Day 3) | 92 | 31 | 33.7% |
| Email 4 (Day 7) | 61 | 14 | 23.0% |
| Cancelled (Day 14) | 47 | N/A | N/A |
Overall recovery rate: 86.3% (295 / 342). The in-app modal at Day 3 recovered $18,400 in MRR that would have churned.
Key Takeaways
- Billing specs prevent billing bugs. Every unspecified edge case will be decided by an engineer on a Friday afternoon
- Proration rules are the most common source of billing disputes. Document the exact formula for every mid-cycle scenario
- Failed payment handling recovers 5-15% of MRR that would otherwise churn. Invest in a proper dunning sequence
- Make downgrade and cancellation flows fair. Customers who feel cheated by billing never come back
- Test every flow in the billing provider's sandbox before shipping. One billing bug erodes more trust than ten product bugs combined
About This Template
Created by: Tim Adair
Last Updated: 3/5/2026
Version: 1.0.0
License: Free for personal and commercial use