SBS Platform Introduction

Topline Cloud Services Logos

System Overview

SBS Partners Logos

Topline's SBS (Small Business Services) platform gives Service Providers like Hosts, ISPs, and Telcos API access to four vendor's SMB applications:

  • Yola Latitude Sitebuilder
  • Uberall Local Marketing Tools
  • Kliken GoogleAds SEM
  • Ecwid eCommerce

Using this SBS API, your internal customer management systems can directly provision and manage the subscriptions that your end users purchase from you, then provide a secure SSO access from your control panel. Your end users only see your brand or that of your subsidiaries/resellers, since all vendor's branding remains invisible.

The user subscription data in SBS can be managed via API calls and also through our admin portal, SBSmanager (http://sbsmanager.com). On-going processes are typically handled via API (adding, modifying, deleting, logging in users) where SBSmanager is used for initial account configuration, technical support, and financial reporting and invoicing. Optionally, SBSgateway can provide a branded end-user login portal that can be exposed to your users. There are four main components to the system.

System Components

Platform Hierarchy diagram
  1. SBS Platform
    • Maintains User and optional Account data, subscriptions and branding
    • Tracks all subscription usage and costs
    • Tightly integrated with all vendor's Application Services
  2. SBS API
    • REST API for all CRUD transactions (create, read, update, delete, plus SSO login)
    • Allows for full integration into your CRM system and control panels.
    • Normalizes your integration to the various application vendor APIs
    • Supports creation of new resellers/affiliates under your master account
    • Pre-integrated packages and extensions for APS 2.0, WHMCS, cPanel, Plesk, ISPsystem and AppDirect platforms
  3. SBSmanager
    • Control panel for interactive management of the services
    • Configuration of branding, upgrade and help URLs, product defaults
    • Support Team interface for reproducing user issues and submitting tickets
    • Access to Reseller’s user base
    • Generates invoicing, reporting and statements
    • Tracks prepaid balance for your finance team
  4. SBSgateway
    • End user facing web login branded to you or your sub Brands
    • Can be used in addition to, or instead of, SSO login
    • End user authentication, forgot password and sign-up functions

N-Tier Branding

All end Users are logically held under a specific Brand so that the user experience is consistent with the service provider’s brand and pricing. Your Partner account within SBS will have the top-level Brand already created plus you can add additional Brands under your account for subsidiaries, alternate brands you use or for resellers of your services. Each Brand has its own distinct set of Users and can also have additional Brands under it (n-tier).

Each User in SBS is related to a single domain. If a user has multiple domains with you, then each domain will require a separate User within SBS. Each User’s data is usually a mirror of the data you already maintain for your users and is in four main areas depending upon the service:

  1. User ID - unique userID, account number etc.
  2. Website URL - can be custom domain, sub domain or sub folder
  3. Subscription details - plan level, service status
  4. FTP login - Optional depending upon web site publishing (FTP/FTPS)

Your system must guarantee the uniqueness of userID within a Brand since all API calls are keyed on the userID. After an User is deleted the userID can be re-used.

Please note that multiple Users (domains) can be stored under a single Account when a brand is using our Account Model. This provides a single login through SBSgateway or the SBSstore for your clients with multiple domains.

Service Provider Billing

You, the Service Provider, decide which our services to offer, what to bundle them with and you set the retail prices for end users and wholesale prices for resellers. SBS tracks all subscriptions you provision across your Brand and your sub Brands. All invoicing is aggregated up to your top-level account for all your Brands.

Prepayment System

Topline uses a prepaid system that deducts your consumption of services from the credit balance that you have deposited with us. SBSmanager provides full transparency of all usage charges, invoices, payments made and your current credit balance. Payments can be by wire transfer, credit card or PayPal with instant credit applied to your account.

Proforma Invoices are generated and sent to you as a request for pre-payment, to top up your credit balance as needed based on your consumption patterns and invoicing preferences. Credit cards can be securely saved in SBSmanager for automatic payment of pro-forma invoices. You can also manually add funds at any time.

Expense Invoices are generated on the 1st of each month for all aggregated subscriptions from the prior month at the rates agreed to in your contract. Expense Invoices can be used in your accounts to reflect the actual costs of service for that period.

Please see the Topline Billing Automation documentation for more details.

Chargeable Subscription Rules

A chargeable item is a new or renewed one-month subscription for a service.

When a new subscription is added to a user under your account, the specific monthly service fee is deducted from your prepaid credit balance. As the subscription renews each month the appropriate fee is again deducted from your credit balance. Each service fee is thus paid in advance for an entire month and there is no pro-rating for partial months.

Cancelled subscriptions will be set to non-renew and at the end of subscription will expire instead of being renewed. There is no charge for a subscription in the month it expires. If an account is set to Suspended status when the renewal date is hit then the subscription renewal date is updated to the next month but no fees are charged, and when the account is set to Active again then there will be a charge in that month.

Upgrades are treated as a new subscription for the new service level at the time of the upgrade. Downgrades are also treated as a new subscription at the new service level but the new lower subscription starts after the original subscription expires.

A subscription life cycle example:

day action
Jan 23 customer signs up, new subscription added and is chargeable
Feb  1 Topline invoices you one month’s service for that user
Feb 23 subscription auto-renews and is chargeable
Mar  1 Topline invoices you one month’s service for that user
Mar 15 user account is suspended by you and so subscriptions are suspended
Mar 23 subscription expiry date is updated adding a month but no charges due
Apr  1 Topline invoice has no charge for that user
Apr 23 subscription expiry date is updated adding a month but no charges due
May  1 Topline invoice has no charge for that user
May  7 User account is made active and all suspended subscriptions reactivated, Current subscription is now chargeable
May 23 subscription auto-renews, next month’s service is chargeable
Jun  1 Topline invoices for 2 months of service for that user.
Jun 20 User upgrades subscription. New subscription is created and is chargeable. Original subscription is set to Expired
Jul  1 Topline invoices for one month of new service level for that user
Jul 19 customer cancels subscription, subscription is set to non-renew
Jul 20 on the renewal date, the subscription automatically set to Expired
Aug  1 no charges for that user on Topline invoice

Initial Service Configuration

These items need to be considered and configured for your services to be launched successfully. After launch, these items are typically static but can be updated as required. SBSmanager supports the updating of these parameters.

Subscription Renewal Method

You have two choices for the monthly renewal of subscriptions. The default, Auto Renewals, let’s our system renew each subscription every month until such time as you cancel the subscription via API or in SBSmanager. The second option is Triggered Renewals that cause all subscriptions created in your account have a “non-renew” status so they will be suspended at the end of the each monthly term instead of auto renewing. Then you can intentionally renew subscriptions using the /renew endpoint anytime before or within one term after the normal renwal date. More information on this feature is available if it is of interest for your integration.

Plan Definitions

Plans specify the pre-defined capabilities of a service level such as number of pages, MB of space for uploaded files, and product features that are available to the user. A default set of plans are available for your use or we may have created custom plans for you during the integration project. Each Plan has an associated planID which is used in the API calls to set the plan level for that subscription, or modify the plan for a subscription.

Each plan also relates to a numeric productID3 that provides hierarchy information so you can, optionally, determine the ranking of different plans for upgrade/downgrades programmatically. Prior to productID3, there was a field productID that is now deprecated but is still returned on some calls to preserve backwards compatibility. Please see the PDF v5.09 of this document for the deprecated values if required.

Upgrade URL (Purchase URLs)

When using the applications the user is presented with in-context purchase or upgrade messages when attempting to use a feature that is not included in their plan level or when they attempt to exceed their limits (i.e. number of pages in Yola, a advertising campaign with higher adspend in Kliken, or more products in Ecwid).

The upgrade messages include a link to “Purchase”, “Upgrade” or “Learn more” about the product, and the URL of that link is defined by you in SBSmanager (Brand > Configuration > Customization).

Setting Usage
Upgrade URL Used for all upgrade and purchase links in the UI
Website URL Fallback used if no Upgrade URL is configured

Upgrade URL formats

Your brand can be configured to receive one of three different types of Upgrade URL.

  1. By default, the parameters are appended to the Upgrade URL as a query string. This allows for scripting on your side that could log the event, personalize the message or simplify the upgrade process. The system will cope with the situation where your URL has an argument list already.
    <upgradeURL>?u=<userID>&d=<domain>&l=<language>&product=<product>&campaignID=<campID>&action=<action>&prodcat=<prodcat>&host1=<host1>&host2=<host2>&host3=<host3>
    
  2. We can also optionally send a single query string parameter that has all the same attributes packed into a single urlencoded JSON string.
    <upgradeURL>?json=%7B%22u%22%3A%22<userID>%22%2C%22d%22%3A%22<domain>%22%2C%22l%22%3A%22<language>%22%2C%22product%22%3A%22<product>%22%2C%22prodcat%22%3A%22<prodcat>%22%2C%22host1%22%3A%22<host1>%22%7D
    
  3. Finally there is one other option which has only the userID as a URL extension.
    <upgradeURL>/<userID>
    

Upgrade URL parameters

parameter value
u SBS user ID from end_user.userid
d Domain from end_user.domain
l Language from end_user.language
product The name of the product being purchased. sitebuilder, admanager, ecommerce
campaignID Optional, just pass through as given - no validation is done
action Optional pass-through when from Yola. Always calculated when from SW. One of purchase, upgrade, update, or cancel
prodcat first 5 characters of the productID3 (e.g. "03.02" for Kliken Search products, "03.01" for Display, "02.01" for YolaEcommerce)
currentplan the current Topline planID
currentproduct the current Topline productID
host1 end_user.host1
host2 end_user.host2
host3 end_user.host3

The host1/2/3 are three fields you can define when adding or editing a user. If present they will be included in the parameters returned. These are typically the ID your internal system uses to locate that user’s account.

Branding

The application UI can be customized to better reflect your brand and target market.

This is currently diplayed in 2 places, and has effects on Legacy sitebuilder (as well as other apps) and Latitude Sitebuilder. There are also 3 areas where adjustments can be made.

Legacy sitebuilder

The following controls, accessed from SBSmanager will control logo and links for Legacy sitebuilder (as well as other apps). This can be found at Brands >> Brand Configuration

Brand Configuration (Customization > Commom) Usage
Logo URL Logo for top left of Yola Sitebuilder UI. Should be the URL to the logo image file that you host. Recommended 25px height and 160px maximum width, transparent png. Not required.
Support URL/email For support links in the Sitebuilder UI. Either a URL or an email address can be used. URL will override the email address if both are configured.
Brand Configuration (General) Usage
Language The Application currently supports 17+ languages. The Brand’s default value is used if no language is specified when an account is created. See Appendix.

Latitude sitebuilder

Sitebuilder has internationalized customization settings as well as common custom colors to let you further refine the look and feel and provides additional branding possibilities.

The controls for the following items are controlled using the Internationalization features found in SBSmanager. Available in the supported languages of your choosing.

Property name value description
Yola Terms and Conditions URL URL a URL with Terms and Conditions governing the use of this product.
Logo Url URL Desktop logo. Dimensions of 180x96 pixels are recommended in order to be compatible with retina screens.
Logo Url Mobile URL Mobile logo. Dimensions of 132x96 pixels are recommended in order to be compatible with retina screens.
Product Name text The product name that you use to describe the sitebuilder product. This is displayed in locations such as the loading screen.
Product Slogan text Product tagline. This is displayed in locations such as the loading screen.
Logo Url Footer URL The logo to be used in the optional branded footer element that can be embedded in free websites for the purpose of driving upgrades and referral traffic.
Footer Message text The message to be used in the optional branded footer element that can be embedded in free websites for the purpose of driving upgrades and referral traffic.
Footer Url URL The url to be used in the optional branded footer element that can be embedded in free websites for the purpose of driving upgrades and referral traffic.
Support Url URL The url to be used in the optional branded footer element that can be embedded in free websites for the purpose of driving upgrades and referral traffic.

The following color and dimension properties are input from SBSmanager Brands >> Brand Configuration (Customization, Sitebuilder)

Latitude Settings default value description
Logo Width 32 px value Controls the desktop logo width. The maximum logo dimension is 90x48 pixels
Logo Width Mobile 32 px value Controls the mobile logo width. The maximum size is 66x48
Logo Width Footer 46 Controls the width of the logo within the optional branded footer.
Theme light "dark" or "light" Choose between a light or dark color theme for the sitebuilder. This theme will be applied to the sitebuilder toolbar. [Not currently supported]
Theme Footer light Choose between a light or dark color theme for the branded footer embedded in free websites.
Latitude Color Settings default value description
Primary Color(600) #34363c (string) - hex color code. Your default Primary color. Primary colors are applied to all main buttons that a user can interact with.
Primary Color(700) #262a31 (string) - hex color code. A darker variation of your Primary color. Primary colors are applied to all main buttons that a user can interact with. This will be used for things like hovers and active states.
Primary Color(800) #141B21 (string) - hex color code. A darker variation of your Primary color. Primary colors are applied to all main buttons that a user can interact with. This will be used for things like hovers and active states.
CTA Color(600) #0072ef (string) - hex color code. Your default call to action color. Call to action colors are applied to elements that draw attention to key interactions such as upgrade and purchase.
CTA Color(700) #005ed9 (string) - hex color code. A darker variation of your call to action color. Call to action colors are applied to elements that draw attention to key interactions such as upgrade and purchase. This will be used for things like hovers and active states.
CTA Color(800) #094aba (string) - hex color code. A darker variation of your call to action color. Call to action colors are applied to elements that draw attention to key interactions such as upgrade and purchase. This will be used for things like hovers and active states.
Info Color(600) #31B0D5 (string) - hex color code. Your default info color. Info colors are used for information and status messages.
Info Color(700) #1F9BBF (string) - hex color code. A darker variation of your info color. Info colors are used for information and status messages. This will be used for things like hovers and active states.
Info Color(800) #0E87AB (string) - hex color code. A darker variation of your info color. Info colors are used for information and status messages. This will be used for things like hovers and active states.
Success Color(600) #1AB744 (string) - hex color code. Your default success color. Success colors are applied to success messages.
Success Color(700) #1B9B4A (string) - hex color code. A darker variation of your success color. Success colors are applied to success messages. This will be used for things like hovers and active states.
Success Color(800) #0B8738 (string) - hex color code. A darker variation of your success color. Success colors are applied to success messages. This will be used for things like hovers and active states.
Warning Color(600) #FFCA28 (string) - hex color code. Your default warning color. Warning colors are applied to warning messages.
Warning Color(700) #FFB302 (string) - hex color code. Warning colors are applied to warning messages.
Warning Color(800) #FF8F00 (string) - hex color code. Warning colors are applied to warning messages.
Danger Color(600) #FF7043 (string) - hex color code. Danger colors are applied to critical actions or actions that cannot be reversed.
Danger Color(700) #F4511E (string) - hex color code. Danger colors are applied to critical actions or actions that cannot be reversed.
Danger Color(800) #D84315 (string) - hex color code. Danger colors are applied to critical actions or actions that cannot be reversed.

Hosting Requirements for Yola sites

When your brand is self-hosted and a user’s site is published from within Yola Sitebuilder, the site files are sent via FTP/FTPS to the user’s web space on your servers. The site is a collection of text, image and config files (text, html and Javascript).

IP Whitelist for FTP publishing

When the published sites are hosted on your servers it is important to whitelist the following IPs to reduce publishing errors on FTP connections (typically port 21). For fastest publishing 10 concurrent connections should be allowed but this limit can be lowered in your Brand’s settings.

Production FTP publishing IPs:

Sandbox FTP publishing IPs:

Prod & Sandbox SBSmanager QA IPs:

SSL Requirements for Latitude

Latitude requires the domain be covered by SSL.

Self-Hosted publishing

You must ensure a certificate covers the domain that is published. There are numerous free solutions available to providers to accomplish this.

Syndicated publishing

The following steps need to be taken to have the domain covered by a free SSL certificate provided by Cloudflare.

  • A zone needs to be created at Cloudflare. This can be accomplished in either of 2 ways.

    1. If your brand is set to Support SSL on Publish the zone will be created when the user first publishes their website. SBSmanager, Brands > Customization > Sitebuilder.
    2. You can manually create a zone using the Tools in SBSmanager.
  • The user domain in our system needs to have www prepended to it. This can be done via API or using SBSmanager.

  • The DNS for the bare domain needs to have an A Record pointing to one of the following Yola Ips

Production Syndicated publishing DNS

Sandbox Syndicated publishing DNS
  • The following CNAME record is required for the www.domain.
www.mycustomerdomain.com => sitebuilderhostsite.net

The end result is that,
https://www.mycustomerdomain.com will be covered by a Cloudflare cert.
http://mycustomerdomain.com will redirect to the secure domain.
https://mycustomerdomain.com will not resolve properly. Yola uses Cloudflare to issue and host SSL certificates. Thus, to make SSL work, HTTPS traffic has to be proxied via Cloudflare by pointing to Cloudflare subdomain via DNS. The problem with bare domains(ex: mycustomerdomain.com) is that you can't create CNAME to Cloudflare on the apex level because of DNS limitations. That's why we recommend having CNAME record pointed to Cloudflare for a subdomain(ex: www.mycustomerdomain.com).

Additionally we supply callbacks to you to help in timing issues when domains are first published.

Brand Management Processes

Initially your account in SBS will have a single Brand which can contain your direct end user accounts and also can contain additional sub Brands which may contain their own end users and sub Brands. The sub Brand functionality could be used for resellers of your service, alternative brands that you market directly or the brands of your subsidiary companies. Each Brand is distinct and can be fully customized. The system supports n-tiers of Brands.

Managing Brands

A new sub Brand can be provisioned via API or SBS and will be added immediately under the Brand identified in the call/SBS login. Required branding information allows for automatic configuration of the application interfaces without further intervention from the new Brand owner.

Each Brand in SBS must have a globally unique brandID that is used in combination with your Partner AuthKey in each API call to allow for user management of the correct Brand’s user base. Each Sub-Brand’s brandID can be set at time of creation to be consistent with your current internal systems; however brandID’s must be globally unique across SBS. If the BrandID selected is already in use, even by one of our other partners, you will get a duplicate brandID error result from the API call.

For large numbers of sub Brands we suggest selecting a prefix of letters appended with a serialized number. Please discuss with Topline to ensure its uniqueness prior to launching.

Brand level access to SBSmanager

Once a new Brand is created, you can generate an SBSmanager user, “SBS Agent”, to allow the Brand owner access to SBSmanager for further configuration and customer management. SBS Agents can then add end-users and other Brands as necessary. Access to SBSmanager is optional and most providers choose not to give sub Brand owners that access to control technical access to the system.

Multi-level Brand User Management

All functions in the User Processes section above apply to the any Brand’s users as well. End users can be created, modified, suspended, deleted, etc., for any of your Brands at any level in the hierarchy, just as it is done for your direct end users. Just identify the Brand being worked on in the API call.

Access to SBSmanager

SBS can be accessed either via the secure web interface at sbsmanager.com or programmatically via the SBS API over HTTPS.

With either method, all normal day to day customer and brand management functions are available like add, modify, suspend and delete customers/brands and to initiate a session in the application. Your sub Brands can also be given access to their separate SBSmanager account if desired, where they can only view their own user records and (optionally) those of their downstream Brands.

SBS Agent Roles

When providing your staff access to the SBSmanager interface you can select from a number of pre-configured Roles that will give each person certain rights while disabling other functions. To invite a new Agent, use the Brands > SBS Agents page. You’ll need their name, email and mobile phone number (used for two factor authentication for initial registration).

Role Brand Agents End Users Subscriptions Reports Billing API Keys
Owner add edit add edit add edit login edit purchase view edit keys logs viewer
Integrator add edit add edit add edit login edit purchase view edit keys logs viewer
Admin add edit add edit add edit login edit purchase view edit logs viewer
Support 2nd view add edit add edit login edit purchase - - logs viewer
Support 1st view view view login view - - -
Management view add edit view view view edit -
Finance view - view view view edit -
Sales view - view view - - -
DIFM view - edit login view - - -

Owner
This is the top Role with access to all features including API keys and Agent invitation rights to all other Roles. To add an Owner please contact Topline to upgrade a current Agent to the Owner Role.

Integrator
Has the same rights as Owner including API keys, except for Agent invitation rights which are more restricted.

Admin
Removes API keys and limits Agent management (invite, edit) to Roles that are listed below.

Support 2nd
Designed to allow 2nd line Technical Support teams to have full access to the user’s records and login as the users to their subscribed applications in order assist and reproduce issues. View only access to Brands. Support+ adds subscription add/edit and inviting Support agents.

Support 1st
Designed to allow 1st line Technical Support teams to have read-only access to the user’s records and login as the users to their subscribed applications in order assist and reproduce issues.

Management
This is a read-only Role for Executives, Product Management and Marketing teams to have safe view access to their brands, reports and end user records.

Finance
View only Role with ability to edit Billing Information.

Sales
This Role is designed for when the partner has a downstream partner/reseller channel that their sales team may be actively inviting into the system.

DIFM
Partners that offer a “Do It For Me” service can use this Role to give DIFM Agents a filtered view seeing only DIFM users, hiding all users marked as DIY. DIFM Agents can be an internal or external team.


Multi-Brand Access
New Agents can be invited to any Brand in your account and will have access to all Brands under the Brand level they are invited to. So Agents at your top level Brand have access to all Brands in your account. Their Role setting is consistent at every Brand level.

To restrict an Agent to a lower Brand (eg: Reseller or Subsidiary), select the lower Brand as your “working as” level prior to sending the invitation.


Dynamic Role change
During your SBSmanager session you can change your Role (top right corner) to any Role below yours. This allows you to interact with the system as a junior Role to visualize how the system looks for those Agents.

Account / User Management

SBS has 2 models for interacting with your users and their domains.

  • One option is the Account model which has a one-account-to-many-domains hierarchy. In this model the brand creates Accounts, which then have Domains added to them. In this model a single client can have many domains.
  • The original option is the User model where there is a one-to-one relationship between users and their domains. Brands that work with this model create Users for each domain.

Creating Users/Domains

Depending on which model you use, Users or Domains can be added via API, manually from SBSmanager and from the self-serve SBSgateway interface. All three methods can be used at the same time. An EndUser is related to a single domain and must be unique within the brand.

The information needed for each User/Domain depends upon the product that is added. The Application services require basic identification information and then each requires product specific information as well.

Common identification Info

1. Unique userID/domainID (unique within the brand)
2. Website URL (can be custom, sub-domain or sub-folder of a domain)

Yola specific info If you will be hosting the resulting web site on your infrastructure then the following is also needed. This is not required for Yola hosted (syndicated) implementations.

3. FTP credentials (address, ftpUserid, password, doc root, port, protocol).

FTP protocol can be set to use standard FTP or FTPS (TLS/SSL AUTH TLS Explicit). FTPS has two supported levels: unverified certificates and verified. Using FTPS verified will first verify the SSL certificates and fail if they do not pass. Using either FTPS option in combination with the SSO login ensures that the FTP password is always encrypted when being passed between any of the processes used by SBS.

These details should be kept in sync with your systems so that items such as FTP password are always current in SBS.

NAP Data for Uberall

Upon creation of an Uberall Subscription we will push NAP data that is in Account or End User to Uberall. Once the subscription has been created we will not push any further changes to Uberall.

We accept the following fields for NAP Data. Please talk to your Topline representative about enabling this feature for your brand

  • email
  • phone
  • address 1
  • address 2
  • city
  • state
  • postcode

Adding Subscriptions

Once a User/Domain is created, a subscription to a Core Plan can be added and then Add-on subscriptions can be added to that Core subscription. See Subscription Management for more information.

Updating Users/Domains

Once created any User/Domain can be modified via API or manually in SBSmanager. All parameters can be modified except for the brandID, and userID/domainID. Only changed values need to be sent.

Suspending Users/Domains

To temporarily suspend the ability to access the system (for lack of payment for example), the User/Domain can be modified to Suspended status. When suspended they will not be able to login to any application and all subscriptions are suspended.

Effect of Suspension:

  • Yola/Uberall/Kliken/Ecwid application unavailable, login will be rejected
  • Yola site will still be served normally from your servers, except that:
    • An Online Store will be marked as “closed”
    • If using Yola hosted sites (syndicated model), the site will be taken offline
  • Kliken marketing campaigns will be suspended
  • All subscriptions will be marked as suspended and not charged at renewal dates
  • Ecwid stores will show a “Closed” sign on the website, but all product data is retained

When the User/Domain is reactivated then access to all subscriptions will be restored to their prior status, they become billable and applications will be available again. Alternatively, you can reactivate just the User/Domain and leave all subscriptions suspended.

Deleting Users/Domains

When a User/Domain is no longer a customer, they can be permanently deleted from SBS. All subscriptions for the User/Domain will be cancelled.

When deleted the User/Domain will not be able to login and modify their site with Sitebuilder. Deletion has no effect on the serving of the published site from your web servers with the following exceptions:

  • the eCommerce module will no longer process orders, the Online Store will be marked as “closed” on the published site
  • Sites published to Yola’s servers (syndicated) will not be served
  • The Yola Facebook connector will no longer function
  • Some 3rd party widgets may stop functioning
  • Kliken accounts will not be able to access the Marketing application.
  • The Connect leads feature will no longer function on the website
  • Any remaining advertising dollars will be consumed ASAP then all advertising will cease.

WordPress plugins

SBS provides you with branded WordPress plugins for the Kliken and Ecwid services so you can easily offer them to your WordPress userbase. The plugins can be installed in an automated process or manually for each User/Domain and are available for you to download in SBSmanager (Brand > Configuration > Customization).

Plugin activation can be automated by your system or left to the client to complete manually. Upon activation the plugin will self-register by connecting to the pre-created User/Domain you have set up for that specific domain in SBS.

An User/Domain in SBS with the same domain value as the WordPress site, is a prerequisite for the plugin deployment. If no matching User/Domain is found during the self-registration process, then the client will be provided a link to sign up for your services. The URL for the link is defined by you in SBSmanager (Brand > Configuration > Customization). This captures any clients that may have access to your branded plugin but don’t have an account with you.

1. Create the User/Domain in SBS
     a. The domain field must be equal to the client's associated WordPress installation, including subdomains if necessary
     b. No base subscription is required for the client in SBS. However, if you want to reflect the subscription in your system it can be added at this step.

2. Install the plugin into the client’s WordPress installation

3. Activate the plugin
     a. Plugin will self-register
     b. Adds a free subscription to Stats (for Kliken plugin) or eCom Free (for Ecwid plugin) in SBS or uses the pre-existing one from step 1b above

4. SSO access to application is provided from your control panel
     a. Upgrades to purchase any higher level plan (AdManager or eCom) are now possible through your ordering process

Activating plugin For clients that are on a managed service or where the nature of the hosting allows you to, we recommend automatically activating the plugin for all accounts. For clients with a self-managed service we recommend letting the client activate the account and messaging them to do so.

DSSO (DomainSSO) User/Domain Create

Domain SSO is a quick and easy way to acquire new clients, and/or make logins to AdPro easy for your existing clients.

You can download a DSSO Package from Brands > Resources. This package contains an example HTML form and accompanying PHP server-side script. You can place this form anywhere on your website, and by submitting a domain to the form the client will trigger one of the following actions;

  • If no User/Domain exists for that domain, then we create a User/Domain in your SBS account with a free stats subscription, and log the client into the AdPro interface. The User will be given a generic ID in our system.
  • If an User with that domain already exists, then the client will login to the existing AdPro interface for the domain.

When logged into the AdPro interface if the client elects to purchase a campaign subscription they will be redirected to your purchase URL. If this is a new client to your system, when you ask to create the User/Domain in our system, instead of creating a new one we will update the existing userID/domainID we had previously created so that the userID/domainID in SBS matches the new one in your records, thereby keeping our records in sync with yours.

SSO to applications

The SBS API is only made available to you (not your downstream) and the calls require a Partner AuthKey as your unique key into the API. The AuthKey is downloadable by “Owner” in SBSmanager and can be used for all calls affecting your top level Brand as well as all of your sub Brands.

The SBS API allows for SSO (Single Sign On) supporting secure one click access from your client control panel to a session in our applications. This process is seamless and transparent to the client and the brand visible is always yours or your respective sub Brand’s.

SBSgateway login to apps

In addition, SBSgateway provides a branded client facing login screen that can be used alongside or instead of SSO. It supports both new User/Domain registration, as well as logins for registered Users/Accounts. It can be exposed as a link on your website. For further information please view the SBSgateway documentation.

DIFM (Do It For Me) Process

DIFM (Do It For Me) services provided by your company (or third party) are supported with a number of functions designed to help streamline the DIFM work flow. Both internal and external teams of DIFM designers can be safely provided access.

DIFM SBS Filtering

DIFM designers that are working on the sites can be provided a login to SBSmanager to allow them to easily see and login to any of the Users/Domains they need to work on. Only DIFM 1 (preview) and 2 (live) Users/Domains will be shown, while hiding the 0 (DIY) Users/Domains. DIFM agents also won’t have access to the client detail screen so for example, FTP details are hidden and no changes to the client's plan can be made.

Preview FTP location

For Yola clients, a common location for publishing the site while still being developed allows the customer to view and comment on the work in progress. A common domain and FTP location can be configured once and then used for all pre-delivery DIFM publishing events.

Assuming a preview domain of my-preview-domain.com and a client domain of myclient.com the following would occur:

  • Self hosted brands will publish to a subfolder inside your preview domains FTP location. When the User/Domain is in DIFM mode, the url would point to that subfolder - my-preview-domain.com/myclient-com. When the User/Domain is updated to “live” then all subsequent publishing events will be to the client's configured FTP location, and the url would revert to the client's url of myclient.com.

  • Yola hosted brands will render at a subdomain of the preview domain - myclient-com.my-preview-mydomain.com until switched to live.

SSL for Yola Hosted Sites

Websites that are hosted on Yola's servers are eligible for Free SSL certificates provided by Cloudflare. The process is detailed in full here.

The process can be initiated or checked for individual clients from within SBSmanager.

  1. Edit the User/Domain and click on the Tools Tab. You will see a button to SSL Setup. Clicking that button will allow you to create a SSL zone as the first step.
  2. The UI will then give step by step instructions to walk you through the process, and will give directions regarding DNS changes you will need to make. Our process will continue to monitor those DNS entries until they all pass the SSL Setup QA.
SSL Setup

Note: This feature is not available to self-hosted websites

Subscription Management Processes

Adding Subscriptions

Once a User/Account is created, a subscription to a Core Plan can be added and then Add-on subscriptions can be added to that Core subscription.

Each subscription will have an independent start and renewal date and can be upgraded or downgraded independently as required.

AdManager Subscriptions

An AdManager subscription is the method of funding a campaign definition so that the ads begin to be placed with the advertising platform (e.g.: Google, Bing, Facebook). A user could have many campaigns defined, then can choose to fund each one independently by purchasing a subscription from you for the campaign. Campaign:subscription is 1:1.

One User can have multiple AdManager subscriptions in either the Yola Add-on or Kliken Add-on implementations. This supports users that want to have multiple ad campaigns each focusing on a certain product or service. Each subscription is connected to a single campaign and has a independent start date and renewal date, and can be upgraded, downgraded and cancelled independently. There is no limit as to the total number of AdManager subscriptions a single User can have.

When an AdManager subscription is upgraded, any residual AdSpend remaining from the original subscription will be added to the first month of the new subscription level. The start date and renewal date will be updated to be the date of upgrade.

When an AdManager subscription is downgraded, the current higher spend level will continue until the renewal date and then the subscription will renew at the new lower level. There is no change to the renewal date when downgrading.

With the Kliken standalone application, Users can also have a single subscription to each of the “Stats” and the “Connect” plans per domain. Stats are a free option and required before any other Kliken services can be added.

With Yola applications, Site Stats come automatically installed with no provisioning required, and the Connect plan is included in the Premium level subscription automatically.

Subscriptions can be provisioned as the AdManager Add-on to a Yola sub or as a standalone application. When the subscription is added onto a Yola sub then the AdManager interface will be integrated into the Yola application interface providing a seamless experience for the user. If AdManager is used standalone, then the login will start a session with the white label Kliken interface as either a new tab or it can be iFramed into your cp.

AdManager Prepurchased Subs

You can offer AdManager subscriptions for purchase either after the user has created a campaign definition in the UI then uses your Upgrade URL for purchase, or prior to campaign creation "Prepurchase". In the prepurchase option a shell campaign is created in a pending state to hold the AdSpend funds that will accumulate until the user completes the campaign creation process and launches it. After launch the system will add the accumulated funds to the normal AdSpend up to a maximum of 2x the normal rate.

While the campaign is in this pending state you are unable to upgrade or downgrade the related subscription. A call to do so will be refused by the API. In this case you need to cancel the current pending subscription, the AdSpend funds will be credited to your Partner Balance (but not the service fees), then you can order the new subscription for the user.

The campaign status waiting indicates that the campaign has been funded, but has not launched in the Kliken app. For example, a pre-purchased campaign can be funded for several terms even if the user never completed its configuration and launched it (activated it) with the accumulated funds.

When a campaign is waiting (its monies are not spent). If the partner cancels the subscription, then the accumulated adspend is refunded to the partner. The service fee portion of the sku is not refunded.

QuickStart for AdManager

The QuickStart Add-on can be ordered for any AdManager subscription and provides a service where our team will create and launch a campaign for the user. To do so we require information from the user about their business and the objective of their advertising campaign which is then submitted via the API as name/value pairs representing the text of the questions and answers the user filled out.

Two campaigns will always be created, Display and Search, even if only one was ordered. The additional campaign will not be launched for the user but will be available to them to launch later by purchasing a new AdManager subscription from you in the normal manner. Turnaround time is 2 business days.

Managing Subs with Currency

Products that require currency (AdManager types for Kliken or Yola) have the following rules:

  • User Currency can be set during User Create.
  • User Currency can be changed via User Edit if there are no subs already using the currency.
  • User Currency can be left blank and it will be set automatically when a subscription involving currency is requested by using the Brand’s default currency.
  • User Currency is locked to the currency of the first AdManager subscription.

Managing Subs with Quantity

Most SKUs do not require a quantity - quantity = 1 is implied throughout the processes. E.g. one Sitebuilder subscription, one e-store per domain, one subscription for one campaign.

However, some products (e.g. listings) require a quantity. E.g. one subscription for the Listings service comes with 0 location. Each location costs X. Create the sub with quantity = N. Later change the sub to have a different quantity if you please.

Macro Processes

Adding Users with Subs

Users with a subscription can be added in one step using our DSSO (Domain SSO) process. Calls with just a domain will in one step create a SBS User and core sub. This process can make integrations easier to accomplish.

These calls can be made from a secure (logged in user) page, or any public page on your website. For those interested, we have examples of a simple 1 button approach to creating users and subs available in the Resources section of SBSmanager.

These calls use a different authorization scheme than our other API calls, and that is outlined in the AuthKey download file obtainable from SBSmanager > Brands > Resources.

API Command Reference

Legend

Symbol Description
The presence of this icon indicates that the feature is still under development (Beta) and may not be completed in the environment (e.g. production, sandbox) that you are using.

Working with REST Requests

Our REST API is stateless so for each call to the API you must fully authenticate. We use a custom HTTP scheme based on a keyed-HMAC (Hash Message Authentication Code) for authentication.

Instructions on how to compose this authorization signature are included when you download your brand's API AuthKeys from SBSmanager. The authKeys can be obtained from SBSmanager using the Brands > Resources menu item.

Request Headers

The following HTTP headers must be included in every call to the API.

Name Description
SBS-Expires The expiry date of the request, where after the request should no longer be considered valid.
In milliseconds since the epoch (in UTC time), e.g.: 1348065218886.
Typically, would be set to now + 5 minutes.

PHP example: $expiry = (time()*1000) + (1000*5*60);
SBS-Signature Created using the method detailed in your API AuthKey download from SBSmanager
Content-Type If content is sent with request this should be set to application/json; charset=UTF-8.
Content-Length If content is sent with request this is the string length of the json.

Note: Parse headers in a case-insensitive way in order to avoid mismatches caused by different layers of software.

Authentication

To authenticate a request, you first concatenate selected elements of the request to form a string. Then use your Partner AuthKey to calculate the HMAC of that string. Add the resulting HMAC signature as a parameter of the request, using the formula described in your brand's API AuthKeys download.

Every request to the API references a specific Brand, e.g. sbsapi.com/hostabc/. The AuthKey to use for such a request can be that of the specific Brand or that of any of the Brand's parent-Brands (e.g. parent, grandparent, etc). In a multi-brand integration, it makes sense to use the top Brand's AuthKey for all calls.

Root Endpoints

Note: all subscriptions added in the production environment are fully chargeable.

Notes

Data Encoding

The SBS API requires all data to be UTF-8 encoded. The date fields are formatted according to ISO8601 format.

Headers

We recommend that headers be parsed in a case-insensitive way in order to avoid mismatches caused by different layers of software.

Dates and Times

Times are express in UNIX (POSIX) epoch time .

International Domain Names

International Domain Names are supported by SBS and API calls should be sent Punycode encoded. SBSmanager will accept and display native URLs but store these values as Punycode.

API URL Format

All contextualized to brandID, eg. https://sbsapi.com/{brandID}/users. In this example the brandID could be the top-level Brand or any of your Sub-Brands.

Service Inaccessible

On occasion our API service may be unavailable to your system, so it is important to build in a re-try mechanism to cope with this situation. Your retry should cope with both a timeout eg: due to network issues, and also a 503 response due to service being temporarily unavailable.

API Stability

We are committed to making all new versions and updates of this API backwards compatible so that your integration will continue to work normally. New versions may add new functionality or pass additional information that you can then decide to take advantage of by extending your integration.

Ref value in Responses

Most calls will return a "Ref" value in the response that is an internal reference number Topline can use for support issues and debugging.

API Agent ID

In order to identify the originator of the requests to the API we recommend that you add a field to the HTTP header for the following.

Name Value
SBS-AgentID To identify your agent version that is calling the API. Alphanumeric, no spaces e.g. MY_BRAND_API_1.0.0

RESTful Web Service HTTP verbs

All APIs will make use of standard HTTP status codes and verbs. Note that not all verbs will be supported on all paths.
Resource GET PUT POST DELETE
Collection URI, such as
https://sbsapi.com/brandID/users
List the URIs of the collection's members. n/a Create a new entry in the collection. Delete the entire collection.
Element URI, such as
https://sbsapi.com/brandID/users/fred
Retrieve a representation of the specific member of the collection. Update the specific member of the collection n/a Delete the specific member of the collection.

Note that URLs terminated with a / will be responded to with a redirection code to the equivalent one without a trailing /.

Status Codes

Code Status Description
200 Success The request completed successfully. No data was changed.
201 Created The Location header will indicate the path to the created resource. The response body may have additional information.
204 No Content The request completed successfully, but there was no content to return. Typical response to a DELETE.
303 See Other The response to the request can be found under another URI using a GET verb.
400 Bad Request The request could not be understood by the server due to malformed syntax. Do not repeat the request until modified.
401 Unauthorized When HMAC Signatures don't match.
402 Insufficient Funds The request is being refused due to lack of prepaid credit on account to pay for the fees associated with the subscription.
Please notify your finance team and re-try the call after funds have been added.
404 Not Found A specified resource couldn't be found, response will contain details and debugging information.
405 Verb Not Allowed A request was made of a resource using a request verb not supported by that resource; for example, using GET on a form which requires data to be presented via POST, or using PUT on a read-only resource.
406 Not Acceptable The requested resource is only capable of generating content not acceptable according to the Accept headers sent in the request.
All requests & responses should be of content type application/json.
409 Conflict A specified resource already existed, the response will contain details for example: "Duplicate UserID"
500 Internal Server Error The response will contain error details for debugging.
502 Upstream  Server Error The response will contain error details for debugging.
503 Service Unavailable Our service is temporarily not able to respond. Please re-try the request.

Macro Calls

These endpoints can be used to combine user and sub creation in one call. When provisioning a new sub these calls all provision a basic core subscription.

On subsequent calls they simply log the user into the product's interface, and will work with either basic or upgraded cores.

These calls can be used from a secure or non-secure section of you website. They do not require the usual authentication, but use a hash-based authentication. The formula for composing that authorization is explained in the AuthKeys download.

The call returns a URL to log the user into the application.

Query string arguments can be applied to specify the language of the application interface and in the case of self-hosted Yola brands, you can also send FTP information for the user. FTP information will be updated for the user whenever it is present.

Yola DSSO call

To add a new user with a Latitude Free core product, or login to Latitude Free or Premium products.

Endpoint

GET
/{brandID}/dsso/yolalogin/{domain}/{secure}/{hash}?=

Parameters

Parameter Description
domain any fully qualified domain or subdomain
secure 1 = secure (from a logged in page)
2 = non-secure (from any public page)

Query string arguments

Field Default Description
lang en the language presented in the Sitebuilder interface
ftpAddress the ftp host address
ftpUserid the username for the ftp account
ftpPassword the user's ftp password
ftpPort the port to use for ftp
ftpProtocol 1 = ftp, 2 = FTPS (unverified), 3 = FTPS (strict)

Success Status

HTTP 200

Response

{
    "detail": {
        "url": "https://editor.sitebuilderhostqa.net/?auth_token=4be9a5490874c78afc39a8a7e9a7bc3d44969f75&expires=1564532877&user_id=2cf0538d3a6e4e0d8fb2955983bbc4a3"
    },
    "code": 200,
    "status": "OK",
    "ref": 2245
}

Kliken DSSO call

To add a new user with a Kliken stats product.

Endpoint

GET
/{brandID}/dsso/swlogin/{domain}/{secure}/{hash}?=

Parameters

Parameter Description
domain any fully qualified domain or subdomain
secure 1 = secure (from a logged in page)
2 = non-secure (from any public page)

Query String Arguments

Field Default Description
lang en the language presented in the Kliken interface

Success Status

HTTP 200

Response

{
    "detail": {
        "url": "https://sandbox.mysite-analytics.com?lang=en&85335263=Hq0wuZGnNi23ILMr4og07HXJ3OrMljOpieO7KpmYN0@djLpAgo6AstYnbxQZFJZT@Z43CCPJbdZ55yrorfz3Gg==&15=9NJThhNMll2uvOYbAE2wrwsw&lc=en"
    },
    "code": 200,
    "status": "OK",
    "ref": 729
}

Brands

These endpoints are used to interact with your Brand (or Company) settings.

Create Brand

Create a new Brand under the specified Brand.

Endpoint

POST
/{brandID}/brands

Input Fields

Property Required Default Description
brandID Yes Alphanumeric and underscore only, no spaces. Must begin with alphanumeric. Max 26 characters.
brandingBarUrl Recom Homepage URL of HTML to be displayed in top frame of Kliken UI. Must be https:// protocol.
brandName Yes Brand name for display only. All characters and spaces.
brandStatus 1 Status:
1=active
3=suspended
4=pending
countryCode parent’s Country code of the reseller. Must be recognized 2 character country code. See Appendix for supported values.
currency parent’s The currency used as a default for the user's purchases if one is not explicitly assigned to the user, nor given in the user's initial purchase.
delayedDowngrade parent’s 0 = downgrade happens immediately;
1 = downgrade is delayed until the end of current subscription term.
difmDomain Domain for publishing for Users to that are in DIFM Preview mode.
difmFtpAddress FTP address for DIFM Preview Users.
difmFtpPassword FTP password for DIFM Preview Users.
difmFtpPort 21 Integer. Allowable range [0, 65535].
difmFtpProtocol 1 1 = FTP
2 = FTPS Explicit
3 = FTPS Explicit and verified
difmFtpUserid FTP userID for DIFM Preview Users.
difmFtpWwwroot Should be blank if web root = ftp root.
ftpLimit parent’s Limits number of concurrent ftp connections used during a single publish event. Range [1,10].
homePageUrl Yes Full homepage of Brand, used for links under logo in Yola UI and as fallback if specific URLs are not set.
hostingType parent’s Where the published site will be hosted:
1=by Service Provider via FTP
2=Yola hosted.
language parent’s This will be the default for all new users. See Appendix for supported values.
loginPageUrl URL for user login in the brand's control panel.
logoUrl Recom URL of logo for Yola Sitebuilder UI. Must be https:// protocol.
logoUrlMobile Must be https:// protocol. For mobile apps.
mapAddress parent’s Default address for Google map in user site.
resellerCap 0 1 = ability for the Sub-Brand to add Sub-Brands.
shortName Yes For display where space is limited, like menu items, max 25 chars.
signupUrl Recom Homepage signup URL for Trial users to sign up for hosting.
sslHosting (Boolean 0 or 1) In combination with hostingType = 2, this determines whether CNAME creation and management is handled by Yola.
supportEmail Yes or URL Address for support used in applications UI. At least one of supportUrl or supportEmail.
supportUrl Yes or Email URL for support link in applications UI. At least one of supportUrl or supportEmail.
timezone parent’s Supports recognized timezone names. See Appendix for supported values.
trialDuration parent’s Default durations in days of Trial Users. Must be in range [0,30].
upgradeUrl Recom Homepage upgrade URL for “upgrade now” links in Application interfaces.

Success Status

HTTP 201
Location: https://sbsapi.com/{brandID}

Response

{
"detail": {
    "brandID": "brand_e584149833fa"
  },
  "code": 201,
  "status": "Created",
  "ref": 664
}

Example Request

{
    "brandID": "brand_e584149833fa",
    "brandName" : "My Topline Brand",
    "homePageUrl" : "https://mybrand.com",
    "logoUrl" : "https://mybrand.com/img/brand-logo.png",
    "shortName" : "My Brand"
}

View Brand

Retrieve details for a specific Brand.

Endpoint

GET
/{brandID}

Success Status

HTTP 200

Response

{
	"code": 200,
	"status": "OK",
	"detail": {
		"brandID": "my_brand",
		"brandingBarUrl": "",
		"brandName": "My Company",
		"brandStatus": 1,
		"country": "Canada",
		"countryCode": "CA",
		"currency" : "CAD",
		"delayedDowngrade": 0,
		"difmDomain": "",
		"difmFtpAddress": null,
		"difmFtpPort": 21,
		"difmFtpProtocol": 1,
		"difmFtpUserid": null,
		"difmFtpWwwroot": null,
		"domain": "topline.cloud",
		"ftpLimit": 1,
		"homePageUrl": "http://www.mybrand.cloud",
		"hostingType": 1,
		"language": "EN",
		"logoUrl": "https://mybrand.com/logos/mybrand-logo.png",
		"mapAddress": null,
      "options":{
         "difm_preview_no_ssl":"0",
         "ecwid.sbsgRetailName":"ShoppingCart",
         "ecwid.url.tnc":null,
         "ecwid_plugin_dashboard_name":"Shopping Cart",
         "ecwid_plugin_download_filename":"shopping-cart.zip",
         "free_root_domains":null,
         "is_user_email_unique":"0",
         "max_nfr":"0",
         "p3_purchase_mode_json":null,
         "send_user_welcome_email_on_first_sub":"0",
         "sw.headerBgColor":"#fff",
         "sw.headerTextColor":"#000",
         "sw.mobileAppPrimaryColor":"#fff",
         "sw.mobileAppPrimaryTextColor":"#000",
         "sw.mobileAppSecondaryColor":"#ccc",
         "sw.mobileAppSecondaryTextColor":"#333",
         "sw.mobileAppSplashScreenColor":"#ADD8E6",
         "sw.sbsgRetailName":"AdManager",
         "sw.showAccountUrl":"1",
         "sw.showHeader":"1",
         "sw.showLogout":"1",
         "sw.suppressMobileApp":"0",
         "sw.topBarBgColor":"#000",
         "sw.topBarTextColor":"#fff",
         "sw.url.tnc":null,
         "sw_plugin_dashboard_name":"Web Analytics",
         "sw_plugin_download_filename":"web-analytics.zip",
         "synup.brandedDomain":"{{brand}}.listme.online",
         "synup.dkimJSON":null,
         "synup.emailFrom":"info",
         "synup.sbsgRetailName":"Listings",
         "synup.url.tnc":null,
         "yola.colors.default.primary":"#fff",
         "yola.colors.default.secondary":"#000",
         "yola.colors.hover.primary":"#000",
         "yola.colors.hover.secondary":"#fff",
         "yola.mode.new.02.00":null,
         "yola.sbsgRetailName":"SiteBuilder",
         "yola.url.tnc":null,
         "yola.ws.colors.cta_600":"#0072ef",
         "yola.ws.colors.cta_700":"#005ed9",
         "yola.ws.colors.cta_800":"#094aba",
         "yola.ws.colors.danger_600":"#FF7043",
         "yola.ws.colors.danger_700":"#F4511E",
         "yola.ws.colors.danger_800":"#D84315",
         "yola.ws.colors.info_600":"#31B0D5",
         "yola.ws.colors.info_700":"#1F9BBF",
         "yola.ws.colors.info_800":"#0E87AB",
         "yola.ws.colors.primary_600":"#34363c",
         "yola.ws.colors.primary_700":"#262a31",
         "yola.ws.colors.primary_800":"#141B21",
         "yola.ws.colors.success_600":"#1AB744",
         "yola.ws.colors.success_700":"#1B9B4A",
         "yola.ws.colors.success_800":"#0B8738",
         "yola.ws.colors.warning_600":"#FFCA28",
         "yola.ws.colors.warning_700":"#FFB302",
         "yola.ws.colors.warning_800":"#FF8F00",
         "yola.ws.company_logo":"https:\/\/mybrand.cloud\/logo.png",
         "yola.ws.company_logo_width":"32",
         "yola.ws.company_mobile_logo":"https:\/\/mybrand.cloud\/logo.png",
         "yola.ws.company_mobile_logo_width":"32",
         "yola.ws.product_name":"Latitude",
         "yola.ws.product_slogan":"Beuatiful Websites made easy",
         "yola.ws.site_footer.logo":"https:\/\/mybrand.cloud\/logo.png",
         "yola.ws.site_footer.logo_width":"46",
         "yola.ws.site_footer.message":"Latitude by MyName",
         "yola.ws.site_footer.theme":"dark",
         "yola.ws.site_footer.url":"https:\/\/mybrand.cloud",
         "yola.ws.theme":"light",
         "yola.ws_exclude.site_footer":"0",
         "yola.ws_support_url":null
      },
        "renewalType": 2,
		"resellerCap": 1,
		"shortName": "TestBrand",
		"signupUrl": "http://www.mybrand.cloud/signup.html",
		"supportEmail": "support@mybrand.com",
		"supportUrl": "http://support.mybrand.cloud",
		"term": 0,
		"timezone": "Eastern Standard Time",
		"trialDuration": 10,
		"upgradeUrl": "http://upgrade.mybrand.cloud"
	}
}

Response Fields (not described in Create Brand)

Property Description Values
renewalType Defines how subscriptions are handled when they reach their expiry date 0 = Automatic (aka evergreen subscription)
1 = Manual (aka triggered). When the subscription reaches its expiry date, it is suspended. If it reaches its expiry date again, while suspended, it is set expired.
2 = Manual (aka triggered). When the subscription reaches its expiry date, it is expired.

List Brands

Retrieves a paginated listing of all Sub-Brands of the specified Brand. Can be filtered using query arguments listed.

Endpoint

GET
/{brandID}/brands

Query String Arguments

Field Default Description
size 50 page size, integer, maximum 50.
page 1 page number, 1-based.
brandID No filtering search text for brandID, using LIKE "TEXT%"
shortName No filtering search text for shortName, using LIKE "TEXT%"
sort shortName either of "brandID" or "shortName"

Success Status

HTTP 200

Response

{
	"results": {
		"status": "OK",
		"detail": {
			"count": 78,
			"previous": "http://sandbox.sbsapi.com/topline/brands?page=1&size=5",
			"next": "http://sandbox.sbsapi.com/topline/brands?page=3&size=5",
			"brands": [{
					"brandID": "test_brand_1",
					"shortName": "test brand 1",
					"brandStatus": 4
				},
				{
					"brandID": " test_brand_2",
					"shortName": "test brand 2",
					"brandStatus": 1
				},
				{
					"brandID": " test_brand_3",
					"shortName": "test brand 3",
					"brandStatus": 3
				},
				{
					"brandID": " test_brand_4",
					"shortName": "test brand 4",
					"brandStatus": 1
				},
				{
					"brandID": " test_brand_5",
					"shortName": "test brand 5",
					"brandStatus": 1
				}
			]
		},
		"code": 200,
		"ref": 1252
	}
}

Edit Brand

Update details of a specific Brand. Only fields that are sent will be updated. Any subset of the fields below can be specified for modification. There are no required fields.

Endpoint

PUT
/{brandID}

Input Fields

Field name Description
all Same fields as Create. Except brandID cannot be changed.

Success Status

HTTP 201

Response

{
  "msg": "OK: editBrand",
  "code": 201,
  "status": "Created",
  "ref": 678
}

Delete Brand

Delete Brand. All users and subscriptions must be deleted first.

Endpoint

DELETE
/{brandID}

Success Status

HTTP 204

Response

{}

List Brand Plans

Retrieve details of all plans available for a specific Brand. Sorted by productID3.

Note that you may also request this listing as a spreadsheet-friendly comma-separated (CVS) file, with a proposed attachment file name pattern like Sample Brand Name SBS Service Plans 2018-04-19.csv. For example, viewing plan data using the CSV format makes it easy to consume pricing data per plan.

Note also that the fields in the list of properties of both output formats are not identical!

Query String Arguments

Field Default Description
extras none Comma-separated list of these:

prices : Only applicable when ?format=json; A prices property is added to each plan, with as many currencies as available.
format json One of these:

json : The response body is a JSON object

csv : The response body is text/csv with a suggested attachment filename in the Content-Disposition header. Note that extras=prices is implied in this format - prices are always returned, no need to ask for them.
lang en Optional. For those values that may be internationalized by the brand, this argument controls the language served. If the individual value was not customized for the requested language, the default (en) value is served.

Endpoint

GET
/{brandID}/plans?extras=prices

Success Status

HTTP 200

Response

{
  "detail": {
    "planIDs": [{
		"ID": 18,
		"planID": "yola_3pg",
		"planName": "Yola Lite",
		"productID": "2.10.0.0",
		"productID3": "02.00.10",
		"shortName": "YOLA LITE",
		"description": "WBB Starter with 3 pages Syndicated",
		"spCost": 0,
		"isCore": 1,
        "multiple": 0,
		"vendor": "yola",
		"needsCampaign": 0,
        "maxTrialDays": "30",
		"prerequisites3": "",
		"prices": {
            "EUR": {
                "fee": 0.06,
                "adspend": null,
                "msrp": 0.07
            },
            "USD": {
                "fee": 0.07,
                "adspend": null,
                "msrp": 0.08
            }
        }

    }, {
		"ID": 19,
		"planID": "yola_prem",
		"planName": "Yola Premium",
		"productID": "2.31.0.0",
		"productID3": "02.00.30",
		"shortName": "Yola Premium",
		"description": "WBB Premium Syndicated",
		"spCost": 0,
		"isCore": 1,
        "multiple": 0,
		"vendor": "yola",
		"needsCampaign": 0,
		"maxTrialDays": "30",
        "prerequisites3": "",
		"prices": {
            "EUR": {
                "fee": 300,
                "adspend": null,
                "msrp": 360
            },
            "USD": {
                "fee": 7.7,
                "adspend": null,
                "msrp": 9.24
            }
        }
    }, {
		"ID": 20,
		"planID": "yola_ecom_base",
		"planName": "WBB Add-on Ecomm Base",
		"productID": "2.0.10.0",
		"productID3": "02.01.10",
		"shortName": "WBB Add-on Ecomm Base",
		"description": "WBB Add-on eCom Base",
		"spCost": 15,
		"isCore": 0,
        "multiple": 0,
		"vendor": "yola",
		"needsCampaign": 0,
		"maxTrialDays": "30",
        "prerequisites3": "02.00",
		"prices": {
            "EUR": {
                "fee": 12,
                "adspend": null,
                "msrp": 14.4
            },
            "USD": {
                "fee": 15,
                "adspend": null,
                "msrp": 18
            }
        }
    }, {
		"ID": 21,
		"planID": "yola_ecom_unlim",
		"planName": "WBB Add-on eComm Unlim",
		"productID": "2.0.20.0",
		"productID3": "02.01.20",
		"shortName": "WBB Add-on eComm Unlim",
		"description": "WBB Add-on eCom Unlim",
		"spCost": 100,
		"isCore": 0,
        "multiple": 0,
		"vendor": "yola",
		"needsCampaign": 0,
		"maxTrialDays": "30",
        "prerequisites3": "02.00",
		"prices": {
            "EUR": {
                "fee": 80,
                "adspend": null,
                "msrp": 96
            },
            "USD": {
                "fee": 100,
                "adspend": null,
                "msrp": 120
            }
        }
    }, {
		"ID": 22,
		"planID": "yola_ad_1",
		"planName": "WBB Add-on AdManager 1",
		"productID": "2.0.0.10",
		"productID3": "02.02.10",
		"shortName": "WBB Add-on AdManager 1",
		"description": "",
		"spCost": 35,
		"isCore": 0,
        "multiple": 1,
		"vendor": "yola",
		"needsCampaign": 1,
		"maxTrialDays": "30",
        "prerequisites3": "02.00",
		"prices": {
            "EUR": {
                "fee": 8.8,
                "adspend": 40,
                "msrp": 70.56
            },
            "USD": {
                "fee": 11,
                "adspend": 50,
                "msrp": 73.2
            }
        }
    }, {
		"ID": 23,
		"planID": "yola_ad_2",
		"planName": "WBB Add-on AdManager 2",
		"productID": "2.0.0.20",
		"productID3": "02.02.20",
		"shortName": "WBB Add-on AdManager 2",
		"description": "",
		"spCost": 70,
		"isCore": 0,
        "multiple": 1,
		"vendor": "yola",
		"needsCampaign": 1,
		"maxTrialDays": "30",
        "prerequisites3": "02.00",
		"prices": {
            "EUR": {
                "fee": 24.8,
                "adspend": 99.2,
                "msrp": 178.56
            },
            "USD": {
                "fee": 31,
                "adspend": 124,
                "msrp": 186
            }
        }
    }, {
		"ID": 24,
		"planID": "yola_ad_3",
		"planName": "WBB Add-on AdManager 3",
		"productID": "2.0.0.30",
		"productID3": "02.02.30",
		"shortName": "WBB Add-on AdManager 3",
		"description": "",
		"spCost": 150,
		"isCore": 0,
        "multiple": 1,
		"vendor": "yola",
		"needsCampaign": 1,
		"maxTrialDays": "30",
        "prerequisites3": "02.00",
		"prices": {
            "EUR": {
                "fee": 32.8,
                "adspend": 131.2,
                "msrp": 236.16
            },
            "USD": {
                "fee": 41,
                "adspend": 164,
                "msrp": 246
            }
        }
    }]
  },
  "code": 200,
  "status": "OK",
  "ref": 671
}
GET
/{brandID}/plans?format=csv

Success Status and Headers

HTTP 200
Content-Type: text/csv;charset=UTF-8
Content-Disposition: attachment; filename="ACME SBS Service Plans 2018-04-19.csv"

Response (truncated)

PlanName,ShortName,Description,ProductID3,PlanID,Vendor,Multi,Type,Bundle,"EUR MSRP","EUR AdSpend","EUR Service fee","USD MSRP","USD AdSpend","USD Service fee"
"AdManager Display Starter","Display Starter",,02.03.20,yola_adm_dis_starter,yola,Yes,monthly,No,$70.56,$40.00,$8.80,$73.20,$50.00,$11.00
...

List Brand Coupons

Retrieve details of the currently active coupons available to the brand, sorted by name.

Endpoint

GET
/{brandID}/coupons

Success Status

HTTP 200

Response

{
	"detail": {
	    "coupons": [
	        {
	            "name": "test_coupon_1",
	            "type": "search",
	            "startDate": "2018-03-17 19:15:46",
	            "endDate": "2018-04-17 19:15:46",
	            "minAdSpend": 25,
	            "value": 100
	        },
	        {
	            "name": "test_coupon_2",
	            "type": "search",
	            "startDate": "2018-03-17 19:15:46",
	            "endDate": "2018-04-17 19:15:46",
	            "minAdSpend": 100,
	            "value": 400
	        },
	        {
	            "name": "test_coupon_3",
	            "type": "search",
	            "startDate": "2018-03-17 19:15:46",
	            "endDate": "2018-04-17 19:15:46",
	            "minAdSpend": 200,
	            "value": 600
	        }
	    ]
	},
    "code": 200,
    "status": "OK",
    "ref": 308169
}
Property Explanation
name Given by administrator who installed the coupon in SBSmanager
type search is the only valid type
startDate, endDate Date/time range where the coupon is active. Only currently active coupons are returned here.
minAdSpend In the partner's billing currency, the minimum amount of adSpend to spend to trigger this coupon.
value In the partner's billing currency, the amount of free adSpend the coupon grants. Buy one term and get this additional value.

Download WordPress plugin

Retrieves a WordPress plugin as an installer zip file. The plugin is the same for all users across the brand, and will connect to the user upon activation. Additional customization (WordPress Dashboard name and filename) are available in SBSmanager > Brands > Brand Configuration > Customization > Admanager. More details here.

Endpoint

GET
/{brandID}/sw/wpPlugin

Success Status

HTTP 200

Accounts

These endpoints are used to interact with Accounts for your brand.

Create Account

To add a new account to a Brand.

Note that submitting an email with the request also creates person1, the principal administrator for the account.

Endpoint

POST
/{brandID}/accounts

Input Fields

Field Vendor Required Vendor Recommended Description
accountId API Account identifier to marry multiple SBS userIDs (domains) to a single billable customer. Must be unique per brand, case-insensitive. (stored in lowercase)
address1 Business first address line
address2 Business second address line
businessCategory Business Category for this account or Google business category
city Business city
country deprecated, use countryCode
countryCode If not sent this will be inherited from the brand setting. Accepts 2 character country code. See Appendix for supported values.
currency Currency can be set during create, or can be changed via edit as long as the account has no subs already using the currency.
Currency can be left blank and it will be set once and for all automatically when a subscription involving currency is requested.
Once currency is set and a subscription exists that locks it for the account, it cannot be be changed ever again.
See Appendix for supported values.
email Ecwid Yola Note this triggers the creation of a Person with Admin role, associated with the Account as "Person1". Recommended for default value in Sitebuilder forms. Required for Ecwid for Store owner notifications (new sale etc.). Not shared externally.
host1
host2
host3
These fields can be used to store your information about this account and have it appended to upgrade / signup urls. E.g.: your internal userID. Up to 255 chars each
$user == $account
isNFR 1 = Any subscriptions added to this account will be NFR and count against total allotted.
language If not sent this will be inherited from the brand setting. See Appendix for supported values.
name Business name. Note that if it is not given, accountID is stored as name instead. Must be unique per brand if given.
phone Business phone number. Used in default site content for Yola. Used for SMS alerts for Kliken.
postcode Business postal code.
registration Optional national business identification. Must be unique per brand if given.
state Business state/province.
status 1 = Active (default on create)
3 = Suspended
timezone If not sent this will be inherited from the brand setting. Supports recognized time zone names. See Appendix for supported values.

Success Status

HTTP 201

Header

Location: https://sbsapi.com/{brandID}/accounts/test_account

Response

{
"detail": {
    "accountID": "test_account",
    "url": "https://sbsapi.com/acme/accounts/test_account",
  },
  "code": 201,
  "status": "Created",
  "ref": 539
}

Note: the url property leads to the View Account endpoint.

Example Request

{
    "accountID": "test_account",
    "city": "Toronto",
    "name" : "Mario Foundation"
}

Sample Create Account PHP Code

<?php
### CREATE ACCOUNT EXAMPLE
$authKey = '';   // see authKey download for instructions
$httpVerb = 'POST';
$contentType = 'application/json;charset=utf-8';
$postData = [
    "accountID" => "test_account",
    "city" => "Toronto",
    "name" => "Mario Foundation",
];
$postContent = json_encode($postData);
$expiry = '';    // see authKey download for instructions
$signature = ''; // see authKey download for instructions
$url = 'https://sandbox.sbsapi.com/<your brand>/accounts/';
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $httpVerb);
curl_setopt($ch, CURLOPT_VERBOSE, true);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postContent);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, "40");
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'SBS-Expires: '.$expiry,
    'SBS-Signature: '.$signature,
    'SBS-AgentID: MyAgentv1.0',
    'Content-Type: '.$contentType,
    'Content-Length: ' . strlen($postContent)
));
$result=curl_exec($ch);
curl_close($ch);
echo $result;
?>

