Bigcommerce

BigCommerce App and Extension Development

Overview

BigCommerce is a SaaS e-commerce platform that hosts storefronts, manages catalogs, processes orders, and handles payments without requiring the merchant to maintain servers. Unlike self-hosted platforms (Magento, WooCommerce), BigCommerce controls the hosting layer, so all third-party integrations connect through APIs rather than modifying core files.

Three primary extension mechanisms exist:

• Single-Click Apps -- Full-featured applications installed from the BigCommerce App Marketplace. Hosted externally, they authenticate via OAuth, receive lifecycle callbacks (load, unload, remove), and interact with store data through REST and GraphQL APIs. This is the most common integration path.
• Connector Apps -- Headless integrations that synchronize data between BigCommerce and external systems (ERP, PIM, OMS, marketing platforms). Connector apps typically run as background services without a merchant-facing UI panel inside BigCommerce.
• Stencil Themes -- Handlebars-based storefront themes that control the customer-facing presentation layer. Stencil themes render server-side on BigCommerce infrastructure, use front matter YAML to inject data, and support widgets and Page Builder for visual customization.

BigCommerce also provides a Checkout SDK for customizing the checkout experience, a Widgets API for injecting dynamic content into storefronts, and a Script Manager for adding third-party scripts without theme modification.

App Architecture

Every BigCommerce app runs on external infrastructure and communicates with BigCommerce through a well-defined OAuth and callback protocol. Understanding this architecture is essential before writing any code.

OAuth Flow

BigCommerce uses a server-to-server OAuth 2.0 flow. When a merchant clicks "Install" on an app listing, BigCommerce redirects to the app's registered Auth Callback URL with a temporary authorization code, the store hash, and scopes. The app exchanges this code for a permanent OAuth access token by calling the BigCommerce OAuth token endpoint. Store the access token securely -- it does not expire but can be revoked if the merchant uninstalls the app.

Lifecycle Callbacks

Register three callback URLs during app creation:

• Auth Callback -- Receives the initial authorization code during installation. Exchange it for an access token.
• Load Callback -- Called each time the merchant opens the app from the BigCommerce admin panel. Receives a signed JWT containing the store hash, user email, and user ID. Verify the JWT signature before rendering the app UI.
• Uninstall Callback -- Called when the merchant removes the app. Clean up stored credentials, cancel webhooks, and delete store-specific data.

Multi-Tenant Architecture

A single app instance serves many stores. Store the access token, store hash, and store metadata in a database keyed by store hash. Each API request must use the correct store's access token. Never mix credentials between stores.

For complete OAuth implementation, callback handling, webhook registration, and multi-store data isolation patterns, see references/app-architecture.md.

Development Setup

BigCommerce Sandbox

Create a free BigCommerce sandbox store at the BigCommerce Developer Portal. Sandbox stores have full API access and support all app features. They do not process real payments but connect to payment gateway sandboxes.

App Registration

Register the app in the BigCommerce Developer Portal:

