Bubble Docs
  • Introduction
  • New? Start Here
  • What is Bubble?
  • The Glossary
  • User manual
    • Getting started
      • What is Bubble?
      • Building your first app
        • Planning features
        • Database structure
        • Design and UX
        • eCommerce and payments
          • Shopping cart
          • Checkout page
          • One-time payments
          • Subscriptions
          • Marketplace
      • Creating and managing apps
      • The Bubble editor
        • Tabs and sections
          • Design tab
            • The element tree
            • The property editor
          • Workflow tab
          • Data tab
          • Styles tab
          • Plugins tab
          • Settings tab
            • Application settings
              • Custom headers/body
              • Visual settings
              • Social media sharing
              • Translating your app
              • Email settings
              • Collaboration
            • Custom domain and DNS
          • Logs tab
        • Tools
          • Key features
          • The search tool
          • The Issue Checker
          • The element tree
          • The element property editor
          • The debugger
          • Notes
        • Previewing your app
      • Transitioning to Bubble from...
        • JavaScript
        • HTML and CSS
        • SQL
    • Design
      • Elements
        • The element hierarchy
          • The element tree
        • The page
        • Containers
          • Groups
          • Repeating groups
          • Table elements
          • Popups
          • Floating groups
          • Group focus
        • Visual elements
        • Input forms
          • Text and numbers
          • Dates and time
          • File uploads
          • Selection controls
        • Reusable Elements
      • Styling
        • Color variables
        • Font variables
        • Styles
        • Custom Fonts
      • Responsive design
        • Building responsive pages
        • Legacy articles
          • The Basics (Legacy)
          • Building Responsive Pages (Legacy)
          • Migrating Legacy Pages
          • Tips When Designing (Legacy)
      • Templates
      • The Component Library
      • Importing from Figma
    • Data
      • The database
        • Data types and fields
        • Creating, saving and deleting data
        • Finding data
        • Displaying data
        • Protecting data with privacy rules
        • The database editor
        • Export/import data
          • Exporting data
          • Importing data (CSV)
        • Working with location data
        • Using Algolia
        • Database structure by app type
          • Marketplace Apps
          • Directory & Listings Apps
          • Social Network Apps
          • SaaS Apps
          • Project Management Apps
          • CRM Apps
          • Professional Services Apps
          • On-demand Apps
          • Documentation/ CMS Apps
          • Applicant Tracking System (ATS) Apps
          • Portfolio Apps
          • Gallery Apps
          • Online Store / Ecommerce Apps
          • Blog Apps
          • Messaging App
          • Dashboards
          • Building Block Apps
          • Bubble as a backend
      • Files
      • Images
      • Static data
        • App texts (translations)
        • Option sets
      • Temporary data
        • Custom states
        • URL parameters
      • User accounts
        • Authentication plugins
          • Facebook plugin
          • Fitbit plugin
          • Google plugin
          • Instagram plugin
          • LinkedIn plugin
          • Pinterest plugin
          • Slack plugin
          • Wistia plugin
          • YouTube plugin
        • Cookies set by Bubble
      • Time, dates and time zones
    • Logic
      • The frontend and backend
      • Workflows
        • Events
          • Frontend events
            • Recurring workflows
            • Custom events
          • Backend events
            • Database trigger events
        • Actions
        • API Workflows
      • Dynamic expressions
      • Conditions
      • Navigation
        • Single-page applications (SPA)
        • Multi-page applications
        • Page slugs
    • Workload
      • Understanding workload
        • Activity types
        • The workload calculation
        • Client-side and server-side processing
      • Tracking workload
        • Measuring
          • Using App Metrics
        • Monitoring
          • Workload notifications
          • Infinite recursion protection
      • Optimizing workload
        • Optimization framework
        • Optimization checklist
          • Page load
          • Searches
          • Workflows and actions
          • Backend workflows
        • Agency showcases
          • Minimum Studio
          • Neam
          • Support Dept
    • Security
      • Bubble's security features
      • Planning app security
      • Client-side and server-side
      • Bubble account security
      • App security
      • Page security
      • Database security
      • API security
        • API Connector security
        • Data API security
        • Workflow API security
      • Flusk
        • Overview
        • Flusk plan features
        • Getting started with Flusk
        • Flusk security tools
          • The Issues Explorer
          • Issue details
          • Tools and settings
            • Pages rating
            • Database rating
        • Flusk FAQ
      • Cookies
      • Security checklist
    • Publishing your app
      • Web app
      • Native mobile app
        • Global native mobile settings
        • iOS App Store
        • Google Play Store
        • Publishing FAQ
    • AI
      • Generate apps with AI
        • About AI app generation
      • AI page designer
      • Connect to AI agents
    • Maintenance
      • Collaborators
      • Version control
        • Best practices: Version control
        • Transitioning from the legacy version control
        • Terminology: Version control
        • Version Control (legacy)
      • Commenting
      • Database maintenance
        • Copying the database
        • Restoring database backups
        • Bulk operations
          • Bulk operation methods compared
        • Wiping change history
      • Performance
        • Hard limits
        • Capacity Usage (legacy)
        • Notes on queries
      • SEO
        • Introduction to SEO
        • SEO: App
        • SEO: Page
      • Testing and debugging
        • Introduction to testing and debugging
        • The debugger
        • The server logs
        • Supported browsers
      • API workflow scheduler
    • Integrations
      • API
        • Introduction to APIs
          • What is a RESTful API?
        • The Bubble API
          • Bubble API terminology
          • Authentication
            • How to authenticate
            • No authentication
            • As a User
            • As an admin
          • The Data API
            • Data API Privacy Rules
            • Data API endpoints
            • Data API requests
          • The Workflow API
            • Workflow API privacy rules
            • Workflow API endpoints
            • API workflows
              • Creating API workflows
              • Scheduling API workflows
              • Recursive API workflows
              • API Workflow Scheduler
              • Case: Stripe notifications
        • The API Connector
          • Authentication
          • API Connector security
          • API guides
            • OpenAI
              • Authentication
              • Calls
                • ChatGPT
                  • Chat
            • Google Translate
              • How to setup Google API keys
          • Streaming API
        • API security
        • Plugins that connect to APIs
        • API Glossary
      • Plugins
        • What Plugins Can Do
        • Installing and using Plugins
        • Authentication plugins
        • Special Plugins
      • SQL Database Connector
      • Bubble App Connector
      • WorkOS
        • WorkOS SSO
        • WorkOS API
    • Infrastructure
      • Sub-apps
      • Bubble release tiers
      • Hosting and scaling
        • How Bubble hosting works
        • Scaling with Bubble
        • CDN (Cloudflare)
        • Bubble app names
        • Domain and DNS
      • Compliance
        • GDPR
        • SOC 2 Type II
        • HIPAA
        • Other frameworks and standards
    • Bubble for Enterprise
      • Hosting and infrastructure
        • Dedicated instance
          • The Dedicated editor experience
          • Technical specs
          • Main cluster dependencies
          • Customizable options
          • Migration process
            • Pre-migration
            • During migration
            • Post-migration
      • Security and compliance
        • Single sign-on (SSO)
        • GDPR
        • SOC 2 Type II
        • HIPAA
        • Other frameworks
        • Bubble's security features
      • Admin and collaboration
      • Priority support
      • Billing and Payment Guideline for Dedicated Instances
  • Core Reference
    • Using the core reference
    • Bubble's Interface
      • Design tab
      • Design tab (Legacy)
      • Workflow tab
      • Data tab
      • Styles tab
      • Styles tab (Legacy)
      • Plugins tab
      • Settings tab
      • Logs tab
      • Template tab
      • Toolbar
      • Top and context menu options
      • Deployment and version control
        • Deployment & Version Control Dropdown (legacy)
      • Notes
    • Elements
      • General properties
      • General properties (Legacy)
      • Styling properties
      • Styling Properties (Legacy)
      • Responsive Properties
      • Responsive Properties (Legacy)
      • Conditional formatting
      • States
      • Page Element
        • Page Element (Legacy)
      • Visual Elements
      • Containers
      • Container Layout Types
      • Containers (Legacy)
      • Input Forms
      • Reusable Elements
      • Element Templates (legacy)
    • Workflows
    • Events
      • General events
      • Element events
      • Custom events
      • Recurring event
      • Database trigger event
    • Actions
      • Account
      • Navigation
      • Data (things)
      • Email
      • Element
      • Custom
    • Data
      • Data Sources
      • Operators and comparisons
      • Search
      • Privacy
    • Styles
    • API
      • The Bubble API
        • The Data API
          • Authentication
          • Data API endpoints
          • Data API requests
        • The Workflow API
      • The API Connector
        • Authentication
        • Adding calls
    • Bubble-made Plugins
      • AddtoAny Share Buttons
      • Airtable
      • API Connector
      • Blockspring
      • Box
      • Braintree
      • Bubble App Connector
      • Chart.js
      • Circle Music Player
      • Draggable Elements
      • Dropzone
      • Facebook
      • Fitbit
      • Full Calendar
      • Google
      • Google Analytics
      • Google Optimize
      • Google Places
      • Ionic Elements
      • iTunes
      • Slidebar Menu
      • LinkedIn
      • Localize Translation
      • Mixpanel
      • Mouse & Keyboard Interactions
      • Multiselect Dropdown
      • Progress Bar
      • Rich Text Editor
      • Rich Text Editor (Legacy)
      • Screenshotlayer
      • SelectPDF
      • Slack
      • Segment
      • Slick Slideshow
      • SQL Database Connector
      • Star Rating
      • Stripe
      • Tinder-like Element
      • Twitter
      • YouTube
      • Zapier
    • Application Settings
      • App plan
      • General
      • Domain / email
      • Languages
      • SEO / metatags
      • API
      • Collaboration
      • Sub-apps
      • Versions
  • Account & Marketplace
    • Account and billing
      • Pricing and plans
        • Plans and billing
        • Billing cycle
        • FAQ: Pricing and Workload
      • Account Management
      • Building Apps for Others
      • Selling on the Marketplace
      • Plans & Billing (legacy)
    • Official Bubble Certification
      • Hiring certified developers
    • Building Plugins
      • The Plugin Editor
      • General Settings
      • Updating to Plugin API v4
      • Adding API Connections
      • Building Elements
      • Building Actions
      • Loading Data
      • Publishing and versioning
      • Github Integration
    • Building Templates
    • Application and data ownership
    • Marketplace policies
    • Bug reports
  • Vulnerability Disclosure Policy
  • Beta features
    • About the Beta features section
    • Native mobile apps 🔒
      • Introduction
        • What is a native mobile app?
        • Native mobile vs. web development
        • Differences in native and web elements
        • Native mobile app terminology
      • Building
        • Views and navigation
        • Native mobile actions
        • Components and gestures
        • Device resources
          • Location services
          • Camera/photo library
      • Previewing
      • Publishing
