Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 28 ยท Practice and Review

BigCommerce Cheat Sheet

A quick BigCommerce developer reference: API base URLs and endpoints, headers, OAuth scopes, webhook scopes, Stencil CLI, theme files and helpers, and common limits.

This page is a lookup table, not a lesson. When you cannot remember the header name for the token, the path of the carts endpoint or which Stencil command bundles a theme, come here. Each section links back to the lesson that explains the idea. Names, limits and options can change between releases, so treat the tables as a memory aid and confirm exact values in the current official documentation before you depend on them.

BigCommerce cannot run on this site, so every real URL, command and snippet below is read-only. Two small Node.js stand-ins at the end help with things that are easy to get wrong: building request URLs and headers, and matching webhook scope names. They are models written for learning, not the platform's code.

flowchart LR
    A["Need an endpoint"] --> T1["API tables"]
    B["Need a header or scope"] --> T2["Headers and scopes"]
    C["Need a theme command"] --> T3["Stencil tables"]
    D["Need a number"] --> T4["Limits"]

Jump to the table that matches what you are looking for.

API base URLs

Surface URL pattern Auth
REST V3 https://api.bigcommerce.com/stores/{store_hash}/v3/... X-Auth-Token
REST V2 https://api.bigcommerce.com/stores/{store_hash}/v2/... X-Auth-Token
GraphQL Storefront https://{store or channel domain}/graphql Authorization: Bearer {storefront token}
GraphQL Admin https://api.bigcommerce.com/stores/{store_hash}/graphql X-Auth-Token
OAuth token exchange https://login.bigcommerce.com/oauth2/token client ID and secret in the body

Background: Platform Architecture, GraphQL Storefront API, GraphQL Admin API and Choosing Between APIs.

Common REST endpoints

Task Method and path
List or create products GET / POST /v3/catalog/products
Read, update or delete a product GET / PUT / DELETE /v3/catalog/products/{id}
Batch update products PUT /v3/catalog/products with an array of objects that include id
Variants of a product /v3/catalog/products/{id}/variants
Options and modifiers /v3/catalog/products/{id}/options, /modifiers
Custom fields /v3/catalog/products/{id}/custom-fields
Categories and brands /v3/catalog/categories, /v3/catalog/brands
Orders (V2) /v2/orders, /v2/orders/{id}, /v2/orders/{id}/products
Order statuses (V2) /v2/order_statuses
Customers (V3) /v3/customers
Carts /v3/carts, /v3/carts/{id}/items
Cart redirect URLs POST /v3/carts/{id}/redirect_urls
Checkout /v3/checkouts/{id}
Webhooks /v3/hooks
Storefront API token POST /v3/storefront/api-token
Customer-impersonation token POST /v3/storefront/api-token-customer-impersonation
Channels /v3/channels

Lessons: The Catalog API (V3), Orders, Customers and the V2/V3 Split, Carts and the Checkout API.

Query parameters you use constantly

Parameter Meaning Example
page, limit Page number (from 1) and page size ?page=2&limit=100
include Embed related data ?include=variants,images
include_fields Return only these fields ?include_fields=id,name,price
exclude_fields Leave these fields out ?exclude_fields=description
id:in Match a list of ids ?id:in=111,112
name:like Text match ?name:like=tote
price:min, price:max Range filters ?price:min=10&price:max=50
sort, direction Ordering ?sort=price&direction=desc
is_visible Boolean filter ?is_visible=true

Which filters exist differs per endpoint; check the reference for the one you call.

Headers

Header Direction Purpose
X-Auth-Token request Access token for REST and the Admin GraphQL API
Authorization: Bearer ... request Storefront GraphQL token
Content-Type: application/json request Body format for writes
Accept: application/json request Ask for JSON
X-Rate-Limit-Requests-Left response Requests remaining in this window
X-Rate-Limit-Requests-Quota response Requests allowed per window
X-Rate-Limit-Time-Window-Ms response Length of the window
X-Rate-Limit-Time-Reset-Ms response Time until the window resets

