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:

• Create a channel and a channel site
• Fetch and manage product data
• Create a cart
• Move a cart to checkout
• Log in a customer
• Create an order
• Learn about PCI compliance

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.

Trusted proxy enablement

Trusted proxy enablement is a feature that allows you to use a custom proxy to send requests to your stores. This feature benefits headless merchants and merchants behind a proxy because it enables BigCommerce to honor the true-client-ip header the proxy passes during the session. Otherwise, when the requests are passed from the head/proxy to BigCommerce, all our systems can see is the IP of the middleware. This structure makes it difficult for BigCommerce to differentiate between traffic sources at the external edge. It may lead us to limit certain aspects of the connection during periods of high traffic.

Headers

• X-BC-Trusted-Proxy-Secret: The value of the secret the rundeck task generates. BigCommerce uses it to validate that the request comes from a trusted proxy.

• True-Client-IP: The IP address passes from the customer's (shopper's) browser to an intermediary. This requires configuration on the merchant's end to set this header appropriately.

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.

  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

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

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

  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