Powered by GitBook
On this page
  • Defining subscriptions
  • Planning subscription services
  • Single subscription
  • Multiple plans
  • Long-term commitment discounts
  • Managing plans and subscribers in your Bubble app using Stripe
  • Subscribing a user to a plan in your Bubble app
  • Confirming the transaction and subscription
  • Canceling a plan subscription in your Bubble app
  • Incomplete payments
  • Trial periods
  • Invoices
  • What's included on a Stripe invoice?
  • Customizing invoices
  • FAQ: Stripe subscriptions
  • Other ways to learn

Was this helpful?

  1. User manual
  2. Getting started
  3. Building your first app
  4. eCommerce and payments

Subscriptions

Last updated 2 days ago

Was this helpful?

Disclaimer: Note that while Stripe is mentioned in this document as an example of a payment platform, this should not be interpreted as an endorsement or recommendation of Stripe's services. The information provided here does not constitute legal advice. As an app builder, it is your responsibility to select a payment platform that meets your specific needs. You are also responsible for ensuring compliance with the terms and conditions of the chosen payment platform.

We encourage you to conduct thorough research and, if necessary, consult with a legal professional to make an informed decision.

Defining subscriptions

Subscriptions are a form of payment setup that triggers billing at set, recurring times. This can be particularly useful in scenarios like collecting a monthly or annual fee in exchange for a product or service offered by your app.

