The Complete Guide to Checkout Customization on BigCommerce

It’s no surprise that the checkout page is where the magic happens on an ecommerce site. And as an ecommerce developer, you know that the requirements for the checkout design can vary widely from business to business.

At BigCommerce, we’ve put a lot of research behind our flagship checkout page, Optimized One-Page Checkout, and it’s designed to create a checkout experience that will streamline the purchase process and increase conversions for merchants across the platform. But we also recognize that there’s no one size fits all solution. Across verticals and business models, there’s a ton of variation in merchants’ design needs and the experience their shoppers expect when they proceed to checkout.

The ability to customize the appearance and functionality of the checkout page is essential, especially for developers who support enterprise businesses. Our philosophy is that merchants should be able to look to the Optimized One-Page Checkout as an example of best practices in checkout form design, but we also want to build as much openness into our checkout as possible to accommodate merchants with specific business needs who are able to take on the effort of advanced customization.

This guide will outline the breadth of checkout customization options on BigCommerce, from no-code or low-code customizations all the way to complex headless builds. We’ll begin with a technical overview of the BigCommerce checkout page and then walk through the spectrum of customization options available for the checkout page, from native settings to defining every pixel of the checkout.

Special Considerations

Let’s start by establishing the fact that customizing the checkout page is different than customizing other default templates in your theme. Although there are many good reasons for customizing the checkout page, the consequences of introducing bugs are significant. Anything that affects checkout page uptime is going to have a direct impact on a store’s sales.

Security is also a consideration. One of the big advantages of using a platform like BigCommerce is that PCI compliance is bundled into the core feature set when using the native checkout page. PCI refers to the Payment Card Industry Data Security Standard, and it governs the way companies who handle credit card information maintain a secure environment. PCI compliance reaches into many areas: infrastructure, engineering, even the practices of company employees. At BigCommerce, we go to great lengths to make sure our platform meets these security standards.

Some types of checkout customizations affect BigCommerce’s ability to assume the burden of PCI compliance and shift this responsibility to the party customizing the checkout. For example, an app that injects JavaScript into the checkout page or a headless checkout that’s hosted on an external server would be within PCI scope.

That being said, there are best practices you can follow to make sure that the custom code you apply to the checkout page is going to play nicely with the platform — today and across future updates. We’ll cover a few of those best practices in this blog post. Full guidelines on PCI compliance are out of the scope of this post, but you can read more on requirements here (Developer Portal).

Technical Overview

The Optimized One-page Checkout is a single page application whose purpose is to convert a Cart to an Order. The checkout application is made up of several layers:

• Backend application
• Storefront Checkout API
• Checkout JS SDK
• Frontend presentation layer

The Optimized One-page checkout consumes the same Storefront Checkout API and JS SDK that are available to external developers. The Storefront Checkout API surfaces the business logic of the backend ecommerce application — retrieving customer information, fetching available shipping methods, and calculating discounts and sales tax. The JS SDK is a wrapper library that provides methods for interacting with the Storefront Checkout API.

The process for converting a cart to an order follows this flow:

1. A Cart object begins as a collection of product line items and a customer account ID. It becomes a Checkout object when it picks up additional data — a billing and shipping address — that provide enough context to calculate discounts, taxes, and shipping options.
2. The next step of checkout is creating what are called consignments. Each consignment is made up of the line items that ship to a particular address. An order that ships to multiple addresses will have multiple consignments.
3. Next, the checkout is converted to an order — but you’ll notice we haven’t accepted a payment yet. At this point the order is in a status called Pending Incomplete.
4. Lastly, when a successful payment is processed through a BigCommerce payment gateway integration, the order status converts from Incomplete to Awaiting Fulfillment.

Although there is quite a bit of flexibility in what you can customize on the checkout page, there’s one important thing to keep in mind. The application logic that backs the Checkout API has certain validations and rules in place around the checkout flow that will still need to be followed, even if you change the UI. For example, a Checkout object must always have an email address associated with it, and if the cart contains physical products, a shipping address.

In most cases, the flow for a custom checkout will still map to the customer experience outlined above, but there may be edge cases that require a different sequence. It’s possible to create a presentation layer in the UI that makes it seem as though you are bypassing required fields (for example, by masking the fields and filling them with dummy data), but you’ll need to handle that logic within your customizations to process orders successfully. Lastly, the checkout customizations detailed here do not allow you to change the underlying functionality of the checkout, for example, by integrating an unsupported payment method.

