Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 28 ยท Checkout and Commerce Services

Customizing Checkout and the Checkout SDK

Understand the options for changing BigCommerce checkout: settings, Checkout JS, the Checkout SDK, embedded checkout and safe handling of payment instruments.

Checkout is where a store earns its money and where a bad change costs the most. BigCommerce therefore gives you a ladder of options. At the bottom are settings that need no code. In the middle you customize a prebuilt checkout. At the top you build your own checkout screens on top of a JavaScript library. Choosing the lowest rung that solves your problem saves time and keeps the risk small.

The checkout itself runs on BigCommerce's servers and payment gateways, so you cannot run it in this lesson. The checkout code, settings and SDK calls here are read-only. The runnable stand-ins are JavaScript models: a step-by-step state machine like the one a checkout needs, and a safe way to display stored payment instruments. They are our own code, and they model the ideas, not the SDK's internals. Background on why checkout is built this way is in Checkout Flow; the cart and Checkout API calls are in Carts and the Checkout API.

The ladder of options

  1. Settings. In the control panel's checkout settings, merchants choose the checkout type (the default is the Optimized One-Page Checkout) and control things such as guest checkout, account creation, order comments, required fields and the terms and conditions checkbox. Most "can you change this?" requests end here.
  2. Theme and branding. The checkout's logo, colors and fonts come from checkout styling settings, not from your theme templates. A visual match with the storefront often needs only this.
  3. Scripts. The Script Manager can add scripts to the checkout page (visibility set to checkout), for example a tracking tag. See Widgets, Regions and Page Builder. Platform rules limit what scripts may do on checkout pages, so check the current policy before relying on one.
  4. Checkout JS. BigCommerce publishes the code of its Optimized One-Page Checkout as an open-source React application called Checkout JS. You can fork it, change components, build it, host the build on your own CDN and tell the store to use it as a custom checkout. You keep the proven flow and change what you need.
  5. Checkout SDK. The @bigcommerce/checkout-sdk package is a framework-neutral library for talking to the checkout. You build your own screens (in any framework) on top of it. It gives you the data and actions of the checkout without the interface.
  6. Embedded checkout. For headless storefronts, the SDK can embed the store's hosted checkout in an iframe on your own domain. You do not build checkout screens at all.

The deeper you go, the more you own: accessibility, validation, error messages, every new payment method and every platform change. Many projects should stop at rung 2 or 6.

flowchart TD
    A["Need a change to checkout"] --> B{"Can a setting do it?"}
    B -->|"yes"| S["Use settings and styling"]
    B -->|"no"| C{"Headless storefront?"}
    C -->|"yes"| E["Embedded checkout<br/>via the SDK"]
    C -->|"no"| D{"Small change to the standard flow?"}
    D -->|"yes"| J["Fork Checkout JS<br/>(custom checkout)"]
    D -->|"no"| K["Build screens with<br/>the Checkout SDK"]

Choose the lowest rung that solves the problem.

Checkout JS as a custom checkout

Because Checkout JS is open source, a custom checkout is "the same app with your changes". The usual workflow (read-only) is:

Terminal
git clone https://github.com/bigcommerce/checkout-js.git
cd checkout-js
npm install
npm run build

You then host the built files, and in the store's checkout settings you point the custom checkout setting at your script, including a checksum (Subresource Integrity hash) so the browser only runs the exact file you approved. Treat the setting as a deployment: version your builds, keep the previous build ready for rollback, and test in a sandbox store with real payment methods in test mode. The details of the settings, the build commands and the supported Node version are in the repository's README and the current documentation, and they change; follow those over this summary.

A fork carries a long-term cost: when BigCommerce improves the standard checkout, you must merge the changes. Keep your changes small and in a few well-marked files to make that merge easy.

The Checkout SDK

The SDK exposes a checkout service: an object that holds the checkout state, offers actions that change it, and lets you subscribe to updates. The shape of a flow (read-only; names are as in the SDK at the time of writing, so confirm with its reference):

JavaScript
import { createCheckoutService } from '@bigcommerce/checkout-sdk';

const service = createCheckoutService();

service.subscribe((state) => {
  const checkout = state.data.getCheckout();
  render(checkout);            // your own UI function
});

await service.loadCheckout(checkoutId);

await service.updateShippingAddress({
  firstName: 'Ana', lastName: 'Lopez', address1: '1 Main St',
  city: 'New York', stateOrProvinceCode: 'NY', postalCode: '10001', countryCode: 'US',
});

const options = service.getState().data.getConsignments()?.[0]?.availableShippingOptions;
await service.selectShippingOption(options[0].id);

