Subscription Commerce Platform

Recurring Billing, Dunning and Plan Changes

Design a platform that charges saved payment methods on a schedule, recovers failed payments with retries and reminders, and handles upgrades, pauses, cancellations and usage-based charges without ever charging twice.

Overview

A subscription platform charges customers on a schedule without them clicking 'pay': every month (or week, or year) it creates an invoice, charges the saved card, and keeps or removes the customer's access based on the result. The card networks call this a merchant-initiated transaction: the merchant charges the card under an earlier agreement with the customer, who is not present.

That simple loop hides four hard parts. Timing: millions of renewals fall on the same dates, and a period that started on January 31 must end on the last day of February, not drift to the 28th forever. Exactly once: a crash between charging the card and saving the result must not lead to a second charge. Failure: some renewals fail (expired cards, insufficient funds, bank declines), and most of those customers still want the product, so the platform retries over days and reminds them, which is called dunning. Change: customers upgrade, downgrade, pause and cancel mid-period, and each change needs a fair, explainable charge or credit.

Questions to ask first

How many subscriptions? — 5 million active, mostly monthly, some yearly
When do they renew? — On their own anchor day; 30% happen to anchor on the 1st
Physical boxes or digital access? — Both; a box ships after its invoice is paid
What happens when a card fails? — Retry for 14 days with emails, keep access during that time, then cancel
Are plan changes prorated? — Yes, to the second: credit the unused old price, charge the new price for the rest
Any usage-based pricing? — Some plans bill per unit used, in arrears at period end
Do we process cards ourselves? — No, a payment processor does; we call it with idempotency keys

What you will be able to do

Draw the subscription state machine and say what grants access in each state.
Schedule millions of renewals with a due-date index and SKIP LOCKED, and keep monthly periods aligned to their anchor day.
Charge exactly once with one invoice per period and an idempotency key per attempt, including the processor-timeout case.
Design dunning around soft and hard declines, and compute prorations in integer cents.

Key concepts

Subscription state machine
Billing cycle anchor
Invoice per period
Idempotency keys
SKIP LOCKED scheduling
Dunning
Soft and hard declines
Proration
Usage metering
MRR and churn

Functional requirements

Create subscriptions on a plan with an optional trial; monthly, yearly and weekly intervals
Renew on schedule: one invoice per period, charged to the saved payment method
Retry failed renewals on a schedule with customer emails; cancel or suspend after the last retry
Upgrade and downgrade mid-period with proration; cancel now or at period end; pause and resume; skip one delivery
Record usage events and bill them at period end for metered plans
Send billing events to access control, fulfilment and email; report MRR and churn

Non-functional requirements

Never charge a customer twice for the same invoice, even across crashes and timeouts
Renewals for a day finish within that day (a target we chose), spread over the hours rather than at midnight
Plan changes show in the customer's account within seconds
Invoices and payment attempts are never deleted; corrections are credits or new invoices
The platform keeps granting access for paid periods even if the processor is down

Interview questions

How do you make sure a renewal never charges twice?
Millions of subscriptions renew on the 1st. How do you process them?
Design the dunning process.
How do you compute a proration for a mid-period upgrade?
What happens to a subscription that starts on January 31?
How do you bill usage correctly?
Should a past_due customer keep access?
Which metrics would you report, and where do they come from?