Available Customization Options

In this section, we’ll start with the lightest lift and talk about a few of the customization options that are built into the BigCommerce Control Panel. Then, we’ll talk about how you can customize the text that appears on the checkout page, and even translate it into another language. Finally, we’ll go over how to add custom styling and functionality to the checkout with CSS and JavaScript.

1. Checkout Form Fields.

BigCommerce natively supports the ability to define new fields on the checkout page address form as well as reordering fields. Custom fields will be visible to the shopper on the checkout page and the values the shopper fills in will be visible in the Order View section of the Control Panel. Custom address fields support a variety of input types: checkbox, text field, date picker, dropdown, number-only, and password.

Common uses for custom checkout form fields include things like collecting a customer’s account number or verifying a delivery preference. Because custom address fields do persist to the Order View screen, developers making advanced customizations can repurpose custom form fields to store data that needs to be carried over to the Order record.

2. Store Design Settings

Another native option for styling the checkout page is Store Design. The Store Design editor provides an interface for controlling settings like the checkout page’s header image, colors, and fonts. It’s always a good idea to check for a setting before hard-coding CSS, because it gives merchants more control over their design and ensures their choices persist through theme updates.

As a theme developer, you can control which Store Design settings are available for merchants to configure. Settings, along with their possible values, are defined in the theme’s schema.json file, and current selected values are stored in config.json, which can be referenced by custom Sass functions. For more on developing Store Design settings, visit our documentation.

3. Multi-language checkout.

Moving on to customizations that require light custom code, the text strings that display on the Optimized One-page Checkout page can be edited, or even translated into multiple languages.

The checkout page follows the same convention used by all Stencil templates to render text strings. The {{lang}} helper, custom to Stencil, pulls a text string’s value from a set of JSON files, based on the language setting detected in the shopper’s browser. A store can have multiple .json lang files, one for each language that a store supports.

To access the translation keys that are rendered on the checkout page, you’ll need to append a JSON object containing the checkout keys and their text string values to your store’s .json lang file(s). If English is the default language on your store but you wish to change the wording on some of the checkout fields, you would add the checkout JSON object to the en.json file; if your store supports English and French and you wish to show a French version of the checkout page to French-speaking shoppers, you would add the checkout JSON object to your fr.json file and translate the key values accordingly.

4. Custom CSS.

The Optimized One-page Checkout references the optimized-checkout.scss file for styling, and you can review our theme documentation for a list of CSS classes that are applied to checkout elements. It’s important to note that you don’t want to nest or alter the built in class names, because it can break compatibility with future checkout page updates. Beyond that, you have the ability to reference a custom stylesheet or add your own CSS rules to manipulate styles and layout.

5. Custom JavaScript.

BigCommerce supports checkout page script injection via the Script Manager, an interface for managing third party scripts. If you’re building an app and need to run custom JavaScript on the checkout or order confirmation page, to create a pop-up for example, you can also inject scripts programmatically using the Scripts API.

The accordion layout of the Optimized One-page checkout loads dynamically as the shopper proceeds through the steps, which is something you’ll want to consider to make sure that your JavaScript is executing at the right time. While you could poll the DOM using setInterval() to make sure the element you want to target has loaded, using Mutation Observer is a nice, clean alternative. Support for Mutation Observer is built into modern browsers, so there’s no need to bring in a dependency to use it.

As an example, let’s say we want to execute some JavaScript on the Billing Address step of the checkout process. We could do the following, which checks for an element with the ID #checkoutBillingAddress. (adapted from Ryan Morr’s blog post)

Mutation Observer listening for Billing Address step

Note: While our engineering team is mindful of keeping DOM elements and classes consistent, we cannot guarantee that element IDs will never change across future updates. The best practice for running custom scripts on the checkout page is to avoid interacting with the checkout code directly, and these instructions are provided as a consideration for developers who have weighed the risk.

Headless Checkout

Now that we’ve covered some of the standard customizations you might want to make to checkout, let’s get into the more advanced options. BigCommerce surfaces APIs that cover the full checkout process end-to-end, which means that you can build a fully custom checkout either on top of the native storefront, or on a remote platform.