View Account

To retrieve the details about a specific Account. This returns:

  • The account details

    • The collection of Domains (Users) per Account.

      • Optionally, the collection of Subs per Domain.
      • Optionally, the collection of Campaigns per Domain.
    • The collection of Persons per account.

Endpoint

GET
/{brandID}/accounts/{accountID}

Query String Arguments

Field Default Description
extras None Optional. Comma-separated list of additional information types. The following are valid:

actions : [note: performance cost] If subs was requested, then each sub in the list also has a allowedActions array of these possible values: changePlan, delete, reactivate, renew, suspend. This is intended to better inform a user interface.

campaigns : a campaigns list is added to the domain, showing all campaigns ever associated with the domain.

subs : a subs list is added to the domain, showing all subscriptions ever associated with the domain.
lang en Optional. For those values, like SKU texts, that may be internationalized by the brand, this argument controls the language served. If the individual value was not customized for the requested language, the default (en) value is served.

Success Status

HTTP 200

Response View Account

GET
/{brandID}/accounts/{accountID}?extras=subs

returns account view with subscription data

Response View Account

{
    "detail": {
        "accountID": "joegar20",
        "address1": null,
        "address2": null,
        "brandID": "topline",
        "brandShortName": "Topline",
        "businessCategory": null,
        "city": null,
        "countryCode": "CAN",
        "creationDate": "2020-06-18",
        "currency": "CDN",
        "host1": null,
        "host2": null,
        "host3": null,
        "isNFR": 0,
        "language": "en",
        "name": "Joe's Garage 2020",
        "phone": null,
        "postcode": null,
        "registration": null,
        "state": null,
        "status": 1,
        "timezone": "Romance Standard Time",
        "activeDomains": 3,
        "domains": [
            {
                "cnames": null,
                "creationAgentId": "toplv-sbsm-pugs",
                "creationDate": "2020-05-18",
                "difm": 2,
                "domain": "",
                "domainID": "abc",
                "ecwidStoreID": null,
                "status": 1,
                "swWpPluginUrl": "https://sbsapi.com/topline/users/100r18a/sw/wp-plugin/30dc6543",
                "domainID": "100r18a",
                "ecwid_ownerid": null,
                "spid": null,
                "sw_account_number": null,
                "swid": null,
                "yid": null,
                "yolaSiteID": null,
                "activeSubs": 0,
                "activeTrials": 0,
                "searchCoupons": 0
            },
            {
                "cnames": null,
                "creationAgentId": "toplv-sbsm-pugs",
                "creationDate": "2020-07-20",
                "difm": 0,
                "domain": "200r19a.subdomain.com",
                "domainID": "def",
                "ecwidStoreID": null,
                "status": 1,
                "swWpPluginUrl": "https://sbsapi.com/topline/users/200r19a/sw/wp-plugin/5432cbf59",
                "domainID": "200r19a",
                "ecwid_ownerid": null,
                "spid": null,
                "sw_account_number": null,
                "swid": null,
                "yid": null,
                "yolaSiteID": null,
                "activeSubs": 0,
                "activeTrials": 0,
                "searchCoupons": 0
            },
            {
                "cnames": null,
                "creationAgentId": "toplv-sbsm-pugs",
                "creationDate": "2020-07-30",
                "difm": 1,
                "domain": "300r20a.subdomain.com",
                "domainID": "ghi",
                "ecwidStoreID": null,
                "status": 1,
                "swWpPluginUrl": "https://sbsapi.com/topline/users/300r20a/sw/wp-plugin/c633d266",
                "domainID": "300r20a",
                "ecwid_ownerid": null,
                "spid": "cabff86c32fca0666a85fafc0ae7cda7",
                "sw_account_number": null,
                "swid": null,
                "yid": "bf23e0021fd94e259de7dc5239a8ceb7",
                "yolaSiteID": null,
                "activeSubs": 3,
                "activeTrials": 0,
                "searchCoupons": 0
            }
        ]
    },
    "code": 200,
    "status": "OK",
    "ref": 4674253
}

