Installing an Open Source Checkout

You can create unique shopping experiences that fit the look and feel of a store's brand using custom checkouts. This article outlines how to package a custom checkout file and install a custom checkout using the control panel.

This article will address using both Open Source Checkout (opens in a new tab) and Checkout SDK (opens in a new tab) powered checkouts.

Obtaining the JavaScript loader file

Custom checkouts must have a single JS loader file. The first step to using a custom checkout is generating this file. The loader file is responsible for the following:

Loading all the required assets, including all CSS files, no matter the location
Running the app

Developing a custom checkout

If you wish to customize the style sheets, enter your CSS into the optimized-checkout.scss (opens in a new tab) in Cornerstone or the scss folder (opens in a new tab) in checkout.js. We suggest moving content from "optimized-checkout.scss to the scss folder or vice-versa to ensure a single source of truth for handling styles.

Note: "optimized-checkout.scss" will always override the CSS rules defined in checkout-js.

In order to build from the source code, you must have the following set up in your development environment.

Node >= v22.x
NPM >= v10.x
Unix-based operating system

Packaging custom checkouts with Open Source Checkout

If using Open Source Checkout (opens in a new tab), you can generate the loader file by following these steps:

Fork and clone checkout-js (opens in a new tab); then, install dependencies.

# Clone the repo
git clone https://github.com/bigcommerce/checkout-js
 
# Install dependencies
cd checkout-js
npm ci

(Optional) Start webpack in watch mode and launch the dev server.

If you are developing the application locally, you can build the source code in watch mode and test your checkout implementation.

npm run dev & npm run dev:server

Open your browser and navigate to http://127.0.0.1:8080/ to confirm the dev server is running. You should see content from the /build folder.
Enter the local URL for auto-loader-dev.js in Checkout Settings > Custom Checkout > Script URL. (e.g., http://127.0.0.1:8080/auto-loader-dev.js)

After you have made changes to the source code, run the following command to build it.

  npm run build

This creates a /dist folder that contains the loader file (e.g., auto-loader-1.564.0.js). You will then need to host the /dist folder and enter the URL to the loader file in Checkout Settings > Custom Checkout > Script URL.

Configuring to comply with PCI DSS 4.0

If you need to make your custom checkout PCI 4.0 compliant, follow the steps outlined in the PCI-specific setup guide.

Hosting a custom checkout

You'll need to host the custom checkout file online so the store can serve it. You can use a hosting service, such as Amazon S3 (opens in a new tab). Using an external host gives you the freedom to automate the build process if you wish and push updates automatically from your local machine. Or you can host it on your store using WebDAV.

The steps to host a custom checkout on BigCommerce are below:

Use WebDAV to upload a custom checkout. For details, see Use WebDAV (opens in a new tab) to upload the checkout-loader.js file.
Install custom checkout using the control panel (opens in a new tab) or use the Update Checkout Settings (opens in a new tab) endpoint to install the loader file.

Related resources

Articles

Did you find what you were looking for?

Open Checkout Setup PCI-Specific Setup Guide