Sign in Get started

Payments & Money APIs · Capstone

Capstone: SaaS Subscription Billing

Plans, seats, usage, dunning and entitlements for a B2B SaaS.

Scenario

A B2B SaaS sells three plans with per-seat pricing, annual and monthly billing, a usage-based add-on (API calls), 14-day trials and EU/US customers needing correct VAT/sales tax and invoices. Customers upgrade mid-cycle and add seats often. Failed renewals currently cut off access immediately, causing churn.

Requirements

  • Correct proration and tax
  • Usage billing from API metering
  • Graceful dunning
  • Fast, reliable entitlement checks

Constraints

  • Small team; prefer buying over building
  • Existing Postgres + event bus

Deliverables

  1. Choose build vs buy and design entitlements.
  2. Design usage metering and dunning.

Draft each deliverable below before revealing the model answer and rubric.

Further reading: Stripe Billing: How subscriptions work

Deliverables

Choose build vs buy and design entitlements.

Model answer

Use a billing platform (e.g. Stripe Billing/Chargebee) for plans, proration, invoices, tax and dunning. Entitlements table in Postgres (plan, seats, add-ons, status, period end) updated from billing webhooks (verified, deduped, re-fetched); app checks entitlements locally; seat changes go through our API → billing API with idempotency keys, quantity proration handled by the platform.

Rubric

Strong answers keep access decisions local and event-driven while delegating billing math to a platform.

Design usage metering and dunning.

Model answer

API gateway emits usage events (idempotent IDs) to the event bus → aggregator per customer per hour → report to billing meters (idempotent identifiers) → invoice at period end; customers see near-real-time usage dashboards and alerts at 80/100% of commitments. Dunning: smart retries over ~2–3 weeks, card updater, emails/in-app banners; status past_due keeps access with a banner for 14 days, then read-only, then downgrade; reactivation restores immediately on invoice.paid.

Rubric

Look for idempotent usage reporting, customer-visible usage, and a graceful grace-period policy instead of instant lockout.

Open in the app to mark lessons complete, take notes and track your progress.