Embedding Checkout

You can embed our checkout experience on your website easily by using our integration script.

Embedding Options

The embedding scripts supports multiple operations as explained below. Depending on the operation, there are different number of arguments and each argument positions might mean something different. All configurations always start with the operation name as the first argument (i.e sb({operationName}, ...{args}))

Initializing the SiteId

(Required)
You need to initialize the embedding script by specifying the "Site Id". You can do this by using the siteId operation as follows:

sb("siteId", "{your_siteId})");

Where:

{your_siteId} is the case-sensitive site id you want to use, which contains the plans you need to attach. Your Subsbase Admin Portal link is in the form of https://{siteId}.subsbase.io

This operation should exist only once, adding it more than once can lead to unexpected behavior.

Customizing Theme

(Optional)
You can customize the primary color which is used in multiple parts of the checkout experience. You can do this by using the theme operation as follows:

sb("theme", "{theme})");

Where:

{theme} is the primary color you want to use in hex format (i.e #FFFFFF)

This is an optional operation, if you do not specify a theme, the default value is #20407D.

This operation should exist only once, adding it more than once can lead to unexpected behavior.

Adding a Callback

(Optional)
When the payment process does not include redirection or if no payment is required, you can specify a certain action to happen, whether to communicate with your backend, trigger a redirection etc.
You can do this by using the callback operation as follows:

sb("callback", { actionToPerform });

Where

{actionToPerform} is the action you want to perform after signup, written in Javascript. This argument could reference a globally available function. The function would receive and event having all signup details (i.e. InfoFields, CustomFields, PlanCustomization, etc.)
Example action e => console.log("signup result:", {e})
This operation should exist only once, adding it more than once can lead to unexpected behavior.

Plan Checkout

There are two ways to integrate the checkout experience: (At least one is needed, unless plan picker is used)

Attaching the subscription plans to clickable elements on your page
Attaching the subscription plans inline to container elements

You can do this by using the attachPlan or inlinePlan operations as follows:

Attaching the subscription plans to clickable elements

sb(
  "attachPlan",
  "{planCode}",
  "{clickableElementReference}",
  ["class|id"],
  ["{attachEvent}"]
);

Where:

{planCode} is the case-sensitive plan code that needs to be attached. You define the 'Plan Code' while creating it
{clickableElementReference} is either the value of the class name or id added to the clickable element on which you want to attach a plan. If the clickable element reference is a class and placed on multiple elements, all elements will open the same plan.
"class|id" should be either "class" or "id". If not specified, default value is "id"
"attachEvent" is a case-sensitive event name on which to trigger the checkout overlay. The event name has to be a valid HTML DOM Event, you can find more here and here If not specified, default value is "click"

This operation should exist at least once and should be repeated as many times as needed to attach all your plans to the required clickable elements.

Attaching Plan using Element's ID

Example If you have the following element and want to attach it to a plan whose code is pro-plan:

<button id="pro-plan-btn">Pro Plan</button>

You can use the following to attach using the id

sb("attachPlan", "pro-plan", "pro-plan-btn", "id");

Attaching Plan using Element's Classname

If you have the following element and want to attach it to a plan whose code is pro-plan:

<button class="pro-plan-btn">Pro Plan</button>

You can use the following to attach using the class name

sb("attachPlan", "pro-plan", "pro-plan-btn", "class");

Attaching the subscription plans inline to container elements

In addition to the previous method of integrating the checkout experience, you can also inline the checkout experience in a page of your own by replacing the operation name attachPlan by inlinePlan to use the Inline Checkout Experience. This creates an iFrame element and injects it to the provided container element.

sb("inlinePlan", "{planCode}", "{containerElementReference}", ["class|id"]);

Where:

{containerElementReference} is the provided container element reference, a div as an example.
"class|id" should be either "class" or "id". If not specified, default value is "id"

You have to set the width and the height for the Container Element and the injected iFrame will fill the entire container i.e. the iframe's height and width are set to 100%.

Setting Success Redirect Url

(Optional)
Sometimes you need to have the checkout experience automatically redirect to your website after a successful checkout. You can do this by using the queryParam operation as follows:

sb("queryParam", "redirects[success]", "{url}");

Where:

"{url}" the url you need to redirect to
This is an optional operation, and you can use it as many times as needed. Duplicated params might cause unexpected behavior.

Pre-filling Info Fields and Custom Fields

(Optional)
Sometimes you need to attach some custom fields to the checking out clients (visible in the Subsbase Admin Portal) or pre-fill any of the info fields in the checkout experience. You can do this by using the queryParam operation as follows:

sb("queryParam", "{param}", "{value}");

Where:

"{param}" is the parameter you wish to pre-fill/attach
"{value}" is the value you need to specify for that particular parameter

Pre-filling info fields

To pre-fill an info field the parameter should be infoFields[{fieldName}]. For example, to pre-fill the name field with the value John Doe you would use:

sb("queryParam", "infoFields[name]", "John Doe");

Please note that fieldName is case-sensitive and should match the field name you chose while creating the plan. This will work on any field you have configured on your plans.

Prevent the user from editing info fields

You can make info fields uneditable by setting the disableInfoFields parameter value to true as shown below:

sb("queryParam", "disableInfoFields", true);

Pre-filling custom fields

To pre-fill an info field the parameter should be customFields[{fieldName}]. For example, to attach a userAgent custom field with the value navigator.userAgent you would use:

sb("queryParam", "customFields[userAgent]", navigator.userAgent);

This is an optional operation, and you can use it as many times as needed. Duplicated params might cause unexpected behavior.

Beware, adding too many info fields and custom fields can result in long urls for loading your checkout experience, so keep that in mind while using this operation.

Setting Customer Identifiers

By default, a random identifier (customerId) is automtically generated while creating a new customer that signs up. In some cases, it is needed to pre-set the customer identifier (customerId) to match pre-existing info in your system or to follow a certain convention. In this case, you need to supply the desired customer for each customer as a pre-filled custom field as discussed above. The 'customerId` key is to be used as shown below:

sb('queryParam', "customFields[customerId]", {desired-customerId})

This has a side effect that the embedding script is dynamically set during navigation or a customerId is auto-generated while the script is rendered. You have make sure that correct value is supplied. Duplicate customerIds would cause a failure during sign up.

Putting it all together

Put the below script before your website's closing head tag </head>.

HTML

<script>
(function (d, o, s, a, m) {
  a = d.createElement(o);
  m = d.getElementsByTagName(o)[0];
  a.async = 1;
  a.defer = 1;
  a.src = s;
  m.parentNode.insertBefore(a, m);
})(document, "script", "https://embed.subsbase.com/sb.min.js");
window.sb =
  window.sb ||
  function () {
    (sb.s = sb.s || []).push(arguments);
  };
sb("siteId", "{your_siteId}"); // Required
sb("theme", "{hex-code}"); // Optional. example: sb('theme', '#20407d')
sb("callback", (e) => console.log("signup result:", { e })); //Optional
sb(
  "attachPlan",
  "{planCode}",
  "{clickableElementReference}",
  ["class|id"],
  ["{attachEvent}"]
); //At least one is required. can be repeated
sb("queryParam", "redirects[success]", "{url}"); //Optional
sb("queryParam", "{param}", "{value}"); // Optional. can be repeated.
sb("queryParam", "disableInfoFields", true); // Optional.
</script>

Integration GuideGetting Started

Integration GuideEmbedding Plan Picker