Installing a Custom Checkout

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

This article will address using both Open Source Checkout and Checkout SDK 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 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:

1. Navigate and locate the Open Source Checkout folder using the terminal, and run npm ci to download dependencies
2. 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

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:

1. 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.
2. 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.
3. From Cyberduck, enter the /content folder and create a new folder named checkout.
4. Navigate into the /dist folder in your checkout project.
5. 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:

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

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

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

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

Related resources

Articles

• Checkout SDK
• File Access (WebDav)