List Accounts

To retrieve a listing of all Accounts under the specific Brand. Can be filtered using query arguments listed.

This returns a collection of

  • The account details

    • The collection of Domains (Users) per Account.

      • Optionally, the collection of Subs per Domain.
      • Optionally, the collection of Campaigns per Domain.
    • The collection of Persons per account.

To retrieve a listing of all Accounts

Endpoint

GET
/{brandID}/accounts/

Query String Arguments

Field Default Description
accountID No filtering search text for these fields
coupon No filtering One of the following:
none : No trials, only subs without coupons
all : Only subs with a coupon, of any type
search : Only subs with a coupon, of type 'search'

(at this point, `all` is the same as `search`)
creationagentid No filtering
creationdate No filtering range
difm No filtering A comma-separated list of integers representing the domain (user) DIFM setting
domain No filtering search for domain text using LIKE "%DOMAIN%"
domaincreationagentid No filtering filter account by their domains' attributes
domaincreationdate No filtering filter account by their domains' attributes
domains No filtering A comma-separated list of domains - search matching the exact domain name in the list
domainstatus No filtering Filter account by their domains' attributes
extras None; no filtering Optional. Comma-separated list of additional information types. The following are valid:

actions : [note: performance cost] If subs was requested, then each sub in the list also has a allowedActions array of these possible values: changePlan, delete, reactivate, renew, suspend. This is intended to better inform the user interface.

campaigns : a campaigns list is added to the domain, showing all campaigns ever associated with the domain.

subs : a subs list is added to the domain, showing all subscriptions ever associated with the domain.
host1
host2
host3
No filtering search text for these fields
nfr no filtering
nottrial no filtering
onlytrial no filtering
page 1 page number, 1-based.
pending 0 0,1
product No filtering A comma-separated list of planIDs. Only domains with trial or subs for products in this collection will be retrieved.
productid3 No filtering A comma-separated list of product_id3. Only domains with trial or subs for products in this collection will be retrieved.
search None Search text for any of the following fields for a match using LIKE "%TEXT%". i.e. an OR operator is applied per account. name, creationagentid, domain, domainid, and yid.
`search` can not be used in conjunction with the other filters listed above.
size 20 page size, integer, maximum 50.
sort -creationDate Prefix with "-" for descending order.
One of accountid, creationagentid, creationDate, name, partner, status.
status No filtering A comma-separated list of integers representing the account status.

Success Status

HTTP 200

Response List Accounts

GET
/{brandID}/accounts?extras=subs&size=2&sort=creationdate

Example with extras, page of size 2, ordered by creation date.