1. Navigate to My Apps and click "Create an App."
2. Set the Auth Callback URL (e.g., https://your-app.com/auth), Load Callback URL, and Uninstall Callback URL.
3. Select the required OAuth scopes -- request only the minimum scopes needed (e.g., store_v2_products for catalog access, store_v2_orders for order management).
4. Note the Client ID and Client Secret. Store the Client Secret in environment variables, never in source code.

Local Development with ngrok

BigCommerce callbacks require publicly accessible HTTPS URLs. Use ngrok or a similar tunnel to expose the local development server:

ngrok http 3000

Update the app's callback URLs in the Developer Portal to the ngrok HTTPS URL. Restart ngrok only when necessary, as the URL changes on each restart (unless using a paid ngrok plan with reserved domains).

Recommended Stack

BigCommerce does not mandate a technology stack. Common choices:

• Node.js + Express/Next.js -- First-class BigCommerce SDK support via @bigcommerce/bigcommerce-api-node.
• Python + Flask/Django -- Use the bigcommerce Python package.
• PHP + Laravel -- Community packages available; use raw HTTP client for the latest API features.
• React or Vue frontend -- For the app panel rendered inside the BigCommerce admin iframe.

API Overview

BigCommerce exposes multiple API surfaces, each serving different use cases.

REST Management API (V2 and V3)

The REST API is the primary interface for managing store data from server-side code.

• V3 (current) -- Covers catalog (products, categories, brands), customers, carts, checkouts, orders, pricing, shipping, tax, and store information. Uses JSON request/response bodies with consistent pagination and filtering. Prefer V3 endpoints for all new development.
• V2 (legacy) -- Older endpoints for orders, customers, and some resources not yet migrated to V3. V2 uses a different pagination model (page/limit query parameters). Use V2 only when the required endpoint does not exist in V3.

Authentication: Include the X-Auth-Token header with the store's OAuth access token, plus the Content-Type: application/json header.

Base URL: https://api.bigcommerce.com/stores/{store_hash}/v3/ (or /v2/ for legacy endpoints).

GraphQL Storefront API

The GraphQL API runs in the storefront context (browser-side) and provides read access to catalog, customer, and cart data. It is designed for headless storefronts and client-side applications.

• Authenticate with a Storefront API token (created via the REST API's /v3/storefront/api-token endpoint).
• Endpoint: https://{store_domain}/graphql.
• Supports queries for products, categories, brands, cart, customer login, and site information.
• Does not support mutations for administrative actions -- use the REST Management API for writes.

Rate Limiting

BigCommerce enforces rate limits on all API endpoints. The response includes X-Rate-Limit-Requests-Left and X-Rate-Limit-Time-Reset-Ms headers. When the limit is reached, the API returns HTTP 429. Implement backoff logic that reads the reset header and waits before retrying.

For endpoint-by-endpoint coverage, authentication patterns, pagination handling, and rate limit strategies, see references/rest-and-graphql-api.md.

Stencil Themes

Stencil is BigCommerce's theme engine. Themes control the storefront's HTML, CSS, and JavaScript and render server-side on BigCommerce infrastructure.

Handlebars Templates

Stencil templates use Handlebars syntax with BigCommerce-specific helpers. Template files live in templates/ and are organized by page type (product, category, cart, checkout, account). Custom partials go in templates/components/.

Front Matter YAML

Each template file can include a YAML front matter block that declares which data objects to inject into the template. For example, requesting products: new in the front matter makes the newest products available as a Handlebars variable.

Theme SDK and CLI

The Stencil CLI (@bigcommerce/stencil-cli) provides local development with hot reloading:

stencil init    # Connect to a sandbox store
stencil start   # Run the local development server
stencil bundle  # Package the theme for upload
stencil push    # Upload and apply the theme

Widgets and Page Builder

The Widgets API allows apps and themes to inject dynamic content blocks into storefront pages without modifying theme templates directly. Widgets are rendered in designated widget regions defined by the theme. Page Builder provides a drag-and-drop interface for merchants to place and configure widgets.

For Stencil CLI setup, template structure, front matter reference, widget development, and Page Builder integration, see references/storefront-stencil.md.

Checkout SDK

BigCommerce provides multiple approaches for customizing the checkout experience.

Embedded Checkout

Embed the BigCommerce checkout into a headless storefront or external site using an iframe. The Embedded Checkout SDK manages the iframe lifecycle, handles cross-origin communication, and provides events for tracking checkout progress.

Checkout JS SDK

The @bigcommerce/checkout-sdk-js package provides a JavaScript API for building a fully custom checkout UI. It abstracts the underlying Checkout and Payments APIs, manages checkout state, and handles payment method initialization.

Open Checkout

BigCommerce's Open Checkout is a React-based reference implementation of a custom checkout built on the Checkout JS SDK. Fork the repository to create a customized checkout while retaining BigCommerce's payment processing and order management.

For Embedded Checkout integration, Checkout JS SDK API reference, Open Checkout customization, and payment method integration, see references/checkout-sdk.md.

Anti-Patterns

Avoid these common mistakes when building BigCommerce apps:

• Storing OAuth tokens in client-side code. The access token is a server-side secret. Never expose it in JavaScript bundles, browser local storage, or frontend source.
• Requesting excessive OAuth scopes. Request only the scopes the app actually uses. Merchants distrust apps that request full store access when only catalog read is needed.
• Ignoring rate limits. Failing to read X-Rate-Limit-Requests-Left and hammering the API leads to 429 errors and degraded user experience. Implement queue-based request throttling for bulk operations.
• Polling instead of using webhooks. BigCommerce supports webhooks for most resource changes (orders, products, customers). Register webhooks instead of polling the API at intervals.
• Hardcoding store URLs or IDs. Apps serve multiple stores. Always resolve the store hash from the OAuth flow and store it per-tenant.
• Skipping JWT verification on load callbacks. The signed JWT in the load callback confirms the request originates from BigCommerce. Skipping verification allows attackers to impersonate merchants.
• Modifying Stencil theme files for app functionality. Apps should use the Widgets API or Script Manager to inject content, not require merchants to edit theme templates.
• Using V2 endpoints when V3 equivalents exist. V2 endpoints have inconsistent pagination, fewer features, and may be deprecated. Always check for a V3 endpoint first.
• Not implementing auto_uninstall on injected scripts. Set auto_uninstall: true on every script created via the Script Manager API. Without this, scripts remain on the storefront after app removal, causing merchant confusion and potential page bloat.
• Blocking the storefront with synchronous scripts. Load all storefront-injected scripts with async or defer. Synchronous script loading degrades page performance and harms the merchant's search engine rankings.
• Not handling multi-currency stores. BigCommerce supports multi-currency natively. Apps that display prices or process financial data must respect the store's configured currencies and format amounts correctly using the Pricing API.

Headless Commerce

BigCommerce has strong support for headless architecture, where the storefront is decoupled from BigCommerce and built with frameworks like Next.js, Gatsby, or Nuxt. Apps targeting headless merchants should:

• Use the GraphQL Storefront API for client-side catalog and cart operations.
• Use the REST Management API for server-side administrative operations.
• Support the Channels API to manage multiple storefronts (headless channel, native BigCommerce channel, social channels).
• Provide embeddable UI components (React, Web Components) that headless frontends can integrate.
• Support Embedded Checkout or the Checkout JS SDK for checkout on headless storefronts.

The Channels API (/v3/channels) allows apps to create and manage sales channels. Each channel has its own site, routes, and storefront API tokens. Apps that create content (scripts, widgets) should scope content to the appropriate channel.

Reference Files

• App Architecture -- App types, OAuth flow, auth/load/uninstall callbacks, multi-store apps, webhooks, installation flow
• REST and GraphQL API -- REST V2/V3 endpoints, GraphQL Storefront API, authentication, rate limiting, pagination, webhooks
• Storefront and Stencil -- Stencil CLI, Handlebars templates, front matter YAML, theme objects, widgets, Page Builder
• Checkout SDK -- Embedded Checkout, Checkout JS SDK, Open Checkout, payment integrations, customization API
• Marketplace Publishing -- App Marketplace submission, technical requirements, listing optimization, partner program