This week has been fully focused on building, so this issue is going to be way more technical than usual. 🔨 

Brace yourself! 🚀 

There are many ways you can integrate Stripe for your SaaS, and today I will share how I tackled it myself.

Table of Contents

• Users’ onboarding and plans management

  • Beta phase and invite-only beta users

  • Generally available phase

  • Migrating beta users

• Representing subscriptions in the database

• Syncing Stripe’s subscriptions lifecycle

  • How subscriptions work in Stripe

    • Users reconciliation

  • Creating the product plans in Stripe

  • Webhook async implementation

• Pricing table component

• DaVinci Resolve

• Conclusion

• Appendix

  • Personal branding

    • X

    • Beehiiv newsletter

Users’ onboarding and plans management

Let’s start by understanding how the onboarding is implemented. I discussed it already both here and here, but this issue will focus more on the technical side of it.

This is going to be a great documentation for myself as well once I’ll face this again! 😂 

Beta phase and invite-only beta users

First of all, both the API and the web app have access to a flag named BETA_PHASE_ACTIVE that indicates whether the product is still in beta or not.

As you can imagine, this flag changes completely how the onboarding works.

When you go to the application during this phase, you’re redirected to the sign-up/in page. Once logged in you will be welcomed and blocked by a screen that says: “Oops! We're still working hard!“.

How can beta users start using the application then? 🤔 

The database has a profiles table and each user has a corresponding entry. One of the columns is a flag is_enabled which is false by default. The web application simply shows the blocking screen whenever a user is not enabled.

Initially, I was enabling users manually one by one by asking them to ping me once they created their account, but it was adding friction to the onboarding. Hence I implemented a very simple mechanism to automatically enable beta users.

The invitation to a beta user is a URL that looks like: https://app.useechowords.com/?invitation-key=<redacted>

When the web app calls the API for creating the user, it also provides the invitation key. If the provided invitation key matches the expected one, then the newly created user is automatically enabled. 🎉 

Ideally, you’d want to have unique invitation keys, but that was an overkill. 😅 

A beta user is also associated with a “fake” subscription which, in turn, is associated with a plan called “Beta” that never expires. In the following sections, I’ll cover more in-depth plans and subscriptions.

Generally available phase

This phase will start the day of the launch which has not been announced yet.

The BETA_PHASE_ACTIVE flag would be set accordingly and the user signing up would cause a profile to be created and enabled automatically. The other difference is that in this case no subscription is created, and the web app in case of no subscriptions associated with the profile, redirects to an onboarding page.

The onboarding page is simply a pricing table that is integrated with Stripe. Once a plan is chosen and the checkout is successful, a new subscription is created, and the user is given access. 🎉 

In the “Subscriptions“ section the user will be able to see again the pricing table and manage their plan.

In the following sections, I’ll explain in more detail the integration with Stripe.

Migrating beta users

During the “generally available” phase, beta users won’t be impacted as soon as their subscription is valid. Before invalidating a subscription, which can be done manually by changing the ending date in the database, I’ll reach out to each beta user.

I promised them a discount for providing feedback, so I’ll share a special offer for each plan through a Stripe payment link. ✨ 

Once a subscription is canceled, only the “Subscription“ page will be usable.

Representing subscriptions in the database

Let’s now see how I’m representing a plan and a subscription in the database.

There’s a plans table and each row corresponds to a specific combination of plan and billing interval. For example, given a “Basic” plan and two possible billing options, yearly and monthly, there would be two different rows in the plans table.

This is the schema of the plans table:

This means that unless I change pricing or add new plans, this table is going to be populated only once. This also includes a placeholder plan corresponding to the “Beta” plan.

So now we have a profiles table and a plans table. The subscriptions table is the table that links them. There are different scenarios, the ones that will occur during the GA phase are:

1. a user doesn’t have any subscription: a new user who joined during the GA phase and didn’t proceed with the onboarding,

2. a user with a subscription that is linked to the “Beta” plan: a beta user who accepted the invitation during the beta phase,

3. a user with only an active subscription: a new user who joined and onboarded during the GA phase,

4. a user with two subscriptions, but only one active: a beta user that has its first subscription expired and onboarded with a new one.

This is the schema of the subscriptions table:

Syncing Stripe’s subscriptions lifecycle

Okay, so now I have a way to represent a plan and a subscription on my side, but how do they link to the corresponding Stripe objects? 🤔 

If you checked the schema you might have noticed that both have a column called external_{plan,subscription}_id. That’s the id of the corresponding Stripe object! 💡 

All the updates happening on Stripe are notified in real-time to a webhook that is exposed in the API. It’s awesome that Stripe offers a way to test the webhook locally. 🤩 

The Stripe API documentation is really well done! I’m going to focus on 4 objects:

1. Product,

2. Price,

3. Subscription,

4. Payment Link.

The “Product” is your offer or your plan. In my case, I have 3 products: “Basic”, “Pro“, “Premium”.

Each “Product” can have multiple “Price“s. In my case, for each product, I have 2 prices: a monthly one, and a yearly one.

The “Subscription” can have multiple “Price”s. In my case, each subscription can have only 1 “Price”. In more complex scenarios a “Subscription” could be associated with a recurring price and other stuff depending on the complexity of the offer.

The “Payment Link” is simply an object with a URL that shows the checkout for a specific “Price”. Each CTA of the pricing table redirects to the corresponding “Payment Link”.

