Checkout SDK Quickstart

The Checkout JS SDK is a JavaScript library of methods for performing actions related to checkout. It includes methods for logging in a customer, adding addresses to the checkout object, and surfacing the shipping and payment methods that a merchant has configured. It’s everything you need to build your own custom checkout page on BigCommerce.

The sample checkout app we provide, built in React, is a great place to get started if you prefer to build within a framework. However, the SDK is framework agnostic because it’s built with VanillaJS.

To illustrate this point, this tutorial will walk through the first steps of building a custom checkout directly into the theme files using VanillaJS. At the end of the tutorial, you will have installed the Checkout SDK, created a new JavaScript module for your custom checkout, and console logged the checkout object.


Installing the Checkout JS SDK

  1. Open your terminal and navigate to your theme’s directory.

For example, cd cornerstone

  1. Run the following command:

npm install --save @bigcommerce/checkout-sdk

Creating a checkout.js file

  1. In your text editor, open your theme and create a new file in the assets/js/theme directory.

  2. Save the file as checkout.js. You can name your checkout JavaScript file anything you like, but the subsequent steps of this tutorial will assume the filename checkout.js.

  3. Add the following to your checkout.js file:

import PageManager from './page-manager';
import { createCheckoutService } from '@bigcommerce/checkout-sdk';

const service = createCheckoutService();

export default class Checkout extends PageManager {
	async onReady() {
		const state = await service.loadCheckout();

Importing and extending the PageManager abstract class sets the page context for the checkout.js module. We also import { createCheckoutService } from the Checkout SDK.

The async keyword ensures that onReady() returns a Promise; the await keyword waits until the Promise resolves to load the checkout. Async/await is supported in nearly all modern browsers, but if you need to support older browsers like IE, you will require the Promise polyfill.

  1. Save the file.

Mapping the checkout.js file to the checkout page type

  1. Open the assets/js/app.js file in your text editor.

  2. Add the following to map your checkout.js file to the checkout page type:

checkout: () => import('./theme/checkout'),

const pageClasses = {
    account_orderstatus: getAccount,
    account_order: getAccount,
    account_addressbook: getAccount,
    shippingaddressform: getAccount,
    account_new_return: getAccount,
    'add-wishlist': () => import('./theme/wishlist'),
    account_recentitems: getAccount,
    account_downloaditem: getAccount,
    editaccount: getAccount,
    account_inbox: getAccount,
    account_saved_return: getAccount,
    account_returns: getAccount,
    account_paymentmethods: getAccount,
    account_addpaymentmethod: getAccount,
    account_editpaymentmethod: getAccount,
    login: getLogin,
    createaccount_thanks: getLogin,
    createaccount: getLogin,
    getnewpassword: getLogin,
    forgotpassword: getLogin,
    blog: noop,
    blog_post: noop,
    brand: () => import('./theme/brand'),
    brands: noop,
    cart: () => import('./theme/cart'),
    category: () => import('./theme/category'),
		checkout: () => import('./theme/checkout'),
    compare: () => import('./theme/compare'),
    page_contact_form: () => import('./theme/contact-us'),
    error: noop,
    404: noop,
    giftcertificates: () => import('./theme/gift-certificate'),
    giftcertificates_balance: () => import('./theme/gift-certificate'),
    giftcertificates_redeem: () => import('./theme/gift-certificate'),
    default: noop,
    page: noop,
    product: () => import('./theme/product'),
    amp_product_options: () => import('./theme/product'),
    search: () => import('./theme/search'),
    rss: noop,
    sitemap: noop,
    newsletter_subscribe: noop,
    wishlist: () => import('./theme/wishlist'),
    wishlists: () => import('./theme/wishlist'),
  1. Save the file.

Preparing the checkout.html template file

  1. Open the checkout.html file in your text editor.
  2. Comment out the following statement:

{{{ checkout.checkout_content }}}

<!--{{{ checkout.checkout_content }}}-->

  1. On the next line, add the following:
<script>window.__webpack_public_path__ = "{{cdn 'assets/dist/'}}";</script>
<script src="{{cdn 'assets/dist/theme-bundle.main.js'}}"></script>

    window.stencilBootstrap("{{page_type}}", {{jsContext}}).load();
  1. Save the file.

Logging the Checkout Object

  1. Navigate to the storefront and open your browser console.
  2. Add an item to your cart and proceed to the checkout page. The checkout page will be blank below the header.
  3. Note the checkout object logged to the console.

Next Steps

Build out your custom checkout page by entering your HTML into the checkout.html file and JavaScript into checkout.js. For detailed documentation on all of the Checkout SDK library methods visit the SDK GitHub repository.


Sample Apps

Related Articles

Additonal Resources