Three ideas run through every SDK flow:

  • State is read-only and observed. You do not change state directly. You call an action (a method that returns a promise), and the service updates its state and calls your subscriber.
  • Selectors read the state. state.data.getCheckout() and similar functions return the current values; state.statuses and state.errors tell you whether an action is running or has failed.
  • The server remains the authority. The SDK calls the Checkout API for you; every address and option you choose is validated and priced on the server, and you display what comes back.

Embedded checkout

For a headless site, the SDK's embed function loads the hosted checkout into a container (read-only):

JavaScript
import { embedCheckout } from '@bigcommerce/checkout-sdk';

embedCheckout({
  url: embeddedCheckoutUrl,        // from the cart's redirect URLs
  containerId: 'checkout',
  onComplete: () => { window.location.assign('/thank-you'); },
  onError: (error) => { console.error(error); },
});

The url comes from the embedded-checkout URL returned when you created redirect URLs for the cart. Your page owns everything around the iframe, and the store owns what is inside it, including the payment form.

Modeling the checkout steps

A checkout is a small state machine: a set of steps, rules for moving between them, and a rule for which steps are complete. Modeling it in plain JavaScript shows why a custom checkout has to be careful. The stand-in below has the steps customer, shipping, billing, payment and complete. A step can only be entered when all earlier steps are complete, a completed step can be edited (which invalidates later steps that depend on it) and subscribers are notified of every change, like the SDK's subscribe.

JS A checkout step state machine

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Paying first is rejected, and each valid change moves the current step forward. The last attempt shows an important rule: after the shipping change, the old payment no longer matches (the total could change), so the machine goes back to the payment step. In a real checkout the totals are recalculated on the server for the same reason.

Payment instruments: what you may and may not touch

Payment is the one place where "build it yourself" can break the law and the store's security. Card numbers must never pass through your own server or even your own JavaScript variables. In BigCommerce's checkout, the card form is rendered by BigCommerce or the payment gateway (often in an iframe or as hosted fields), and your code only receives a token or a result. Read How Online Payments Work and PCI and 3-D Secure before touching any payment code.

In the SDK, you choose a payment method and let the SDK initialize the correct form for it, then submit an order with the payment details the method needs. Methods that redirect to another site (a wallet or bank) or need an extra authentication step (3-D Secure) are handled by the method's own strategy; do not try to reproduce them. When a shopper has saved a card, the SDK returns stored instruments with only safe fields: brand, last four digits, expiry and a token or id.

The second stand-in shows a safe way to present those instruments: mask what you show, check expiry, and never keep or log anything beyond the safe fields.

JS Display stored instruments safely

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The expired Mastercard is shown but marked not selectable, and the log line hides most of the token. The date is fixed at June 2026 so the result is repeatable. The real SDK returns its own instrument objects; use their documented fields, and store nothing more than you need.

Testing and rollout

Treat checkout changes like a payments release:

  • Test every payment method you enable, in test mode, on a sandbox store, on mobile and desktop.
  • Test the failure paths: declined card, expired session, out-of-stock item, coupon removed mid-checkout and slow network.
  • Keep accessibility in mind: error messages must be announced, and focus must move sensibly when steps change.
  • Deploy behind a switch you can flip back (the custom checkout setting makes this possible), and watch orders, abandonment and error rates after launch. For a wider checklist see Testing Apps and Themes.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the lowest-risk way to change a checkout's logo and colors?

    Checkout branding comes from checkout settings. Start with settings and move to code only if a setting cannot do the job.
  2. 2. How do you change state in the Checkout SDK's checkout service?

    State is read-only. Actions such as updateShippingAddress return promises and update the state, which notifies subscribers.
  3. 3. Why should a custom checkout script be configured with a checksum?

    A Subresource Integrity checksum makes the browser refuse a modified file, which protects the checkout from tampering.
  4. 4. What may your code receive from a saved card?

    Card data is handled by the hosted form and the gateway. Your code works with tokens and masked display fields.
  5. 5. Which option fits a headless storefront that does not want to build checkout screens?

    Embedded checkout puts the hosted checkout into an iframe on your page, so you build everything around it, not inside it.

Summary

  • Prefer the lowest rung: settings and styling, then embedded checkout or a Checkout JS fork, and only then your own screens with the SDK.
  • Checkout JS is open source; a custom checkout is a build you host and configure with a checksum.
  • The Checkout SDK exposes a service with read-only state, actions and subscriptions; the server validates and prices everything.
  • Embedded checkout suits headless storefronts: you own the page, the store owns the iframe and payment form.
  • Never handle raw card data; use hosted payment forms, tokens and masked fields.
  • Test every method and failure path, and keep a rollback ready.
  • The state machine and instrument display are stand-ins that model ideas, not the SDK's code.

Next: Payment, Shipping and Tax Providers