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?

I want to use BigCommerce headlessly with little or no coding.
I want to build a custom solution, but I don’t want to code it from scratch.
I want to extend an existing solution or build one from scratch.

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.

Multisite

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 (medium.com).

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:

Use BigCommerce’s Sites and Routes API to create redirects from BigCommerce hosted pages back to the non-BigCommerce storefront (recommended).
Hide non essential pages by removing the back links in Cart and Checkout
Add a JavaScript redirect on all pages (except /checkout) that redirects to the non-BigCommerce storefront
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.
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 backend¹	Responsible for the PCI DSS compliance requirements applicable stated in BigCommerce as a storefront or BigCommerce as a backend¹
Checkout and Payments API	Responsible for the PCI DSS compliance requirements applicable stated in BigCommerce as a storefront or BigCommerce as a backend¹	Responsible for the PCI DSS compliance requirements applicable stated in BigCommerce as a storefront or BigCommerce as a backend¹

Note

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 compliance@bigcommerce.com.

Sample API workflows

Creating orders from a cart

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
Add a Billing Address to the Cart changing it to a Checkout
Add a Consignment to Checkout with the line items and the consignments.available_shipping_options query
Update each Consignment with the chosen shipping option from the Add Consignment response.
Create the Order by sending a request to Create Order
1. Returns an order_id
2. Order is created in incomplete status
Take a Payment for the Order using one of the two methods below

Create an Order Directly

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
Take a Payment for the Order using one of the two methods below
Vaulted Card – The shopper has saved a credit card
Credit Card – The shopper has not saved a credit card
1. Create Access Token
2. Process Payment