Scripts API

The BigCommerce Scripts API gives developers the ability to deploy scripts on storefront pages programmatically. Scripts are channel-aware.

This article explains the benefits and limitations of the Scripts API, then works through different strategies you might employ to migrate an existing app's script management mechanism from the control panel to the API. It assumes you're familiar with the BigCommerce app installation process. For more information on the app installation process from the merchant perspective, see our Help Center article on Installing Apps (opens in a new tab). For information on responding to app installation callbacks, see our article on Implementing OAuth.

Scripts API and Script Manager

The control panel counterpart of the Scripts API is the Script Manager, which is available in the channel settings for the subject storefront on non-Blueprint stores. Scripts that you install with the Scripts API appear in the storefront's Script Manager, but can only be modified by the API account that created them. However, authorized control panel users can change the consent category or entirely delete any script using Script Manager, including scripts created using the API. To learn more, see our Help Center article on Script Manager (opens in a new tab).

Similarly, scripts added manually belong to control panel users collectively. When you use the API to Get all scripts, Get a script, Update a script, or Delete a script, you can only retrieve, modify, and delete scripts added by API account you use to make the request. The Scripts API can’t update or delete scripts added using the control panel Script Manager.

After a merchant installs your app, the app can freely update its own scripts. All the app's scripts are available in the Script Manager for the merchant to inspect.

The following list gives examples of the kinds of scripts you can add and manage using the Scripts API:

Analytics scripts
Single-click app scripts
Live chat and support plugins
Theme extensions or connector apps

You can use the Scripts API to associate a script with a channel, including a React or other compiled JavaScript framework bundle.

Before installing any scripts using the Scripts API, we highly recommend checking a combination of the Get store information and Get all channels endpoints to determine Stencil or headless support for the subject storefront or storefronts.

We also recommend leaving the auto_uninstall flag set to true, so that your app has the option of garbage collecting on uninstallation.

These steps can help prevent unexpected behavior.

Limits

Each app can have 10 API-created scripts
Each channel can have 50 control panel-created scripts
You can install up to five scripts in a single call
On a BigCommerce-hosted storefront, new or updated scripts take 20 seconds to cache

Stencil themes

You can associate scripts with a Stencil template page or headless storefront location. On Stencil, you can specify whether scripts are added to the header object as {{head.scripts}} or the footer object as {{footer.scripts}}.

When you are using Stencil CLI to develop a theme locally, scripts added with the Scripts API will not render.

The following table describes the locations you can associate with Scripts API or Script Manager scripts on headless or Stencil storefronts:

Script scope / template	Storefront page
`all_pages`	Add Wishlist Blog List Blog Post Brand Pages All Brands Page Cart Category Checkout My Account Product Compare Order Confirmation Page Payment Methods Login Contact Form Product Search All Wishlist Wish List 404 page
`storefront`	Add Wishlist Blog List Blog Post Brand Pages All Brands Page Cart Category Product Compare Page Contact Form Product Search All Wishlist Wish List 404 page
`checkout`	Checkout
`order_confirmation`	Order Confirmation

You cannot make a Scripts API script available on the following Stencil pages:

giftcertificates.php
sitemap.php

To associate scripts with a checkout page, you need the Modify Checkout Content OAuth scope.

Blueprint themes

Storefront-wise, all stores have access to Stencil themes and headless storefronts. In addition to those two frameworks, older stores may use our legacy theme engine, Blueprint, which does not support rendering scripts inserted using the Scripts API or the Script manager.

For more on checking which theme engine a storefront is using, see this article's section on Scripts API and Script Manager.

Managing scripts using single-click app callbacks

If you're using an app-level API account, we recommend inserting your scripts immediately following completion of the auth callback. The app can use the uninstall callback to remove its scripts when a merchant uninstalls it, and the remove_user callback to remove any scripts related to a particular user when they lose access privileges.

Your implementation may use a store-level API account to authenticate. If so, any references to app callbacks do not apply to your code.

