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, or the Help Center’s Headless Commerce Guide.

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 Configuration

Overview

The Trusted Proxy feature allows merchants to set up authenticated proxy servers in front of BigCommerce. When properly configured, BigCommerce will use the end user’s actual IP address instead of the proxy’s IP address, enabling more accurate traffic management and improved security.

How It Works

1. Merchant sets up a proxy server in front of BigCommerce
2. BigCommerce provides a secret key to the merchant
3. Proxy server includes two required headers in all requests:
   • A secret key to authenticate the proxy
   • The remote user’s original IP address

Required Headers

Implementation Steps

1. Contact BigCommerce support to receive your trusted proxy secret
2. Configure your proxy server to:
   • Include the secret in the X-BC-Trusted-Proxy-Secret header
   • Extract the remote user’s IP address
   • Pass the remote user’s IP in the True-Client-IP header

Technical Notes

• All headers must be included with every request
• The proxy secret should be kept secure and not exposed publicly
• Invalid or missing headers will cause requests to be treated as coming from the proxy IP

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.

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

1
  mutation completeCheckout($completeCheckoutInput: CompleteCheckoutInput!) {
2
    checkout {
3
      completeCheckout(input:$completeCheckoutInput) {
4
        orderEntityId
5
        paymentAccessToken
6
      }
7
    }
8
  }

1
  {
2
    "completeCheckoutInput": {
3
      "checkoutEntityId": "812ece1a-da23-46eb-ab6b-c2ee210aae54"
4
    }
5
  }

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

Headless/GraphQL account login

BigCommerce has introduced a feature that leverages the Customer Access Token for seamless redirection, logging in customers automatically when they reach checkout from the storefront. Built with JWT-based “Session Sync,” this enhancement enables transferring session details, such as customer and cart data, across various contexts. Developers can use GraphQL API for advanced session syncing, ensuring a smoother, cohesive experience for customers across platforms.

The following examples demonstrate how to sync and validate session details for headless storefronts and hosted checkouts.

# Returns JUST a JWT, *not* a URL
# Can "sync" any arbitrary combination of parameters
# e.g., just sync analytics ID, just sync customer ID, just sync analytics + customer, etc
# Designed to be used omni-directionally
# e.g., headless -> stencil, stencil-> headless, headless->headless, stencil->stencil
mutation GenerateSessionSyncJwt ($redirectTo: String!,$cartId: String,$visitorId: String,$ipAddress: IpAddress){
   generateSessionSyncJwt(redirectTo:$redirectTo,cartId: $cartId, visitorId: $visitorId, ipAddress: $ipAddress){
      result {
        token
        url
        }
     }
  }

Persisting analytics session IDs

The GraphQL API supports including a visitor ID when creating a session sync JWT using the generateSessionSyncJwt mutation, enhancing tracking consistency across different contexts. The visitor ID acts as a unique identifier that links a user’s activity across multiple storefronts, ensuring that analytics session IDs remain persistent as users move across various parts of the storefront (e.g., Catalyst to Stencil) and other digital touchpoints.

Including a visitor ID in session sync requests helps maintain a cohesive session structure, providing more accurate insights into customer behavior. This is especially valuable for businesses leveraging analytics tools to track user interactions across headless storefronts, native checkouts, and other platforms.

Multi-Language support

After October 2025, new headless stores will have access to Multi-language features similar to Catalyst storefronts.

Next step

• Learn how to create a channel and a channel site