{
	"detail": {
		"count": 18,
		"next": "https://sbsapi.com/topline/accounts?extras=subs&page=2&size=2&sort=-creationdate",
		"accounts": [{
				"accountID": "joegar2020",
				"address1": null,
				"address2": null,
				"brandID": "topline",
				"brandShortName": "Topline",
				"businessCategory": null,
				"city": null,
				"countryCode": "CAN",
				"creationDate": "2020-05-18",
				"currency": "CDN",
				"host1": null,
				"host2": null,
				"host3": null,
				"isNFR": 0,
				"language": "en",
				"name": "Joe's Garage 2020 Inc.",
				"phone": null,
				"postcode": null,
				"registration": null,
				"state": null,
				"status": 1,
				"timezone": "Romance Standard Time",
				"activeDomains": 2,
				"domains": [{
						"cnames": null,
						"creationAgentId": "toplv-sbsm-pugs",
						"creationDate": "2020-05-18",
						"difm": 2,
						"domain": "",
                        "domainID": "abc",
						"ecwidStoreID": null,
						"status": 1,
						"swWpPluginUrl": "https://sbsapi.com/topline/users/joegar2020/sw/wp-plugin/3d7c99",
						"domainID": "joegar2020",
						"activeSubs": 0,
						"activeTrials": 0,
						"searchCoupons": 0,
						"subs": []
					},
					{
						"cnames": null,
						"creationAgentId": "toplv-sbsm-pugs",
						"creationDate": "2020-07-30",
						"difm": 1,
						"domain": "joegar2020-nc-4.sbudomain.com",
                        "domainID": "def",
						"ecwidStoreID": null,
						"status": 1,
						"swWpPluginUrl": "https://sbsapi.com/topline/users/joegar2020-nc-4/sw/wp-plugin/05e19dd",
						"domainID": "joegar2020-nc-4",
						"activeSubs": 3,
						"activeTrials": 0,
						"searchCoupons": 0,
						"subs": [{
							"originalSubID": "s667800",
							"planID": "yola_prem",
							"delayedPlanID": null,
							"delayedQuantity": null,
							"productID": "",
							"productID3": "02.00.50",
							"status": 1,
							"term": "P1M",
							"quantity": "1",
							"path": "https://sbsapi.com/topline/users/joegar2020-nc-4/subscriptions/667800",
							"hostPlan": null,
							"hostSubID": null,
							"couponCode": null,
							"ID": 667800,
							"startDate": "2020-07-30 20:25:26",
							"expiryDate": "2020-08-30 20:25:26"
						}]
					}
				]
			},
			{
				"accountID": "jill2019",
				"address1": null,
				"address2": null,
				"brandID": "topline",
				"brandShortName": "Topline",
				"businessCategory": null,
				"city": null,
				"countryCode": "CAN",
				"creationDate": "2020-05-18",
				"currency": "CDN",
				"host1": null,
				"host2": null,
				"host3": null,
				"isNFR": 0,
				"language": "en",
				"name": "Jean 2018",
				"phone": null,
				"postcode": null,
				"registration": null,
				"state": null,
				"status": 1,
				"timezone": "Romance Standard Time",
				"activeDomains": 2,
				"domains": [{
						"cnames": null,
						"creationAgentId": "toplv-sbsm-pugs",
						"creationDate": "2020-05-18",
						"difm": 0,
						"domain": "",
                        "domainID": "ghi",
						"ecwidStoreID": null,
						"status": 1,
						"swWpPluginUrl": "https://sbsapi.com/topline/users/jeanr18/sw/wp-plugin/d041c9fd0",
						"domainID": "jill2019",
						"activeSubs": 0,
						"activeTrials": 0,
						"searchCoupons": 0,
						"subs": []
					},
					{
						"cnames": null,
						"creationAgentId": "SBS Store V1.0",
						"creationDate": "2020-05-18",
						"difm": 0,
						"domain": "jill2019-nc5.subdomain.com",
                        "domainID": "jkl",
						"ecwidStoreID": null,
						"status": 1,
						"swWpPluginUrl": "https://sbsapi.com/topline/users/jill2019-nc5/sw/wp-plugin/9386719",
						"domainID": "jill2019-nc5",
						"activeSubs": 0,
						"activeTrials": 0,
						"searchCoupons": 0,
						"subs": [{
							"originalSubID": "s667358",
							"planID": "yola_prem",
							"delayedPlanID": null,
							"delayedQuantity": null,
							"productID": "",
							"productID3": "02.00.80",
							"status": 5,
							"term": "P1M",
							"quantity": "1",
							"path": "https://sbsapi.com/topline/users/jill2019-nc5/subscriptions/667358",
							"hostPlan": null,
							"hostSubID": null,
							"couponCode": null,
							"ID": 667358,
							"startDate": "2020-05-18 15:22:06",
							"expiryDate": "2020-08-18 15:22:06"
						}]
					}
				]
			}
		]
	},
	"code": 200,
	"ref": 4674596
}

Edit Account

To edit an Account's details. Only fields that are sent will be updated. Any subset of the fields listed in the Create Account table above can be specified.

Input Fields

Field name Description
all Same fields as Create. Except accountID cannot be edited, and currency cannot be changed if it has already been set. None are required.
newAccountID This value will be assigned to the Account's accountID. Thereafter, the previous accountID will no longer be available to access the account.

Endpoint

PUT
/{brandID}/account/{accountID}

Success Status

HTTP 201

Header

Location: https://sbsapi.com/acme/accounts/test_account

Response

{
  "detail": {
    "accountID": "test_account",
    "url": "https://sbsapi.com/acme/accounts/test_account",
  },
  "code": 201,
  "status": "Created",
  "ref": 539
}

Delete Account

To delete a specific Account. Will delete Domains and their subs, and Persons.

Endpoint

DELETE
/{brandID}/accounts/{accountID}

Success Status

HTTP 204

Response

{}

Account State Changes

Suspend Account

Will suspend the account, all domains (users) and subscriptions, and persons under that account.

Endpoint

PUT
/{brandID}/accounts/{accountID}/suspend

Success Status

HTTP 201

Response

{
    "detail": {
        "accountID": "joegar2020",
        "url": "https://sbsapi.com/topline/accounts/joegar2020",
        "newAccountStatus": 3
    },
    "code": 201,
    "extra_headers": [
        "Location: https://sbsapi.com/topline/accounts/joegar2020"
    ],
    "status": "Created",
    "ref": 4674324
}

Reactivate Account

Will reactivate the account, all domains (users) and subscriptions, and persons under that account.

Endpoint

PUT
/{brandID}/accounts/{accountID}/reactivate

Success Status

HTTP 201

Response

{
    "detail": {
        "accountID": "joegar2020",
        "url": "https://sbsapi.com/topline/accounts/joegar2020",
        "newAccountStatus": 1
    },
    "code": 201,
    "extra_headers": [
        "Location: https://sbsapi.com/topline/accounts/joegar2020"
    ],
    "status": "Created",
    "ref": 4674341
}

Undelete Account

This will change the account's status to active; all its domains (users) will also become active, and all their subscriptions will be undeleted into a suspended status; and all deleted persons will be changed to an active status. You may then reactivate the subscriptions of interest as needed.

Endpoint

PUT
/{brandID}/accounts/{accountID}/undelete

Success Status

HTTP 200

Response

{
    "message": "OK: undeleteAccount",
    "code": 200,
    "status": "OK",
    "ref": 4674393
}

Persons

A Person is an administrative entity that has login capabilities to an account. There can be multiple Persons per Account.

Note: person1 is automatically created if email is included in Account creation.

These endpoints are used to interact with Persons for your brand.

Create Person

To add a Person to an Account.

Endpoint

POST
/{brandID}/accounts/{accountID}/persons

Input Fields

Field Vendor Required Vendor Recommended Description
consentToContact GDPR consent has been granted.
email API Not shared externally.
emailConfirmed The email has been confirmed.
firstName
language If not sent this will be inherited from the brand setting. See Appendix for supported values.
lastName
password Access to Account.
personID
phone
role 1 = Admin (with purchase rights)
2 = User (SSO only)
status 1 = Active (default on create)
3 = Suspended

Success Status

HTTP 201

Response

{
    "detail": {
        "personId": "xo-8670ebb42c07",
        "url": "https://api.local/top__pr/accounts/xo-8670ebb42c07/persons/xo-8670ebb42c07"
    },
    "code": 201,
    "extra_headers": [
        "Location: https://api.local/top__pr/accounts/xo-8670ebb42c07/persons/xo-8670ebb42c07"
    ],
    "status": "Created",
    "ref": 4573
}

View Person

To retrieve the details about a specific Person.

Endpoint

GET
/{brandID}/accounts/{accountID}/persons/{personID}

Success Status

HTTP 200

Response

{
    "detail": {
        "creationDate": "2021-07-09",
        "consentToContact": 1,
        "email": "mario@bobo.com",
        "firstName": "Mario",
        "language": "en",
        "lastName": "Supra",
        "personID": "z-d9ad2affc171-1",
        "phone": null,
        "role": 1,
        "status": 1,
        "accountID": "z-d9ad2affc171"
    },
    "code": 200,
    "extra_headers": [
        "Location: https://api.local/top__pr/accounts/z-d9ad2affc171/persons/z-d9ad2affc171-1"
    ],
    "status": "OK",
    "ref": 19523
}

List Persons

To retrieve a listing of all Persons under the specific Account.

Endpoint

GET
/{brandID}/accounts/{accountID}/persons

Success Status

HTTP 200

Response

{
    "detail": {
        "count": 3,
        "persons": [
            {
                "creationDate": "2021-07-09",
                "consentToContact": 1,
                "email": "monkey@bobo.com",
                "firstName": "Simon",
                "language": "en",
                "lastName": "Gibbons",
                "personID": "z-d9ad2affc171",
                "phone": null,
                "role": 1,
                "status": 1
            },
            {
                "creationDate": "2021-07-09",
                "consentToContact": 1,
                "email": "mario@bobo.com",
                "firstName": "Mario",
                "language": "en",
                "lastName": "Supra",
                "personID": "z-d9ad2affc171-1",
                "phone": null,
                "role": 1,
                "status": 1
            },
            {
                "creationDate": "2021-07-09",
                "consentToContact": 1,
                "email": "maria@bobo.com",
                "firstName": "Maria",
                "language": "es",
                "lastName": null,
                "personID": "z-d9ad2affc171-2",
                "phone": null,
                "role": 2,
                "status": 1
            }
        ]
    },
    "code": 200,
    "status": "OK",
    "ref": 2045
}

Edit Person

To edit an Person details. Only fields that are sent will be updated. Any subset of the fields listed in the Create Person table above can be specified.

Input Fields

Field name Description
all Same fields as Create. Except personID cannot be edited. None are required.

Endpoint

PUT
/{brandID}/accounts/{accountID}/persons/@personID

Success Status

HTTP 201

Response

{
    "detail": {
        "message": "OK: editPerson",
        "personID": "xo-8670ebb42c07",
        "url": "https://api.local/top__pr/accounts/xo-8670ebb42c07/persons/xo-8670ebb42c07"
    },
    "code": 201,
    "extra_headers": [
        "Location: https://api.local/top__pr/accounts/xo-8670ebb42c07/persons/xo-8670ebb42c07"
    ],
    "status": "Created",
    "ref": 12347
}

Delete Person

To delete a specific Person.

Endpoint

DELETE
/{brandID}/accounts/{accountID}/persons/{personID}

Success Status

HTTP 204

Response

{}

Person State Changes

Suspend Person

Will suspend the Person.

Endpoint

PUT
/{brandID}/accounts/{accountID}/persons/{personID}/suspend

Success Status

HTTP 201

Response

{
    "detail": {
        "personID": "xo-8670ebb42c07",
        "url": "https://api.local/top__pr/accounts/xo-8670ebb42c07/persons/xo-8670ebb42c07",
        "newPersonStatus": 3
    },
    "code": 201,
    "extra_headers": [
        "Location: https://api.local/top__pr/accounts/xo-8670ebb42c07/persons/xo-8670ebb42c07"
    ],
    "status": "Created",
    "ref": 1463
}

Reactivate Person

Will reactivate the Person.

Endpoint

PUT
/{brandID}/accounts/{accountID}/persons/{personID}/reactivate

Success Status

HTTP 201

Response

{
    "detail": {
        "personID": "xo-8670ebb42c07",
        "url": "https://api.local/top__pr/accounts/xo-8670ebb42c07/persons/xo-8670ebb42c07",
        "newPersonStatus": 1
    },
    "code": 201,
    "extra_headers": [
        "Location: https://api.local/top__pr/accounts/xo-8670ebb42c07/persons/xo-8670ebb42c07"
    ],
    "status": "Created",
    "ref": 1465
}

Domains

Domains are the same SBS entity as Users. Whether you conceive of this containership: Partner has Accounts, which have Domains (which have Subscriptions), or this containership: Partner has Users (which have Subscriptions), Domains and Users are the same object. This section focuses on Domain-oriented endpoints.

domainID must be unique per Brand because it is a userID.

When these Domain endpoints return Subscription endpoints, they do so as "user" endpoints, as follows: {partnerID}/users/{domainID}/subscriptions/{subID}.

Create Domain

To add a new Domain to an Account.

Endpoint

POST
/{brandID}/accounts/{accountID}/domains

Input Fields

Field Vendor Required Vendor Recommended Description
domain Yola Kliken Can be sub domain, domain, or sub-folder (not supported for YOLA hosted). Required to add Yola or Kliken subs to User.
domainID API domainID, must be unique within the Brand. domainID can be 2-50 characters, must start and end with an alphanumeric but can contain "-" "_" or "." (hyphen, underscore, period)
ftpAddress Yola The FTP server (FTP settings are only required if the Brand is configured to use FTP self-hosting for Yola Sitebuilder)
ftpPassword Yola The FTP password (FTP settings are only required if the Brand is configured to use FTP self-hosting for Yola Sitebuilder)
ftpPort Yola Integer. The default port is 21. Allowable range [ 0, 65535] (FTP settings are only required if the Brand is configured to use FTP self-hosting for Yola Sitebuilder)
ftpProtocol Yola 1 = FTP (default)
2 = FTPS Explicit
3 = FTPS Explicit and verified (FTP settings are only required if the Brand is configured to use FTP self-hosting for Yola Sitebuilder)
ftpUserid Yola The FTP userID (FTP settings are only required if the Brand is configured to use FTP self-hosting for Yola Sitebuilder)
ftpWwwroot Yola Should be blank if web root = ftp root (FTP settings are only required if the Brand is configured to use FTP self-hosting for Yola Sitebuilder)
status 1 = Active (default on create)
3 = Suspended
yolaMode latitude = Yola Sitebuilder will be Latitude
legacy = Yola Sitebuilder will be legacy type
Overrides the brand default for this user. This determines which type of Yola Sitebuilder will be provisioned for this user (Only send this property to override the brand's default Yola Sitebuilder mode. YolaMode cannot be changed once a Yola sub has been created)

Success Status

HTTP 201

Header

Location: https://sbsapi.com/{brandID}/accounts/123-456-798/domains/dom-4b75d933c2968ff8

Response

{
"detail": {
    "domain": "test.domain",
    "domainID": "dom-4b75d933c2968ff8",
    "url": "https://sbsapi.com/acme/accounts/123-456-798/domains/dom-4b75d933c2968ff8",
  },
  "code": 201,
  "status": "Created",
  "ref": 539
}

Note: the url property leads to the View User endpoint.

Example Request

{
    "domain": "test.domain",
}

View Domain

To retrieve the details about a specific domain.

Note that {domainID} is the same as {userID}.

Endpoint

GET
/{brandID}/accounts/{accountID}/domains/{domainID}

Query String Arguments

Field Default Description
extras None Optional. Comma-separated list of additional information types. The following are valid:

actions : [note: performance cost] If subs was requested, then each sub in the list also has a allowedActions array of these possible values: changePlan, delete, reactivate, renew, suspend. This is intended to better inform the user interface.

campaigns : a campaigns list is added to the user, showing all campaigns ever associated with the user.

subs : a subs list is added to the user, showing all subscriptions ever associated with the user.
lang en Optional. For those values, like SKU texts, that may be internationalized by the brand, this argument controls the language served. If the individual value was not customized for the requested language, the default (en) value is served.

Some Values Explained

Some of the values returned are computed by SBS, cannot be added to the user by the Create or Edit request, so are described here and not in that table.

Property Explained
cnames A JSON object with a single property named after the domain, and an array value, containing the pair to compose a DNS CNAME.
e.g.:
{
    "domain.com": [
        "domain.com",
        "sitebuilderhostsite.net"
    ]
}           

Success Status

HTTP 200

Response Yola or Ecwid Domain

{
    "detail": {
        "accountID": "domainco",
        "activeSubs": 1,
        "activeTrials": 0,
        "brandID": "acme",
        "brandShortName": "Acme",
        "cnames": {
            "test-user.com": [
                "test-user.com", "sitebuilderhostsite.net"
            ]
        },
        "country": "Canada",
        "countryCode": "CA",
        "creationDate": "2017-09-07",
        "difm": 0,
        "domain": "test-user.com",
        "domainID": "test_user",
        "ecwidStoreID": '26883004',
        "email": "",
        "ftpAddress": "",
        "ftpPort": 21,
        "ftpProtocol": 1,
        "ftpUserid": "",
        "ftpWwwroot": "",
        "host1": "",
        "host2": "",
        "host3": "",
        "isNFR": 0,
        "searchCoupons": 0,
        "status": 1,
        "subs": [
            {
                "ID": "249096",
                "status": 5,
                "productID": "2.31.0.0",
                "productID3": "02.00.31",
                "planID": "yola_prem",
                "startDate": "2017-01-02 21:00:32",
                "expiryDate": "2017-05-02 21:00:32",
                "skuGuid": "4dd2bdd0f714257d432c898da38884a5",
                "skuVendor": "yola",
                "skuVendorSkuId": "WL_PREMIUM",
                "skuShortname": "Yola Premium",
                "skuName": "Yola Premium"
            },
            {
                "ID": "250217",
                "status": 1,
                "productID": "2.31.0.0",
                "productID3": "02.00.31",
                "planID": "yola_prem",
                "startDate": "2018-01-13 20:26:15",
                "expiryDate": "2018-04-13 20:26:15",
                "skuGuid": "4dd2bdd0f714257d432c898da38884a5",
                "skuVendor": "yola",
                "skuVendorSkuId": "WL_PREMIUM",
                "skuShortname": "Yola Premium",
                "skuName": "Yola Premium"
            }
        ],
        "timezone": "Eastern Standard Time",
        "yolaMode": "latitude",
        "storeSnippet": "<div id=\"my-store-26883004\"></div><div><script data-cfasync=\"false\" type=\"text/javascript\" src=\"https://app.ecwid.com/script.js?26883004&data_platform=code\" charset=\"utf-8\"></script><script type=\"text/javascript\"> xProductBrowser(\"id=my-store-26883004\", \"defaultCategoryId=0\");</script></div>"
        },
    "code": 200,
    "status": "OK",
    "ref": 541
}

Response Kliken Domain

A Kliken user response will include the Javascript tracking code snippet that can be inserted into the user’s web site.

{
    "detail": {
        "accountID": "domainca`",
        "activeSubs": 2,
        "activeTrials": 0,
        "brandID": "acme`",
        "brandShortName": "Acme",
        "cnames": null,
        "country": "Canada",
        "countryCode": "CA",
        "creationDate": "2017-02-16",
        "difm": 0,
        "domain": "test_user.com",
        "domainID": "test_user"
        "ftpAddress": "",
        "ftpPort": 21,
        "ftpProtocol": 1,
        "ftpUserid": "",
        "ftpWwwroot": "",
        "host1": "",
        "host2": "",
        "host3": "",
        "isNFR": 0,
        "jsAnalytics": "<script type=\"text/javascript\">\r\nvar _swaMa =[\"173758944\",\"2493a325-2b52-3119-4694-2e4a7bbf4052\"];\"undefined\"==typeof sw&&!function(e, s, a){function t(){for(;o[0]&&\"loaded\"==o[0][d];)i=o.shift(),i[w]=!c.parentNode.insertBefore(i,c)}for(var r,n,i,o=[],c=e.scripts[0],w=\"onreadystatechange\",d=\"readyState\";r=a.shift();)n=e.createElement(s),\"async\"in c?(n.async=!1,e.head.appendChild(n)):c[d]?(o.push(n), n[w]=t): e.write(\"<\" + s +' src=\"'+r+'\" defer></'+s+\">\"),n.src=r}(document,\"script\",[\"//analytics.sitewit.com/v3/\"+_swaMa[0]+\"/sw.js\"]);\r\n</script>\r\n",
        "language": "EN",
        "phone": "",
        "searchCoupons": 1,
        "status": 1,
        "subs": [
            {
                "ID": "180309",
                "status": 1,
                "productID": "",
                "productID3": "03.00.10",
                "planID": "sw_stats",
                "startDate": "2017-02-16 23:42:44",
                "expiryDate": "2018-03-16 23:42:44",
                "skuGuid": "47da2626c3285821f45447b1d2625720",
                "skuVendor": "sw",
                "skuVendorSkuId": "",
                "skuShortname": "Stats",
                "skuName": "Kliken Stats"
            },
            {
                "ID": "250307",
                "status": 1,
                "productID": "",
                "productID3": "03.02.20",
                "planID": "sw_sem_starter",
                "startDate": "2017-03-17 12:41:44",
                "expiryDate": "2018-03-17 12:41:44",
                "skuGuid": "928d3cef41b3c6078284ec058462787d",
                "skuVendor": "sw",
                "skuVendorSkuId": "search",
                "skuShortname": "SEM Starter",
                "skuName": "Kliken SEM Starter"
            }
        ],
        "swAccountNumber": 173758944,
        "swWpPluginUrl": "https://sbsapi.com/BRAND_ID/accounts/{accountID}/domains/{domainID}/sw/wp-plugin/HASH",
        "timezone": "Eastern Standard Time",
    },
    "code": 200,
    "status": "OK",
    "ref": 9686175
}

Edit Domain

To edit a Domain's details. Only fields that are sent will be updated. Any subset of the fields listed in the Create Domain table above can be specified.

Input Fields

Field name Description
all Same fields as Create. Except domainID cannot be edited, and currency cannot be changed if it has already been set. None are required.
newUserID This value will be assigned to the user's userID. Thereafter, the previous userID will no longer be available to access the user.

Note that {domainID} is the same as {userID}.

Endpoint

PUT
/{brandID}/accounts/{accountID}/domains/{domainID}

Success Status

HTTP 201

Header

Location: https://sbsapi.com/{brandID}/accounts/{accountID}/domains/{domainID}

Response

{
      "detail": {
        "domainID": "jeanr18_1",
        "url": "https://sandbox.sbsapi.com/acme/accounts/joegar2020/domains/joegar2020-nc1",
        "message": "OK: editDomain (nothing to do)"
    },
    "code": 201,
    "extra_headers": [
        "Location: https://sandbox.sbsapi.com/acme/accounts/joegar2020/domains/joegar2020-nc1"
    ],
    "status": "Created",
    "ref": 4677733
}

Delete Domain

To delete a specific domain (user). All subscriptions will be deleted.

Endpoint

DELETE
/{brandID}/accounts/{accountID}/domains/{domainID}

Success Status

HTTP 204

Response

{}

Domain CNAME

See User Cname section.

Domain State Changes

Suspend Domain

Will suspend the domain (user) and all subscriptions under that domain. Response lists all affected subs with URLs to view.

Endpoint

PUT
/{brandID}/account/{accountID}/domains/{domainID}/suspend

Success Status

HTTP 201

Response

{
    "detail": {
        "domainID": "{domainID}",
        "url": "https://sbsapi.com/{brandID}/accounts/{accountID}/domains/{domainID}",
        "newDomainStatus": 3,
        "message": "2 subscriptions were suspended",
        "subscriptions": {
            "02.00.10": "https://sbsapi.com/{brandID}/users/{domainID}/subscriptions/{subID}",
            "02.01.20": "https://sbsapi.com/{brandID}/users/{domainID}/subscriptions/{subID}"
        }
    },
    "code": 201,
    "status": "Created",
    "ref": 85732
}

Reactivate Domain

Will make the domain (user) Active again but leave all subscriptions suspended. Response lists all remaining suspended subs with URLs to reactivate them.

Endpoint

PUT
/{brandID}/accounts/{accountID}/domains/{domainID}/reactivate

Success Status

HTTP 201

Response

{
    "detail": {
        "domainID": "{domainID}",
        "url": "https://sbsapi.com/{brandID}/accounts/{accountID}/domains/{domainID}",
        "newDomainStatus": 1,
        "message": "1 subscription may be reactivated",
        "subscriptions": {
            "02.00.10": "https://sbsapi.com/{brandID}/users/{domainID}/subscriptions/{subID}/reactivate"
        }
    },
    "code": 201,
    "status": "Created",
    "ref": 85728
}

Reactivate Domain + Subs

To make the domain (user) Active again and also return all subscriptions to their previous state. Response lists all affected subs with URLs to view them. Note that subs that were previously in status "non-renew" and expired while under suspension will not be restored.

Note: This function will trigger a repurchase of suspended subscriptions as required to make all subs Active.

Endpoint

PUT
/{brandID}/accounts/{accountID}/domains/{domainID}/reactivate-all

Success Status

HTTP 201

Response

{
    "detail": {
        "domainID": "{domainID}",
        "url": "https://sbsapi.com/{brandID}/accounts/{accountID}/domains/{domainID}",
        "newDomainStatus": 1,
        "message": "2 subscriptions were reactivated",
        "subscriptions": {
            "02.00.10": "https://sbsapi.com/{brandID}/users/{domainID}/subscriptions/{subID}",
            "02.01.20": "https://sbsapi.com/{brandID}/users/{domainID}/subscriptions/{subID}"
        }
    },
    "code": 201,
    "status": "Created",
    "ref": 86328
}

Users

These endpoints are used to interact with End Users in your account.

Create User

To add a new User to a Brand.

Endpoint

POST
/{brandID}/users

Input Fields

Field Vendor Required Vendor Recommended Description
accountId Account identifier to marry multiple SBS userIDs (domains) to a single billable customer
address1 Business first address line
address2 Business second address line
businessCategory Business Category for this account or Google business category
city Business city
companyName Common name for this company for display
companyRegistration Company's Government registration number or ID
consentToContact has the user consented to be contacted (GDPR)
country deprecated, use countryCode
countryCode If not sent this will be inherited from the partner setting. Accepts 2 character country code. See Appendix for supported values.
currency Currency can be set during create, or can be changed via edit as long as there are no subs already using the currency.
Currency can be left blank and it will be set once and for all automatically when a subscription involving currency is requested.
Once currency is set and a subscription exists that locks it for the user, it cannot be be changed ever again.
See Appendix for supported values.
domain Yola Kliken Can be sub domain, domain, or sub-folder (not supported for YOLA hosted). Required to add Yola or Kliken subs to User.
email Ecwid Yola Recommended for default value in Sitebuilder forms. Required for Ecwid for Store owner notifications (new sale etc.). Not shared externally.
firstName Yola End user first name. Used in default site content.
ftpAddress Yola The FTP server (FTP settings are only required if the Brand is configured to use FTP self-hosting for Yola Sitebuilder)
ftpPassword Yola The FTP password (FTP settings are only required if the Brand is configured to use FTP self-hosting for Yola Sitebuilder)
ftpPort Yola Integer. The default port is 21. Allowable range [ 0, 65535] (FTP settings are only required if the Brand is configured to use FTP self-hosting for Yola Sitebuilder)
ftpProtocol Yola 1 = FTP (default)
2 = FTPS Explicit
3 = FTPS Explicit and verified (FTP settings are only required if the Brand is configured to use FTP self-hosting for Yola Sitebuilder)
ftpUserid Yola The FTP userID (FTP settings are only required if the Brand is configured to use FTP self-hosting for Yola Sitebuilder)
ftpWwwroot Yola Should be blank if web root = ftp root (FTP settings are only required if the Brand is configured to use FTP self-hosting for Yola Sitebuilder)
host1
host2
host3
These fields can be used to store your information about this user and have it appended to upgrade / signup urls. E.g.: your internal userID. Up to 255 chars each
$user == $account
isNFR 1 = Any subscriptions added to this user will be NFR and count against total allotted.
kaToken deprecated
language If not sent this will be inherited from the partner setting. See Appendix for supported values.
lastName Yola End user last name. Used in default site content.
password Only required for manual SBSgateway logins. Not needed for SSO logins.
phone Yola End user mobile phone number. Used in default site content for Yola. Used for SMS alerts for Kliken.
pleskServerID deprecated
postcode Business postal code.
state Business state/province.
status 1 = Active (default on create)
3 = Suspended
timezone If not sent this will be inherited from the partner setting. Supports recognized time zone names. See Appendix for supported values.
userID API End userID, must be unique within the Brand. UserID can be 2-50 characters, must start and end with an alphanumeric but can contain "-" "_" or "." (hyphen, underscore, period)
yolaMode latitude = Yola Sitebuilder will be Latitude
legacy = Yola Sitebuilder will be legacy type
Overrides the brand default for this user. This determines which type of Yola Sitebuilder will be provisioned for this user (Only send this property to override the brand's default Yola Sitebuilder mode. YolaMode cannot be changed once a Yola sub has been created)

Success Status

HTTP 201

Header

Location: https://sbsapi.com/{brandID}/users/test_user

Response

{
"detail": {
    "userID": "test_user",
    "url": "https://sbsapi.com/acme/users/test_user",
    "swWpPluginUrl": "https://sbsapi.com/acme/users/test_user/sw/wp-plugin/HASH"
  },
  "code": 201,
  "status": "Created",
  "ref": 539
}

Note: the url property leads to the View User endpoint.

Example Request

{
    "userID": "test_user",
    "domain": "http://myuserdomain.com",
    "email" : "test@mybrand.com"
}

Sample Create User PHP Code

<?php
### CREATE USER EXAMPLE
$authKey = '';   // see authKey download for instructions
$httpVerb = 'POST';
$contentType = 'application/json;charset=utf-8';
$postData = [
    "firstName" => "Bob",
    "lastName" => "Loblaw",
    "email" => "bob@loblaw.com",
    "userID" => "tester25",
    "domain"=>"userdomain.com"
];
$postContent = json_encode($postData);
$expiry = '';    // see authKey download for instructions
$signature = ''; // see authKey download for instructions
$url = 'https://sandbox.sbsapi.com/<your brand>/users/';
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $httpVerb);
curl_setopt($ch, CURLOPT_VERBOSE, true);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postContent);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, "40");
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'SBS-Expires: '.$expiry,
    'SBS-Signature: '.$signature,
    'SBS-AgentID: MyAgentv1.0',
    'Content-Type: '.$contentType,
    'Content-Length: ' . strlen($postContent)
));
$result=curl_exec($ch);
curl_close($ch);
echo $result;
?>

