Loading…

The decisions that matter

One non-void invoice per subscription and period, saved before any charge, and a key per attempt.A rerun finds the invoice, and the provider recognises a resent attempt.
Issued invoices stay as issued; credit notes correct them.The customer’s copy, the tax filed and the books keep agreeing.
Retries on the same open invoice, stopped by hard declines.Customers who mean to stay are kept, and nobody pays twice.
Access from the server’s state, moved only by newer provider events.A faked page or a late “failed” can’t change what anyone may watch.

Architecture diagramThe final design at a glance

Each period’s invoice is saved before the provider charges it, provider events move state only when newer, and the apps ask the entitlements service. Dashed lines are asynchronous.

Diagram as text

Components: Streaming apps (Client); Billing API (API gateway); Billing service (Service); Payment provider (External API); Entitlements: who may watch (Service); Tax service (External API); Billing DB: subscriptions, invoices, attempts (SQL DB); Provider events: newest wins (Worker); Email service (Notifications); Renewal run: sliced, rate-limited (Worker); India: debits presented a day ahead (Worker). Connections: Streaming apps → Billing API (start, change, cancel); Billing API → Billing service; Billing service → Tax service (tax, fixed at issue); Billing service → Billing DB: subscriptions, invoices, attempts (invoice first); Billing service → Payment provider (charge, a key per attempt); Payment provider → Provider events: newest wins (signed events), asynchronous; Provider events: newest wins → Billing DB: subscriptions, invoices, attempts (apply if newer); Streaming apps → Entitlements: who may watch (may I watch?); Renewal run: sliced, rate-limited → Billing DB: subscriptions, invoices, attempts (due slices, checkpoints); Renewal run: sliced, rate-limited → India: debits presented a day ahead (Indian renewals); Renewal run: sliced, rate-limited → Email service (receipts), asynchronous.

Understanding the problem

A streaming service sells monthly and yearly plans in India and abroad. Billing turns each subscription into an invoice and a charge every period, for years, through a payment provider that holds the cards. The hard parts: runs that repeat, declined renewals, plan changes mid-month, access that matches what was paid, India’s rules for automatic debits, and the busiest day.

The practice brief states the requirements up front; confirm them in the first few minutes.

Functional requirements

CoreCustomers start a subscription on one of four plans, monthly or yearly, with a 7-day free trial for new subscribers.
CoreEach subscription is billed every period, with an invoice the customer can see, until it is cancelled.
CoreCustomers move up or down a plan at any time, including part-way through a period.
CoreCustomers cancel from the app, and update their card at any time.
CoreRenewal payments are sometimes declined; the company wants to keep customers who mean to stay.
CoreWhat a customer can watch always matches what they have paid for.
CoreIndian customers pay by card or UPI AutoPay, under the Reserve Bank of India’s rules for automatic debits.
CoreThe company’s accounting system learns what was billed, collected and given back.
Below the lineCoupons and discounts.
Below the lineGift subscriptions.
Below the lineDashboards and reports for finance.
Below the lineUsage-based pricing and metering.Every plan here is a fixed price per period.
Below the lineHow the payment provider reaches banks.Treat it as a service that saves cards, charges them and reports outcomes.
Below the lineThe books and revenue reports.Billing hands each document to the ledger.
Below the lineHow tax is computed.A tax service gives the amount; billing fixes it on the invoice at issue.

Non-functional requirements

ConsistencyA customer is never billed or charged twice for one period, however the billing run fails or repeats.
DurabilityEvery invoice can be explained years later, with every correction made to it.
ConsistencyAmounts are exact to the paisa or cent.
SecurityEvery Indian automatic debit follows the rules in the brief: told at least 24 hours ahead with the exact amount and a way to opt out, approved again above ₹15,000, never debited without that notice.
LatencyA customer who pays gets access back within a minute.
Availability

Scale

From the briefNumbers here are given in the practice brief.

ScaleAbout 40 million subscribers in India and abroad, most on monthly plans (illustrative).
ScaleAbout 2 million renewals fall due on the busiest day of the month (illustrative).
ScaleThe payment provider accepts up to about 1,000 charge requests a second from you (illustrative).
ScaleFour plans, with prices that change a few times a year.

Out of scope

Out of scopeHow the payment provider reaches banks, cards and UPI.
Out of scopeThe accounting system and revenue reports.
Out of scopeDisputes and chargebacks.
Out of scopeHow tax is computed (a tax service gives you the amount).

Check yourself

Why can’t the billing system simply skip a subscription that already has a paid invoice this month?
Show answerHide answer
The dangerous case is a charge whose answer was lost before anything was marked paid, and a skip based on “paid” charges that customer again. Only an invoice saved before the charge, with its attempt recorded, shows the next run that money may have moved.

The numbers that shape the design

Illustrative exampleNumbers here are illustrative: round figures to reason with, not measurements.

Work out only the numbers this design depends on. The share of yearly plans is the assumption to say out loud.

Back of the envelope for subscription billing

Quantity	Value	Working
Renewals on an average day	About 1.2 million	About 90% of 40 million on monthly plans, over 30 days; yearly plans add about 11,000.
Renewals on the busiest day	About 2 million	From the brief.
Charges a second, averaged over that day	About 23	2 million ÷ 86,400; the provider takes about 1,000 a second.
The busiest day at the limit	About 37 minutes	2 million at about 900 a second.
Invoice data	About 900 GB a year	About 2 KB per invoice with its lines.

What the numbers tell you

The rates are small for a database; correctness every period, for years, is what shapes the design.
The busiest day is much busier than an average one, so the run is shaped to the provider’s limit.

Read:Learn: Numbers and capacity estimation

Try it: The numbers that shape the designGuided practice · Subscription billing, Streaming subscriptions, India and abroad · Senior

