Developers Guide to Headless Commerce
On this page
This article providers 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 Healdess 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 |
---|---|---|---|
DEITY Falcon | BigCommerce App | DEITY Faclon | PWA |
Bloomreach | BigCommerce App | Bloomreach | CMS / DXP |
Sitrecore Extend | BigCommerce App | Sitecore | CMS |
BigCommerce for Wordpress | WordPress Plugin | WordPress | CMS |
BigCommerce for Drupal | Drupal Module | Drupal | CMS |
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 |
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.
- Create storefront channels with the Channels API..
- Mannage sites and routes for headless storefronts with the sites and routes API.
- Manage 301 redirects for one or more storefronts with Redirects V3 API
- Create storefront specific product listings with the Channels API.
- Query storefront data with GraphQL.
- Use customer impersonation tokens to query data specific to the shopper.
- Create carts with the Server-to-Server Carts API.
- Fetch and display abandoned cart information using the Abandoned Carts API.
- Create and manage shopper wishlists with the Wislists API
- Manage product data with the Catalog API.
- Embed BigCommerce’s checkout in an iFrame with Embedded Checkout.
- Redirect to BigCommerce’s hosted checkout using the Server-to-Server Checkout API
- Create custom BigCommerce hosted checkout pages from scratch using Checkout SDK.
- Create a custom BigCommerce hosted checkout from a fork of BigCommerce’s Checkout-JS.
- Build a custom checkout experience from scratch using the Server-to-Server Checkout API.
- Restyle the BigCommerce hosted checkout.
- Process payments using the Payments API.
- Manage orders with Orders V2 and V3 APIs.
- Use webhooks to get notified when specific events occur in BigCommerce.
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.
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.
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. |
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 |
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
- Add the Customer ID or leave blank if shopper is a guest
- 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
- Returns an
order_id
- Order is created in
incomplete
status
- Returns an
- Take a Payment for the Order using one of the two methods below
Create an Order Directly
- Send a request /POST request to Orders
- Make sure the
status_id
is 0 - Add the Customer ID or leave blank if the shopper is a guest
- Add Line Items or Custom Line Items
- Add a Billing Address
- Add a Shipping Address
- Create a custom shipping quote
- Make sure the
- 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
Related resources
Articles
- Customers Overview
- Customer Login API
- Launching your store
- PCI Compliance
- Multisite Ecommerce with WordPress and BigCommerce
- Matter Makes Waves with a Headless Build using BigCommerce for WordPress
- New Era in Headless CaaS
- BigCommerce Doubles Down on Headless Commerce with BloomReach, Sitecore, Adobe Experience Manager, and More
- Merchants Classification Levels Visa
- Merchants Classification Levels Mastercard
- Self Assessment Questionnaire (SAQ) Types and Identifying which SAQ is for you
- Maintaining Payment Security
Endpoints
- Catalog API
- Server to Server Checkout API
- Server to Server Cart API
- Orders API
- Payments API
- Customers API
- Validate Customer Password