Headless commerce decouples the front end from the ecommerce platform that powers it, allowing developers to build flexible and content-rich storefronts. BigCommerce provides APIs for the Catalog, Cart, Checkout, Orders, Customers, Authentication and Payments. The APIs can be plugged into an existing CMS or website for flexible content management. BigCommerce used this approach to create our WordPress Plugin. The WordPress Plugin allows for a developer to take advantage of WordPress content management while using our APIs to manage the catalog and shopper checkout. For a deeper guide on Headless, see our Whitepaper, A New Era of Ecommerce: Headless Commerce.


With headless, developers can 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. To learn more about Multisite, see Multisite Ecommerce with WordPress and BigCommerce.

In this article we will review ways you can implement headless, what requires PCI compliance audits and go through sample workflows for cart and checkout.


To use the BigCommerce platform for headless commerce, you must have a store on an active plan. The store does not need to be launched.

Ways to Implement Headless

There are many ways to implement headless commerce. Below are just a few ways to start with Headless commerce.

  • Use our Wordpress Plugin to leverage a custom CMS powered by the BigCommerce Catalog, Cart and Checkout APIs.
  • Create a custom shopper experience by creating your own storefront and checkout using our APIs to manage the Catalog, Cart, Checkout and Payments.
  • Use the BigCommerce storefront with a customized checkout using the Checkout SDK.

Below are ways to manage the catalog, cart and checkout. With the flexibility of using APIs, you can use one or all the options for a store.

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 + 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 BigCommerce has webhooks 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. To prevent this, there are two options:

  • Hide non essential pages by removing the back links in Cart and Checkout.
  • Edit the theme files to hide the other pages from all visitors except for those who need to see them for maintenance. The steps to edit the theme files are outlined below.

Edit the schema.json file

Edit the schema.json file
Add the following object to the settings array
  "name": "Administrators",
  "settings": [
      "type": "text",
      "label": "Administrator Emails (separated by commas)",
      "id": "admin_emails"

Edit the config.json file and add "admin_emails": "" to the settings object. Add the emails to the object that should have access to all store pages.

Modify the following pages to gate all pages except checkout, order confirmation, down for maintenance, and order invoices:

  • layout/amp-iframe
  • layout/amp
  • layout/base

Add the following conditional wrapper to each page:

Conditional Wrapper
{{#contains theme_settings.admin_emails customer.email}}
<-- page content -->
<-- display login form -->

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.


The storefront is 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.


The application is what a developer builds 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 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.

Sample Headless Integration
Sample Headless Integration

PCI Compliance

When handling customer information PCI compliance can be complicated and expensive. It is important to know that you are responsible for the PCI compliance of your storefront outside of BigCommerce. We make this easier for you by ensuring our endpoints are PCI DSS compliant at all times.

If you want to avoid your own PCI compliance audits use one of the following:

  • Checkout SDK
  • WordPress plugin

Both of the above are PCI compliant. If you call any external JavaScript, make AJAX requests or use any service on the Checkout that is not provided by BigCommerce you will be responsible for compliance audits. This includes adding scripts to the Checkout SDK and Wordpress plugin.

Using the APIs directly including the Payments API and Server to Server Checkout API will require you to be responsible for your own PCI compliance audits as well.

To learn more abohout what PCI Compliance is, see our support article, PCI Compliance.

If your application handles credit card data, you will need to be PCI Compliant. SAQs (self-assessment questionnaires) can be submitted to compliance@bigcommerce.com.

Sample API Workflows

Below are example workflows that list which APIs are needed to create a Cart, Checkout and Order on BigCommerce. Our headless implementation is based on the Server to Server Cart and Checkout APIs. There are currently two ways to handle this:

  • Create an order from a cart
  • Creating an order directly to bypass the cart and checkout

Create an Order from a Cart

Run in Postman

  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
  7. Vaulted Card – The shopper has saved a credit card
    1. Get Payment Methods
    2. Create Access Token
    3. Process Payment
  8. Credit Card – The shopper has not saved a credit card
    1. Create Access Token
    2. Process Payment

Create an Order Directly

Run in Postman

  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