View User

To retrieve the details about a specific user.

Endpoint

GET
/{brandID}/users/{userID}

Query String Arguments

Field Default Description
extras None Optional. Comma-separated list of additional information types. The following are valid:

actions : [note: performance cost] If subs was requested, then each sub in the list also has a allowedActions array of these possible values: changePlan, delete, reactivate, renew, suspend. This is intended to better inform the user interface.

campaigns : a campaigns list is added to the user, showing all campaigns ever associated with the user.

subs : a subs list is added to the user, showing all subscriptions ever associated with the user.

stats : a stats node is added for the user, containing one node per vendor associated with this user via a subscription. The possible properties per vendor, where applicable, are: lastQa, lastSso, totalSso, lastPublish, totalPublished, lastSslSetup.
lang en Optional. For those values, like SKU texts, that may be internationalized by the brand, this argument controls the language served. If the individual value was not customized for the requested language, the default (en) value is served.

Some Values Explained

Some of the values returned are computed by SBS, cannot be added to the user by the Create or Edit request, so are described here and not in that table.

Property Explained
cnames A JSON object with a single property named after the domain, and an array value, containing the pair to compose a DNS CNAME.
e.g.:
{
    "domain.com": [
        "domain.com",
        "sitebuilderhostsite.net"
    ]
}           

Success Status

HTTP 200

Response Yola or Ecwid User

An Ecwid-direct user response will include the storeSnippet HTML that can be inserted into the user’s web site.

{
    "detail": {
        "accountID": "domainco",
        "activeSubs": 1,
        "activeTrials": 0,
        "brandID": "acme",
        "brandShortName": "Acme",
        "cnames": {
            "test-user.com": [
                "test-user.com", "sitebuilderhostsite.net"
            ]
        },
        "country": "Canada",
        "countryCode": "CA",
        "creationDate": "2019-01-07",
        "currency": "CAD",
        "difm": 0,
        "domain": "test-user.com",
        "ecwidStoreID": '26883004',
        "email": "",
        "firstName": null,
        "ftpAddress": "",
        "ftpPort": 21,
        "ftpProtocol": 1,
        "ftpUserid": "",
        "ftpWwwroot": "",
        "host1": "",
        "host2": "",
        "host3": "",
        "isNFR": 0,
        "language": "EN",
        "lastName": "",
        "phone": "",
        "searchCoupons": 0,
        "status": 1,
        "stats":{
            "vendors": {
                "Yola": {
                    "lastQa": "1",
                    "lastSso": "2020-10-14 23:33:45",
                    "totalSso": "4",
                    "lastPublish": "2020-10-14 22:55:56",
                    "totalPublish": "1",
                    "lastSslSetup": "0",
                },
            },
        },
        "subs": [
            {
                "ID": "249096",
                "status": 5,
                "productID": "2.31.0.0",
                "productID3": "02.00.31",
                "planID": "yola_prem",
                "startDate": "2017-01-02 21:00:32",
                "expiryDate": "2017-05-02 21:00:32",
                "skuGuid": "4dd2bdd0f714257d432c898da38884a5",
                "skuVendor": "yola",
                "skuVendorSkuId": "WL_PREMIUM",
                "skuShortname": "Yola Premium",
                "skuName": "Yola Premium"
            },
            {
                "ID": "250217",
                "status": 1,
                "productID": "2.31.0.0",
                "productID3": "02.00.31",
                "planID": "yola_prem",
                "startDate": "2018-01-13 20:26:15",
                "expiryDate": "2018-04-13 20:26:15",
                "skuGuid": "4dd2bdd0f714257d432c898da38884a5",
                "skuVendor": "yola",
                "skuVendorSkuId": "WL_PREMIUM",
                "skuShortname": "Yola Premium",
                "skuName": "Yola Premium"
            }
        ],
        "timezone": "Eastern Standard Time",
        "userID": "test_user",
        "yolaMode": "latitude",
        "storeSnippet": "<div id=\"my-store-26883004\"></div><div><script data-cfasync=\"false\" type=\"text/javascript\" src=\"https://app.ecwid.com/script.js?26883004&data_platform=code\" charset=\"utf-8\"></script><script type=\"text/javascript\"> xProductBrowser(\"id=my-store-26883004\", \"defaultCategoryId=0\");</script></div>"
        },
    "code": 200,
    "status": "OK",
    "ref": 541
}

Response Kliken User

A Kliken user response will include the Javascript tracking code snippet that can be inserted into the user’s web site.

{
    "detail": {
        "accountID": "domainca`",
        "activeSubs": 2,
        "activeTrials": 0,
        "brandID": "acme`",
        "brandShortName": "Acme",
        "cnames": null,
        "country": "Canada",
        "countryCode": "CA",
        "creationDate": "2017-02-16",
        "currency": null,
        "difm": 0,
        "domain": "test_user.com",
        "email": "",
        "firstName": null,
        "ftpAddress": "",
        "ftpPort": 21,
        "ftpProtocol": 1,
        "ftpUserid": "",
        "ftpWwwroot": "",
        "host1": "",
        "host2": "",
        "host3": "",
        "isNFR": 0,
        "jsAnalytics": "<script type=\"text/javascript\">\r\nvar _swaMa =[\"173758944\",\"2493a325-2b52-3119-4694-2e4a7bbf4052\"];\"undefined\"==typeof sw&&!function(e, s, a){function t(){for(;o[0]&&\"loaded\"==o[0][d];)i=o.shift(),i[w]=!c.parentNode.insertBefore(i,c)}for(var r,n,i,o=[],c=e.scripts[0],w=\"onreadystatechange\",d=\"readyState\";r=a.shift();)n=e.createElement(s),\"async\"in c?(n.async=!1,e.head.appendChild(n)):c[d]?(o.push(n), n[w]=t): e.write(\"<\" + s +' src=\"'+r+'\" defer></'+s+\">\"),n.src=r}(document,\"script\",[\"//analytics.sitewit.com/v3/\"+_swaMa[0]+\"/sw.js\"]);\r\n</script>\r\n",
        "language": "EN",
        "lastName": "",
        "phone": "",
        "searchCoupons": 1,
        "status": 1,
        "stats":{
            "vendors": {
                "SiteWit": {
                    "lastQa": "1",
                    "lastSso": "2020-11-22 23:33:45",
                    "totalSso": "4",
                },
            },
        },
        "subs": [
            {
                "ID": "180309",
                "status": 1,
                "productID": "",
                "productID3": "03.00.10",
                "planID": "sw_stats",
                "startDate": "2017-02-16 23:42:44",
                "expiryDate": "2018-03-16 23:42:44",
                "skuGuid": "47da2626c3285821f45447b1d2625720",
                "skuVendor": "sw",
                "skuVendorSkuId": "",
                "skuShortname": "Stats",
                "skuName": "Kliken Stats"
            },
            {
                "ID": "250307",
                "status": 1,
                "productID": "",
                "productID3": "03.02.20",
                "planID": "sw_sem_starter",
                "startDate": "2017-03-17 12:41:44",
                "expiryDate": "2018-03-17 12:41:44",
                "skuGuid": "928d3cef41b3c6078284ec058462787d",
                "skuVendor": "sw",
                "skuVendorSkuId": "search",
                "skuShortname": "SEM Starter",
                "skuName": "Kliken SEM Starter"
            }
        ],
        "swAccountNumber": 173758944,
        "swWpPluginUrl": "https://sbsapi.com/BRAND_ID/users/USER_ID/sw/wp-plugin/HASH",
        "timezone": "Eastern Standard Time",
        "userID": "test_user"
    },
    "code": 200,
    "status": "OK",
    "ref": 9686175
}

List Users

To retrieve a listing of all users under the specific Brand. Can be filtered using query arguments listed.

Endpoint

GET
/{brandID}/users/

Query String Arguments

Field Default Description
accountID No filtering search text for these fields
coupon No filtering One of the following:
none : No trials, only subs without coupons
all : Only subs with a coupon, of any type
search : Only subs with a coupon, of type 'search'

(at this point, `all` is the same as `search`)
difm No filtering A comma-separated list of integers representing the user DIFM setting
domain No filtering search for domain text using LIKE "%DOMAIN%"
domains No filtering A comma-separated list of domains - search matching the exact domain name in the list
email
firstName
lastName
phone
userID
No filtering search text for these fields using LIKE "TEXT%". If more than one is submitted, they must all match to return a user. i.e. an AND operator is applied per user.
extras None Optional. Comma-separated list of additional information types. The following are valid:

actions : [note: performance cost] If subs was requested, then each sub in the list also has a allowedActions array of these possible values: changePlan, delete, reactivate, renew, suspend. This is intended to better inform the user interface.

campaigns : a campaigns list is added to the user, showing all campaigns ever associated with the user.

subs : a subs list is added to the user, showing all subscriptions ever associated with the user.
page 1 page number, 1-based.
host1
host2
host3
No filtering exact value to find in these fields
lang en; no filtering Optional. For those values, like SKU texts, that may be internationalized by the brand, this argument controls the language served. If the individual value was not customized for the requested language, the default (en) value is served.
product No filtering A comma-separated list of planIDs. Only users with trial or subs for products in this collection will be retrieved.
search None search text for any of the following fields for a match using LIKE "%TEXT%". i.e. an OR operator is applied per user. userID, firstName, lastName, domain, email, and phone search can not be used in conjunction with the other filters listed above.
size 20 page size, integer, maximum 50.
sort None any of userID, firstName, lastName, domain, status, difm, partnerID
status No filtering A comma-separated list of integers representing the user status

Success Status

HTTP 200

Response

GET
/{brandID}/users?extras=subs,campaigns&page=3&size=2

Example with extras, requesting page 3, each page of size 2.

{
        "detail": {
        "previous": "https://sbsapi.com/{brandID}/users?page=2&size=2",
        "next": "https://sbsapi.com/{brandID}/users?page=4&size=2",
        "count": 204,
        "users": [{
            "activeSubs": 0,
            "activeTrials": 0,
            "brandID": "acme",
            "brandShortName": "Acme",
            "campaigns": [{
                "campID": 26715,
                "campName": "PHP Programmers For Sale",
                "type": "search",
                "status": "cancelled",
                "subID": "9838",
                "viewSub": "https://sandbox.sbsapi.com/topline/users/test_user/subscriptions/9838",
                "vendor": "sw"
            }, {
                "campID": 26719,
                "campName": "The Voodoo Lounge",
                "type": "display",
                "status": "active",
                "subID": "9839",
                "viewSub": "https://sandbox.sbsapi.com/topline/users/test_user/subscriptions/9839",
                "vendor": "sw"
            }],
            "country": "Canada",
            "countryCode": "CA",
            "currency": null,
            "difm": 0,
            "domain": "test-user-100.com",
            "email": "",
            "firstName": null,
            "ftpAddress": "",
            "ftpPort": 21,
            "ftpProtocol": 1,
            "ftpUserid": "",
            "ftpWwwroot": "",
            "host1": "",
            "host2": "",
            "host3": "",
            "language": "EN",
            "lastName": "",
            "phone": "",
            "searchCoupons": 0,
            "status": 1,
            "subs": [{
                "ID": "9836",
                "status": 1,
                "productID": "2.10.0.0",
                "productID3": "02.00.10",
                "planID": "yola_3pg",
                "startDate": "2018-08-31 16:47:45",
                "expiryDate": "2018-09-30 16:47:45",
                "skuGuid": "utest_yola_3pg_1",
                "skuVendor": "yola",
                "skuVendorSkuId": "WL_LITE",
                "skuShortname": "WBB Starter Syn",
                "skuName": "WBB Starter Syndicated"
            },
            {
                "ID": "9837",
                "status": 1,
                "productID": "",
                "productID3": "03.00.10",
                "planID": "sw_stats",
                "startDate": "2018-08-31 16:47:47",
                "expiryDate": "2118-08-31 16:47:47",
                "skuGuid": "utest_sw_stats_1",
                "skuVendor": "sw",
                "skuVendorSkuId": null,
                "skuShortname": "sw_stats",
                "skuName": "Kliken Stats"
            },
            {
                "ID": "9838",
                "status": 1,
                "productID": "",
                "productID3": "02.04.20",
                "planID": "yola_adm_sem_starter",
                "startDate": "2018-08-31 16:47:50",
                "expiryDate": "2018-09-30 16:47:50",
                "campaignID": "26715",
                "skuGuid": "b33aa7386d3ea57e0982ba3c88b0fc1f_1",
                "skuVendor": "yola",
                "skuVendorSkuId": "wl_advertising_search_starter",
                "skuShortname": "SEM Starter",
                "skuName": "AdManager SEM Starter"
            },
            {
                "ID": "9839",
                "status": 1,
                "productID": "",
                "productID3": "03.01.10",
                "planID": "sw_dis_1",
                "startDate": "2018-08-31 16:47:57",
                "expiryDate": "2018-09-30 16:47:57",
                "campaignID": "26719",
                "skuGuid": "utest_sw_dis_1_1",
                "skuVendor": "sw",
                "skuVendorSkuId": "display",
                "skuShortname": "sw_d1",
                "skuName": "Kliken Display 1"
            }],
            "timezone": "Eastern Standard Time",
            "userID": "test_user_100"
        }, {
            "activeSubs": 0,
            "activeTrials": 0,
            "brandID": "acme",
            "brandShortName": "Acme",
            "campaigns": [],
            "country": "Canada",
            "countryCode": "CA",
            "currency": null,
            "difm": 0,
            "domain": "test-user-101.com",
            "email": "",
            "firstName": null,
            "ftpAddress": "",
            "ftpPort": 21,
            "ftpProtocol": 1,
            "ftpUserid": "",
            "ftpWwwroot": "",
            "host1": "",
            "host2": "",
            "host3": "",
            "language": "EN",
            "lastName": "",
            "phone": "",
            "searchCoupons": 0,
            "status": 1,
            "subs": [],
            "timezone": "Eastern Standard Time",
            "userID": "test_user_101"
        }]
    },
    "code": 200,
    "ref": 545
}

Edit User

To edit a user's details. Only fields that are sent will be updated. Any subset of the fields listed in the Create User table above can be specified.

Input Fields

Field name Description
all Same fields as Create. Except userID cannot be edited, and currency cannot be changed if it has already been set. None are required.
newUserID This value will be assigned to the user's userID. Thereafter, the previous userID will no longer be available to access the user.

Endpoint

PUT
/{brandID}/users/{userID}

Success Status

HTTP 201

Header

Location: https://sbsapi.com/{brandID}/users/test_user

Response

{
  "detail": {
    "message": "dns_update_required_external",
    "data": {
      "registrar": null,
      "a_record": "52.2.192.9",
      "c_record": "sitebuilderhostsite.net."
    }
  },
  "code": 202,
  "status": "Accepted",
  "ref": 14
}

Delete User

To delete a specific user. All subscriptions will be deleted.

Endpoint

DELETE
/{brandID}/users/{userID}

Success Status

HTTP 204

Response

{}

Download User Kliken WP Plugin

To download a plugin already configured for the user, you may use the user.swWpPluginUrl provided in User Create or User View. You may also compose the URL using the following algorithm:

The final URL looks like this: "https://sbsapi.com/{brandID}/users/{userID}/sw/wp-plugin/{HASH}"

You need to request the SECRET used in the hashing function explicitly. See the Authentication section for more information. The endpoint accepts the brand's own SECRET or any of the parent brands' SECRET.

  1. Compose the URL without the protocol;
  2. Create the hash from the URL;
  3. Finish composing the URL.

Pseudo-code

url1 =  "sbsapi.com/" + brand_id + "/users/" + user_id + "/sw/wp-plugin";
hash = md5( url1 + SECRET);
url = "https://" + url1 + "/" + hash;

PHP Example

$interim_url = "sbsapi.com/{$BRAND_ID}/users/{$USER_ID}/sw/wp-plugin";
$hash = md5( $interim_url . $SECRET);
$final_url = "https://{$interim_url}/{$hash}";

User CNAME

When the brand requests SSL for Yola-Hosted users (legacy), or in all cases where the User is Yola-hosted with Latitude, CNAME information is registered at Cloudflare and the CNAME information is stored (and retrievable) in the User record. When this information changes as the User goes through diverse states, our TESS notification system will alert those who subscribed to those events.

The state changes for CNAME and corresponding events are as follows:

Event TESS Subscription
SBS registers domain at Yola SSL Zone Created
User DIFM mode moves out of Preview SSL Activated
User publishes their site Pub Event

SSL Zone Created

This happens when:

  • The first subscription of a Yola core service is purchased for the domain
  • The Yola user's domain changes

When the TESS subscriber is notified of the event, they should retrieve the user information. The following fields are of particular interest:

If there is cname information, it means the domain was successfully registered at Cloudflare (via Yola).

SSL Activated

The user's difm mode moved out of preview and the DNS for the domain should be modified to have the CNAME in the user record. This happens whether the user is switched to DIFM-Live or DIY, it only requires they be switched out of DIFM-Preview.

Pub Event

The user (or DIFM agent) published their site via the Yola app. This happens regardless of mode. However, if their difm mode is not preview, then the partner should ensure the CNAME is in place.

Domain Info

To retrieve information on a domain as it relates to a specific user. Information returned can comment on state, or suitability of the domain for particular application. May display messages with information and directions on how to proceed.

Endpoint

GET
/{brandID}/users/{userID}/domains/{url_encoded_domain}/info

Success Status

HTTP 202

Response

{
    "message": "dns_update_required_external",
    "data": {
        "registrar": "Domain.com",
        "a_record": "52.2.192.9",
        "c_record": "sitebuilderhostsite.net."
    }

}

The message corresponds a row in the i18n translation spreadsheet where the message = name column. If the default_text for that row indicates {tokens} are used in that message, then they will be returned as data.

User State Changes

Suspend User

Will suspend the user and all subscriptions under that user. Response lists all affected subs with URLs to view.

Endpoint

PUT
/{brandID}/users/{userID}/suspend

Success Status

HTTP 201

Response

{
    "detail": {
        "userID": "{userID}",
        "url": "https://sbsapi.com/{brandID}/users/{userID}",
        "newUserStatus": 3,
        "message": "2 subscriptions were suspended",
        "subscriptions": {
            "02.00.10": "https://sbsapi.com/{brandID}/users/{userID}/subscriptions/{subID}",
            "02.01.20": "https://sbsapi.com/{brandID}/users/{userID}/subscriptions/{subID}"
        }
    },
    "code": 201,
    "status": "Created",
    "ref": 85732
}

Reactivate User

Will make the user Active again but leave all subscriptions suspended. Response lists all remaining suspended subs with URLs to reactivate them.