This model is frequently employed by SaaS (Software as a Service) applications, where the product is the app itself. Implementing a subscription-based payment system simplifies the financial relationship for both the app owner and the user, ensuring a consistent revenue stream for the former and uninterrupted service access for the latter.

Planning subscription services

Just as with other payment types, it's useful to carefully consider your revenue model and the kind of subscription you plan to charge your users before you build it.

In this section, we'll explore various options you can consider for your subscription model. This will help you make informed decisions about structuring your app's revenue stream in a way that aligns with your business goals and meets your users' needs.

Single subscription

Simply offering one single subscription at a set cost is the easiest way to get started. In this scheme, your end-users are not looking at multiple plans, discounts or anything else that might complicate the pricing structure, but are simply offered one choice with a set price.

Example:

Plan
Price

Monthly subscription

$12

Multiple plans

For complex apps and services, it can be beneficial to offer multiple subscription plans, providing end-users with options to choose how much they're willing to pay. Typically, the price point of each plan correlates with the level of access or features available to the user.

This tiered approach allows users to select a plan that best fits their needs and budget, while also giving them the flexibility to upgrade for more advanced features as required.

Example:

Plan
Price
Possible differences

Basic plan

$12 per month

Basic features

Professional plan

$24 per month

Additional features, additional team members

