Storefront APIs
Introduction
BigCommerce Storefront APIs are tailored specifically to facilitate the actions of shoppers on your storefront. They are generally characterized by a scope of capabilities limited to shopper actions and are streamlined for a front-end use case.
Storefront APIs are also personalized. Unlike with admin APIs, the data storefront APIs expose or consume is bounded by the context of a specific storefront user.
Of special note, a storefront API is not characterized by whether requests are made from a browser or server (the “front-end” or “back-end” of your website). Most of these APIs can be used just as easily in client-side or server-side contexts. Rather, “storefront” refers to API request coverage (facilitating shopper actions) and scope (on behalf of an individual shopper).
The following are common use cases for storefront APIs.
Building Storefronts
Storefront APIs are designed specifically to facilitate front-end shopper interactions. From querying catalog or company data to managing a cart and checkout to authenticating customer credentials, these APIs will be your standard toolkit for interfacing with BigCommerce from your storefront implementation.
Front-end Facing Apps
The GraphQL APIs, in particular, are well suited to any number of front-end use cases, even outside an actual storefront. This could include side apps integrating additional functionality into a storefront, or even other front-end facing applications providing a separate portal for interacting with BigCommerce. While some app use cases might require admin APIs, most of your front-end querying and typical shopper actions can be handled with storefront APIs.
GraphQL Storefront API
The GraphQL Storefront API supports all major facets of the core commerce experience from a shopper perspective.
GraphQL is particularly well suited for storefront implementations, with a predictable type system, an agile syntax for fine-tuning your queries to just the data you need, and the ability to request many resources in a single request.
The GraphQL Storefront API is equally relevant for both Stencil and composable storefront implementations, and it is the core API strategy used in Catalyst.
This API supports catalog, customer, and cart/checkout operations like:
- Fetching core storefront settings like store name, logo, or robots.txt content
- Fetching front-end facing catalog data
- Managing all major steps of a cart/checkout workflow except payment processing
- Registering and authenticating customer accounts
- Fetching an authenticated customer’s details, including address book and order history
Authentication and Customer Context
REST API endpoints are used to generate a normal storefront token or customer impersonation token for authentication with the GraphQL API.
Deprecation notice for normal/storefront tokens: Normal/storefront tokens created after June 30, 2026 will no longer support server-to-server (S2S) requests. Normal/storefront tokens created on or before June 30, 2026 will be able to make S2S calls until March 31, 2027. For server-to-server integrations, use Private Tokens instead.
Customer impersonation tokens facilitate an easy way to provide a customer context for a GraphQL request, but it is recommended to use a normal storefront token with a customer access token instead. See the documentation for more details.
This token is provided as a Bearer token in the Authorization header for all GraphQL requests.
Example Request:
Note that, in contrast with admin APIs, requests to the GraphQL Storefront API are directed to the /graphql endpoint on your own storefront domain. A storefront channel’s canonical URL can also be used, which is particularly helpful for headless storefronts where your primary domain is not pointed at BigCommerce, or in a pre-launch/testing context before a domain has been assigned.
The customer context for a request will affect the data that can be accessed and the data returned — for example, product pricing that reflects a customer group discount. Customer context is established for a given request by providing a unique header with a customer access token or customer ID. See the documentation on authentication for more details.
Context in Stencil and Client-Side Requests
When constructing a GraphQL query within a Stencil storefront, whether in the front matter of a template or in client-side JavaScript, manually creating an authentication token is not necessary, as a token can be obtained from Stencil. The customer context in this case is provided by the customer’s storefront session (tracked via a cookie) rather than with headers.
B2B GraphQL Storefront API
Like the core GraphQL API, the B2B GraphQL Storefront API facilitates core front-end actions, specifically related to B2B Edition data like companies, invoices, and quotes.
The B2B GraphQL Storefront API can be used in Stencil and composable storefronts.
Examples of what you can do with the B2B GraphQL API include:
- Managing a company’s users and address book
- Submitting quote requests
- Initiating a BigCommerce checkout from a quote or for invoice payment
- Initiating a “masquerade” of a particular company for a Super Admin
Authentication and User Context
Some B2B GraphQL operations, like the login mutation that authenticates a user’s BigCommerce customer credentials, are fully anonymous, not requiring a token.
Most operations require a Bearer token that is obtained through the login mutation. In Stencil storefronts, this token can also be obtained with a mutation that requires using the Current Customer API with the B2B Edition client ID.
Example Request:
Since the Bearer token provided is specific to a user, this will establish that user’s context for any request; the data managed or fetched by GraphQL requests will be specific to that user.
Storefront and Authentication APIs for Stencil
A few storefront and authentication APIs rely directly on the integrated session management and unified origin domains characteristic of Stencil storefronts. These APIs are relevant only for client-side requests, and only in a Stencil storefront or other context on the same origin and utilizing the built-in storefront session cookies.
REST Storefront API
The REST Storefront API handles many of the same operations as the GraphQL Storefront API - particularly focused on cart and checkout flow.
The more extensive feature set and streamlined performance of the GraphQL Storefront API usually make it the better choice for front-end applications. However, a good understanding of the REST Storefront API is essential for customizing BigCommerce checkout with Checkout JS.
The REST Storefront API uses CORS headers-based authentication and relies on requests coming from the same origin as the BigCommerce endpoints. The built-in storefront session provides the customer context.
Example Request:
Customer Login API
The Customer Login API supports single sign-on use cases by allowing a trusted application to log in a specific BigCommerce customer in the Stencil storefront session, bypassing the need for the user to enter their credentials.
This API endpoint relies on the client ID and secret of an API account authorized for the store, to facilitate secure and trusted communication between BigCommerce and the originator of the request.
See the documentation for more details.
Current Customer API
The Current Customer API verifies the identity of and provides information about the currently logged-in user on a Stencil storefront, allowing trusted applications to access and use details about the customer.
Like the Customer Login API, the Current Customer API relies on the client ID and secret of an API account authorized for the store, ensuring that the details returned by the BigCommerce endpoint are trusted.
See the documentation for more details.
