Subscription Management Portal Configuration

Overview

The Subscription Management Portal is designed to be flexible and easy to set up for any pricing model and on-boarding flow. The Portal handles the initial creation of your users subscription in Stripe, as well as the subscription management functionality. Below is a list of options as well as how those setting will change what your users see in the portal. You can change these setting from the Servicebot Dashboard or directly in code.

Settings

Property Name

Type

Required?

Description

servicebot_id

string

yes

Servicebot unique ID associated with your account. It can be found on the Dashboard->Subscription Portal. Note: This ID is different for Live & Test mode.

email

string

no

User's email. The email for the user must be on the Stripe Customer object as well. Also required for the signup process, and Servicebot will automatically create a Stripe Customer with email set. The Stripe customer ID may also be used as the primary lookup key.

customer_id

string

no

Stripe customer ID. This ID can be used to display a customer's subscription information. Eg: cus_FtWXI6U0YxebLd

hash

string

no

An HMAC string used for authenticating the user loading the embed more securely. This is required in order to go to 'Live Mode' in Servicebot (connected to 'Live Mode' in Stripe).

service

string

no

The service name configured in Stripe (metadata sb_service). This is required to use the Plan Picker functionality and to use the portal for signup. If a customer has a subscription already they will still be able to see the subscription details from the portal. This is also required in the signup process if you want to automatically register a user for a specific tier and interval.

subscription_id

string

no

The Stripe subscription ID. Pass if you want a user to only see and manage a single subscription. Used if your customers have multiple subscriptions and you only want them to view one.

handleResponse

function

no

Function that is called when users signup, change plan (upgrade/downgrade), resubscribe, or update Credit Card. Used to update user data, do redirects, or provide notifications. Details below.

options.hideCancelDropdown

boolean

no

Set to true to disable users from being able to cancel their subscription on their own

options.disableCoupon

boolean

no

Set to true to hide the coupon section from users on signup and on the subscription management portal

options.hideChangePlan

boolean

no

Set to true to disable users from being able to change their plan (upgrade/downgrade)

options.hideUpdateCard

boolean

no

Set to true to disable users from being able to update their Credit Card information

options.forceCard

mixed

no

By default, the embed UI does not ask for payment information if they are on a free tier or there is a free trial for the tier.

This setting will enforce credit card form to show up as required input when users signup, change plan resubscribe depending on the value you set here. The available values are as follows:

true = always enforced for any of the events.

'always' = same as true, always enforced.

'signup' = only when user is signing up.

'change_plan' = only when user is changing plan.

options.cancel_now

boolean

no

Set to true to force cancellations to go through immediately. By default Servicebot will cancel a subscription at the end of the billing cycle.

options.disableTiers

array

no

Add an array of tiers (corresponds to metadata tag sb_tier) to disable users from being able to change to those specific plans. Eg: ['Tier 1', 'Tier 2']

options.messageOnCancel

string

no

A message to override the default cancellation message. When a user selects to cancel their plan, this is the message that appears in the pop-up.

options.card.hideName

boolean

no

Set to true to hide the name field on the Credit Card form.

options.card.hideAddress

boolean

no

Set to true to hide the address field on the Credit Card form.

options.card.hideCountryPostal

boolean

no

Set to true to hide the Country and Postal Code fields on the Credit Card form.

options.behavior. no_active_subscription

string

no

Set to 'show_pricing' to show the pricing page if a customer has no active subscriptions.

The default behavior is to show the list of the user's subscriptions with any status.

Servicebot Subscription Portal with Options

Handling actions

The handleResponse function can be used to update user information in your database regarding the customers subscription information, to do redirects on signup, or present notifications.

Parameters

handleResponse will pass a variable which contains the following properties

Variable Name

Description

event

The name of the event that occurred

response

The response object returned from Stripe

Events

Event Name

Description

Response Object

pre_load

First thing run after the embed javascript loads, before any API calls have been made. Use to inject React components or tell when the embed has loaded.

Embed Configuration

post_load

billingData: null — means the subscription portal is not loaded yet

billingData: {no_user: true} — means the current email is not a customer

productData: null — means pricing (products) are not loaded yet

productData: [ … ] — means the pricing (products) are loaded

billingData

currentConfig

productData

create_subscription

Triggered when a subscription is created from the portal. Use this event to update your user system with the Stripe subscription ID and tier. Learn more on the install guide.

Subscription

change_plan

Triggered when a user upgrades or downgrades using the Plan Picker. You can use this to update their tier information or create notifications.

Subscription

select_plan

Triggered when a user selects a plan from the pricing page or plan picker. Use this to redirect to other pages or forms to create custom on-boarding flows.

Tier name & Plan

resubscribe

Triggered when a customer resubscribes from the portal. This occurs when a customer was cancelled, they come back to the portal and choose to resubscribe to a plan. Use this event to update your user system with the Stripe subscription ID and tier.

Subscription

cancel_subscription

Triggered when a customer requests a cancellation. Use this event to update subscription status for a user.

Subscription

update_card

Triggered when a customer updates their Credit Card information or enters it for the first time. Use for presenting notifications to the user.

Customer

Sample Portal Code

<div id="servicebot-billing-embed"></div>
<script>
window.servicebotSettings = {
servicebot_id: "Zsl0kaHKNxQq",
service: "Example Simple",
email: "example@somemail.com",
options: {
hideCancelDropdown: true,
hideChangePlan: true,
hideUpdateCard: true,
disableCoupon: true,
forceCard: true,
disableTiers: [
Simple,
],
},
handleResponse: async function(payload){
console.log("Event ", payload.event);
console.log("Response Object ", payload.response);
//Redirect on Signup example
if(payload.event == "create_subscription") {
window.location.href = "https://google.com";
}
}
};
(function () { var s = document.createElement('script'); s.src = 'https://js.servicebot.io/embeds/servicebot-billing-settings-embed.js'; s.async = true; s.type = 'text/javascript'; var x = document.getElementsByTagName('script')[0]; x.parentNode.insertBefore(s, x); })();
</script>