Configure Portal

Configuration Options for the Servicebot Subscription Management Portal

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

yes

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.

email_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.

tier

string

no

The tier name configured in Stripe (metadata sb_tier). This is required in the signup process if you want to automatically register a user for a specific tier and interval.

interval

string

no

The interval value of the plan (day, month, year). This is required in the signup process if you want to automatically register a user for a specific tier and interval. Note: Not required if there is only one interval on that tier.

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.

Servicebot Subscription Portal with Options

Options

#

Property Name

Type

Description

1

hideCancelDropdown

boolean

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

2

hideCoupon

boolean

Set to true to hide the coupon section from users

3

hideChangePlan

boolean

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

4

hideUpdateCard

boolean

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

5

forceCard

boolean

Set to true to force users to enter in their Credit Card information during signup process. By default the embed will not ask for payment information if they are on a free tier or there is a free trial.

6

cancel_now

boolean

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

7

disableTiers

array

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']

8

messageOnCancel

string

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.

9

metadata

object

An object of key-value pairs. They will be added to the metadata of the Customer and Subscription in Stripe when they are created using the portal.

Eg: {key1: 'value1', key2:'value2'}

10

quantity

object

Use to set the quantity of a subscription during creation. Can get an integer or an object of key-value pairs. The quantity will apply to products with the unti_label defined. If an integer is passed, it will apply the quantity to all products on the tier, if an object is passed with the unit_labels as keys, it will assign that quantity to the respective unit_label.

Eg: 5

Eg: {product_unit_label1 : 10, unit_label2: 20}

11

card.hideName

boolean

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

12

card.hideAddress

boolean

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

13

card.hideCountryPostal

boolean

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

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

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

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,
hideCoupon: true,
forceCard: true,
disableTiers: [
Simple,
],
},
handleResponse: async function(payload){
console.log("Event ", payload.event);
console.log("Response Object ", payload.response);
}
};
(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>