Enterprise plan

$36 per month

All features, advanced reports, even more team members

The previous description serves merely as an example to demonstrate a potential approach to structuring tiered subscription plans. The specific plans you choose to offer and their distinct features depend entirely on your preferences and business strategy. However, it's advisable to have a clear plan in place before beginning development. This ensures that both your app and Stripe setup are aligned and configured to support your chosen subscription model effectively.

Long-term commitment discounts

Some services offer discounts on their plans as an incentive for end-users who commit to a longer subscription period. For instance, choosing an annual plan might come with a discount, serving as a reward for the user's willingness to pay a larger sum upfront.

There doesn't need to be any kind of complex calculations behind this – simply set up a new plan with a different price in Stripe's dashboard.

Managing plans and subscribers in your Bubble app using Stripe

The different between subscriptions and plans

When working with subscriptions and plans, it's useful to get to know the difference between the two, and how they are stored in Stripe.

In short, a user is subscribed to one or more plans. In other words, the subscription object contains information such as the customer, start/end dates, trial period, and plan(s) the user is subscribed to.

The plan object contains the information about a particular subscription offering. It specifies details such as the name, cost, and billing interval.

Stripe, in conjunction with Bubble's official plugin, is engineered to streamline the management of subscriptions in your Bubble app. This entails the straightforward creation of pricing plans, specification of pricing and billing frequency, and instructing Stripe to manage the subscription process on your behalf. You will find all the plugin's actions under the Payments section in the action dropdown.

When you build an app using subscriptions, most of the work is usually done in the Stripe dashboard:

  • Create plans: In your Stripe Dashboard, you can define the products or services you offer, along with the pricing plans associated with them. You'll specify details such as the plan name, pricing amount, billing frequency (e.g., monthly or annually), and any trial periods if applicable.

  • Customer billing: When a user subscribes to one of your plans, Stripe handles the billing process. It can generate invoices, automatically charge customers according to the billing frequency, and send email notifications about upcoming charges.

  • Subscriber management: You can easily manage your subscribers within the Stripe Dashboard. This includes handling cancellations, upgrades, downgrades, and other subscription-related actions.

  • Subscription events: Stripe provides events related to subscriptions, allowing you to track changes, cancellations, or other subscription-related actions in real-time. You can set up webhook endpoints in your Bubble app to handle these events.

  • Reporting and analytics: Stripe offers reporting tools that help you gain insights into your subscription business. You can access data on revenue, customer retention, churn rates, and more.

Subscribing a user to a plan in your Bubble app

Before proceeding to set up the action needed to start an end-user on a plan, you need to set up one or more plan(s) in the Stripe Dashboard and finish setting up the Stripe plugin with Client ID and Secret Key. Bubble will then fetch the available subscription plans for you.

