Prompt
I'm building a subscription service and need invoicing, proration, and refunds handled correctly
Latest observation
Absolutely — for a subscription service, the key is to make invoicing, proration, and refunds consistent and auditable.
Here’s a solid way to structure it.
1) Core billing model
Track these separately:
- Customer
- Subscription
- Billing period
- Invoice
- Invoice line items
- Payment / transaction
- Credit note / refund
- Subscription events
Examples: start, upgrade, downgrade, pause, resume, cancel, renewal.
This separation helps you avoid mixing billing logic with payment processing logic.
2) Invoicing rules
Each invoice should represent a clearly defined charge period.
Typical invoice contents:
- Subscription plan base fee
- Proration adjustments
- Add-ons / usage charges
- Discounts / coupons
- Taxes
- Credits from prior overpayment or refunds
Recommended invoice behavior:
- Generate invoices at:
- subscription start
- renewal
- plan change
- manual billing events
- Lock invoice line items once finalized
- Use unique invoice numbers
- Keep invoices immutable after finalization
If something changes later, issue a new invoice/credit note instead of editing the old one
3) Proration rules
Proration is needed when a subscription changes mid-cycle.
Common cases
Upgrade mid-cycle
Charge the customer only for the unused time difference between old plan and new plan.
Example:
- Monthly plan: $30
- Upgrade on day 15 to $60 plan
- Remaining 15 days are recalculated
- Customer is billed the prorated difference
Downgrade mid-cycle
Either:
- issue a credit for the unused higher-tier time, or
- apply the lower tier at next renewal only
Choose one policy and document it clearly.
Recommended prorations formula
For a billing period:
prorated_amount = plan_price × (remaining_time / total_period_time)
For plan changes:
proration_charge = new_plan_remaining_value - old_plan_remaining_value
Where:
remaining_time= time left in billing cycletotal_period_time= full billing cycle length
Practical notes
- Use high-precision decimal math, not floats
- Decide whether to prorate by:
- exact seconds
- days
- calendar months
Be consistent
- Define rounding rules:
- round per line item
- round invoice total
- round to nearest cent
4) Refund handling
Refunds should not modify the original payment record directly. Instead, create a refund transaction and link it to the original payment.
Refund types
- Full refund
- Partial refund
- Refund of unused subscription time
- Refund due to billing error
Recommended process
- Identify eligible payment
- Compute refundable amount
- Create refund record
- Update customer balance / ledger
- Notify customer
- Issue credit note if required by accounting rules
Important policy decision
Define when refunds are allowed:
- within a grace period only
- only for first purchase
- prorated refunds on cancellation
- no refunds, only credits
Make this a business rule, not ad hoc logic.
5) Best practice: use a ledger
To keep everything auditable, use a double-entry or at least event-based ledger:
Track:
- invoice issued
- payment captured
- credit issued
- refund issued
- balance adjustments
This gives you:
- auditability
- reliable customer balance calculation
- easier reconciliation with payment processors
6) Suggested lifecycle
New subscription
- Create subscription
- Generate invoice
- Collect payment
- Activate access
Renewal
- Create renewal invoice
- Collect payment
- Extend subscription
Upgrade
- Calculate proration
- Generate invoice for difference
- Collect payment or add to next invoice
Downgrade
- Record change
- Apply credit now or next cycle, depending on policy
Cancellation
- Stop auto-renew
- Decide whether access ends immediately or at period end
- Refund unused time only if policy allows
7) Edge cases to handle
- Subscription starts and cancels on same day
- Plan changes multiple times in one cycle
- Failed payment after proration invoice creation
- Refund after invoice already paid and settled
- Tax changes mid-cycle
- Coupons applied to prorated charges
- Trial periods
- Paused subscriptions
- Annual plans with monthly usage add-ons
- Currency conversion and multi-currency refunds
8) Strong implementation recommendation
If you’re implementing this yourself, build around these invariants:
- Every financial event is recorded once
- Invoices are immutable after finalization
- Refunds are separate from original charges
- Proration is deterministic and repeatable
- All money values use decimal types
- Time calculations use UTC and a single canonical timezone policy
9) Minimal data model example
subscriptions
- id
- customer_id
- plan_id
- status
- start_at
- current_period_start
- current_period_end
invoices
- id
- customer_id
- subscription_id
- status
- total_amount
- currency
- issued_at
- finalized_at
invoice_line_items
- id
- invoice_id
- description
- amount
- type (base, proration, discount, tax)
payments
- id
- invoice_id
- amount
- processor_reference
- status
- captured_at
refunds
- id
- payment_id
- amount
- reason
- status
- refunded_at
If you want, I can also provide:
- a billing/proration algorithm in pseudocode,
- a database schema, or
- examples for monthly and annual plans with upgrades, downgrades, and refunds.