Read the rate-limit headers; do not hard-code quotas, which depend on plan and can change. See Orders, Customers and the V2/V3 Split.

Status codes you will meet

Status Usual meaning Retry?
200, 201, 204 Success (read, created, deleted) no
400 Malformed request no, fix it
401 Missing or invalid token no, fix the credential
403 Token lacks the scope no, change scopes
404 Resource not found (or hidden) no
409 Conflict, such as a duplicate no, resolve it
422 Validation failed no, fix the data
429 Rate limited yes, after the reset time
500, 502, 503, 504 Transient server problem yes, with backoff and jitter

OAuth scopes (naming style)

Scope Allows
store_v2_products Modify products and catalog
store_v2_products_read_only Read products and catalog
store_v2_orders / store_v2_orders_read_only Modify / read orders
store_v2_customers / store_v2_customers_read_only Modify / read customers
store_v2_content Modify content such as pages and scripts
store_v2_information_read_only Read store information
store_cart, store_checkout Carts and checkouts
store_storefront_api Create storefront API tokens

Prefer read-only scopes wherever they work, and see API Accounts, Tokens and Scopes. Always confirm the scope an endpoint needs in its reference page; names look V2-flavored for historical reasons but cover V3 areas too.

App callbacks

Callback When Receives You must
Auth Merchant installs code, scope, context Validate, exchange the code for a token, store it by store hash
Load Merchant opens the app Signed payload (JWT) Verify the signature, audience and expiry before trusting it
Uninstall Merchant removes the app Signed payload Revoke access, stop jobs, clean up
Remove user A user loses access (multi-user apps) Signed payload Remove that user's access

See App Types and the OAuth Flow and Building an App Backend.

Webhook scopes

Scopes follow the pattern store/{resource}/{event}. Common ones:

Scope Fires when
store/order/created An order is placed
store/order/updated An order changes
store/order/statusUpdated An order's status changes
store/product/created, updated, deleted A product is created, changed or removed
store/product/inventory/updated Inventory changes
store/customer/created, updated A customer is added or changed
store/cart/created, updated, converted A cart is created, changed or becomes an order
store/shipment/created A shipment is created
store/app/uninstalled The app is uninstalled

