Installing a Custom Checkout
On this page
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:
- Navigate and locate the Open Source Checkout folder using the terminal, and run
npm cito download dependencies - Run
npm run buildto 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 IdcheckoutId: If present, the ID of the active checkout. You can’t have bothorderIdandcheckoutId
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
/contentfolder and create a new folder named checkout. - Navigate into the
/distfolder in your checkout project. - Copy the contents of the
/distfolder 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:alphacommand:
`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.
- Click the Save button at the bottom of the page.
- Navigate to your live storefront to view your new custom checkout.