To start a subscription for a user, you use the action. A user can be subscribed to one or more plans at the same time, and you can start multiple plans in one single action by using the property.

When you use the Subscribe a user to a plan action, Bubble will redirect the user to the Stripe checkout page, where they can enter their card details.

Confirming the transaction and subscription

As the illustration shows, the final step of the process is redirecting the end-user back to the page where the initial page where the process was started. Bubble behaves as if the user never left the page, meaning that the workflow that contained the Charge the current user action will continue to run as soon as the end-user returns to the page.

The plugin connects to Stripe's API, which means that Stripe gets a request from your app, and then sends a response in return. You can use this to verify that the payment was successful, or to display an error message if it wasn't, as well as save any relevant data in your database as needed.

Stripe's response

The following parameters are made available after a charge has been attempted (whether it was successful or not):

  • Subscription ID: The unique identifier for the subscription.

  • Plan ID: Unique identifier for the subscription plan associated.

  • Plan name: The name of the subscription plan.

  • Items: Lists subscription items.

  • Status: Describes the current status of the subscription.

  • Starting date: When the subscription started.

  • Creation date: Denotes when the subscription was created.

  • Current period starting date: The start date of the current billing period.

  • Current period ending date: The end date of the current billing period.

  • Quantity: Specifies the associated quantity.

  • Trial end date: Indicates when any trial period ends.

  • Trial start date: Indicates when any trial period ends.

The expandable box above shows the different parameters that are returned to your app after a charge attempt has been made. If the charge was unsuccessful, Stripe will still return parameters. The following key parameters are often a good idea to save, to make it easy to manage the subscription later:

  • Subscription ID (text): this is the auto-generated unique ID of the subscription object in Stripe's records. It's often useful to save this ID in your app's database, so that you are able to refer to it later as needed. For example, if you want to cancel a subscription, you will need this ID. You cannot set the initial value or change the value of this ID. There's normally no reason to display this value to the end-user.

  • Plan ID: this is the auto-generated unique ID of the plan in Stripe's records. The ID is generated when the Plan is created, and not when a subscription is created. You cannot set the initial value or change the value of this ID.

Other parts of the response can of course be useful to store as well, but these two make it easy to quickly identify a subscription and the plan to which the subscription is connected.

Canceling a plan subscription in your Bubble app

To terminate a user's subscription to a plan in your Bubble app, you can use the Cancel the current user's plan action. You can cancel multiple plans in a single action

Incomplete payments

Common misconception: Note that Incomplete payments refer to the status of the transaction, not the amount to be paid. In other words, an incomplete payment in this context is a transaction process that is not yet completed.

The Subscribe the user to a plan action lets you allow incomplete payments. You can specify the behavior using the Payment behavior dropdown. This property allows you to set the status of subscriptions as "incomplete" if it can't be fully completed.

Why use incomplete payments?

Stripe Checkout handles by default, ensuring that payments are authenticated according to regulatory requirements. However, there may be scenarios where additional customer actions are necessary to complete a payment.

In such cases, the incomplete payment parameter provides flexibility in managing subscriptions. For example, if a payment requires SCA authentication but the customer fails to complete the process within a specified time frame, the subscription may transition to an incomplete status. This allows you to handle scenarios where payments cannot be immediately confirmed, providing a seamless experience for both you and your customers while ensuring compliance with regulatory requirements.

Time limit: If the PaymentIntent remains unconfirmed for 23 hours, subscriptions automatically transition to an incomplete_expired status, at which point the payment is considered failed.

The following options are available when you set the Payment behavior property. The Stripe parameter column indicates the associated .

Option
Stripe Parameter
Explanation

Allow incomplete

allow_incomplete

Creates Subscriptions with status=incomplete if the first invoice requires additional payment actions from the customer.

Error if incomplete

error_if_incomplete

Generates an error if the first invoice can't be paid, preventing the creation of Subscriptions with incomplete status.

Pending if incomplete

pending_if_incomplete

Sets Subscriptions with status=pending if the first invoice requires additional payment actions from the customer. Useful for managing scenarios where additional actions are needed before activating the Subscription.

