Docs
Integrations
Scripts

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 are visible to all control panel users. 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 the 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
  • If you use inline scripts, you can include up to five <script> tags
  • 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 / templateStorefront page
all_pagesAdd 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
storefrontAdd 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
checkoutCheckout
order_confirmationOrder Confirmation

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.

Subresource integrity

Subresource integrity (SRI) (opens in a new tab) is a security feature browsers use to verify that attackers have not manipulated external hosted resources, including scripts.

All scripts on the checkout page need at least one SRI hash to meet PCI 4.0 - 6.4.3 requirements (opens in a new tab).

You can generate SRI hashes (opens in a new tab) or work with a script provider or host to generate a hash. We support all the hashing algorithms the SRI standard allows, including SHA-256, SHA-384, and SHA-512. The hash corresponds to the contents of the script. If you modify the contents of your script at its original location, you must generate a new hash.

You can add SRI hashes through the Script Manager (opens in a new tab) or using the REST Management API's scripts feature.
For external SRC scripts, BigCommerce will use the provided hashes within the integrity attribute when we generate the script tag from your external SRC script. BigCommerce will also set the crossorigin attribute of the script to anonymous. This is because SRI requires that browsers don't include any credentials (like cookies or HTTP authentication) in the request when fetching the resource.

A hash becomes invalid when the contents of a script change, and the script will fail to execute. To prevent this from happening, we support multiple hashes so that a script can always have a valid hash while the script provider updates the script. You should supply another hash before the contents of the script change. The browser will check each hash to see if any of them match a corresponding script. You can add up to five SRI hashes and remove hashes when they are no longer valid. The browser will typically check hashes starting from the leftmost hash in the integrity attribute and proceed to the right until it finds a match. For this reason, you can use the allotted five hashes to sort hashes in decreasing algorithmic strength so that browsers use the strongest available hash.

⚠️

If there is a change to the host script, you must update or add a valid hash. If no hashes match the contents of the script, the browser console will show an error that the script failed to execute.

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.

Resources

Endpoint and theme reference

Articles

Help center

Tools

Did you find what you were looking for?
MetafieldsShipping providers