What’s the relationship between these 4 objects and the 2 tables? The plans table loosely corresponds to the “Price” objects and the subscriptions table to the “Subscription” objects.

How subscriptions work in Stripe

I’ll describe only what is necessary for managing what I needed, for the rest you can read more about subscriptions here.

A subscription goes through multiple statuses, the ones that I’m tracking are:

• active,

• past_due,

• canceled.

A new user signs up, and a profile is created. Once the user picks a plan in the pricing table and successfully checks out, an checkout.session.completed event is sent to the webhook.

This event contains all the information that I need including the “Subscription” and the “Price” object. At this point, I can create an entry in the “subscriptions” table, and associate it to the user.

As I mentioned above, once an active subscription is attached to the user, the web app will make the user move forward by granting access. 🚀 

Every time a subscription is renewed an customer.subscription.updated event is sent to the webhook. This makes it possible to ensure that the status is aligned. One important thing is that upon renewal, the subscription object is always the same with the very same id.

If the payment fails, the status of the subscription sent to the webhook is past_due. This makes it easy to reflect this change in the subscriptions table and block users from using the platform. ❌ 

Stripe will automatically retry the payments according to some rules that you can set in the dashboard, once all the retries will fail, an customer.subscription.deleted event is sent to the webhook. This event will change the status to “canceled”. At this point, there’s no going back for that subscription, the user would need to start a new checkout. This is the case where I’d have two subscriptions associated with the same user (excluding the case of beta users): an active one and a canceled one.

Users reconciliation

2 users successfully checked out, and you receive 2 checkout.session.completed events. How do you know which one corresponds to whom? 😅 

This is called “reconciliation”.

As mentioned above, each CTA in the pricing table redirects to the corresponding checkout, and the URL is given by the “Payment Link” Stripe object. This payment link can be extended by providing a query param client_reference_id.

Hence, each user will have the URLs specific to them with their own specific reference id. In my case, I’m using a unique identifier of the user in the profiles table. This value is then available when you receive the checkout.session.completed event so it’s possible to associate the subscription to the correct user.

Creating the product plans in Stripe

I started simply by using the Stripe dashboard. This was the best way to get started, understand how everything is linked, and explore the events in the webhook, etc. It’s great that Stripe has also a “development” mode where you can mess up however you want to explore and you also have a handy button to just reset it completely. 🚀 

Once I understood what I needed, I just didn’t want to rely on me manually copying to production the same products, prices, and whatever else. There should be a button to “clone” what you have from “development” to “production”, but still. 😅 

The thing is that billing is definitely something that I don’t want to fuck up. 🤣 

For this reason, I implemented a simple script that takes as input the definition of my “Product”s and “Price”s and creates them in Stripe using the API.

Webhook async implementation

Stripe expects your webhook to respond fast. Otherwise, Stripe would consider it as a timeout, and you’d mess up with the events. I’d rather not be in that situation. 😅

Yeah I know, I don’t have paying users yet, so I’m overthinking things that I might not even bump into. Still, billing is really something that I’d rather not ship buggy, even in the first launch. For this reason, I’ve been super careful in implementing this and I’m still covering all the possible scenarios (new users, beta users to migrate, etc.).

The requirement of being fast means that you should return a 2xx status code asap and all the operations on the database should be done async.

Pricing table component

Stripe offers a built-in pricing table that you can just embed as it is. But I don’t like it. 😂 In particular, when you toggle from monthly to yearly it doesn’t show the monthly cost, but only the total yearly cost, so it’s harder to see the benefit of the yearly plan.

For this reason, I ended up implementing my own. My implementation toggles between monthly and yearly plans, and also shows available promos.

DaVinci Resolve

DaVinci Resolve is a video editing tool. I’m not really into this space, so it might not be the right way to describe it, let me just copy here the description from the website:

DaVinci Resolve is the world’s only solution that combines editing, color correction, visual effects, motion graphics and audio post production all in one software tool!

Thinking about the launch, I started wondering whether a cool video teaser might be beneficial rather than just a loom video. 😅 

In my (little) spare time, I’m also exploring this. 😁 

Conclusion

Uff… Writing this was quite some work. 😅 

This might not be the BEST solution as Stripe is HUGE, but it seems that it’s working well.

Funny enough this morning I was thinking “I don’t know what to write today as I’ve been in fully building mode“. But in the end, there’s no reason why I shouldn’t write about this stuff as well. 😎 

I’m now making sure that all the scenarios are covered, and I also need to make sure that tracking the feature usage is still working. Last week I described how I implemented the tracking, but it has been implemented with some assumptions that turned out to be wrong once I started linking with Stripe objects. 😭 

I already implemented somehow the Stripe integration for NextCommit, but it was poorly done, that’s why I decided to start from scratch. This time, all this work will definitely be part of my own boilerplate.

The goals for the end of next week:

1. be ready for the launch from an implementation perspective (test all the scenarios for the billing, plan the migration of beta users, fix the usage tracking, etc.),

2. get all feedback from the beta users and prepare them for what will happen next,

3. plan the work needed for launch and decide on when to do it.

I hope you enjoyed this week’s updates! 👋 

If you’re interested in following my journey, make sure to subscribe or follow me on X/Twitter and LinkedIn!

Appendix

Personal branding

X

Beehiiv newsletter