How to Integrate Stripe Subscriptions in Bubble.io: The Right Way
Taking a one-off payment in Bubble.io is straightforward. Running subscriptions properly is not: users upgrade, downgrade, cancel, start trials and occasionally fail to pay, and your app must always know who has access. This guide shows the architecture that works in production: Stripe Checkout to start subscriptions, webhooks as the single source of truth, and the Stripe Customer Portal for self-service.
The most common mistake: granting access when the user lands back on your “success” page. Users can reach that page without paying, and it tells you nothing about renewals, cancellations or failed payments. Always update access from Stripe webhooks.
- The architecture at a glance
- Set up products and prices in Stripe
- Store subscription data in Bubble.io
- Start subscriptions with Stripe Checkout
- Webhooks: the source of truth
- Trials, upgrades and cancellations
- Failed payments and dunning
- Testing before launch
- FAQ
1. The architecture at a glance
- The user chooses a plan in your Bubble.io app
- Your app creates a Stripe Checkout session and sends the user to Stripe’s hosted payment page
- Stripe takes payment and creates the subscription
- Stripe sends webhooks to a backend workflow in your app
- The backend workflow updates the user’s or account’s subscription status
- Your app grants or restricts features based on that status
Payment details never touch your Bubble.io database, which keeps your card-data compliance burden low.
2. Set up products and prices in Stripe
In the Stripe dashboard, create a product for each plan (for example Starter and Pro) and a recurring price for each billing interval (monthly and annual). Copy each price ID; your app will use these IDs when creating checkout sessions. Work in Stripe’s test mode until everything is verified.
3. Store subscription data in Bubble.io
Add these fields to your User, or to your Account data type in a team-based SaaS:
| Field | Type | Purpose |
|---|---|---|
| stripe_customer_id | text | Links the user or account to the Stripe customer |
| stripe_subscription_id | text | Links to the active subscription |
| plan | option set | Which plan they are on, and which features it unlocks |
| subscription_status | option set | Trialing, Active, Past due, Canceled |
| current_period_end | date | When the current billing period ends |
Protect these fields with privacy rules so users cannot change them. Only backend workflows triggered by Stripe should update them.
4. Start subscriptions with Stripe Checkout
You can create Checkout sessions with the official Stripe plugin or with the API Connector. With the API Connector, the call to Stripe’s Checkout Sessions endpoint includes:
- mode: subscription
- line_items: the chosen price ID and quantity (or number of seats)
- customer (if the user already has a Stripe customer) or a customer email
- client_reference_id: the Bubble.io unique ID of the user or account, so the webhook knows whom to update
- success_url and cancel_url: pages in your app
Then redirect the user to the session’s URL. Our Bubble.io Stripe integration guide covers the API setup, parameter format and security in detail.
5. Webhooks: the source of truth
Create a backend workflow exposed as an API endpoint, and register its URL in Stripe’s webhook settings. Handle at least these events:
| Stripe event | What your app should do |
|---|---|
| checkout.session.completed | Save the customer and subscription IDs, set the plan, mark Active or Trialing |
| customer.subscription.updated | Update plan, status and period end after upgrades, downgrades or renewals |
| customer.subscription.deleted | Mark Canceled and restrict paid features |
| invoice.paid | Confirm the account is Active and extend the period |
| invoice.payment_failed | Mark Past due and prompt the user to update their card |
Make the endpoint safe: verify that events are genuinely from Stripe (for example by checking the event with Stripe’s API before acting), and make each step safe to run twice, because Stripe can resend events. More on backend workflows in our backend workflows guide.
6. Trials, upgrades and cancellations
Free trials
Set a trial period on the price or the Checkout session. Users get full access while the status is Trialing, and Stripe starts charging automatically when the trial ends.
Upgrades and downgrades
The simplest reliable approach is the Stripe Customer Portal. Your app creates a portal session for the customer and redirects them; they can switch plans, update cards and download invoices, and Stripe handles proration. Your app learns about every change through the webhooks above.
Cancellations
Through the portal, users can cancel immediately or at the end of the period. Keep access until current_period_end, then restrict features when the subscription is deleted.
7. Failed payments and dunning
Some renewals will fail, usually because a card expired. Turn on Stripe’s automatic retries and customer emails, mark the account Past due when invoice.payment_failed arrives, show a clear banner asking the user to update their card, and only restrict access after a grace period. This recovers a large share of failed payments. See dunning for SaaS for recovery emails and timing.
8. Testing before launch
- Use Stripe test mode and test cards, including cards that decline
- Test each event: new subscription, trial ending, upgrade, downgrade, cancellation and failed payment
- Confirm your app’s status changes after every webhook, using Bubble.io’s server logs
- Switch to live keys, re-register the live webhook endpoint and run one real low-value test
Building a marketplace that pays sellers rather than a subscription product? See Bubble.io Stripe Connect.
Frequently asked questions
Should I use the Stripe plugin or the API Connector in Bubble.io?
Both work. The official Stripe plugin is quicker for standard checkout and subscriptions. The API Connector gives full control over Stripe's API and is better for advanced setups such as custom checkout options, the customer portal and detailed webhook handling. Many production apps use the API Connector.
How does my Bubble.io app know a subscription is active?
Use Stripe webhooks as the source of truth. When Stripe sends events such as checkout.session.completed, customer.subscription.updated and customer.subscription.deleted, a backend workflow updates the subscription status stored on the user or account. Never activate access only because a user returned from the checkout page.
How do I let users cancel or change plans themselves?
Use the Stripe Customer Portal. Your app creates a portal session for the customer through the API and redirects them there, where they can update payment details, switch plans or cancel. Stripe then notifies your app through webhooks.
How do I handle failed subscription payments in Bubble.io?
Turn on Stripe's automatic payment retries and emails, listen for invoice.payment_failed webhooks, and mark the account as past due in your app. Give users a grace period and a clear prompt to update their card before restricting access.
Can I offer a free trial with Stripe in Bubble.io?
Yes. Set a trial period on the price or when creating the Checkout session. Stripe starts billing automatically when the trial ends, and sends events your app can use to update the user's status.
Want subscriptions built right from day one?
Book a free Idea Audit. We build Stripe billing, trials, plan changes and dunning into SaaS products on Bubble.io.