Upgrading

If your app is already live, you may have previously asked merchants to paste a code snippet into one of these places:

The footer scripts or other in-template location in a Stencil or Blueprint theme
The Web Analytics control panel menu or its successor, Data solutions > Web analytics (SSF) (opens in a new tab) or Data solutions > Web analytics (MSF channel 1) (opens in a new tab)
Site verification tags or its successor, Data Solutions > Site verification tags (SSF) (opens in a new tab) or Data solutions > Web analytics (MSF channel 1) (opens in a new tab)
Script Manager (SSF) (opens in a new tab) or Script Manager (MSF channel 1) (opens in a new tab)

Although Blueprint-based themes do not support Script Manager or the Scripts API, you may choose to add or continue Blueprint support. If so, you need some way of providing Blueprint stores access to the app's programmatically created scripts, without burdening users of Stencil or headless storefronts with additional unnecessary steps.

To ease your app's transition to using the Scripts API, there are several possible strategies, depending on your app's ecosystem and customer base.

Do nothing

You may decide that it doesn't make sense for your implementation to use the Scripts API.

Upgrade or encourage upgrade

If you want your merchants to upgrade to programmatically created scripts, you can prompt them to do so on your app’s landing page. You’ll need to keep track of which of your merchants are not using the Scripts API to know whether you need to display this prompt. For more on checking which theme engine a storefront is using, see this article's section on Scripts API and Script Manager.

Once a user decides to upgrade, you can use a form to walk them through removing the old manual code in their control panel. When the merchant clicks submit, install your scripts using the Scripts API.

Silently upgrade

You may decide that your old pasted-in scripts can live alongside your new approach to script management. However, BigCommerce does not recommend upgrading without disclosure. See this article's section on disclosure.

Disclosure is best practice

Solutions that add dynamic script support using revisions to or additions of scripts pasted into the theme or inserted in a Data Solutions > Web Analytics menu should disclose the change to all client stores, including Blueprint users.

Release notes can work for all storefronts. Changes to the OAuth scopes of apps that use app-level API accounts require the store owner or other authorized user to accept the new scopes, which could provide a mechanism to trigger release note display. Store owners aren't prompted to reauthorize until they next open an app in the control panel, so direct contact may be advisable from a conversion perspective. You can't change the OAuth scopes for a store-level API account, so directly contacting the store or stores that you want to change may be your only option for disclosure.

Troubleshooting

Your app installation may find itself unexpectedly missing one or more scripts. Below are some possible causes of this issue.

The merchant deleted your script

Merchants receive a warning when they attempt to delete a script belonging to an app, but they can.

To determine whether the expected scripts are present, we recommend you check the Get all scripts endpoint when your app receives the load callback. If they are not, you can prompt the user to click a button to repair their installation automatically.

It's best practice to request the user’s permission rather than doing this automatically, as they may have had a good reason for deleting the missing script. See this article's section on disclosure.

The merchant's theme is not set up correctly

Stencil templates must have the Handlebars expressions {{head.scripts}} and {{footer.scripts}} in the pages to render scripts. If either of these is absent, scripts on that page with location set to head or footer, respectively, will not render.

To ensure your app is compatible with as many themes as possible, we recommend {{footer.scripts}} over {{head.scripts}} for the checkout, order_confirmation, and all_pages contexts.

Read more about the head object and footer object.

Scripts do not render in the checkout or order confirmation contexts

To render scripts, the store must have BigCommerce’s Optimized One-Page Checkout (opens in a new tab) enabled. This is the default checkout type for all new Stencil stores. Existing stores have to change the checkout type manually. To change the checkout type (opens in a new tab), visit the store control panel.

Stencil themes from the marketplace support Optimized One-Page Checkout (Help Center) (opens in a new tab). However, there could be instances where the merchant maintains their private theme without the ability to support the optimized one-page checkout. In this case, the merchant must add the theme support, following the steps to customize optimized one-page checkout.