Check yourself

Why isn’t 40 million subscribers 40 million charges a day?
Show answerHide answer
Each subscription renews once a period, so an average day sees about 1.2 million renewals, and the brief’s busiest day about 2 million.

Core entities

Illustrative exampleNumbers here are illustrative: round figures to reason with, not measurements.

Start from the reads: a customer opening last year’s invoices, support explaining one amount, finance adding up a month. Amounts are whole numbers of the smallest unit with their currency, so ₹499.00 is 49900 paise.

The records that matter

Record	Key fields	Why it exists
Price	`price_id`, plan, `amount_minor`, `currency`, month or year, active from	A new row when a price changes, so every subscriber’s price stays known.
Customer	`customer_id`, country, the provider’s customer id and payment-method reference	Card numbers stay with the provider.
Subscription	`subscription_id`, price, `status`, trial end, current period start and end	Where the customer stands now, and what renews next.
Invoice	`invoice_id`, subscription, period start and end, `status`, `currency`, subtotal, tax, total	One non-void invoice per subscription and period; draft, open, paid, void or uncollectible.
Invoice line	invoice, description, dates covered, `amount_minor`	What was billed, for which days.
Charge attempt	invoice, attempt number, key, provider reference, outcome	Saved before each charge, so a rerun can find it.
Credit note	invoice, amount, tax, reason	A correction against an issued invoice.
Customer balance	customer, `currency`, `amount_minor`	Credits owed, per currency, used by later invoices.

Where each kind of data lives

Data	Store	Why
Subscriptions, invoices, attempts, credits	A transactional database: PostgreSQL, MySQL or Spanner	They change together, and amounts must be exact.
Card details	The payment provider	Billing keeps its reference and the last four digits.
Documents for the ledger	An outbox table	Each reaches the books once, by its id.

Architecture diagramPrices, subscriptions, invoices and what corrects them

Read:Learn: Data model design Learn: PostgreSQL

Try it: Plans, subscriptions and invoicesGuided practice · Subscription billing, Streaming subscriptions, India and abroad · Senior

Keep reading+1 min

Tax fixed at issue

The tax service gives the tax when the invoice is issued, and it is stored on the invoice. A rate change in July doesn’t alter a March invoice read in August: the invoice says what was charged then.

Check yourself

An invoice the customer paid last week used the wrong price. What do you do?
Show answerHide answer

The API

Illustrative exampleNumbers here are illustrative: round figures to reason with, not measurements.

A small surface that apps call for years, with the customer’s session; services use a service key. Card details go to the provider’s own form, a declined card is answered differently from a bad request, and the provider’s events reach an endpoint that checks their signature.

The calls the apps and services make

Call	Request	Response	Errors
`POST /v1/subscriptions`	price, the provider’s payment-method reference, trial	subscription id, status, trial end	`400`, `401`, `402` declined, `409` already subscribed
`GET /v1/subscriptions/{id}`	none	plan, status, current period end	`401`, `404`
`POST /v1/subscriptions/{id}/plan`	new price	the subscription, and the amount charged or credited	`400`, `404`, `409` once ended
`POST /v1/subscriptions/{id}/cancel`	now or at period end	the subscription	`404`, `409`
`PUT /v1/customers/{id}/payment-method`	the reference from the provider’s form	brand, last four, expiry	`400`, `402`
`GET /v1/customers/{id}/invoices`	cursor	invoices, next cursor	`401`, `404`
`GET /v1/invoices/{id}`	none	lines, tax, total, status, credit notes	`401`, `404`

Architecture diagramWho calls the billing API, and how the provider calls back

Read:Learn: API contract design

Try it: The API the apps callGuided practice · Subscription billing, Streaming subscriptions, India and abroad · Senior

Check yourself

An app gets an error back from starting a subscription. How does it know what to do?
Show answerHide answer
From the answer: 402 with the decline reason means ask for another card, 400 means fix the request, 409 means the customer already has one.

High-level design

Build the design one flow at a time.

Renew every period

Nobody opens the app on renewal day, so something on a timer starts each renewal. The order of saving and charging matters, and is the first deep dive.

A scheduler finds the subscriptions whose trial or period ends now, and the billing service gets the tax.
It saves the period’s invoice with its lines and tax, issues it, and records charge attempt 1 with its key.
It asks the provider to charge the invoice’s total to the saved card, with that key.
The answer is recorded: the invoice paid, the period moved on, and a receipt sent.

Architecture diagramA renewal with nobody in the app

Change the plan

A plan change part-way through a period follows one stated rule. An upgrade charges the difference; a downgrade credits the customer’s balance now or waits for the next renewal, as the stated policy says.

The app asks to move the subscription to Premium.
Billing credits the unused part of the old price and charges the rest at the new one, each line rounded once.
An upgrade’s net is billed now; a downgrade’s net credit goes to the balance.
Access switches to the new plan, and each document goes to the ledger once.

Architecture diagramA plan change: what it costs, who hears about it

Design a subscription billing system

The answer in two minutes

Also asked as

What interviewers look for

The decisions that matter

Understanding the problem

Functional requirements

Non-functional requirements

Scale

Out of scope

The numbers that shape the design

Core entities

Tax fixed at issue

The API

High-level design

Renew every period

Change the plan

Sign in with Google to read the rest

Practise this

The answer in two minutes

Also asked as

What interviewers look for

The decisions that matter

01Understanding the problem

Functional requirements

Non-functional requirements

Scale

Out of scope

02The numbers that shape the design

03Core entities

Tax fixed at issue

04The API

05High-level design

Start a trial

Renew every period

Change the plan

Sign in with Google to read the rest

12Practise this

Understanding the problem

The numbers that shape the design

Core entities

The API

High-level design

Practise this