First, let’s set a quick baseline for what we mean by “headless checkout.”

Headless means that the front-end presentation layer has been decoupled from the backend platform that powers it. Remember when we talked about the layers that make up the Optimized One-page checkout? When you’re building a headless checkout, you’re still leveraging the backend application logic that’s surfaced through the API, but you replace the frontend presentation layer — or “head” — with a UI that’s purpose-built to your design needs and technology preferences.

You have several options for building decoupled checkouts, and the right choice for the job will depend on the level of control that you need, your ability to take on advanced development and security compliance, and the domain on which you need to run the checkout. We’ll talk through those considerations below.

1. Checkout JS SDK.

The BigCommerce Checkout JS SDK is a wrapper library for the Storefront Checkout API, which is the same API that powers the native checkout page. You can use the Checkout SDK to call methods on the Storefront Checkout API to move the shopper through the purchase process.

The Checkout SDK is a tool for building a custom UI for the checkout page, on the BigCommerce store domain. Essentially, it allows you to build a checkout UI replacement on BigCommerce.

The frontend technology that you use to build your custom checkout page is entirely up to you — you could use React or Vue, or even vanilla JavaScript or jQuery. This gives you a great deal of freedom to build highly customized checkout experiences, including features like a local pickup or delivery step or other add-ons.

So how does the Checkout SDK relate to the concept of headless checkout? Checkout pages built with the SDK are considered headless because you’re replacing the native presentation layer with one that’s custom-built on another framework. The Checkout SDK can also provide a checkout solution for remote headless storefronts, if you redirect back to the BigCommerce domain for the checkout step. This can be a good option if you need a great deal of control over the checkout look-and-feel, but want to reduce the overhead of building a remote checkout completely from scratch.

2. Embedded Checkout.

Embedded Checkout is a version of the Optimized One-page checkout that can be iframed into an external website, like a CMS. Embedded checkout is a great solution for a remote headless storefront, because shoppers can complete their purchase in-context, without being redirected to a BigCommerce domain.

The advantage of Embedded Checkout is that it limits the PCI scope taken on by the developer. Because the checkout page is on the BigCommerce domain and isn’t modified by external code, BigCommerce PCI compliance can extend to the remote storefront’s checkout. That built-in security comes with a few trade offs when it comes to how much the checkout page can be customized. Some styling options are available, allowing you to customize things like colors and font sizes, but the ability to inject custom CSS or JavaScript is limited.

Today, embedded checkout is coupled to the BigCommerce for WordPress plugin, but soon we’ll be releasing documentation on using embedded checkout with a wider range of CMSs and external storefronts. Stay tuned!

3. Server-to-Server Checkout API.

The Server-to-Server (S2S) Checkout API allows developers to orchestrate a checkout on a remote server. This means that developers can leverage the BigCommerce backend business logic to convert a cart to an order, external to the BigCommerce storefront.

To understand how the S2S Checkout API contrasts with other headless checkout options, let’s compare it to the Checkout SDK and embedded checkout. The Checkout SDK allows you to have a high degree of control over presentation, but it must be used on the native storefront. Embedded checkout allows you to use the BigCommerce checkout on a remote storefront easily and securely, but it gives you less control over the checkout page presentation. The S2S Checkout API allows you to build your checkout on a remote storefront, and it gives you complete control over the presentation.

The S2S Checkout API provides maximum flexibility both in terms of presentation and context. You can use the S2S checkout API to build a checkout page on a remote storefront, mobile app, or other checkout experience, like a kiosk. Along with that flexibility comes a heavier development lift, and because you are building and hosting the form that will accept credit card information, responsibility for making sure the checkout is PCI compliant.

Conclusion

BigCommerce offers a wide range of options for customizing the checkout page — everything from settings that can be adjusted from within the control panel, to completely custom-built headless checkout pages. In this blog post, we’ve surveyed a number of those options, including:

• Custom Address Form Fields
• Custom Styles and CSS
• JavaScript injection
• Headless Checkout, three ways

No matter which checkout customization option you choose, be sure to visit our Developer Portal for detailed documentation on the features mentioned here. Let us know your questions and how you’re customizing the BigCommerce checkout by commenting below or tweeting @BigCommerceDevs.