Developers Guide to Headless Commerce

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.

Multisite

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.

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 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.

Storefront

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.

Application

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

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

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.

Integrations with BigCommerce and 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	Not Responsible The way your business consumes the SDKs (either BigCommerce as a storefront and backend or BigCommerce as a backend ) would determine BigCommerce’s responsibilities.	Responsible for the PCI DSS compliance requirements applicable stated in BigCommerce as a storefront or BigCommerce as a backend. The way your business consumes the SDKs (either BigCommerce as a storefront and backend or BigCommerce as a backend ) would determine BigCommerce’s responsibilities.
Checkout and Payments API	Not Responsible* The way your business consumes the SDKs (either BigCommerce as a storefront and backend or BigCommerce as a backend ) would determine BigCommerce’s responsibilities.	Responsible for the PCI DSS compliance requirements applicable stated in BigCommerce as a storefront or BigCommerce as a backend. The way your business consumes the SDKs (either BigCommerce as a storefront and backend or BigCommerce as a backend ) would determine 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.

Additional Resources

• Merchants Classification Levels Visa
• Merchants Classification Levels Mastercard
• Self Assessment Questionaire (SAQ) Types and Identifying which SAQ is for you

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

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
   3. Returns an order_id
   4. 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
   5. Get Payment Methods
   6. Create Access Token
   7. Process Payment
8. Credit Card – The shopper has not saved a credit card
   8. Create Access Token
   9. Process Payment

Create an Order Directly

1. Send a request /POST request to Orders
   2. Make sure the status_id is 0
   3. Add the Customer ID or leave blank if the shopper is a guest
   4. Add Line Items or Custom Line Items
   5. Add a Billing Address
   6. Add a Shipping Address
   7. 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
   8. Get Payment Methods
   9. Create Access Token
   10. Process Payment
4. Credit Card – The shopper has not saved a credit card
   9. Create Access Token
   10. Process Payment

Resources

Tools

• Cart, Checkout and Order Postman Collection
• Checkout SDK
• WordPress Plugin (WordPress Plugin Directory)

Related Endpoints

• Catalog API
• Server to Server Checkout API
• Server to Server Cart API
• Orders API
• Payments API
• Customers API
• Validate Customer Password

Related Articles

• Orders API
• Customers Overview
• Customer Login API
• Launching your store (BigCommerce Support)
• PCI Compliance (BigCommerce Support)
• Multisite Ecommerce with WordPress and BigCommerce (BigCommerce Developers Blog)
• Matter Makes Waves with a Headless Build using BigCommerce for WordPress (BigCommerce Developers Blog)
• New Era in Headless CaaS (BigCommerce Whitepaper)
• BigCommerce Doubles Down on Headless Commerce with BloomReach, Sitecore, Adobe Experience Manager, and More (BigCommerce Blog)

Additional Resources

• Merchants Classification Levels Visa (Visa USA)
• Merchants Classification Levels Mastercard (Mastercard)
• Self Assessment Questionaire (SAQ) Types and Identifying which SAQ is for you (PCI Security Standards)
• Maintaining Payment Security (PCI Security Standards)