Installing a Custom Checkout

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 must be responsible for the following:

Loading all the required assets, including CSS files
Running the app

Packaging custom checkouts with Open Source Checkout

If using Open Source Checkout, you can generate the loader file by following these steps:

Navigate and locate the Open Source Checkout folder using the terminal, and run npm ci to download dependencies
Run npm run build to generate a /dist/ folder with all the files

When using Open Source Checkout to view changes and test implementations through the UI, deploy, and install the custom checkout. More details are below.

Properties available on the checkout page

When a store uses custom checkout, some properties are attached to the window.checkoutConfig object on the checkout page. These properties are:

containerId: ID of the HTML component where you load the checkout app.
orderId: If present, it means we should render an order confirmation page for the given order ID.
checkoutId: If present, the ID of the active checkout. You can’t have both orderId and checkoutId.
publicPath: If present, the public URL of the custom checkout file’s directory.

To use the data exposed in the window object, include relevant code in your loader file. Here is an example of this code :

ReactDOM.render(
  <Checkout checkoutId={ window.checkoutConfig.checkoutId } />,
  document.getElementById(window.checkoutConfig.containerId)
);

Hosting a custom checkout

You will need to host the custom checkout file online so it can be served by the store. You can use a hosting service, such as Amazon S3. Using an external host will allow you the freedom to automate the build process if you wish and push updates automatically from your local machine.

Using WebDAV to host a custom checkout

You can upload a custom checkout to your store’s server using WebDAV. The instructions to upload the /dist folder to the BigCommerce server using WebDav are below:

Before proceeding, ensure you have downloaded Cyberduck, our recommended WebDAV client. Note: For more information on how to use Cyberduck, refer to the File Access (WebDAV) page.
From your store control panel, navigate to Server Settings > File Access (WebDAV).
- To automatically connect with Cyberduck, see Single-click Login.
- To manually connect with Cyberduck, see Connecting with Cyberduck Manually.
From Cyberduck, enter the /content folder and create a new folder named checkout.
Navigate into the /dist folder in your checkout project.
Copy the contents of the /dist folder and paste it into the checkout folder.

Installing custom checkouts

To install a custom checkout on a store, follow these steps:

Navigate to Advanced Settings > Checkout in your store’s control panel.
Under Checkout Type, select Custom Checkouts.
Type the following in the Script URL field, replacing with the latest version number generated by running the npm run release:alpha command:

webdav:checkout/auto-loader-<version>.js

NOTES:

*Prepending webdav: Indicates that the URL is in the remote WebDAV directory. It will treat /content as the root WebDAV directory.

*It is important to include <version> number in the Script URL field. Because if you make changes to the same provided loader filename, you could serve a cached version to the user.

custom-checkout-01

Click the Save button at the bottom of the page.
Navigate to your live storefront to view your new custom checkout.