Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 28 ยท Getting Started

Platform Architecture

Understand BigCommerce architecture: stores, channels and storefronts, the catalog, order and customer domains, REST V2/V3 and GraphQL APIs, and multi-storefront.

Before you write code against a platform, you need a map of it. BigCommerce has a small number of big ideas: a store that owns the data, channels that sell that data, a set of domains (catalog, orders, customers and others), and several API surfaces that expose them. Once you can place a feature on this map, the documentation becomes much easier to navigate.

This lesson draws the map. The real platform cannot run here, so the runnable example is a small Node.js model of channels and catalog assignment. It is a teaching model of the idea, not BigCommerce's code, and we say where it differs.

Store, hash and control panel

A store is one merchant's account on the platform. It has a store hash, a short string such as abc123xyz that appears in API URLs: https://api.bigcommerce.com/stores/{store_hash}/v3/.... Every API call is made against exactly one store, and every token belongs to exactly one store (apps get one token per installing store).

The control panel is the merchant's admin web interface. Everything a merchant can click there is, in general, also reachable through an API, but not always on the same day and not always in the same shape. When you hit a missing feature, check whether it is control-panel-only before you design around it.

Channels and storefronts

Modern BigCommerce separates where the data lives from where it is sold. A channel is a place that sells products from the store's single catalog. Channels have a type, such as a storefront, a marketplace, a point of sale or a marketing channel, and a platform, such as bigcommerce for a Stencil theme storefront or a headless platform like next. A channel that renders pages has one or more sites that carry domain names and routes.

Why this matters to you:

  • One store can have multiple storefronts, each with its own domain, theme and settings, selling overlapping or different products. This is the multi-storefront feature, and it may depend on the plan.
  • Products are assigned to channels. A product that exists in the catalog but is not assigned to a channel is invisible there.
  • Categories, currencies and some settings can be configured per channel, so code that assumes a single global store may break on multi-channel stores. A good habit is to pass the channel id explicitly instead of relying on a default.
flowchart TD
    S["Store<br/>(store hash)"]
    S --> C["Catalog<br/>products, variants, categories, brands"]
    S --> O["Orders"]
    S --> U["Customers"]
    S --> CH1["Channel 1<br/>Stencil storefront"]
    S --> CH2["Channel 2<br/>headless Next.js"]
    S --> CH3["Channel 3<br/>marketplace"]
    C -. "assignment" .-> CH1
    C -. "assignment" .-> CH2
    C -. "assignment" .-> CH3

One catalog, many channels: products are assigned to the channels that may sell them.

The domains

Inside a store, data is grouped into domains. The names below are the ones you will meet most often:

  • Catalog: products, variants, options and modifiers, categories, brands, images, custom fields. See The Catalog API (V3).
  • Orders: orders, line items, shipping addresses, shipments, statuses, refunds and transactions. See Orders, Customers and the V2/V3 Split.
  • Customers: accounts, addresses, groups and consent data.
  • Carts and checkout: carts, checkout sessions, consignments, coupons. See Carts and the Checkout API.
  • Content: pages, blog posts, widgets, scripts. See Widgets, Regions and Page Builder.
  • Settings and infrastructure: store information, payment, shipping and tax settings, webhooks.

These match the generic model described in The E-commerce Domain Model, with BigCommerce's own names. The big practical point is that the domains are separate: an order keeps a snapshot of what was bought, so editing the catalog later does not rewrite old orders.

API surfaces

The same domains are exposed through several APIs:

Surface Style Typical use
REST V3 JSON, resource URLs, data and meta Catalog, customers, carts, most new endpoints
REST V2 Older JSON REST Orders and some settings endpoints
GraphQL Storefront One endpoint, queries for the shopper's view Headless storefronts, Stencil frontmatter queries
GraphQL Admin One endpoint for store management Admin-style queries, one request for related data
Webhooks Outbound HTTP calls from BigCommerce to you Reacting to changes

V2 and V3 coexist because the platform grew over time. New work generally lands in V3, but some resources, notably orders, still live in V2 while related V3 endpoints (transactions, refunds, some order data) exist next to them. You will see this split again in lesson 2030. GraphQL Storefront API and GraphQL Admin API and Choosing Between APIs explain when to use which.

A model of channels and assignments

The stand-in below models a store with a catalog and three channels. Products are assigned to channels, and a helper answers "what can this channel sell?" and "where is this product sold?". The real platform stores these assignments in its own database and exposes them through channel and product-assignment endpoints. Here it is a few arrays and a Map.

Node.js Catalog and channel assignments

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The "Wholesale Crate" exists in the catalog but is assigned nowhere, so no shopper can see it. That is a common surprise after importing products: they exist, but a missing assignment hides them.

Reading a response by domain

A second stand-in practices something you will do constantly: look at a URL and say which surface and domain it belongs to. The rules mirror real URL layouts (/v2/..., /v3/..., and the separate GraphQL endpoint), but the table of domains is deliberately small.

Node.js Classify an API path

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice that orders are v2 while catalog and customers are v3. That is exactly the split to remember.

Putting the map to use

When a requirement arrives, run through three questions. First, which domain owns the data? Second, which channel(s) are involved: a product description change is global, but whether a product is visible is per channel. Third, which API surface gives you the right trade-off: REST for simple writes and exports, GraphQL for rich storefront reads, webhooks for reacting to events rather than polling.

Also remember that reads on the storefront side (what a shopper sees) and reads on the admin side (what a merchant manages) use different credentials. A storefront token is meant to be used from a browser and is limited, while an admin API token must never leave your server. Lesson 2010 covers this in detail, and the general reasoning is in Shop Security Basics.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the store hash in an API URL identify?

    Every API call targets one store, and the hash in the URL says which one.
  2. 2. A product exists in the catalog but shoppers on a channel cannot see it. What is a likely cause?

    Products are assigned to channels. Unassigned products are not sold there, even though they exist in the catalog.
  3. 3. Which statement about REST V2 and V3 is the best summary?

    You will often combine both versions in one integration, for example V2 orders with V3 customers.
  4. 4. Why should code pass a channel id explicitly on multi-storefront stores?

    Assuming a single global store breaks when a second channel is added. Being explicit avoids that.

Summary

  • A store (identified by its hash) owns the data; channels sell it; sites carry domains and routes.
  • Products must be assigned to a channel to be sold there.
  • The main domains are catalog, orders, customers, carts and checkout, content and settings.
  • REST V3, REST V2, GraphQL (Storefront and Admin) and webhooks expose these domains; orders still live mostly in V2.
  • Place every feature on the map: which domain, which channel, which API surface.

Next: Setting Up a Development Environment