Integration guide

This guide provides an overview of a typical partner integration. It details the key concepts that you need to know about to fully understand how provisioning via the BaseKit API works. The lifecycle of a user is presented, along with the relevant API calls that need to be made to transition the user between each state.

Brands

A brand represents the configuration of a partner within the BaseKit application. Users created within a specific brand will belong to that brand, and are securely partitioned from all other brands.

You will be provided with a brand reference. This is a unique number that is used to identify your brand. This may be required for some API calls and will always be a parameter named brandRef. Your API credentials are locked to your brand, so you can’t access users in other brands, and other brands can’t access your users.

Note that users are sometimes referred to as account holders, and the two terms may be used interchangeably.

Packages

All users have a package that represents the features and capabilities that are available for them to use within their account. For example, a package may designate the number of sites they are allowed to create, the templates they are allowed to access, the storage limit they have available, etc.

A typical brand will follow the Trial package model (referenced below) having a suspension package, a trial package and two premium packages. These packages may only be used by users within the corresponding brand.

The suspension package will typically be designated as the brand’s default package. The default package is automatically assigned to new users created within this brand.

Users can only have one package at any given time. If a new package is given to the user then the existing package is automatically expired.

All packages have a billing period that indicates how regularly the user has decided to pay for their subscription. Typically this will be either monthly or annually.

Package models

Every partner integration will choose one of the following package models. Which one to choose will depend on the marketing and commercialisation strategy for the project. It is recommended that all partners implement the Trial model, which has been shown to give the best results.

Trial

A trial package provides users with access to a complete set of features for a limited period of time. The period of time is set as a number of days and is typically between 7 and 30 days.

Each trial package will mirror a paid package, with the only difference being that it is time limited. If the user decides to upgrade, they will move to the corresponding paid version of the package.

If the user does not subscribe to a paid package during the trial period, they will be moved back to the brand’s default package, here is when the Suspension package becomes important. If you did not have a Suspension package, at the end of the trial period the user would stay on that trial package indefinitely without their site being taken offline. Our system - at the end of the trial period - will automatically shift down the user from the Trial to the Suspension package. This process takes the site offline and restricts their ability to re-publish. The user will not lose their site, but they lose their ability to publish until they upgrade.

When you provision a user onto a trial package, you always create on the ‘default’ package first, which in this case is the Suspension package. You should then on-board them straight away in the background onto your 14 day trial package. The user should have no exposure to this process.

Freemium

A freemium package provides users with access to a wide range of features but with limit resources. For example, a user may be able to publish a site with all available widgets, but only up to 2 or 3 pages. A limit of 2 pages is recommended to give a user a feel for the product but the user will need to upgrade to create a typical small business site.

The user will be encouraged to upgrade or buy additional bolt-ons in order to be able to enhance their site.

User lifecyle

To integrate with the BaseKit provisioning API, it is imperative that you adhere to the provisioning lifecycle described below. This involves the following set of calls, which are also described later in more detail.

  1. Create a User. This transitions them from a Visitor to a User on the above diagram, and this is tracked as a Freemium Registration Event.
  2. If using a Trial package model, the user needs to be immediately Transitioned to the Trial Package to get the features and capabilities that have been chosen for the trial period. This will be tracked as a Trial Registration Event. The user will be automatically transitioned back to the default package after the trial period.
  3. Create a Site for the new user.
  4. Optionally, you can Map a Domain to (and Unmap a Domain from) the new site.
  5. If a user pays for the premium service, they will Upgrade to a Premium Package to get access to premium features and the ability to publish a full website. This transitions them from a User to a Subscriber on the above diagram, and this is tracked as a Subscription Event.
  6. Optionally, the user may then Upgrade to a Higher Package or Downgrade to a Lower Package. The user remains a Subscriber on the above diagram, but the transition to a different package will be tracked as an Upgrade or Downgrade Event.
  7. If a user decides to cancel the premium service, they will Downgrade to the Free Package or Suspension if using Trial package model. This transitions them from a Subscriber back to a User on the above diagram, and is tracked as a Cancellation Event. The following diagram shows the provisioning lifecycle of a BaseKit user.
Figure 1: The provisioning lifecycle of a BaseKit user

