Management APIs
Building Apps
Quick Start
Building Channels
Quick Start
Building Headless Storefronts
Embedded Checkout
Next.js Commerce
Managing Currencies
Partner Information
Becoming A Partner
Getting Started
Staying Current with Platform Changes
POS Solutions
ERP Solutions
PIM Solutions
OMS Solutions
Marketing Solutions
Shipping Solutions
Payment Solutions

Developers Guide to Headless Commerce

This article provides a high level guide to using BigCommerce to power headless storefronts; we’ll assume you’re already familiar with headless commerce as a concept; if you’re not, check out our whitepaper, A New Era of Ecommerce: Headless Commerce or the Help Center’s Headless Commerce Guide.

Ways to implement headless

Which headless approach fits your business requirements?

Pre-built solutions

Want to build a headless storefront powered by a BigCommerce back-end, but don’t want to write a bunch of code? Use one of the pre-built headless storefront solutions below.

Solution Method of Integration Platform Type
BigCommerce for Wordpress WordPress Plugin WordPress CMS
BigCommerce for Drupal Drupal Module Drupal CMS
Bloomreach BigCommerce App Bloomreach CMS / DXP
DEITY Falcon BigCommerce App DEITY Falcon PWA
Sitrecore Extend BigCommerce App Sitecore CMS

Note. CMS = Content Management System; DXP = Digital eXperience Platform; PWA = Progressive Web App.

See more headless solutions and tools.

Starter apps

Need code up a custom storefront but don’t want to start from scratch? Kick-start your development with one of the following starter apps.

Starter Stack
gatsby-bigcommerce-netlify-cms-starter Node / React / Gatsby / Netlify
bc-nuxt-vue-starter Node / Vue / Nuxt
acf_bc PHP / ACF / Drupal
Next.js Commerce Node / Next / React

See more headless starter apps and tools.

Custom solutions

Need to build a custom solution from scratch? BigCommerce has APIs, SDKs, and toolkits to help you do whatever you need, headlessly.

Storefront channels

Want to market your headless storefront as an app in BigCommerce’s control panel? Use Channels Toolkit to install a storefront channel into Channel Manager during the single-click app installation process.

Channel Manager

Learn how to build a storefront channel.


Use BigCommerce as the back-end for several stores. By placing an application layer between the storefront and the APIs, the application can control which catalog information is pushed to which storefront.

