Subscriptions
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 Stripe
Stripe, in conjunction with Bubble's official plugin, is engineered to streamline the management of subscriptions. 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
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.
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
To terminate a user's subscription to a plan, 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.
Article: The API Connector External page: Using trial periods | Stripe docs
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.
External page: Branding Settings | Stripe Dashboard
FAQ: Stripe subscriptions
How are invoices and receipts different?
Invoices and receipts serve different purposes in a financial transaction:
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.
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
Last updated
