If you are building a new SaaS or updating your onboarding flow and/or pricing model, you must understand your billing flow's high-level architecture.

SaaS freemium flow architecture

Let's understand the typical freemium billing flow from the end user's perspective. There are five steps each user will go through during the initial onboarding:

High-level flow diagram of SaaS freemium billing flow

User views pricing on the marketing website. This pricing can either be a static HTML page on your website or dynamically populated from your Stripe Products and Prices.

User creates a free account by registering. Whether you've built a custom SaaS or have used a no-code tool like Bubble, you have an account authentication system that allows users to register, login, logout, and have private access to your web app.

User continues to use the freemium features. Give value through the most basic features that solve the pain point of your users.

User upgrades their plan to use premium features. Once the initial value is provided, the user will upgrade to premium features through a plan picker.

User manages their subscription through a billing page. This is often called a customer portal that allows users to view their plan details, update credit card, upgrade or downgrade between plans, or download invoices.

Integrate Stripe Billing with your SaaS

In a freemium model, interaction with your billing system starts at the point when your free user accounts upgrade to premium plans. This guide assumes that you are using Stripe Billing, a Stripe product that handles the billing logic.

It is recommended not to create the customer or subscription objects in your billing system until the account is upgraded. This is different in the case of the free-trial flow.

Stripe Billing freemium SaaS integration flow

Plan Picker: shows the available plans for the user to upgrade by getting the price information from Stripe. Once the user selects and pays for a plan, the subscription will be created in Stripe, which automatically charges the user every on billing cycle.

Customer Portal: retrieves the subscription information from Stripe and shows it to the user. It will also allow the user to add and update the payment method card attached to the customer object, download the PDF-generated invoices, and cancel the subscription. Customer portal's functionality will evolve as you scale and require more retention behaviors such as churn flow.

The connection between your SaaS and the billing system is identified with either the logged in user's email or their Stripe customer id. This field mapping is stored at the tenant level in a tenant-based architecture—more on this in the future guide.

Set up webhooks

The last step to build your freemium billing flow is to sync the Stripe subscription data with your SaaS. The best way to get and store this data is to listen to Stripe's webhooks. There are three basic webhooks that you should listen to:

What is a webhook: How they work and how to set them up

customer.subscription.created - Occurs whenever a customer subscribes for a new plan.

customer.subscription.deleted - Occurs whenever a customer's subscription cancels.

customer.subscription.updated - Occurs whenever a subscription changes—for example, user upgrades or downgrades between plans.

For a more advanced setup, please refer to this guide.

Restrict access to features

You may want to restrict access to certain features based on the user's tier.

The two most basic attributes that you should store in your app's database regarding billing are each paid account's subscription status and subscription tier.

Subscription status: this is typically a string that defines whether the subscriber is active, canceled, or still on freemium.

Subscription tier: this is also a string data field that stores the plan name of each subscriber. This field allows you to gate what features the user has access to based on their current tier.

Billflow embeddable billing pages for Stripe Billing

The most time-consuming part of building your SaaS billing flow is the customer-facing billing pages. From showing the plan picker to the user to letting them manage their subscription, building a UI/UX of your billing can consume precious development resources. Billflow is a customer-facing UI toolkit on top of Stripe Billing that helps you build your billing flow in minutes without coding. You can embed billing page interfaces inside your SaaS.

Live Demo

Here is a video of an example freemium billing flow built using Stripe Billing and Billflow.

You can also view the live demo example bellow. Link to the demo.