DEV Community

FastAPI Incident Analyst
FastAPI Incident Analyst

Posted on

Building a Stripe Subscription Backend with FastAPI

#fastapi #stripe #python #webdev

Many Stripe tutorials stop at Checkout integration.

But real SaaS products require more than that.

A production subscription backend must handle:

  • subscription state management
  • webhook processing
  • access control
  • expiration logic
  • duplicate webhook protection

To explore this architecture, I built a small project:

FastAPI Revenue Core

Repository
https://github.com/hiro-kuroe/fastapi-revenue-core

This project demonstrates a minimal SaaS-style subscription backend using FastAPI and Stripe.

What This Project Implements

The backend includes the essential components required for subscription-based services.

  • JWT authentication
  • Stripe Checkout integration
  • Stripe Webhook processing
  • Subscription state engine
  • Automatic expiration logic
  • Docker deployment

The goal was to build a reusable revenue backend foundation that could power subscription products.

Architecture

The system is intentionally simple.

Client
   ↓
FastAPI API
   ↓
Stripe Checkout
   ↓
Stripe Webhook
   ↓
Subscription Status Engine
Enter fullscreen mode Exit fullscreen mode

Stripe handles payment processing.

The FastAPI backend manages user access state.

This separation keeps payment logic clean and allows the API to control feature access.

Subscription State Engine

Each user has a subscription status stored in the database.

FREE
PRO
EXPIRED
Enter fullscreen mode Exit fullscreen mode

Stripe webhook events update these states.

Example transitions:

subscription.created
FREE → PRO

subscription.deleted
PRO → EXPIRED
Enter fullscreen mode Exit fullscreen mode

This state engine ensures the backend always knows whether a user has access to paid features.

Handling Subscription Expiration

Stripe provides the timestamp:

current_period_end
Enter fullscreen mode Exit fullscreen mode

Example extraction:

period_end_ts = items[0]["current_period_end"]
Enter fullscreen mode Exit fullscreen mode

This timestamp is stored in the database and used to determine whether the user's subscription has expired.

Whenever a protected API endpoint is accessed, the backend checks the expiration timestamp.

If the subscription is no longer valid:

PRO → EXPIRED
Enter fullscreen mode Exit fullscreen mode

This guarantees that access control stays correct even if webhook timing changes.

Webhook Design

Stripe webhooks are essential for subscription systems.

The backend processes events such as:

customer.subscription.created
customer.subscription.deleted
Enter fullscreen mode Exit fullscreen mode

The webhook updates user subscription status and expiration timestamps.

Because Stripe may resend webhook events, the backend design supports idempotent event handling to avoid duplicate processing.

Running the Project

Clone the repository:

git clone https://github.com/hiro-kuroe/fastapi-revenue-core
cd fastapi-revenue-core
Enter fullscreen mode Exit fullscreen mode

Install dependencies:

pip install -r requirements.txt
Enter fullscreen mode Exit fullscreen mode

Run the server:

uvicorn app.main:app --reload
Enter fullscreen mode Exit fullscreen mode

Swagger documentation will be available at:

http://localhost:8000/docs
Enter fullscreen mode Exit fullscreen mode

Running with Docker

The project also supports Docker deployment.

Build the image:

docker build -t fastapi-revenue-core .
Enter fullscreen mode Exit fullscreen mode

Run the container:

docker run -p 8000:8000 fastapi-revenue-core
Enter fullscreen mode Exit fullscreen mode

What This Project Demonstrates

This repository demonstrates a minimal backend architecture for subscription-based services.

It combines:

  • FastAPI
  • Stripe subscription billing
  • webhook processing
  • access control logic
  • Docker deployment

This type of backend is commonly used for:

  • SaaS products
  • paid API services
  • membership platforms
  • subscription-based applications

Repository

Full source code:

https://github.com/hiro-kuroe/fastapi-revenue-core

Final Thoughts

Stripe integration tutorials often focus only on payment processing.

But real subscription systems require:

  • backend state management
  • expiration handling
  • webhook reliability
  • API access control

This project demonstrates how these pieces can be combined into a simple but practical backend architecture.

If you're building a FastAPI SaaS backend or working with Stripe subscriptions, feel free to check out the repository.　　

Incident Intake

If you are experiencing issues with Stripe payments or subscription systems,

you can submit a diagnosis request through the intake form below.

Typical problems include:

  • Stripe Webhook not triggering
  • Subscription status not updating
  • Checkout succeeds but user access does not change
  • Cancelled subscriptions still retaining access

Submit an incident report here:

https://github.com/hiro-kuroe/fastapi-revenue-core/blob/main/Intake-en.md

Top comments (0)