Cart & Checkout

Unlike a plain form-based add-to-cart, BigCommerce's Stencil themes drive the cart primarily through the Storefront API from JavaScript. Checkout is more locked down by default, but BigCommerce actually offers a wider range of ways to customize it than a single fixed extension point — from small content tweaks up to replacing the whole thing.

Adding to cart

fetch('/api/storefront/carts', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    lineItems: [{ productId, quantity: 1, optionSelections: selectedOptions }]
  })
})
  .then(res => res.json())
  .then(cart => updateCartIcon(cart));

If a cart doesn't exist yet for the current session, this call creates one; if it does, subsequent updates go to /api/storefront/carts/{cartId}/items instead.

Displaying cart contents

A cart preview or drawer typically renders from the JSON response of these same Storefront API calls rather than a server-rendered Handlebars template — the cart's contents change through client-side interaction more than page loads, so JavaScript owns that part of the UI in most themes.

Promotions and coupon codes

A coupon code is applied to an existing cart through its own Storefront API endpoint, and the response reflects the discounted totals immediately — a theme doesn't calculate the discount itself, it just displays whatever the API returns:

fetch(`/api/storefront/carts/${cartId}/coupons`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ couponCode: 'SAVE10' })
})
  .then(res => res.json())
  .then(cart => updateTotals(cart));

The checkout customization spectrum

How much of checkout you can touch depends on how far you're willing to go. At the light end, a theme can inject custom content and scripts into the standard checkout at defined points — a trust badge, a tracking pixel, a short message — without changing how checkout actually works. One step further, BigCommerce publishes an open-source reference checkout that a developer can fork as a starting point for moderate visual or flow changes, rather than building from nothing. Beyond that sits the Checkout JS SDK, a client-side library that wraps the underlying calls needed to move a shopper through checkout — signing in, fetching shipping quotes, submitting payment — so a fully custom checkout page doesn't have to reimplement that logic by hand:

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

const service = createCheckoutService();
const { data } = await service.loadCheckout(checkoutId);
console.log(data.getCheckout());

The SDK trades some flexibility for that convenience — it can filter which of a store's existing shipping and payment methods are shown, but it can't introduce entirely new ones. A store that needs that level of control instead builds checkout directly against the raw GraphQL or REST Storefront API, with no SDK abstraction in between, which is the most work but the fewest constraints.

Cart persistence and recovery

Because the cart lives server-side and is addressable by ID, BigCommerce can support features like cart recovery emails without any special theme code — the cart simply persists and can be resumed later by its ID, independent of whatever browser or device the shopper returns on.