Endpoint

PUT
/{brandID}/users/{userID}/reactivate

Success Status

HTTP 201

Response

{
    "detail": {
        "userID": "{userID}",
        "url": "https://sbsapi.com/{brandID}/users/{userID}",
        "newUserStatus": 1,
        "message": "1 subscription may be reactivated",
        "subscriptions": {
            "02.00.10": "https://sbsapi.com/{brandID}/users/{userID}/subscriptions/{subID}/reactivate"
        }
    },
    "code": 201,
    "status": "Created",
    "ref": 85728
}

Reactivate User + Subs

To make the user Active again and also return all subscriptions to their previous state. Response lists all affected subs with URLs to view them. Note that subs that were previously in status "non-renew" and expired while under suspension will not be restored.

Note: This function will trigger a repurchase of suspended subscriptions as required to make all subs Active.

Endpoint

PUT
/{brandID}/users/{userID}/reactivate-all

Success Status

HTTP 201

Response

{
    "detail": {
        "userID": "{userID}",
        "url": "https://sbsapi.com/{brandID}/users/{userID}",
        "newUserStatus": 1,
        "message": "2 subscriptions were reactivated",
        "subscriptions": {
            "02.00.10": "https://sbsapi.com/{brandID}/users/{userID}/subscriptions/{subID}",
            "02.01.20": "https://sbsapi.com/{brandID}/users/{userID}/subscriptions/{subID}"
        }
    },
    "code": 201,
    "status": "Created",
    "ref": 86328
}

Subscriptions

These endpoints are used to interact with your end user subscriptions.

Create Sub

Add a new subscription to an existing User. If it is an Add-on subscription the sub will assume the status of the Core subscription.

Endpoint

POST
/{brandID}/users/{userid}/subscriptions

Input Fields

Field Required Description
campID Optional For AdManager, to connect an existing marketing campaign to the new subscription.
countryCode Yes / Uberall Required for all Uberall products. Optional otherwise.
couponCode Optional For some AdManager plans, a couponCode can be submitted where applicable. Billing for this subscription will take the value of the coupon into account.
currency Optional For AdManager subscriptions the AdSpend currency must be specified from the currencies available in your Plans. If a user has a currency set from a prior subscription this must be used. Note the user’s currency value is returned in the view user end point and if null can be set to any value available. See Appendix for supported values.
hostPlan Optional Used to relate the retail name or ID of the Partner’s Service Plan to the subscribed service. Provides more context for reports. Max 50 characters.
hostSubID Optional Used to relate the partner's Subscription ID to the subscribed service. Can be used in the /hosted/ endpoints. Max 50 characters.
planID Yes / All Identifies the product plan that the subscription will be created for. See Appendix for information.
quantity Optional A positive integer (including 0), applicable for SKUs which require a quantity, ignored otherwise.
transactionID Optional A string linked to the user action that triggered the purchase in the vendor UI (see Transactions).
  • If the transactionID is not found, the request fails with a 404.
  • If the transactionID does not belong to this brandID and/or userID, the request fails with a 404.
  • If the transaction is already not in a Pending state, there is no consequence.
  • If the transaction is in a Pending state, the vendor is notified and the transaction status is set to Success.

Success Status

HTTP 201

Response

{
  "detail": {
    "subID": "131372",
    "url": "https://sandbox.sbsapi.com/topline/users/test_user/subscriptions/131372"
  },
  "code": 201,
  "status": "Created",
  "ref": 559
}

Note that DIFM products will be created with the sub in "preview" mode. This can be changed via editSub or SBSmanager.

View Sub

To retrieve the details about a specific subscription.

Endpoint

GET
/{brandID}/users/{userID}/subscriptions/{subID}

Query String Arguments

Field Default Description
lang en Optional. For those values, like SKU texts, that may be internationalized by the brand, this argument controls the language served. If the individual value was not customized for the requested language, the default (en) value is served.

Success Status

HTTP 200

Response

{
  "detail": {
    "subID": 131373,
    "originalSubID": "s131373",
    "planID": "yola_prem",
    "productID": "2.0.30.0",
    "productID3": "02.00.30",
    "status": 1,
    "term": "P1M",
    "startDate": 1472243805,
    "expirationDate": 1474922205,
    "path": "https://sandbox.sbsapi.com/topline/users/test_user_/subscriptions/131373",
    "couponCode": "abcd1234abcd1234",
    "quantity": 1
  },
  "code": 200,
  "status": "OK",
  "ref": 563
}

Additional Response

When applicable, there may be these additional fields in the Response.
Field Explanation
delayedPlanID The planID that the subscription is slated to downgrade to at the next renewal date.
campID The campaign ID subscribed to, applicable for AdManager subscriptions.
hostPlan If it was submitted during create or edit requests.
hostSubID If it was submitted during create or edit requests.
couponCode If it was submitted during the create request.

List Subs

To retrieve a listing of all subscriptions under the specific User.

Endpoint

GET
/{brandID}/users/{userID}/subscriptions

Query String Arguments

Field Default Description
lang en Optional. For those values, like SKU texts, that may be internationalized by the brand, this argument controls the language served. If the individual value was not customized for the requested language, the default (en) value is served.

Success Status

HTTP 201

Response

{
  "detail": {
    "count": 2,
    "subIDs": [{
      "subID": 131376,
      "originalSubID": "s131376",
      "planID": "yola_prem",
      "productID": "2.0.30.0",
      "productID3": "02.00.30",
      "status": 1,
      "term": "P1M",
      "startDate": 1472244279,
      "expirationDate": 1474922679,
      "path": "https://sandbox.sbsapi.com/topline/users/test_user/subscriptions/131376",
      "quantity": 1
  }, {
      "subID": 131377,
      "originalSubID": "s131377",
      "planID": "yola_ecom_base",
      "productID": "2.0.10.0",
      "productID3": "02.01.10",
      "status": 1,
      "term": "P1M",
      "startDate": 1472244282,
      "expirationDate": 1474922682,
      "path": "https://sandbox.sbsapi.com/topline/users/test_user/subscriptions/131377",
      "quantity": 1
}]
  },
  "code": 200,
  "status": "OK",
  "ref": 587
}

Additional Response

When applicable, there may be these additional fields in the Response.
Field Explanation
delayedPlanID The planID that the subscription is slated to downgrade to at the next renewal date.
campID The campaign ID subscribed to, applicable for AdManager subscriptions.
hostPlan If it was submitted during create or edit requests.
hostSubID If it was submitted during create or edit requests.
couponCode If it was submitted during the create request.

View Sub by hostSubID

To retrieve the details about a specific subscription.

Endpoint

GET
/{brandID}/hosted/{hostSubID}

Success Status

HTTP 200

Response

{
  "detail": {
    "partnerID": "acme",
    "userID": "bob",
    "subID": 131373,
    "hostSubID": "abc-123",
    "originalSubID": "s131373",
    "planID": "yola_prem",
    "productID": "2.0.30.0",
    "productID3": "02.00.30",
    "status": 1,
    "term": "P1M",
    "startDate": 1472243805,
    "expirationDate": 1474922205,
    "path": "https://sandbox.sbsapi.com/acme/users/bob/subscriptions/131373",
    "couponCode": "abcd1234abcd1234",
    "quantity": 1
  },
  "code": 200,
  "status": "OK",
  "ref": 563
}

Additional Response

When applicable, there may be these additional fields in the Response.
Field Explanation
delayedPlanID The planID that the subscription is slated to downgrade to at the next renewal date.
campID The campaign ID subscribed to, applicable for AdManager subscriptions.
hostPlan If it was submitted during create or edit requests.
couponCode If it was submitted during the create request.

Edit Sub

To upgrade/downgrade the planID, connect an AdManager subscription with a campID, or update the hostPlan value.

Endpoint

PUT
/{brandID}/users/{userID}/subscriptions/{subID}

Input Fields

Field Required Description
campID Optional For AdManager, to connect an existing marketing campaign to subscription
hostPlan Optional Used to relate the retail name or ID of the Partner’s Hosting Plan to the subscribed service. Provides more context for reports. Max 50 characters.
planID Optional To upgrade/downgrade the planID of the subscription. A new subID will be returned in the response. You can only submit a planID with a productID3 that shares the first 4 digits as the current one. E.g. 03.02.xx
quantity Optional A positive integer (including 0), applicable for SKUs which require a quantity, ignored otherwise.
transactionID Optional A string linked to the user action that triggered the purchase in the vendor UI (see Transactions).
  • If the transactionID is not found, the request fails with a 404.
  • If the transactionID does not belong to this brandID and/or userID, the request fails with a 404.
  • If the transaction is already not in a Pending state, there is no consequence.
  • If the transaction is in a Pending state, the vendor is notified and the transaction status is set to Success.
difm Optional string "preview" or "live", pertains only to DIFM products

Note that planID and quantity cannot be changed in the same request; the request will be rejected.

Success Status

HTTP 201

Response

{
  "detail": {
      "subID": "4805",
      "url": "https://api.local/top__pr/users/p-967fe7aaf6ec/subscriptions/4805",
      "billing": {
          "expiryDate": "2018-09-24 16:17:50",
          "currency": "USD",
          "credit": {
              "ratio": 0.355,
              "fee": 53.23,
              "spend": 212.9
          },
          "debit": {
              "ratio": 1,
              "fee": 70,
              "spend": 280
          },
          "total": {
              "ratio": 0.24,
              "fee": 16.77,
              "spend": 67.1
          }
      }
  },
  "code": 201,
  "status": "Created",
  "ref": 380955
}

Note that the ratio properties are rounded to 3 precision places, yielding percentage values rounded to single precision. e.g. 0.355 is 35.5%; 0.24 is 24.0%.

Preview Sub Action

To preview the effect of some subscription actions. Although the method is POST, nothing is changed by this endpoint. It merely does the work and returns the response but does not affect any state, not in SBS or at the vendors. Note that when this endpoint pretends to create a new subscription, it gives it a subID = -99.

Endpoint

POST
/{brandID}/users/{userID}/subscriptions/preview

Input Fields

Field Description
action One of the following, case-insensitive:

changeplan: pretends to perform an upgrade/downgrade more to come, as requested
planID To upgrade/downgrade the planID of the subscription.
subID The subID that would change.

Success Status

HTTP 201

Response

{
  "detail": {
      "subID": -99,
      "url": "https://api.local/top__pr/users/p-967fe7aaf6ec/subscriptions/-99",
      "billing": {
          "expiryDate": "2018-09-24 16:17:50",
          "currency": "USD",
          "credit": {
              "ratio": 0.355,
              "fee": 53.23,
              "spend": 212.9,
              "quantity": 1
          },
          "debit": {
              "ratio": 1,
              "fee": 70,
              "spend": 280,
              "quantity": 1
          },
          "total": {
              "ratio": 0.24,
              "fee": 16.77,
              "spend": 67.1
          }
      }
  },
  "code": 201,
  "status": "Created",
  "ref": 380955
}

Note that the ratio properties are rounded to 3 precision places, yielding percentage values rounded to single precision. e.g. 0.355 is 35.5%; 0.24 is 24.0%.

Sub Lifecycle Changes

Renew Sub

Can be used to renew a subscription for 1 additional term. Will not extend the subscription end date beyond today + 2 terms. Typically used by Brands set to use Triggered Renewals to action the renewal before or after the current subscription’s end date.

Endpoint

PUT
/{brandID}/users/{userID}/subscriptions/{subID}/renew

Success Status

HTTP 201

Response

{
    "code": 201,
    "status": "OK",
    "newSubscriptionStatus": 1,
    "message": "2 add-on subscriptions may be reactivated ",
    "subscriptions": {
        "02.10.15": "https://sbsapi.com/{brandid}/users/{userid}/subscriptions/{subid}/reactivate",
        "03.10.20": "https://sbsapi.com/{brandid}/users/{userid}/subscriptions/{subid}/reactivate"
    },
    "ref": 617
}

Non-Renew Sub

To change a specific subscription from auto-renew to non-renew. At the end of the current subscription term the subscription will be set to expired. If a core subscription is non-renewed, then all related Add-ons will also be set to non-renew. Response lists all affected subs with URLs to view.

This endpoint is idempotent, meaning that you can call it for a subscription already with non-renew status and it will return 201, leaving the subscription (and its children) unchanged.

Caveat: If a core subscription was non-renewed and its children subscriptions were non-renewed in the single call, then later a child subscription is reactivated without reactivating the core subscription, calling non-renew on the core subscription again will not change the status of the active child subscription back to non-renew.

Endpoint

PUT
/{brandID}/users/{userID}/subscriptions/{subID}/nonrenew

Success Status

HTTP 201

Response

{
    "detail": {
        "subID": "{subID}",
        "url": "https://sbsapi.com/{brandID}/users/{userID}/subscriptions/{subID}",
        "newSubscriptionStatus": 2,
        "message": "2 subscriptions were set to non-renew",
        "subscriptions": {
            "02.00.10": "https://sbsapi.com/{brandID}/users/{userID}/subscriptions/{subID}",
            "02.01.20": "https://sbsapi.com/{brandID}/users/{userID}/subscriptions/{subID}"
        }
    },
    "code": 201,
    "status": "Created",
    "ref": 85763
}

Non-Renew All Subs

To change all the user’s subscriptions to non-renew. At the end of the current subscription term the subscriptions will be set to expired. Response lists all affected subs with URLs to view.

Endpoint

PUT
/{brandID}/users/{userID}/subscriptions/nonrenew

Success Status

HTTP 201

Response

{
    "detail": {
        "newSubscriptionStatus": 2,
        "message": "3 subscriptions were set to non-renew",
        "subscriptions": {
            "02.00.10": "https://sbsapi.com/{brandID}/users/{userID}/subscriptions/{subID}",
            "02.01.20": "https://sbsapi.com/{brandID}/users/{userID}/subscriptions/{subID}",
            "03.00.10": "https://sbsapi.com/{brandID}/users/{userID}/subscriptions/{subID}"
        }
    },
    "code": 201,
    "status": "Created",
    "ref": 112437
}

Delete Sub

To delete a specific subscription. Will include all related Add-on subscriptions if any exist. For Kliken subscriptions any residual AdSpend will be consumed ASAP.

Endpoint

DELETE
/{brandID}/users/{userID}/subscriptions/{subID}

Success Status

HTTP 204

Response

{}

Refund Sub for Fraud

This is to be used when the partner could not collect from the user.

  • This is applicable to Kliken Search subscriptions only.
  • The request will be rejected with a 409 if the subscription is not in suspended state.

The endpoint deletes the subscription immediately and begins the process to recoup all possible funds. This includes all fees charged to date for the subscription, as well as all adspend that has not been consumed by Google. This process is asynchronous and will result in reversing entries in the current period's ledger.

The endpoint merely acknowledges your request and starts working. It does not return any accounting information.

Endpoint

PUT
/{brandID}/users/{userID}/subscriptions/{subID}/refund

Success Status

HTTP 200

Response

{
    "detail": {
        "subID": "{subID}",
        "url": "https://sbsapi.com/{brandID}/users/{userID}/subscriptions/{subID}",
        "newSubscriptionStatus": 5
    },
    "code": 200,
    "status": "OK",
    "ref": 81767
}

Sub State Changes

Suspend Sub

To suspend a specific subscription. If a Core subscription is suspended, then all related Add-on subscriptions will also be suspended. Response lists all affected subs with URLs to view. For Kliken subscriptions, the spending stops immediately.

Depending on the brand.renewalType, the suspended subscription will either expire or continue (get renewed) into the next term in its suspended state.

Endpoint

PUT
/{brandID}/users/{userID}/subscriptions/{subID}/suspend

Success Status

HTTP 201

Response

{
    "detail": {
        "subID": "{subID}",
        "url": "https://sbsapi.com/{brandID}/users/{userID}/subscriptions/{subID}",
        "newSubscriptionStatus": 3,
        "message": "2 subscriptions were suspended",
        "subscriptions": {
            "02.00.10": "https://sbsapi.com/{brandID}/users/{userID}/subscriptions/{subID}",
            "02.01.20": "https://sbsapi.com/{brandID}/users/{userID}/subscriptions/{subID}"
        }
    },
    "code": 201,
    "status": "Created",
    "ref": 85801
}

Reactivate Sub

To reactivate a subscription that is in suspended or non-renew status.

  • If it is suspended, it is restored to its pre-suspension status;
  • If it is non-renew, it is set to active (i.e. auto-renew).

Note: Related Add-ons will not be reactivated, but will be listed in the response with URLs to reactivate them.

Note: Even though it is possible to change an add-on subscription's status to automatically renew (status = active) while leaving its core subscription to be manually renewed (status = non-renew), it is probably a business mistake which should be avoided.

Endpoint

PUT
/{brandID}/users/{userID}/subscriptions/{subID}/reactivate

Success Status

HTTP 201

Response

{
    "detail": {
        "subID": "{subID}",
        "url": "https://sbsapi.com/{brandID}/users/{userID}/subscriptions/{subID}",
        "newSubscriptionStatus": "1",
        "message": "1 subscription may be reactivated",
        "subscriptions": {
            "02.01.20": "https://sbsapi.com/{brandID}/users/{userID}/subscriptions/{subID}/reactivate"
        }
    },
    "code": 201,
    "status": "Created",
    "ref": 85778
}

Transactions

Transactions are created when the user, in the vendor app, initiates a purchase process which is handled asynchronously by the partner.

  1. The user triggers the purchase.
  2. The vendor app shows a spinner.
  3. SBS communicates the user's intention to the partner, including a transactionID and responds to the vendor that the process has started.
  4. On a separate thread, the partner can

    • either create or update a subscription to provision the purchase, including the transactionID, to express that this purchase is related to the user's action;
    • or fail the transaction with an optional explanation.
  5. SBS marks the transaction accordingly and communicates its status to the vendor, who may then stop the spinner.

A transaction can have one of these stati:

Status Notes
Pending The transaction was initiated and communicated to the partner. We're awaiting their notification.
Success The transaction was referenced in a purchase request to SBS.
Failure The transaction was referenced in a fail transaction request.

Fail Transaction

The partner tells SBS that transactionID has failed and the vendor should stop the spinner.

Endpoint

POST
/{brandID}/transactions/{transactionID}/fail

Input Fields

Field Description
reason Optional text to show to the user in the vendor UI.

Possible Responses

HTTP Code Notes
200 Transaction status was changed from Pending to Failure and vendor was notified successfully
204 Transaction status was no longer Pending, so nothing happened
400 Invalid request (e.g. this transactionIDdoes not belong to this brandID)
404 transactionID not found
502 Something went wrong when communicating with the vendor about the transaction

Success Status

HTTP 200

Response

null

Campaigns

Campaigns are created by the end user manually in the Yola or Kliken UI. There is no programmatic method to create the campaign. Once created they can be listed using the following and then funded by creating a subscription that is related to the campID. If the user purchases a subscription to AdManager prior to making a campaign, then a shell campaign will be created to accumulate the funds until the user completes and launches the campaign. See here for more details.

View Campaign

To retrieve the details about a specific campaign. Note that the response is an array of a single campaign.

Endpoint

GET
/{brandID}/users/{userID}/campaigns/{campID}

Success Status

HTTP 200

Response

{
	"detail": {
		"count": 1,
		"campaigns": [{
			"campID": 26719,
			"campName": "We Build Great Sites",
			"type": "search",
			"status": "active",
			"subID": "131400",
			"viewSub": "https://sandbox.sbsapi.com/topline/users/test_user/subscriptions/114",
			"vendor": "yola"
		}],
		"code": 200,
		"status": "OK",
		"ref": 612
	}
}

View Campaign Details

To retrieve the details about a specific campaign. Only applicable for Search, not Display campaigns, and not applicable for campaigns associated with Yola subscriptions.

Endpoint

GET
/{brandID}/users/{userID}/campaigns/{campID}/details

Success Status

HTTP 200

Response

{
	"detail": {
		"geoTargetRegion": null,
		"geoTargetCity": [
			{
				"id": 62396,
				"name": "Toronto",
				"regionCode": "ON",
				"country": "CA"
			}
		],
		"targetLanguage": "en",
		"adGroups": [
			{
				"ads": [
					{
						"headline1": "{KeyWord:Come hither}",
						"headline2": "Feed your face",
						"description": "It's good and good for you.",
						"id": 293301,
						"landingUrl": "http://lalabobo.net",
						"displayUrl": "lalabobo.net",
						"status": "Active",
						"adGroupId": 81202
					},
					{
						"headline1": "Come hither",
						"headline2": "Feed your face",
						"description": "It's good and good for you.",
						"id": 293300,
						"landingUrl": "http://lalabobo.net",
						"displayUrl": "lalabobo.net",
						"status": "Active",
						"adGroupId": 81202
					}
				],
				"keywords": [
					{
						"text": "french cuisine",
						"matchType": "broad",
						"status": "enabled"
					},
					{
						"text": "french cuisine",
						"matchType": "phrase",
						"status": "enabled"
					},
					{
						"text": "french cuisine",
						"matchType": "exact",
						"status": "enabled"
					},
					{
						"text": "french country dishes",
						"matchType": "broad",
						"status": "enabled"
					},
					{
						"text": "french country dishes",
						"matchType": "phrase",
						"status": "enabled"
					},
					{
						"text": "french country dishes",
						"matchType": "exact",
						"status": "enabled"
					},
					{
						"text": "french cooking cookbook",
						"matchType": "broad",
						"status": "enabled"
					},
					{
						"text": "french cooking cookbook",
						"matchType": "phrase",
						"status": "enabled"
					},
					{
						"text": "french cooking cookbook",
						"matchType": "exact",
						"status": "enabled"
					},
					{
						"text": "famous french cookbook",
						"matchType": "broad",
						"status": "enabled"
					},
					{
						"text": "famous french cookbook",
						"matchType": "phrase",
						"status": "enabled"
					},
					{
						"text": "famous french cookbook",
						"matchType": "exact",
						"status": "enabled"
					},
					{
						"text": "easy french food recipes",
						"matchType": "broad",
						"status": "enabled"
					},
					{
						"text": "easy french food recipes",
						"matchType": "phrase",
						"status": "enabled"
					},
					{
						"text": "easy french food recipes",
						"matchType": "exact",
						"status": "enabled"
					}
				],
				"id": 81202,
				"name": "Chez Grenouille",
				"landingUrl": "http://lalabobo.net",
				"status": "Active",
				"campaignId": 68863
			}
		],
		"id": 68863,
		"name": "French Cuisine",
		"landingUrl": "http://lalabobo.net",
		"campaignFocus": "Unknown",
		"geoTargetCountry": "",
		"geoTargetFocus": "LocationOfPresence",
		"status": "Active",
		"type": "Search",
		"vendor": "sw",
		"path": "https://api.local/top__pr/users/johnny/subscriptions/4174",
		"toplineSubID": "4174"
	},
	"code": 200,
	"status": "OK",
	"ref": 377966
	}

List Campaign Subs

To retrieve a listing of all campaigns under the specific user account.

Endpoint

GET
/{brandID}/users/{userID}/campaigns/

Success Status

HTTP 200

Response

{
	"detail": {
		"count":4,
		"campaigns": [{
			"campID": 26719,
			"campName": "PHP Programmers For Sale",
			"type": "search",
			"status": "cancelled",
			"subID": "131394",
			"viewSub": "https://sandbox.sbsapi.com/topline/users/test_user/subscriptions/1314",
			"vendor": "sw"
		}, {
			"campID": 26722,
			"campName": "Site Builders",
			"type": "search",
			"status": "active",
			"subID": "131393",
			"viewSub": "https://sandbox.sbsapi.com/topline/users/test_user/subscriptions/1393",
			"vendor": "sw"
		}, {
			"campID": 26721,
			"campName": "Front End Web Developers Network",
			"type": "display",
			"status": "active",
			"vendor": "sw"
		}, {
			"campID": 26715,
			"campName": "The Voodoo Lounge",
			"type": "search",
			"status": "active",
			"subID": "131395",
			"viewSub": "https://sandbox.sbsapi.com/topline/users/test_user/subscriptions/1315",
			"vendor": "sw"
		}]
	}
}

Special Products

Uberall Dashboard

