Collapse Menu
Docs Home
Extensibility Options
Contact Support

Getting Started with Store Builder Library


This article covers the basics of Store Builder Library.


Store Builder Library (SBL) must be "initialized" with a specific Storefront. This Storefront will be used when the customer is ready to check out, and products associated with the Storefront will be available in the data returned by the FastSpring back-end to the Store Builder Library.

You can use either a Web Storefront or a Popup Storefront with the Store Builder Library, depending on the preferred checkout experience. There is no difference in the behavior of the two types of Storefronts in regard to the Store Builder Library and available data; the only difference is what happens when the buyer initiates checkout. 


If you are planning to use a Popup Storefront, you will need to "whitelist" domains where the Popup Storefront will be shown. All of your domains (including those you will use for testing and development) need to be whitelisted.


When using a Popup Storefront, we recommend that you deploy a security certificate and use the https: protocol for your website. Otherwise, most web browsers will not display a closed padlock icon, and some may display warning messages about non-secure pages. For more information, please see Popup Storefronts and Browser Security Features.

Selecting Products That Will Be Accessible with the Library

If you would like to display dynamic, localized product pricing and descriptions to your customers, you need to log on to the FastSpring Dashboard and explicitly choose products which will be delivered to your page. To do this:

For Web Storefronts

  1. Select Storefronts → Web Storefronts.
  2. For the Web Storefront you have chosen to use with the Library, click HOMEPAGE. The Homepage Products dialog will appear.

    User-added image

For Popup Storefronts

  1. Select Storefronts → Popup Storefronts.
  2. For the Popup Storefront you have chosen to use with the Library, click PRODUCTS. The Homepage Products dialog will appear.

    User-added image

Using the Homepage Products Dialog

User-added image

In the Main Products field, begin typing the name of the first product you want to add. As you type each character, a list of matching products will be filtered dynamically. To select the product from the list, you can use the arrow keys and press Enter / Return, or just click the desired product. Then, repeat this process to add any additional products that you want to make available to the Library. If you make a mistake, click the red Remove command to the left of the product that you do not want to include in the Storefront.

 Note about Web Storefronts

If you are using a Web Storefront, keep in mind that this process also controls which items will appear on the Homepage of the Storefront. For more information, please see Choosing Products to be Displayed on the Storefront's Homepage. If you plan to send some customers to the Homepage of a Web Storefront separately from your Store Builder Library implementation, you can create a separate Web Storefront for use with the Library, if need be.

 Note about Popup Storefronts

The Popup Storefront does not include a Home Page / product catalog. However, adding products via a Popup Storefront's Homepage Products dialog will make them available in the Library's data set so the products can be referenced when accessing the library from HTML using Markup and accessing the library using JavaScript. This is only necessary if you want to display product attributes (such as price, display name, icon, etc.) on your SBL page; you can initiate checkout for any product path in the Store, regardless of whether or not it is included in the Popup Storefront's Home Page products dialog.

Initializing the Library

After choosing the Storefront and selecting available products, you can insert the Library in all pages where its features will be used.

 Tutorial Video

Check out our tutorial video on adding a Popup Storefront to your website, which includes a functional demonstration of initializing the Store Builder Library:  How to Add a Popup Storefront to Your Website.

 Live Interactive Examples

Check out our interactive, hands-on examples at

To Get the Latest Library Code

Navigate to the Storefront of your choice. Then:

  • For Web Storefronts, click the LINKS command; the code in the Advanced Links section of the resulting dialog will reference the Storefront and the latest version of the Library.
  • For Popup Storefronts, click PLACE ON YOUR WEBSITE. The code in the resulting dialog will reference the Storefront and the latest version of the Library.


We recommend that you keep your links to the Store Builder Library updated with the latest / current URL, in order to take advantage of the latest features and improvements.


Third-party tools that attempt to compress, concatenate, or defer JavaScript loading may interfere with initializing the Store Builder Library.  For example, the Rocketscript tool from Cloudflare may modify your script that loads the Store Builder Library like this:  <script id='fsc-api' data-rocketsrc=""> . This may not work because data-rocketsrc is not supported by Store Builder Library at this time. To ensure the Store Builder Library can load successfully, we recommend that you avoid using these types of tools on pages that load the library.


The code provided will be limited to a simple reference, but to use advanced features you will need to provide additional data and register callbacks:

Store Builder Library Code Example
	  src="" type="text/javascript" 
	  data-access-key=".. access key .."        

