Storefront vs. Management API

BigCommerce's API surface is split along a trust boundary: code that runs in a shopper's browser gets a deliberately limited, session-scoped API, while code that runs on a trusted backend gets a fuller, authenticated one. Knowing which side a task belongs on is one of the first design decisions in any BigCommerce integration.

The Storefront API

The Storefront API is what a theme's own JavaScript calls directly — updating the cart, applying a coupon code, fetching current checkout state. Calls made this way rely on the browser already being on the store's own domain and holding the shopper's session cookie, rather than a separate credential the JavaScript has to manage itself:

fetch('/api/storefront/carts/' + cartId + '/items', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    lineItems: [{ productId, quantity: 1 }]
  })
});

The Management API

The Management API is authenticated with an API account's access token and used from a trusted backend — a custom app, an integration syncing inventory with an external system, or an admin script. It can create products, modify orders, and perform operations no shopper-facing code should ever be able to trigger. It's mainly known as a REST API, but BigCommerce also offers a newer GraphQL Admin API covering a growing subset of the same store-management operations, for teams that would rather query and mutate store data through GraphQL than a REST resource per endpoint:

GET /stores/{store_hash}/v3/catalog/products
Host: api.bigcommerce.com
X-Auth-Token: {access_token}

Why the split exists

Embedding a Management API token in browser JavaScript would expose it to anyone who opens dev tools — a straightforward way to leak full store access. Splitting the APIs means the browser only ever holds a narrow, session-scoped capability, while anything more powerful stays server-side where a token can be kept secret.

GraphQL Storefront API

Beyond the REST-shaped Storefront endpoints used for cart updates, BigCommerce also offers a GraphQL Storefront API, useful when a page needs several related pieces of data (a product plus its reviews plus related products) in a single request instead of several separate REST calls. Rather than relying on the browser's session cookie the way the REST Storefront endpoints do, GraphQL Storefront API requests are authenticated with a short-lived token BigCommerce issues to the storefront — the mechanism a headless frontend like Catalyst is built on:

query {
  site {
    product(entityId: 123) {
      name
      prices { price { value currencyCode } }
      reviewSummary { numberOfReviews averageRating }
    }
  }
}

API accounts and scopes

A Management API token comes from creating an API account in the control panel (or, for an installable app, through the OAuth flow covered in lesson 8), where specific scopes are granted per resource — read-only access to products, write access to orders, and so on. As with any platform, a token should only ever be granted the narrowest set of scopes a given integration actually needs.