Subscription Management and Billing

The majority of B2B SaaS applications have draw from four different subscription models:

  • User Based - Where we subscribe individual users to the system and grant access to features on a per user basis.
    • Free - Free access given to the system to a specific named user generally for an indefinite period of time.  This is the default state for any customers that sign-up for the app.  The goal of a Free user, from the company's perspective, is to show enough value and get enough user engagement to drive the user to have a discussion with the sales team about an enterprise license.
    • Professional - Where specific, named users have a subscription to access the system on a monthly or annual basis.   These users typically have access to most of the features of the system but are not given access to systemic, enterprise level features.
    • Enterprise - A license to use all the features of the system across a given, named organization.   This license level typically provides "full" access to the system and allows the creation of unlimited users in the context of that organization.  Enterprise licenses may be restricted in other ways such as API calls, storage or other metrics.
  • Usage Based - Where we care about the overall use of the system.   In this model, a license to use all the features of the system up to a certain level of usage (API calls, credits, whatever) for a period of time - almost always daily, monthly or annually.  In this license model as users access the service (in the UI, via API) a running total of their usage is kept.  When they exceed that level of usage they are either automatically billed for the overages or usage is cutoff until they "replenish" their credits.

Baseplate supports Free, Professional and Enterprise subscription types out of the box.   These are modelled in the subscription_types tables and mapped to specific products in Stripe.   The default period of time for a subscription is annual with a fallback to monthly as and if needed.   

Customer billing support is accomplished via Stripe Billing and each organization using Baseplate to deploy apps will need to setup their own Stripe instance.  Stripe will generally store all the detailed information related to subscriptions tiers, offering configuration pricing and handling the payments associated with subscriptions.  The result is Baseplate developers need to implement two things to support payments:

Pricing Table / Pricing Page 

Each application will provide a Pricing page that embeds a Stripe Pricing Table specific to the application.

  • The code for the pricing table is embedded using a simple SCRIPT tag
  • The look and feel of the pricing page is defined in the wrapping code and further configured in price
  • The content of the page itself is automatically created and delivered via Stripe
  • Activating a “Subscribe” button for any of the options will take the user to a hosted Stripe Checkout page
  • The pricing page will setup the pricing table with the following information:
    • Provide the mapped “Customer” object for the relevant customer
    • A Checkout Session related to this Customer object
      • We’d create a customer session for the user we’ve already authenticated server-side and return the client_secret to the client
    • Set the customer e-mail
      • The <stripe-pricing-table> web component supports setting the customer-email property. 
      • When the property is set, the pricing table passes it to the Checkout Session’s customer_email attribute, automatically entering the email address on the payment page
      • Pricing is only shown to customer that have registered with the system and are logged in

Customer Billing Portals

  • Customer specific billing portals will be provided via Stripe Billing Customer Portals support. 
  • Information on how to integrate these portals for each application is here.  Key things to integrate
    • Create the portal launch feature via a button that customers can click to enter the portal. (Instructions)
    • Setup webhooks to handle changes in subscription notifications (Instructions)
      • All the events provided via the webhooks into the customers action log
      • Only the events related to customer.subscription.updated and customer.subscription.deleted will trigger updates to the customers subscription setup in the system
        • When subscriptions are upgraded, downgraded, or canceled, you need to make sure that customers receive only the products or services they’re actively subscribed to. 
        • Stripe sends notifications of these changes to your integration using webhooks. 
        • In the Event object, look at the ID for the subscription or the customer to determine which customer the event applies to.
        • Stripe also sends notifications if an invoice is paid to your integration using webhooks. In the Event object, look at the ID for the invoice or the customer to determine which customer the event applies to.