A wildcard such as store/order/* subscribes to all events of a resource, and store/* to everything; use the narrowest scope that does the job. Payloads are small notifications (scope, store id, a data object with a type and id, a hash, a creation time), so fetch the resource afterwards. Register a destination header with a secret, answer with a 2xx quickly, and dedupe. See Webhooks.

Stencil CLI

Command Does
stencil init Create .stencil configuration (store URL, token, port)
stencil start Run a local server with live preview and reload
stencil bundle Package the theme into a zip file
stencil push Upload a bundle to the store (see --help for options such as activation)
stencil pull Download the active configuration to your machine
stencil --version, stencil --help Check the installed version and options

Keep the Node version the CLI supports, and keep .stencil out of version control, because it holds a token. See Stencil CLI and the Cornerstone Theme and Setting Up a Development Environment.

Theme files

Path Role
config.json Theme settings defaults, variations, image sizes, CSS and JavaScript settings
schema.json Defines the settings merchants see in the theme editor
schemaTranslations.json Translations for the schema
lang/*.json Storefront text translations used by the lang helper
templates/pages/ One template per page type
templates/components/ Reusable partials
templates/layout/ Wrapping layouts (base.html)
assets/scss/ Styles
assets/js/ Page-type JavaScript classes and app.js
webpack.*.js Bundling configuration

See Handlebars Templates, Helpers and Page Context and Theme Settings, SCSS and JavaScript.

Handlebars and Stencil helpers

Syntax Use
{{name}} Output an escaped value
{{{html}}} Output raw HTML (only for trusted markup)
{{#if x}}...{{else}}...{{/if}} Conditional
{{#each items}}...{{/each}} Loop
{{> components/common/foo}} Include a partial
{{lang 'key'}} Translated text
{{getImage image 'size'}} Image URL for a named size from config.json
{{cdn 'path'}} URL for a theme asset
{{inject 'key' value}} and {{jsContext}} Pass data to JavaScript
{{region name="home_below_hero"}} Page Builder region for widgets
{{{head.scripts}}}, {{{footer.scripts}}} Required platform script slots in the layout

GraphQL snippets

Read-only examples for the Storefront API:

GRAPHQL
query Product($id: Int!) {
  site {
    product(entityId: $id) {
      entityId
      name
      path
      prices { price { value currencyCode } }
    }
  }
}
GRAPHQL
mutation {
  cart {
    createCart(input: { lineItems: [{ productEntityId: 111, quantity: 1 }] }) {
      cart { entityId }
    }
  }
}

Ask for only the fields you render, check the errors array even on HTTP 200, and expect null for products that do not exist or are not visible on the channel.

Common limits and defaults

Topic Rule of thumb
List page size Default 50, maximum 250 on most V3 catalog lists; the server may cap lower
Batch writes Small per-request caps (for products, 10 items); chunk your work
Rate limits Plan-dependent; read the X-Rate-Limit-* headers; wait after a 429
Webhook response Return a 2xx quickly; slow handlers cause retries and can lead to deactivation
Access tokens Treat as long-lived secrets; store encrypted, rotate by reissuing
Storefront tokens Have an expiry and allowed origins; renew before they expire

When a number matters, look it up; the guideline here is only to show which kind of limit exists.

Stand-in 1: build URLs and headers

This helper builds a REST URL from a store hash, API version, path and query object, and the right headers for a token. It refuses a path that tries to leave the API root and a store hash with odd characters. It is a model of careful request building, not an official SDK.

Node.js Build a REST URL and headers

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 first request shows the usual list call: the include array becomes a comma list, the colon in name:like is kept readable and the token is hidden in the printout. The second is a V2 PUT with a JSON body and Content-Type. The three bad inputs are rejected before any request would be made.

Stand-in 2: match webhook scopes

Wildcards are easy to get subtly wrong. This stand-in checks whether a subscription pattern covers an event scope, and warns about patterns that are broader than the events you handle. The known-scope list is a small sample.

Node.js Does this subscription cover that event?

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.

An exact pattern is the safest: every event is handled. store/order/* also delivers store/order/updated, which this handler ignores, so it creates traffic and work for nothing. store/* is far broader still, and a typo such as orders matches nothing at all, which in real life would mean silence rather than an error, a good reason to test a subscription with a real event on a sandbox store.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which header carries the token for the REST API?

    REST calls send the access token in X-Auth-Token. The GraphQL Storefront API uses a Bearer token in the Authorization header instead.
  2. 2. A response has status 429 and X-Rate-Limit-Time-Reset-Ms of 900. What should the client do?

    A 429 is transient. The reset header says how long until the window reopens.
  3. 3. Which subscription is the narrowest way to receive only new orders?

    An exact scope delivers only that event. Wildcards deliver more events than you may handle.
  4. 4. Which command packages a theme into a zip file?

    stencil bundle creates the zip you can upload with stencil push or the control panel.
  5. 5. Why should you keep the .stencil file out of version control?

    Configuration with credentials belongs in the developer's environment, not in a shared repository.

Summary

  • REST uses X-Auth-Token on api.bigcommerce.com/stores/{hash}/v2|v3; the Storefront GraphQL API uses a Bearer storefront token on the store domain.
  • Use page, limit, filters, include and include_fields to fetch exactly what you need, and read the rate-limit headers.
  • Retry 429 (after the reset) and 5xx (with backoff); do not retry 4xx client errors.
  • Webhook scopes look like store/order/created; subscribe narrowly and answer quickly.
  • Stencil commands are init, start, bundle, push and pull; theme settings live in config.json and schema.json.
  • Treat every number here as a pointer, and confirm limits and options in the current documentation.

That is the end of the track. To start again or revisit a topic, go back to What Is BigCommerce Development?