Full Code Reference

  • id – Required, do not change value, must be "fsc-api".
  • src – Required, will be changed with each version of the FastSpring JavaScript API
  • data-storefront – Required, the Storefront that the API initializes. Use the Storefront's usual Domain URL without "https://". For example, "" or "". This Storefront will be used when redirecting the customer to checkout. You can use both Test and Live Storefronts here. Test Storefronts might not respond as quickly as Live Storefronts.
  • data-data-callback – A JavaScript function you should provide, which will be invoked when new JSON ("order object") is obtained from the server. This function must accept 1 parameter, an object. See more information on returned data structure in Accessing the Library from Javascript.
  • data-error-callback – A JavaScript function you should provide, which will be invoked when an error is received from the backend. This function must accept 2 parameters, an error code and an error string. See the example callback function below. 

    Error callback function example
    function errorCallback (code, string) {
      	console.log("Error: ", code, string);
  • data-validation-callback – An optional JavaScript function you can provide, which must accept a JSON object consisting of an array with field validation results. This makes it easier to display user-friendly field validation error messages.  See more information on the returned data structure in Accessing the Library from JavaScript.
  • data-before-requests-callback and data-after-requests-callback -- Two JavaScript functions you may provide, which will be called before and after making any network requests. No parameters are passed to these functions.
  • data-before-markup-callback and data-after-markup-callback – Two JavaScript functions you may provide, which will be called before and after markup is performed. No parameters are passed to these functions.
  • data-decorate-callback -- A JavaScript function you may provide, which will be invoked before redirecting to checkout for the purpose of obtaining Google Analytics linker "decorations". This function must accept a URL (string) as a parameter and return the decorated URL as a string. You must use this function If you are using Google Analytics for tracking to avoid gaps in tracking your users.

    Decoration Callback Example
    function decorateURL(url) {
            var linkerParam = null;
            if ( ga && typeof ga === 'function') {
                    ga(function() {
                            var trackers = ga.getAll();
                            linkerParam = trackers[0].get('linkerParam');
            return (linkerParam ? url + '?' + linkerParam : url);
  • data-popup-webhook-received – A JavaScript function you may provide, which will be invoked when the webhook event is received from the Popup store. This function must accept 1 parameter, an object. To setup webhooks, login to Dashboard and navigate to Integrations > Webhooks. At least one event will always fire on successful order containing basic order information. Refer to Webhooks > Browser Script Examples for more information about data structure.
  • data-popup-event-received – A JavaScript function you may provide, which will be invoked when an analytics event is received from the popup checkout process. This function must accept 1 parameter, an object. See Google Universal Analytics docs for all event types our checkout process generates. Those events are intended to be used with Google Analytics on your page. 
  • data-popup-closed – A JavaScript function you may provide, which will be invoked when popup is closed. The function must accept an object which will contain the internal FastSpring order ID (key: id) and a customer-facing order reference (key: reference). The order id will only be passed upon successful order completion. If the popup is closed before the order is completed, "null" will be passed.


    For orders that use certain types of delayed payment methods, such as wire transfer orders, the order reference will not be not returned but the order id still will be returned.
    Example of the data-popup-closed object
    popup closed: Object {id: "cbhpinwOS52LKQ5SMoU812", reference: "FUR161216-8786-75309"}
      Do not initiate redirect, navigation page change after you directed your customer to checkout and before you received "data-popup-closed" event. This might result in interruption of the checkout process. For suggested handling of the order completion in popup stores please refer to Validating Popup Storefront Orders.
  • data-access-key – Required for making requests with the secure payload. Please refer to Passing Sensitive Data with Secure Requests for more information.
  • data-continuous – The default is "false". When set to "true", the Library remembers a visitor in the browser (products currently in cart, applied discounts, etc) and keeps that data across pages of a single domain for 24 hours. This is useful if the visitor flow may be across multiple pages and you want to display the correct pricing, including discounts, across all pages of the website. Continuous data uses JavaScript's local storage feature in the visitor's browser, so it is not necessary for visitors to have cookies enabled.
  • data-debug – The default is "false". When set to "true", the Library provides extensive logging and other information to the browser console. 
  If you are providing callback functions to be called by the FastSpring API, the functions must exist on the page when the Library is loaded. Make sure the function (or the inclusion of the JavaScript file that contains the function) is located in your webpage in a place that will be loaded before the API calls are made.


Try FastSpring

Get a free account and see why FastSpring is the ecommerce partner of choice for software providers around the world. Try our full-service ecommerce solution today to unlock revenue growth for your online company.