Learn more about multisite ecommerce with WordPress and BigCommerce (

Catalog Management

Using the Catalog API you can return product data to your product details page and product listing page.

Sync the catalog

Best practice is to get product details and cache them in a database to display them. This will speed up the application and allow you to control what information is shown to the customer. Caching the details also lets you implement search in your application.

Real time catalog

If your catalog is changing all the time, you can use the Catalog API to return real time product information.

Real time pricing and inventory

If you prefer working with a local copy of your data, but want to make sure that high priority pieces of data like pricing and inventory are always up to date, you can consider a hybrid model. A hybrid model would cache only certain product details and pull the other information in real time. BigCommerce has webhooks that you can use for listening to store events.

Cart management

Use the Server to Server Cart API to create carts for existing customers and guest customers.

Guest Cart

A guest cart assumes the shopper is not a customer and is not logging in or creating an account during checkout. Handle guest checkouts by displaying the cart data to the customer and then moving them to Checkout using the Checkout API.

Content management system

Using a CMS is a good way to offer a custom shopper experience without needing build a content engine as well. The CMS needs to have a database so catalog information can be stored and retrieved and a way to store accounts. The BigCommerce WordPress plugin loads the catalog into the database while using an embedded checkout to display cart and checkout details to customers.

Checkout management

Use the Checkout API to move the cart to checkout and turn an existing checkout into an order.

Redirect to a BigCommerce checkout

When creating a cart, there is an optional query to create a redirect URL. Use this to redirect the shopper to a BigCommerce hosted checkout page.

If you are using the hosted checkout option, shoppers will be able to navigate to other pages of the store. Here’s a few methods to prevent this:

  1. Use BigCommerce’s Sites and Routes API to create redirects from BigCommerce hosted pages back to the non-BigCommerce storefront (recommended).
  2. Hide non essential pages by removing the back links in Cart and Checkout
  3. Add a JavaScript redirect on all pages (except /checkout) that redirects to the non-BigCommerce storefront
  4. Wrap all content in the theme’s layouts in a conditional that only renders the BC storefront if certain conditions are met (like an admin customer group, for example), and redirect to the non-BigCommerce storefront otherwise.
  5. Replace all content in theme layout files with a redirect to the non-BigCommerce storefront

To customize the checkout when using a redirect URL, use our Checkout SDK. The Checkout JS SDK is a library of methods for interacting with the checkout page’s underlying Storefront Checkout API, allowing you to build a custom checkout page UI in the framework of your choice.

Checkout API

If you need complete control over the checkout page, you have the option to build an external checkout in your CMS or app using the server-to-server Checkout API. Then use the Payments API to process a payment through BigCommerce to take payment for the order. If you are using the Payments API, you are responsible for PCI compliance.

Customer login

Associate cart with a customer

If a shopper creates a cart as a guest then logs into the store, you can use the following process to associate the cart to the customer and log them in at the same time. The Server to Server Cart API is used since it allows for the front end to be bypassed when creating a cart.

When a cart is created, your app should store the cart_id. The cart_id is used to generated a redirect_url. Using the Customer Login API set the redirect_to parameter as the generated cart or checkout redirect url. This will both log the customer in and show them either the cart or checkout depending on which url was used. To make sure the cart is matched to the right customer you should compare the entered email address to what is the store’s database.

To populate the customer_id on the cart with the correct data, use the email address entered to match against the Customers API. If the email address matches what the customer input and what is in the BigCommerce database then proceed with login. If a match is not found then direct the customer to a sign up screen.

Creating a new customer

Our WordPress plugin uses the approach of using the Customer API to validate the password against what is stored in BigCommerce.

If a new account is created in WordPress, the password is written to the customer account in BigCommerce and used as the validation in future requests. The password is never stored in the WordPress database. You can match customers using the email address and the Customers API.

Sample integration

In the diagram below, the Storefront is any location the products are being rendered and where the shopper browses for products. With headless the storefront can be a CMS or an app. The Application is making API calls to BigCommerce in order to perform certain actions and return data either to display to the shopper or pass it along to another system. BigCommerce is creating the order and processing payments so you don’t need to worry about building the infrastructure.

Sample Headless Integration

Entity Description
Storefront The front end presentation layer where a shopper interacts with products. In a headless architecture, the storefront might be a CMS, native mobile app, kiosk, static site, or any other front end solution you can imagine. The BigCommerce WordPress plugin is built using an existing CMS and injecting a stores catalog. Any CMS that accepts custom integrations can be used. Another option is to build a storefront from scratch using a framework such as Gatsby.
Application Solution built by developer to control the requests and responses from the BigCommerce APIs. In addition to handling essential ecommerce tasks like requesting product information or sending the request to process a payment, the application layer can also handle logic for custom functionality, like presenting discount codes based on a shopper’s history or pre filling details on the checkout page.
BigCommerce BigCommerce will respond to the application with the requested data to power the backend ecommerce functionality. It can handle processing payments, storing customer data, retrieving the catalog and order information.

Managing access to your Stencil site

Once you transition to a headless setup and are no longer using your Stencil storefront, make sure to redirect shoppers to your new frontend by changing your custom domain’s nameservers. Also, make sure that your unused Stencil storefront is inaccessible to both search engines and shoppers. To prevent search engines from crawling and indexing your Stencil storefront, edit your robots.txt file to disallow all robots. To prevent shoppers from accessing your Stencil storefront’s permanent URL, Set Store as Down for Maintenance with a custom message directing shoppers to your new frontend.

PCI compliance

BigCommerce offers different avenues or channels for integration, depending on your business needs. The ultimate responsibility of PCI compliance lies with you and takes into consideration the architecture of your e-commerce store and multiple channels of integrations. BigCommerce is a PCI DSS compliant service provider and certifies annually all requirements (1-12) including as a shared hosting provider.

The BigCommerce PCI DSS attestation of compliance (AOC) outlines the description of the technology stack certified annually.

Merchants can use BigCommerce’s PCI DSS AOC to satisfy the compliance requirements for the part that outlines its responsibilities.

Responsibility matrix

BigCommerce Responsibility Merchant Responsibility
BigCommerce as a storefront and backend Responsible for all PCI DSS requirements (1-12) of the product to the point that it has control of Merchants stores. Responsible for ensuring that all modifications that result in external calls to, or integrations with outside parties are done in a PCI DSS compliant manner.
Responsible for ensuring all design modifications are done in a PCI DSS compliant manner.
Responsible for ensuring that all service providers it uses are compliant with PCI DSS.
BigCommerce as a backend for example headless integrations or the BigCommerce WordPress Plugin. Responsible for all PCI DSS requirements from the point at which cardholder data is handed to a BigCommerce controlled interface (see BigCommerce Attestation of PCI DSS 2019-2020). Responsible for the PCI DSS compliance of its storefront plus all of the above.
Checkout and Payments SDK Responsible for the PCI DSS compliance requirements applicable stated in BigCommerce as a storefront or BigCommerce as a backend1 Responsible for the PCI DSS compliance requirements applicable stated in BigCommerce as a storefront or BigCommerce as a backend1
Checkout and Payments API Responsible for the PCI DSS compliance requirements applicable stated in BigCommerce as a storefront or BigCommerce as a backend1 Responsible for the PCI DSS compliance requirements applicable stated in BigCommerce as a storefront or BigCommerce as a backend1


  1. The way your business consumes the SDKs (either BigCommerce as a storefront and backend or BigCommerce as a backend ) determines BigCommerce’s responsibilities; It is possible to use one more of BigCommerce’s technology stack at the same time. Your PCI DSS compliance responsibilities will be a combination of each stack consumed.

If your application handles credit card data, it must be PCI Compliant. self-assessment questionnaires can be submitted to

Sample API workflows

Creating orders from a cart

  1. Create a Cart with a redirect url
    1. Add the Customer ID or leave blank if shopper is a guest
    2. Add Line Items or Custom Line Items
  2. Add a Billing Address to the Cart changing it to a Checkout
  3. Add a Consignment to Checkout with the line items and the consignments.available_shipping_options query
  4. Update each Consignment with the chosen shipping option from the Add Consignment response.
  5. Create the Order by sending a request to Create Order
    1. Returns an order_id
    2. Order is created in incomplete status
  6. Take a Payment for the Order using one of the two methods below

Create an Order Directly

  1. Send a request /POST request to Orders
    1. Make sure the status_id is 0
    2. Add the Customer ID or leave blank if the shopper is a guest
    3. Add Line Items or Custom Line Items
    4. Add a Billing Address
    5. Add a Shipping Address
    6. Create a custom shipping quote
  2. Take a Payment for the Order using one of the two methods below
  3. Vaulted Card – The shopper has saved a credit card
    1. Get Payment Methods
    2. Create Access Token
    3. Process Payment
  4. Credit Card – The shopper has not saved a credit card
    1. Create Access Token
    2. Process Payment

Related resources