Default incomplete

default_incomplete

Sets the default behavior for Subscriptions, creating them with incomplete status if the first invoice requires additional payment actions from the customer.

Trial periods

Setting up a trial period is not support by the Stripe plugin, but you can set this up in the API Connector plugin.

Stripe allows you to provide trial periods in your app, allowing customers to try it out for a specified duration before making a payment. This is useful when you want your customers to be able to try out your app for a free period, such as a week or month.

To set up a trial period, all you need to do is to add the trial_end parameter to the call. This is a timestamp that determines when the trial should end. As such, you don't set up a given period, but a start and end date, where the start date is automatically set to the time of signup and the end date is specified with the trial_end parameter.

After the trial period concludes, and if the subscription status hasn't been paused, Stripe automatically generates an invoice for the subscription. Starting a trial period requires the user to provide their card details.

Invoices

Stripe automatically creates an invoice for each billing cycle of a subscription (including the first). When you subscribe a customer, the invoice is first generated, and then immediately finalized.

On later billing cycles, the process looks slightly different:

First, Stripe generates the new invoice. It maintains this invoice in a for 60 minutes, while it tries to finalize the transaction using the user's saved payment method. This is to avoid the invoice becoming without payment. If the payment is successful, the invoice is updated to paid.

What's included on a Stripe invoice?

Stripe automatically includes the following information on invoices. Your app needs to provide information as needed:

  • Line items with product details

  • Custom invoice numbering

  • Customer information

  • Discounts or coupons

  • Tax rates

  • Footer

Customizing invoices

Stripe lets you customize invoices so that they match your company's brand. You can customize the following points:

  • Icon

  • Logo

  • Brand color

  • Accent color

Changes to the brand can be done through the Stripe's API, but is not supported in the official Stripe plugin. However, you can change the design of the invoice in the Stripe Dashboard, by opening the Branding settings panel.

FAQ: Stripe subscriptions

How are invoices and receipts different?

Invoices and receipts serve different purposes in a financial transaction:

  1. Invoice:

    • An invoice is a document issued by a seller to request payment from a buyer for goods or services.

    • It typically includes details such as the seller's information, buyer's information, a breakdown of products or services provided, quantities, prices, and the total amount due.

  2. Receipt:

    • A receipt is a document provided by the seller to the buyer after the payment has been made.

    • It acknowledges that payment has been received and provides proof of the transaction.

    • A receipt usually includes information such as the date of payment, payment method, transaction reference or ID, and details of what was purchased.

What is a line item?

A line item is a specific entry or itemized charge within an invoice or bill that represents a particular product, service, or fee. It includes the item's description, price, currency and tax rate. You can optionally link the line item to an existing subscription by providing the subscription ID.

Line items are used to clearly specify what the recipient of the invoice is being charged for, making it easier to understand and verify the expenses or services being billed.

Let's illustrate with an example, and imagine your company is offering a SaaS app plan. In addition, you offer extra credits that can be used for fast-track customer support:

Invoice: ABC-123 Date: January 15, 2024 Due: February 1, 2024

Product
Currency
Cost

Monthly fee

USD

$39.00

Extra credits

USD

$12.00

Each of the rows is one line item. Stripe automatically includes a line item for the relevant plan the user is subscribed to, and you can add additional line items as needed by using the action.

Other ways to learn

Articles
Core reference
External documentation

Article: External page:

External page:

- how to set up API workflows that can receive webhooks from Stripe

- setting up additional Stripe API calls not supported by the official Stripe plugin, using the API Connector

– use ready-made component templates to set up designs similar to the pricing plans example above

The API Connector
Using trial periods | Stripe docs
Branding Settings | Stripe Dashboard
The Bubble API
The API Connector
The Component Library
The Stripe plugin
Stripe docs
Subscriptions
Prorate for usage-based billing
Invoices
Webhooks
With a single action, you can set up regular payments from a customer.
All actions related to Stripe can be found under the Payments section in the action dropdown.
Using multiple different plans you can offer your customers tiered payments. Hint: the design above is part of Bubble's , and you can set up one just like it in seconds.
Component Library