Note that no other API calls are required in order to implement a full integration. You do not need to delete or suspend users after they are cancelled. You will not be charged for any users after cancellation.

Any other API calls will be for ancillary features outside of user and site provisioning.

Billing cycles

Every paid package is assigned to a billing cycle that represents how frequently the user is making subscription payments for the service.

The frequency is specified as a number of months. For example, a billing frequency of 3 means that the package subscription payment is made by the user every 3 months. The typical billing frequencies are 1 for monthly and 12 for annual, but any number may be used.

It is critical that you indicate the correct billing frequency in all API calls. This is used to tell the provisioning engine how to update the user’s package, and also used to synchronise billing reports.

API method overview

In this section, the API calls for each of the above lifecycle steps are detailed. More detailed information about each endpoint is available in the API reference, to which each method is linked.

Create a user

POST /users (Click for more information)

As a minimum, you should pass in the brandRef, username, password, email, firstname and lastname parameters.

When a user is created, the brand’s default package is automatically assigned to them. This is tracked as a Registration Event. We do not charge for users with a free package.

Create a site

Users are created without any sites by default. You may create one or multiple sites for the user. The number of sites you can create via the API is unlimited, but the number of sites that the user is allowed to publish is limited by the user’s current package.

POST /sites (Click for more information)

You should pass in the brandRef, accountHolderRef and subdomain parameters.

The subdomain is prepended to the brand’s domain to give the full site URL. For example, if the brand domain is example.com and the subdomain parameter passed in is testing then the full site URL would be testing.example.com.

Log in a user to a site

Generate a login hash that is used to automatically login a user to one of the sites they own.

POST /users/:userRef/auto-login (Click for more information)

You should pass in the accountHolderRef and siteRef parameters.

Map a domain

Sites are automatically created with a subdomain so that you are able to instantly access them. However, you will usually want to map a custom domain to a site.

POST /sites/:siteRef/domains (Click for more information)

You should pass in the domain parameter. This is the full host name, not including the protocol, port or path. The API will respond with the ref of the mapped domain. You may also retrieve all domains mapped to a site via the following API endpoint:

GET /sites/:siteRef (Click for more information)

Unmap a domain

DELETE /sites/:siteRef/domains/:domainRef (Click for more information)

Note that all domains mapped to a site will need to have the appropriate DNS settings for the environment on which the site is located.

Upgrade to a premium package

When a user upgrades to a paid subscription, the corresponding premium package should be added to the user’s account.

POST /users/:userRef/account-packages (Click for more information)

You should pass in the packageRef and billingFrequency parameters that represent the new package.

When the new package is added, the free package is automatically expired. This step is tracked as a Subscription Event. We charge for all users with a premium package.

It is critical that you indicate the correct billing frequency in this API call. This is used to tell the provisioning engine how to update the user’s package, and also used to synchronise billing reports.

Upgrade to a higher package

The user may decide to switch to a higher package in order to take advantage of more features or capabilities. The corresponding higher package should be added to the user’s account.

POST /users/:userRef/account-packages (Click for more information)

You should pass in the packageRef and billingFrequency for the new package.

When the higher package is added, the existing lower package is automatically expired. This step is tracked as an Upgrade Event. We will immediately begin to charge the higher package price for this user.

Downgrade to a lower package

Conversely, a user may decide to switch to a lower package. The corresponding lower package should be added to the user’s account.

POST /users/:userRef/account-packages (Click for more information)

You should pass in the packageRef and billingFrequency for the new package.

When the lower package is added, the existing higher package is automatically expired. This step is tracked as a Downgrade Event. We will immediately begin to charge the lower package price for this user.

Downgrade to the free package

This happens when the user decides to cancel or stop paying for the premium package.

When the user decides to stop paying, they move back to the free package, which is typically the brand’s default package.

POST /users/:userRef/account-packages (Click for more information)

You should pass in the packageRef and billingFrequency for the new package.

When the free package is added, the existing premium package is automatically expired. This step is tracked as a Cancellation Event. We will immediately stop charging the user.

Note that a cancellation event will cause the user’s sites to be automatically taken offline.

You never need to delete or suspend users. You will not be charged for users that have the free package.

Need help?

Our teams are always on hand to assist you. For commercial enquires contact partners@basekit.com, and for technical questions integrations@basekit.com.