Topline provides the Uberall dashboard as html ouput available for instance to be iframed into your control panel. This dashboard contains deeplinks into a full Uberall session opening in a new browser tab.

Tokens are single use.

Endpoint

GET
/{brandID}/users/{userID}/uberdash

Query String Arguments

Argument Response HTTP Code Response Headers Response Body
?noredir or ?noredir=1 200 Not applicable JSON
absent or ?noredir=0 303 Location JSON metadata

Success Status (?noredir=1)

HTTP 200

Response Body (?noredir=1)

{
  "code": 200,
  "status": "OK",
  "detail": {
    "URL": "https://sbsgateway.com/uberdashapi/startup?token=81bde580"
  },
  "ref": 5710716

Success Status (?noredir=0)

HTTP 303

Headers (?noredir=0)

Location: https://sbsgateway.com/uberdashapi/startup?token=18dla151

Response Body (?noredir=0)

{
  "code": 303,
  "status": "See Other",
  "ref": 879
}

Kliken Quickstart

The Kliken Quickstart service provides your users with a simple way to get started with one or two campaigns by giving the initial creation of the campaigns to the Kliken experts.

The user purchases subscriptions, purchases this service, fills out a form, and your integration associates the form data to the subscriptions and this service.

Set QuickStart Form

To add or modify the questionnaire form data for the Kliken QuickStart Add-on. Also to connect this subscription to the related AdManager subscription(s) to ensure the newly created campaign is connected to the intended subscription.

Endpoint

POST
/{brandID}/users/{userID}/subscriptions/{subID}/meta/quickstart

Input Fields

Field Description
subIDs Array of one or two integers that are subIDs for the Kliken Display and/or Search subscriptions that this QuickStart order will be completed for.
form_data Name/value pairs that represent the question and answer fields respectively of the questionnaire form the user filled out about their business and intent of the advertising campaign. This data will be provided to our staff, so they can create and launch the campaigns on behalf of the user.

Success Status

HTTP 201

Response

{
  "code": 201,
  "status": "Created",
  "ref": 610
}

Sample Request

{
  "form_data": {
    "question 1": "answer 1",
    "question 2": "answer 2",
    "question 3": "answer 3",
    "question 4": "answer 4"
  },
  "subIDs": [
    50820,
    50821
  ]
}

Topline Domain Redirection

Topline's Domain Redirection subscription represents a service whereby any domain which is pointed to our redirect IP (18.196.58.208) will be redirected to the user.domain for which the subscription has been purchased.

After purchasing a Topline Domain Redirection subscription, you may GET or POST a list of "domain aliases" associated with the subscription. The list aliases is served and posted as a JSON-encoded array. A short time after this information is created or updated, the redirection mechanism reflects the changes, routing traffic to the user's domain.

Set Domain Aliases

Use this endpoint to add or update the existing list of domain aliases associated with the user.domain.

Endpoint

POST
/{brandID}/users/{userID}/subscriptions/{subID}/meta/domains

Input Fields

A JSON-encoded array of domain aliases.

  • Any other data type is rejected with a 400.
  • If the SKU for the subscription has a limit on the number of domains and the list is larger than said limit, the request is rejected.
  • An empty array is a valid submission.
  • A valid request overwrites existing data as a whole.
  • Do not append www to the redirect domains, we will add an alias so that both domain.com and www.domain.com will redirect to the subscription domain.

Success Status

HTTP 201

Response

{
  "code": 201,
  "status": "Created",
  "ref": 610
}

Sample Request

[
  "domain1.com",
  "other-domain1.com",
  "something-else.net"
]

Get Domain aliases

Use this endpoint to retrieve the existing list of domain aliases already attached to the subscription. If there is none, an empty array is returned.

Endpoint

GET
/{brandID}/users/{userID}/subscriptions/{subID}/meta/domains

Response Fields

A JSON-encoded array of domain aliases.

Success Status

HTTP 200

Response when the list is empty

{
  "code": 200,
  "status": "OK",
  "ref": 610,
  "details": []
}

Response when the list is not empty

{
  "code": 200,
  "status": "OK",
  "ref": 610,
  "details": [
    "domain1.com",
    "other-domain1.com",
    "something-else.net"
  ]
}

SSO Logins

These endpoints are used for SSO Login to various interfaces.

Subscription Login

To request a login URL for a specific subscription using its SBS subID. The URL expiration is 5 minutes for all subs, except Uberall subs which have a 2 minute expiry. All URLs are single use.

Endpoint

GET
/{brandID}/users/{userID}/subscriptions/{subID}/sso

Query String Arguments

Argument Response HTTP Code Response Headers Response Body
?noredir or ?noredir=1 200 Not applicable JSON
absent or ?noredir=0 303 Location JSON metadata
Argument Default Notes
lang given person.language, or account.person1.language, or account.language a language code for the SSO session
person account.person1 personID for this SSO session

Success Status (?noredir=1)

HTTP 200

Response Body (?noredir=1)

{
  "code": 200,
  "status": "OK",
  "detail": {
    "ssoURL": "http://sitebuilderhost.net/?partner_domain=ff124fd8b796.utest&auth_token=7680ee80fb259944384f44f51cc0ec4c9&expires=14798&user_id=f61e3005e8c85291418da8e24"
  },
  "ref": 646
}

Success Status (?noredir=0)

HTTP 303

Headers (?noredir=0)

Location: http://sitebuilderhost.net/?partner_domain=ff124fd8b796.utest&auth_token=7680ee80fb259944384f44f51cc0ec4c9&expires=14798&user_id=f61e3005e8c85291418da8e24

Response Body (?noredir=0)

{
  "code": 303,
  "status": "See Other",
  "ref": 645
}

Deep-Linking Sub-based SSO

The type of product for the subscription determines the deep-link path, as detailed below. Any additional "deep-linking" path submitted with the request will be discarded.

ProductID3 Deep Link
02.00 editor
02.01 onlinestore
02.02 paidsearch
02.03 paidsearch
02.04 paidsearch
03.00 ThreadReports
03.01 Display/BuildCampaignProfile?ProtoCampaignId={camp_id}
03.02 Campaigns/BuildCampaignTarget?NewCampaign=False&DisplayWelcome=False&ProtoCampaignId={camp_id}
04.00
05.00

Vendor Specific Login

To request a login URL for a specific Vendor product using its SBS userID. Deep linking paths are available for some products as listed in the Vendor table below.

Endpoint

GET
/@brandID/users/@userID/sso/@vendorID

Query String Arguments

Argument Response HTTP Code Response Headers Response Body
?noredir or ?noredir=1 200 Not applicable JSON
absent or ?noredir=0 303 Location JSON metadata
Argument Default Notes
lang given person.language, or account.person1.language, or account.language a language code for the SSO session
person account.person1 personID for this SSO session

Success Status (?noredir=1)

HTTP 200

Response Body (?noredir=1)

{
  "code": 200,
  "status": "OK",
  "detail": {
    "ssoURL": "http://sitebuilderhost.net/?partner_domain=ff124fd8b796.utest&auth_token=7680ee80fb259944384f44f51cc0ec4c9&expires=14798&user_id=f61e3005e8c85291418da8e24"
  },
  "ref": 646
}

Success Status (?noredir=0)

HTTP 303

Headers (?noredir=0)

Location: http://sitebuilderhost.net/?partner_domain=ff124fd8b796.utest&auth_token=7680ee80fb259944384f44f51cc0ec4c9&expires=14798&user_id=f61e3005e8c85291418da8e24

Response Body (?noredir=0)

{
  "code": 303,
  "status": "See Other",
  "ref": 645
}

Vendor Table

vendor @VendorID expiry deeplinks
Ecwid ecwid 5 minutes na
Kliken sw 5 minutes available
Uberall uber 2 minutes na
Yola yola 5 minutes available

Hosted Subscription Login

To request a login URL for a specific subscription using its hostSubID. The URL expiration is 5 minutes for all vendors except Uberall which has a 2 minute expiry. All URLs are single use.

Endpoint

GET
/{brandID}/hosted/{hostSubID}/sso

Query String Arguments

Argument Response HTTP Code Response Headers Response Body
?noredir or ?noredir=1 200 Not applicable JSON
absent or ?noredir=0 303 Location JSON metadata
Argument Default Notes
lang given person.language, or account.person1.language, or account.language a language code for the SSO session
person account.person1 personID for this SSO session

Success Status (?noredir=1)

HTTP 200

Response Body (?noredir=1)

{
  "code": 200,
  "status": "OK",
  "detail": {
    "ssoURL": "http://sitebuilderhost.net/?partner_domain=ff124fd8b796.utest&auth_token=7680ee80fb259944384f44f51cc0ec4c9&expires=14798&user_id=f61e3005e8c85291418da8e24"
  },
  "ref": 646
}

Success Status (?noredir=0)

HTTP 303

Headers (?noredir=0)

Location: http://sitebuilderhost.net/?partner_domain=ff124fd8b796.utest&auth_token=7680ee80fb259944384f44f51cc0ec4c9&expires=14798&user_id=f61e3005e8c85291418da8e24

Response Body (?noredir=0)

{
  "code": 303,
  "status": "See Other",
  "ref": 645
}

Deep-Linking Hosted SSO

Any "deep-linking" path submitted with the request will be discarded. The type of product for the subscription determines the deep-link path.

See Deep-Linking Sub-based SSO.

To request a login URL for a Kliken user. The URL is to be sent to the user's mobile by the partner.

Endpoint

GET
/{brandID}/users/{userID}/sw/magiclink

Success Status

HTTP 200

Response

{
  "code": 200,
  "status": "OK",
  "detail": {
    "magicLink": "https://msa.app.link/A1b2A1b2A1b2"
  },
  "ref": 952167
}

To request that Kliken sends a login URL to a Kliken user.

Endpoint

POST
/{brandID}/users/{userID}/sw/magiclink

Input Fields

Property Required Default Description
message Yes Text sent to the user's mobile. The required placeholder {{magiclink}} in the message will be replaced by the URL.
phone Yes User's The SMS destination.
countryCode Yes User's The country code for the SMS destination. Must be recognized 2 character country code. See Appendix for supported values.

Success Status

HTTP 200

Response

{
  "code": 200,
  "status": "OK",
  "detail": {
    "magicLink": "https://msa.app.link/A1b2A1b2A1b2"
  },
  "ref": 952167
}

Data Reconciliation

Partners can use these endpoints for the reconciliation of data between your data and our systems.

Note: At this point, reconciliation processes and data do not recognize that subscription.quantity could be something else than 1.

Upload Subs for Recon

You can post your subscription data in CSV or JSON format and we will reconcile them with our data. These endpoints use a "hash" for authorization, and don't require the usual signature. You can obtain pre-configured URLs for these endpoints from SBSmanager > Brands > Resources by clicking the Download API AuthKey button.

Endpoints BrandID

Brands are set up hierarchically. For example, ACME might be a brand that has sub-brands ACME_CA, ACME_NO, ACME_US. In this scenario, very likely, ACME does not have direct customers, its sub-brands do.

If you want to reconcile subscriptions that belong to customers of ACME_CA, you may send the batch to a ACME or a ACME_CA endpoint.

If you want to reconcile subscriptions that belong to customers of ACME_CA and ACME_NO and want to do so in a single batch, you must submit to the ACME endpoint.

You cannot submit a batch to reconcile ACME_CA subscriptions to the ACME_NO endpoint, even though they are sibling sub-brands.

Endpoint (CSV)

POST
/{brandID}/recon/subscriptions/csv/@hash

Endpoint (JSON)

POST
/{brandID}/recon/subscriptions/json/@hash

Success Status

HTTP 201

Response

{
    "detail": {
        "reconID": "190121-195454"
    },
    "code": 201,
    "status": "Created",
    "ref": 38345
}

Data format

CSV must be comma-delimited with a header row. Both formats have the following fields.

Property DataType Required Default Description
brandID string yes na The brandID in each row is the brand where the user/customer is registered. In a hierarchical brand/sub-brand structure, the users are usually registered at the leaves. So, you must submit the rows with `brandID = ACME_NO` for those users. You cannot submit that user's subscriptions with `brandID = ACME`, even though ACME_NO is a sub-brand of ACME.
subID integer see campID na subID is required, unless you supply campID
campID integer see subID na campID is required, unless you supply subID
planID string yes na
sub_status string yes na 1 or "active",
2 or "non-renew",
3 or "suspended",
5 or "deleted" or "expired" or "terminated"
trial string no 0 1 or "yes" or "true",
0 or "false" or "no,
is_nfr boolean no 0
currency string yes na null allowed for non-advertising subscriptions
userID string yes na
domain string yes na
startDate string yes na mysql format "YYYY-MM-DD hh:mm:ss"
expiryDate string yes na mysql format "YYYY-MM-DD hh:mm:ss" OR null

Sample Upload (CSV)

"brandID","subID","campID","planID","sub_status","is_nfr","trial","currency","userID","domain","startDate","expiryDate"
"acme_us","22357","184695","sw_sem_emerging","1","0","0","USD","user_1","domain1.net","2019-01-11 19:35:30","2019-02-11 19:35:30"
"acme_eu","25637","184768","sw_sem_starter","3","0","0","EUR","user_2","domain2.net","2018-12-08 19:35:30","2019-22-08 19:35:30"
"acme_eu","25789","184769","sw_sem_growth","3","0","0","EUR","user_3","domain3.net","2018-11-07 19:35:30","2019-02-07 19:35:30"
"acme_eu","34234","184776","sw_sem_starter","3","0","0","EUR","user_4","domain4.net","2018-12-15 19:35:30","2019-02-15 19:35:30"
"acme_us","35647","175674","sw_sem_starter","1","0","0","USD","user_5","domain5.net","2019-01-21 19:35:30","2019-02-21 19:35:30"

Sample Upload (JSON)

[
 {
   "brandID": "acme_us",
   "subID": 22357,
   "campID": 184695,
   "planID": "sw_sem_emerging",
   "sub_status": 1,
   "is_nfr": 0,
   "trial": 0,
   "currency": "USD",
   "userID": "user_1",
   "domain": "domain1.net",
   "startDate": "2019-01-11 19:35:30",
   "expiryDate": "2019-02-11 19:35:30"  
 },
 {
   "brandID": "acme_eu",
   "subID": 25637,
   "campID": 184768,
   "planID": "sw_sem_starter",
   "sub_status": 3,
   "is_nfr": 0,
   "trial": 0,
   "currency": "EUR",
   "userID": "user_2",
   "domain": "domain2.net",
   "startDate": "2018-12-08 19:35:30",
   "expiryDate": "2019-22-08 19:35:30"
 },
 {
   "brandID": "acme_eu",
   "subID": 25789,
   "campID": 184769,
   "planID": "sw_sem_growth",
   "sub_status": 3,
   "is_nfr": 0,
   "trial": 0,
   "currency": "EUR",
   "userID": "user_3",
   "domain": "domain3.net",
   "startDate": "2018-11-07 19:35:30",
   "expiryDate": "2019-02-07 19:35:30"
 },
 {
   "brandID": "acme_eu",
   "subID": 34234,
   "campID": 184776,
   "planID": "sw_sem_starter",
   "sub_status": 3,
   "is_nfr": 0,
   "trial": 0,
   "currency": "EUR",
   "userID": "user_4",
   "domain": "domain4.net",
   "startDate": "2018-12-15 19:35:30",
   "expiryDate": "2019-02-15 19:35:30"
 },
 {
   "brandID": "acme_us",
   "subID": 35647,
   "campID": 175674,
   "planID": "sw_sem_starter",
   "sub_status": 1,
   "trial": 0,
   "is_nfr": 0,
   "currency": "USD",
   "userID": "user_5",
   "domain": "domain5.net",
   "startDate": "2019-01-21 19:35:30",
   "expiryDate": "2019-02-21 19:35:30"
 }
]

Retrieve Recon Report

Following your upload, you can retrieve the latest processed report in JSON or CSV format by calling one of the following preconfigured endpoints available in your AuthKey Download.

Note these reports are generated asynchronously after receiving an upload. The latest report available is always sent back. The report will have the reconID of the upload it is referring to.

The CSV reports can be automatically sent as a spreadsheet download via our Notification system (email or SMS).

The report will contain 1 row for a sub missing on either side, or 2 rows for a sub with a mismatched sub_status, planID, campID, userID, currency, domain, is_nfr, or expiryDate. The issue(s) for the subscription will be described in the issues field.

Endpoint (CSV)

GET
/{brandID}/recon/subscriptions/csv/@hash

The report is text representing a CSV file. The file name if you download via a browser is in the "Content-Disposition: attachment; filename=FILENAME" header. It contains the reconID of the POST for this report.

Endpoint (JSON)

GET
/{brandID}/recon/subscriptions/json/@hash

The report is JSON in the body of the respose.

Success Status

HTTP 200

Sample CSV Report

"id","issues","subID","sub_status","trial","is_nfr","planID","campID","currency","startDate","expiryDate","userID","domain","brandID","source"
"1","Missing at ACME","271360","3","0","0","sw_sem_emerging","171206","CAD","2018-10-15 07:29:58","2019-02-15 07:29:58","user_1","domain1.net","acme","topline"
"2","Missing at ACME","274636","3","0","0","sw_sem_emerging","174344","CAD","2018-11-09 01:48:38","2019-02-09 01:48:38","user_2","domain2.net","acme","topline"
"3","Missing at ACME","281550","1","0","0","sw_sem_emerging","175674","CAD","2019-01-12 17:12:52","2019-02-12 17:12:52","user_3","domain3.net","acme","topline"
"4","Mismatched sub_status","281765","1","0","0","sw_sem_emerging","184987","USD","2019-01-14 14:17:05","2019-02-14 14:17:05","user_4","domain4.net","acme","topline"
"5","Mismatched sub_status","281765","3","0","0","sw_sem_emerging","184987","USD","2019-01-14 14:17:05","2019-02-14 14:17:05","user_4","domain4.net","acme","partner"

Sample JSON Report

 {
 	"detail": {
 		"reconID": "190128-233608",
 		"report": [{
            "id": 1,
            "issues": "Missing at ACME",
            "subID": 271360,
            "sub_status": 3,
            "trial": "0",
            "is_nfr": "0",
            "planID": "sw_sem_emerging",
            "campID": 171206,
            "currency": "CAD",
            "startDate": "2018-10-15 07:29:58",
            "expiryDate": "2019-02-15 07:29:58",
            "userID": "user_1",
            "domain": "domain1.net",
            "brandID": "acme",
            "source": "topline"
        },
        {
            "id": 2,
            "issues": "Missing at ACME",
            "subID": 274636,
            "sub_status": 3,
            "trial": "0",
            "is_nfr": "0",
            "planID": "sw_sem_emerging",
            "campID": 174344,
            "currency": "CAD",
            "startDate": "2018-11-09 01:48:38",
            "expiryDate": "2019-02-09 01:48:38",
            "userID": "user_2",
            "domain": "domain2.net",
            "brandID": "acme",
            "source": "topline"
        },
        {
            "id": 3,
            "issues": "Missing at ACME",
            "subID": 281550,
            "sub_status": 1,
            "trial": "0",
            "is_nfr": "0",
            "planID": "sw_sem_emerging",
            "campID": 175674,
            "currency": "CAD",
            "startDate": "2019-01-12 17:12:52",
            "expiryDate": "2019-02-12 17:12:52",
            "userID": "user_3",
            "domain": "domain3.net",
            "brandID": "acme",
            "source": "topline"
        },
        {
            "id": "4",
            "issues": "Mismatched sub_status",
            "subID": "281765",
            "sub_status": "1",
            "trial": "0",
            "is_nfr": "0",
            "planID": "sw_sem_emerging",
            "campID": "184987",
            "currency": "USD",
            "startDate": "2019-01-14 14:17:05",
            "expiryDate": "2019-02-14 14:17:05",
            "userID": "user_4",
            "domain": "domain4.net",
            "brandID": "acme",
            "source": "topline"
        },
        {
            "id": "5",
            "issues": "Mismatched sub_status",
            "subID": "281765",
            "sub_status": "3",
            "trial": "0",
            "is_nfr": "0",
            "planID": "sw_sem_emerging",
            "campID": "184987",
            "currency": "USD",
            "startDate": "2019-01-14 14:17:05",
            "expiryDate": "2019-02-14 14:17:05",
            "userID": "user_4",
            "domain": "domain4.net",
            "brandID": "acme",
            "source": "partner"
        }
	  ]
	},
 	"code": 200,
 	"status": "OK",
 	"ref": 380
 }

Download Users and Subs

To request a csv download of all the active and suspended users with subs in your account. Returns Domain, First Name, Last Name, UserID, Email, Phone, Language, SubStatus, as csv text. CSV data is comma delimited, values enclosed in double quotes where required, one record per line with header row.

Endpoint

GET
/{brandID}/recon/users

Success Status

HTTP 200

Response

Domain,"First Name","Last Name",Userid,Email,Phone,Language,Status,Subscriptions
domain-3593416.com,sally,ride,3593416-11551,user@gmail.com,"+41 111 234567",FR,3,"Yola Premium,Yola +eCom Base"
domain-1528638.com,wilson,pickett,1528638-1497,user@gmail.com,"+41 111 345678",EN,1,"Yola Premium"
domain-3664845.com,stefi,graff,3664845-11415,user@gmail.com,"+41 111 456789",DE,1,"Stats, SW Display Starter"
...
domain-1981779.com,robert,hull,1981779-2662,user@gmail.com,"+41 111 235567",EN,3,"Yola Premium,Yola +eCom Unlim"
domain-5018954.com,jim,brown,5018954-11957,user@gmail.com,"+41 111 234667",EN,1,"Yola Premium,Yola +Adm-2"
domain-5018923.com,willie,mays,5018954-11958,user@gmail.com,"+41 111 244567",EN,1,"Yola 3 Page"
domain-5033954.com,diego,maradonna,1246116-11289,user@gmail.com,"+41 111 234267",ES,1,"Yola 3 Page,Yola +eCom Base"

List All Subs for User

To retrieve a listing of all subscriptions under the specific user account. Can be filtered by vendor with a query string argument.

Endpoint

GET
/{brandID}/users/{userID}/subscriptions

Query String Arguments

name value
vendor can be any one of yola, sw, or ecwid

ex: {brandID}/users/{userID}/subscriptions?vendor=yola

Success Status

HTTP 200

Response

{
  "detail": {
    "count": 2,
    "subIDs": [{
      "subID": 131376,
      "originalSubID": "s131376",
      "planID": "yola_prem",
      "productID": "2.0.30.0",
      "productID3": "02.00.30",
      "status": 1,
      "term": "P1M",
      "startDate": 1472244279,
      "expirationDate": 1474922679,
      "path": "https:\/\/sandbox.sbsapi.com\/topline\/users\/test_user\/subscriptions\/131376"
  }, {
      "subID": 131377,
      "originalSubID": "s131377",
      "planID": "yola_ecom_base",
      "productID": "2.0.10.0",
      "productID3": "02.01.10",
      "status": 1,
      "term": "P1M",
      "startDate": 1472244282,
      "expirationDate": 1474922682,
      "path": "https:\/\/sandbox.sbsapi.com\/topline\/users\/test_user\/subscriptions\/131377"
  }]
  },
  "code": 200,
  "status": "OK",
  "ref": 587
}

Additional Response

When applicable, there may be these additional fields in the Response. ```json { "delayedPlanID": "The planID that the subscription is slated to downgrade to at the next renewal date", "campID": "The campaign ID subscribed to, applicable for AdManager subscriptions", "hostPlan": "If it was submitted during create or edit", } ```

Deprecated

These endpoints continue to function but are not the recommended method for achieving your goal.

Yola Login

To request a login URL for a Yola account. The URL will expire in 5 minutes and is single use.

Endpoint

GET
/{brandID}/users/{userID}/yolalogin

Query String Arguments

Argument Response HTTP Code Response Headers Response Body
?noredir or ?noredir=1 200 Not applicable JSON
absent or ?noredir=0 303 Location JSON metadata
Argument Default Notes
lang given person.language, or account.person1.language, or account.language a language code for the SSO session
person account.person1 personID for this SSO session

Success Status (?noredir=1)

HTTP 200

Response Body (?noredir=1)

{
  "code": 200,
  "status": "OK",
  "detail": {
    "ssoURL": "http://sitebuilderhost.net/?partner_domain=ff124fd8b796.utest&auth_token=7680ee80fb259944384f44f51cc0ec4c9&expires=14798&user_id=f61e3005e8c85291418da8e24"
  },
  "ref": 646
}

Success Status (?noredir=0)

HTTP 303

Headers (?noredir=0)

Location: http://sitebuilderhost.net/?partner_domain=ff124fd8b796.utest&auth_token=7680ee80fb259944384f44f51cc0ec4c9&expires=14798&user_id=f61e3005e8c85291418da8e24

Response Body (?noredir=0)

{
  "code": 303,
  "status": "See Other",
  "ref": 645
}

Deep-Linking Yola SSO

The following paths can be appended to the endpoint to provide a more targeted landing within the Yola app. These granular deep links also act as above with respect to the use of the ?noredir query parameter.

GET
/{brandID}/users/{userID}/yolalogin*
* value landing spot
/sitebuilder Sitebuilder
/analytics SW Analytics Dashboard
/admsearch SW Campaign management UI
/ecom Ecwid e-store UI

Uberall Login

To request a login URL for an Uberall account. The URL will expire in 2 minutes and is single use.

Endpoint

GET
/{brandID}/users/{userID}/uberlogin

Query String Arguments

Argument Response HTTP Code Response Headers Response Body
?noredir or ?noredir=1 200 Not applicable JSON
absent or ?noredir=0 303 Location JSON metadata
Argument Default Notes
lang given person.language, or account.person1.language, or account.language a language code for the SSO session
person account.person1 personID for this SSO session

Success Status (?noredir=1)

HTTP 200

Response Body (?noredir=1)

{
  "code": 200,
  "status": "OK",
  "detail": {
    "ssoURL": "http://acme.listmy.business/sso/120934"
  },
  "ref": 646
}

Success Status (?noredir=0)

HTTP 303

Headers (?noredir=0)

Location: http://acme.listmy.business/sso/120934da8e24

Response Body (?noredir=0)

{
  "code": 303,
  "status": "See Other",
  "ref": 645
}

Kliken Login

To request a login URL for a standalone Kliken account. The URL will expire in 5 minutes and is single use.

Endpoints

GET
/{brandID}/users/{userID}/klikenlogin

Query String Arguments

Argument Response HTTP Code Response Headers Response Body
?noredir or ?noredir=1 200 Not applicable JSON
absent or ?noredir=0 303 Location JSON metadata
Argument Default Notes
lang given person.language, or account.person1.language, or account.language a language code for the SSO session
person account.person1 personID for this SSO session

Success Status (?noredir=1)

HTTP 200

Response (?noredir=1)

{
  "code": 200,
  "status": "OK",
  "detail": {
    "ssoURL": "https://sandbox.mysite-analytics.com/Campaigns/Manage/Dashboard/?89536919=dvv@ujI/U32ZvvJkeOSj/xP@lPp7vak8NP@kaRDRST0rKfjLImVzVjT9aMw==&15=74IpX6yuB1Y45EiAWic"
  },
  "ref": 95214
}

Success Status (?noredir=0)

HTTP 303

Headers (?noredir=0)

Location: https://sandbox.mysite-analytics.com/Campaigns/Manage/Dashboard/?89536919=dvv@ujI/U32ZvvJkeOSj/xP@lPp7vak8NP@kaRDRST0rKfjLImVzVjT9aMw==&15=74IpX6yuB1Y45EiAWic

Response Body (?noredir=0)

{
  "code": 303,
  "status": "See Other",
  "ref": 95213
}

Deep-Linking Kliken SSO

The following paths can be appended to the endpoint to provide a more targeted landing within the Kliken app. These granular deep links also act as above with respect to the use of the ?noredir query parameter.

GET
/{brandID}/users/{userID}/klikenlogin*
* value landing spot
/ThreadReports Analytics Dashboard
/CampaignReports SEM Dashboard
/Campaigns/Manage SEM Campaign List
/Campaigns/GetStarted SEM Campaign Get Started
/Campaigns/EditActiveCampaign?ProtoCampaignId= Edit Active SEM Campaign
/Campaigns/EditCampaign?ProtoCampaignId= Edit Unfinished SEM Campaign
/Display/Dashboard Display Dashboard
/Display/Manage Display Campaign List
/Display/GetStarted Display Campaign Get Started
/Display/EditActiveCampaign?ProtoCampaignId= Edit Active Display Campaign
/Display/EditCampaign?ProtoCampaignId= Edit Unfinished Display Campaign
/Store/Dashboard Normal Store Reports similar to ThreadReports
/Shopping/GetStarted New Shopping Campaign
/Shopping/Dashboard Shopping Campaign Reports
/Shopping/Manage List of Shopping Campaigns
/Shopping/EditActiveCampaign?ProtoCampaignId= Edit Active Shopping Campaign
/Shopping/EditCampaign?ProtoCampaignId= Edit Unpurchased Shopping Campaign

Ecwid Login

To request a login URL for an Ecwid account. The URL will expire in 5 minutes and is single use.

Endpoint

GET
/{brandID}/users/{userID}/ecwidlogin

Query String Arguments

Argument Response HTTP Code Response Headers Response Body
?noredir or ?noredir=1 200 Not applicable JSON
absent or ?noredir=0 303 Location JSON metadata
Argument Default Notes
lang given person.language, or account.person1.language, or account.language a language code for the SSO session
person account.person1 personID for this SSO session

Success Status (?noredir=1)

HTTP 200

Response Body (?noredir=1)

{
  "code": 200,
  "status": "OK",
  "detail": {
    "ssoURL": "https://my.shopsettings.com/api/v3/13787255/sso?token=secret_FT5pKJPLRKMgy7NCWPLh7zrNBHqF1s53&timestamp=1525279057&signature=bf0d398766a4e921824e759c24ecbe27dff6f73bc1ce11e43267ee4e5ca9d"
  },
  "ref": 649
}

Success Status (?noredir=0)

HTTP 303

Headers (?noredir=0)

Location: https://my.shopsettings.com/api/v3/13787255/sso?token=secret_FT5pKJPLRKMgy7NCWPLh7zrNBHqF1s53&timestamp=1525279057&signature=bf0d398766a4e921824e759c24ecbe27dff6f73bc1ce11e43267ee4e5ca9d

Response Body (?noredir=0)

{
  "code": 303,
  "status": "See Other",
  "ref": 648
}

Syndication (dep)

For sites created prior to Nov 25, 2021. You can find out by using the SBSmanager Tools SSL Setup to determine the exact instructions you need to follow. What follows is the old instructions in their entirety.

The following steps need to be taken to have the domain covered by a free SSL certificate provided by Cloudflare.

  • A zone needs to be created at Cloudflare. This can be accomplished in either of 2 ways.

    1. If your brand is set to Support SSL on Publish the zone will be created when the user first publishes their website. SBSmanager, Brands > Customization > Sitebuilder.
    2. You can manually create a zone using the Tools in SBSmanager.
  • The user domain in our system needs to have www prepended to it. This can be done via API or using SBSmanager.

  • The DNS for the bare domain needs to have an A Record pointing to one of the following Yola Ips

Production Syndicated publishing DNS

Sandbox Syndicated publishing DNS
  • The following CNAME record is required for the www.domain.
www.mycustomerdomain.com => www.mycustomerdomain.com.cdn.cloudflare.net

The end result is that,
https://www.mycustomerdomain.com will be covered by a Cloudflare cert.
http://mycustomerdomain.com will redirect to the secure domain.
https://mycustomerdomain.com will not resolve properly. Yola uses Cloudflare to issue and host SSL certificates. Thus, to make SSL work, HTTPS traffic has to be proxied via Cloudflare by pointing to Cloudflare subdomain via DNS. The problem with bare domains(ex: mycustomerdomain.com) is that you can't create CNAME to Cloudflare on the apex level because of DNS limitations. That's why we recommend having CNAME record pointed to Cloudflare for a subdomain(ex: www.mycustomerdomain.com).

Additionally we supply callbacks to you to help in timing issues when domains are first published.

Default PlanIDs

ProductID3 Structure

Each service that Topline offers has a unique planID that is used in API calls to identify the correct service for each end user subscription. Each planID has a related productID3 code that is made up of a 3-segment numeric that describes that service in relation to other services available. This is useful for supporting what upgrades or downgrades are available from the user’s current subscription.

The first segment is the product line, for example the 02 in 02.00.20 represents Yola Latitude Sitebuilder product line.

The second segment is the product category representing a core plan with 00 (eg 02.00.60) or an Add-on plan with 01, or 02 etc. Any subscription can be upgraded or downgraded to another plan that is in the same product line and category. So 02.00.60 can be up/downgraded to anything in 02.00.xx.

The third segment is the product and allows you to determine whether a certain plan is an upgrade or a downgrade based on its increasing value. For example, if the user currently is on a plan with productID3=02.00.70, then moving to the plan with 02.00.60 is a downgrade and 02.00.80 is an upgrade.

Yola Services

Yola Core

With the Yola service you can select a Core planID for the base Yola product level and then optionally use Add-on planIDs to extend Yola with eCommerce and AdManager functionality. Entry level Add-ons are included with each Core plan automatically as listed below.

Plan name Core planID productID3 Max Pages Max MB Included Add-ons
Kliken Ecwid
Latitude Free yola_free 02.00.60 2 50 Stats, Mobile eCom Free
Latitude Unlimited yola_unlim 02.00.70 Unlimited 2000 Stats, Mobile eCom Free
Latitude Premium yola_prem 02.00.80 Unlimited 5000 Stats, Mobile eCom Free

Yola Add-on: eCommerce

The eCommerce Add-on for Yola is powered by the Ecwid service (ecwid.com) and can be added to any of the Yola product plans. Only one eCom Add-on can be added to a Yola core plan, meaning only one Online Store per domain. There is a free 3 Product version of eCom included in every Yola core package.

Add-on name Add-on planID productID3 maximum products
eCom Base yola_ecom_base 02.01.10 100
eCom Pro yola_ecom_pro 02.01.20 2500
eCom Unlimited yola_ecom_unlim 02.01.30 Unlimited

Yola Add-on: AdManager

Yola AdManager is powered by the Kliken service (Kliken.com) and can be added to any of the Core Yola plans. Multiple AdManager plans can be added to a single Yola Core subscription. All Yola Core plans include the Site Stats Add-on automatically. The currencies you offer your customers and the spend levels can be customized to your market needs during your initial integration project.

AdManager add-on MSRP
Add-on Name planID productID3 USD EUR CHF
Display Starter yola_adm_dis_starter 02.03.20 50 50 50
Display Growth yola_adm_dis_growth 02.03.30 100 100 100
Display Nurture yola_adm_dis_nurture 02.03.40 250 250 250
Display Pro yola_adm_dis_pro 02.03.50 500 500 500
SEM Emerging yola_adm_sem_emerging 02.04.10 75 75 75
SEM Starter yola_adm_sem_starter 02.04.20 150 150 150
SEM Growth yola_adm_sem_growth 02.04.30 300 300 300
SEM Nurture yola_adm_sem_nurture 02.04.40 500 500 500
SEM Pro yola_adm_sem_pro 02.04.50 1,000 1,000 1,000
SEM Enterprise yola_adm_sem_ent 02.04.60 2,000 2,000 2,000
QuickStart yola_adm_quickstart 02.05.10 100 100 100

Kliken Services

Kliken Core

When provisioning Kliken as a standalone service (not part of a Yola subscription) the following Core planIDs should be used. Only one Kliken Core plan can be connected to a user account.

Plan Name Core planID productID3 function
Kliken Stats sw_stats 03.00.10 Site Stats, Analytics, Mobile app

Kliken Add-on: AdManager

A user account may have multiple AdManager Add-ons to allow for multiple ad campaigns to be running concurrently. The currencies you offer your customers and the spend levels can be customized to your market needs during your initial integration project.

AdManager add-on MSRP
Add-on Name planID productID3 USD EUR CHF
Display Starter sw_dis_starter 03.01.20 50 50 50
Display Growth sw_dis_growth 03.01.30 100 100 100
Display Nurture sw_dis_nurture 03.01.40 250 250 250
Display Pro sw_dis_pro 03.01.50 500 500 500
SEM Emerging sw_sem_emerging 03.02.10 75 75 75
SEM Starter sw_sem_starter 03.02.20 150 150 150
SEM Growth sw_sem_growth 03.02.30 300 300 300
SEM Nurture sw_sem_nurture 03.02.40 500 500 500
SEM Pro sw_sem_pro 03.02.50 1,000 1,000 1,000
SEM Enterprise sw_sem_ent 03.02.60 2,000 2,000 2,000
QuickStart sw_quickstart 03.04.10 100 100 100

Ecwid Services

Ecwid Core

The Ecwid services include 4 core plans and no Add-ons. These are to be used as standalone Ecwid plans for WordPress, Drupal, or Joomla sites and not as an add-on to Yola.

Plan name Add-on planID productID3 maximum products
eCom Free ecwid_free 05.00.01 3
eCom Base ecwid_base 05.00.10 100
eCom Pro ecwid_pro 05.00.20 2500
eCom Unlimited ecwid_unlim 05.00.30 Unlimited

Status Values

User Status

Each User has a status level that affects how it can be used and how charges apply. This status affects all product subscriptions for that User.

User Status Characteristics Can be updated to Response value
Active Full access to subscribed applications Suspended, Deleted 1
Suspended No access to applications, no charge at subscription renewal dates Reactivated, Deleted 3
Deleted No access and not listed in most reports except for historic usage 5

Subscription Status

Each subscription to a service also has a status level independent of the User’s status level.

Sub Status Characteristics Can be updated to: Response
Active Subscription will renew automatically. Usage fees accrue at initial creation and each renewal. Non-renew, Suspended, Deleted 1
Non-Renew Subscription will not renew but subscription is still available until renewal date. Sub will automatically be changed to Expired status at the renewal date, except if Brand is set to Triggered Renewals then it will be set to Suspended for one term then expired. Reactivated, Suspended, Deleted 2
Suspended No access to application. Subscription will renew but will not be chargeable until changed to Active status. Reactivated, Deleted 3
Obligated Subscription has been cancelled but is still running out its obligation. After obligation is complete it will be expired. 4
Deleted Not listed in most reports, sub listings 5
Downgraded Subscription was replaced with a new sub of a lower value. 6
Upgraded Subscription was replaced with a new sub of a higher value. 7
Expired Subscription is auto-expired at end of Non-Renew period and then will no longer be charged. Must add a new subscription to access product again. No need to delete. Deleted 8

Kliken campaigns

Kliken supports a single domain having an unlimited number of advertising campaigns. Each campaign is a collection of keywords and the text ad copy that the keywords would relate to. The end user adds campaigns manually in the AdManager interface. There is no charge for a campaign until the user wants to fund the AdSpend with a subscription.

Campaigns are considered Inactive when not connected to a current subscription. This would occur if a user adds multiple campaigns without funding them, or if the subscription connected to a campaign expires. Inactive campaigns can always be funded by connecting them to a valid subscription.

Pre-purchased campaigns which have not been launched are considered to be Waiting. AdSpend portion of the sub can still be refunded at this time.

Campaign Status Description
Active Campaign is connected to a subscription with status of Active, Non-Renew, or Suspended.
Inactive Campaign is not currently connected to subscription with status of Active, Non-Renew, or Suspended.
Waiting The original status, before the campaign has been activated, by funding it with a subscription. e.g. pre-purchased campaigns can accumulate funds but never be activated / launched.

DIFM

The DIFM (Do it for me) process is configured on a User basis by setting the value of the DIFM field. See DIFM Process section for details on this feature.

DIFM status API value Characteristics
DIY 0 Will not be listed for DIFM designers in SBS
DIFM Preview 1 Will show in SBS for DIFM designers. Publish will be to the common “DIFM Preview” URL/FTP configured for that brand.
DIFM Live 2 Will show in SBS for DIFM designers. Publish will be to the URL/FTP configured in user’s record.

Codes

Country

Requests should submit the 2 letter code from the ISO 3166-1 alpha-2 standard for the countryCode field.

Currency

Requests should submit the "Code" value as the currency field.

Name Code
Australian Dollar AUD
Brazilian Real BRL
British Pound GBP
Canadian Dollar CAD
Euro EUR
Hong Kong Dollar HKD
Indonesian Rupiah IDR
Japanese Yen JPY
Mexican Peso MXN
New Zealand Dollar NZD
Norwegian Krone NOK
Singapore Dollar SGD
South African Rand ZAR
US Dollar USD

Language

Requests should submit the "Code" value as the language field.

Name Code
Chinese (simplified) zh
Czech cs
Danish da
Dutch nl
English (US) en
French fr
German de
Hungarian hu
Indonesian id
Italian it
Japanese ja
Norwegian nb
Polish pl
Portuguese (Brazilian) pt-BR
Portuguese (Portuguese) pt-PT
Russian ru
Simplified Chinese zh-CN
Slovak sk
Spanish es
Swedish sv
Swedish (Sweden) sv-SE
Vietnamese vi

Timezone

Requests should submit the "Code" value as the timezone field.

Name Code
(UTC) Casablanca Morocco Standard Time
(UTC) Coordinated Universal Time UTC
(UTC) Dublin, Edinburgh, Lisbon, London GMT Standard Time
(UTC) Monrovia, Reykjavik Greenwich Standard Time
(UTC+01:00) Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna W. Europe Standard Time
(UTC+01:00) Belgrade, Bratislava, Budapest, Ljubljana, Prague Central Europe Standard Time
(UTC+01:00) Brussels, Copenhagen, Madrid, Paris Romance Standard Time
(UTC+01:00) Sarajevo, Skopje, Warsaw, Zagreb Central European Standard Time
(UTC+01:00) West Central Africa W. Central Africa Standard Time
(UTC+01:00) Windhoek Namibia Standard Time
(UTC+02:00) Athens, Bucharest GTB Standard Time
(UTC+02:00) Beirut Middle East Standard Time
(UTC+02:00) Cairo Egypt Standard Time
(UTC+02:00) Damascus Syria Standard Time
(UTC+02:00) E. Europe E. Europe Standard Time
(UTC+02:00) Harare, Pretoria South Africa Standard Time
(UTC+02:00) Helsinki, Kyiv, Riga, Sofia, Tallinn, Vilnius FLE Standard Time
(UTC+02:00) Istanbul Turkey Standard Time
(UTC+02:00) Jerusalem Israel Standard Time
(UTC+02:00) Tripoli Libya Standard Time
(UTC+03:00) Amman Jordan Standard Time
(UTC+03:00) Baghdad Arabic Standard Time
(UTC+03:00) Kaliningrad, Minsk Kaliningrad Standard Time
(UTC+03:00) Kuwait, Riyadh Arab Standard Time
(UTC+03:00) Nairobi E. Africa Standard Time
(UTC+03:30) Tehran Iran Standard Time
(UTC+04:00) Abu Dhabi, Muscat Arabian Standard Time
(UTC+04:00) Baku Azerbaijan Standard Time
(UTC+04:00) Moscow, St. Petersburg, Volgograd Russian Standard Time
(UTC+04:00) Port Louis Mauritius Standard Time
(UTC+04:00) Tbilisi Georgian Standard Time
(UTC+04:00) Yerevan Caucasus Standard Time
(UTC+04:30) Kabul Afghanistan Standard Time
(UTC+05:00) Ashgabat, Tashkent West Asia Standard Time
(UTC+05:00) Islamabad, Karachi Pakistan Standard Time
(UTC+05:30) Chennai, Kolkata, Mumbai, New Delhi India Standard Time
(UTC+05:30) Sri Jayawardenepura Sri Lanka Standard Time
(UTC+05:45) Kathmandu Nepal Standard Time
(UTC+06:00) Astana Central Asia Standard Time
(UTC+06:00) Dhaka Bangladesh Standard Time
(UTC+06:00) Ekaterinburg Ekaterinburg Standard Time
(UTC+06:30) Yangon (Rangoon) Myanmar Standard Time
(UTC+07:00) Bangkok, Hanoi, Jakarta SE Asia Standard Time
(UTC+07:00) Novosibirsk N. Central Asia Standard Time
(UTC+08:00) Beijing, Chongqing, Hong Kong, Urumqi China Standard Time
(UTC+08:00) Krasnoyarsk North Asia Standard Time
(UTC+08:00) Kuala Lumpur, Singapore Singapore Standard Time
(UTC+08:00) Perth W. Australia Standard Time
(UTC+08:00) Taipei Taipei Standard Time
(UTC+08:00) Ulaanbaatar Ulaanbaatar Standard Time
(UTC+09:00) Irkutsk North Asia East Standard Time
(UTC+09:00) Osaka, Sapporo, Tokyo Tokyo Standard Time
(UTC+09:00) Seoul Korea Standard Time
(UTC+09:30) Adelaide Cen. Australia Standard Time
(UTC+09:30) Darwin AUS Central Standard Time
(UTC+10:00) Brisbane E. Australia Standard Time
(UTC+10:00) Canberra, Melbourne, Sydney AUS Eastern Standard Time
(UTC+10:00) Guam, Port Moresby West Pacific Standard Time
(UTC+10:00) Hobart Tasmania Standard Time
(UTC+10:00) Yakutsk Yakutsk Standard Time
(UTC+11:00) Solomon Is., New Caledonia Central Pacific Standard Time
(UTC+11:00) Vladivostok Vladivostok Standard Time
(UTC+12:00) Auckland, Wellington New Zealand Standard Time
(UTC+12:00) Coordinated Universal Time+12 UTC+12
(UTC+12:00) Fiji Fiji Standard Time
(UTC+12:00) Magadan Magadan Standard Time
(UTC+12:00) Petropavlovsk-Kamchatsky - Old Kamchatka Standard Time
(UTC+13:00) Nuku'alofa Tonga Standard Time
(UTC+13:00) Samoa Samoa Standard Time
(UTC-01:00) Azores Azores Standard Time
(UTC-01:00) Cape Verde Is. Cape Verde Standard Time
(UTC-02:00) Coordinated Universal Time-02 UTC-02
(UTC-02:00) Mid-Atlantic - Old Mid-Atlantic Standard Time
(UTC-03:00) Brasilia E. South America Standard Time
(UTC-03:00) Buenos Aires Argentina Standard Time
(UTC-03:00) Cayenne, Fortaleza SA Eastern Standard Time
(UTC-03:00) Greenland Greenland Standard Time
(UTC-03:00) Montevideo Montevideo Standard Time
(UTC-03:00) Salvador Bahia Standard Time
(UTC-03:30) Newfoundland Newfoundland Standard Time
(UTC-04:00) Asuncion Paraguay Standard Time
(UTC-04:00) Atlantic Time (Canada) Atlantic Standard Time
(UTC-04:00) Cuiaba Central Brazilian Standard Time
(UTC-04:00) Georgetown, La Paz, Manaus, San Juan SA Western Standard Time
(UTC-04:00) Santiago Pacific SA Standard Time
(UTC-04:30) Caracas Venezuela Standard Time
(UTC-05:00) Bogota, Lima, Quito SA Pacific Standard Time
(UTC-05:00) Eastern Time (US & Canada) Eastern Standard Time
(UTC-05:00) Indiana (East) US Eastern Standard Time
(UTC-06:00) Central America Central America Standard Time
(UTC-06:00) Central Time (US & Canada) Central Standard Time
(UTC-06:00) Guadalajara, Mexico City, Monterrey Central Standard Time (Mexico)
(UTC-06:00) Saskatchewan Canada Central Standard Time
(UTC-07:00) Arizona US Mountain Standard Time
(UTC-07:00) Chihuahua, La Paz, Mazatlan Mountain Standard Time (Mexico)
(UTC-07:00) Mountain Time (US & Canada) Mountain Standard Time
(UTC-08:00) Baja California Pacific Standard Time (Mexico)
(UTC-08:00) Pacific Time (US & Canada) Pacific Standard Time
(UTC-09:00) Alaska Alaskan Standard Time
(UTC-10:00) Hawaii Hawaiian Standard Time
(UTC-11:00) Coordinated Universal Time-11 UTC-11
(UTC-12:00) International Date Line West Dateline Standard Time
SBS API Documentation