Introduction to Headless Commerce

This is the first article in a comprehensive developer's guide to using BigCommerce as a commerce backend for headless storefronts. If you are not familiar with headless commerce as a concept, start by reviewing our whitepaper, A New Era of Ecommerce: Headless Commerce (opens in a new tab), or the Help Center's Headless Commerce Guide (opens in a new tab).

Ways to implement headless commerce

If you want to build a headless storefront powered by a BigCommerce backend without starting from scratch, BigCommerce offers multiple starter apps and pre-built solutions. For headless storefront solutions and tools, see Headless Integrations.

If you need to build a custom solution, BigCommerce has APIs and SDKs available to support your headless architecture. For specific use cases, see the following sections of the guide:

Sample integration

In the diagram below, the storefront is where the shopper interacts with products through a UI. With headless commerce, the storefront can be a CMS or an app. The application makes API calls to BigCommerce to perform specific actions and return data either to display to the shopper or to 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 frontend 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 frontend solution you can imagine. The BigCommerce for WordPress plugin is built by using an existing CMS and injecting a store's catalog. You can use any CMS that accepts custom integrations. Another option is to build a storefront from scratch using a framework such as Gatsby (opens in a new tab).
`Application`	A solution built by a developer to control the requests and responses from 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 the 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, and retrieving the catalog and order information.

Correlating requests

Completing an operation on a headless storefront may require several API calls. For example, processing a payment and refunding an order each require reading and writing information using multiple endpoints. When you perform a multi-part operation on a headless storefront, group the constituent requests by generating one UUID to represent the whole operation, then use the X-Correlation-Id request header to send that UUID with every request in the group. The value you pass to the X-Correlation-Id header should be a UUID-type string you generate independently. This indicates to BigCommerce's infrastructure that an API call is part of a larger operation, and helps us track the handoff from request to request as the operation moves through our servers. To learn more about the header, see our list of request headers.

When you're using the BigCommerce for WordPress plugin, there is no need to send the X-Correlation-Id header.

The following example uses the GraphQL Storefront API to complete a checkout and generate a payment access token, then uses that payment access token to make the payment using the Payments API.

Example request, GraphQL Storefront

  POST https://store.example.com/graphql
  Accept: application/json
  Content-Type: application/json
  # Customer impersonation token
  Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
  # Correlation header matches next request
  X-Correlation-Id: a7d28ca2-d4b2-4dc8-9f07-0706c431a372

Example mutation: Complete checkout

  mutation completeCheckout($completeCheckoutInput: CompleteCheckoutInput!) {
    checkout {
      completeCheckout(input:$completeCheckoutInput) {
        orderEntityId
        paymentAccessToken
      }
    }
  }

GraphQL variables

  {
    "completeCheckoutInput": {
      "checkoutEntityId": "812ece1a-da23-46eb-ab6b-c2ee210aae54"
    }
  }

Example request: Process a payment

  POST https://payments.bigcommerce.com/stores/{{STORE_HASH}}/payments
  Accept: application/vnd.bc.v1+json
  Content-Type: application/json
  # Payment access token from the GraphQL Storefront API response
  Authorization: PAT eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2ODU3MjQwMzQsIm5iZiI6MTY4NTcyMDQzNCwiaXNzIjoicGF5bWVudHMuYmlnY29tbWVyY2UuY29tIiwic3ViIjoidmpid3FiYWJwMSIsImp0aSI6IjAzODU3ODk2LTdkY2YtNDIzNi04OTQ5LWU0MjcyYWU3ZGZjMSIsImlhdCI6MTY4NTcyMDQzNCwiZGF0YSI6eyJzdG9yZV9pZCI6IjEwMDI4ODA3NDYiLCJvcmRlcl9pZCI6IjEwNiIsImFtb3VudCI6MjUwMCwiY3VycmVuY3kiOiJVU0QifX0.iiJ96cYKtk2-oLRXvZHs1lWUl9v8JkEkCdHShbyfEK4
  # Correlation header matches previous request
  X-Correlation-Id: a7d28ca2-d4b2-4dc8-9f07-0706c431a372
 
  {
    "payment": {
      "instrument": {
        "type": "stored_card", // type from Get Payment Methods
        "token": "050a1e5c982e5905288ec5ec33f292772762033a0704f46fccb16bf1940b51ef", // token from Get Payment Methods
        "verification_value": "900" // card CVV/CVC, if Get Payment Methods indicates it's required
      },
      "payment_method_id": "stripe.card" // id from Get Payment Methods
    }
  }

Next step

Learn how to create a channel and a channel site

Resources

Did you find what you were looking for?

Changelog REST Management API: Headless checkout flow