BigCommerce App Development
Before writing code
Fetch live docs:
- Fetch
https://docs.bigcommerce.com/developer/docs/integrations/apps/introduction for the apps guide
- Web-search
site:developer.bigcommerce.com apps guide auth for OAuth patterns
- Web-search
bigcommerce single-click app tutorial for step-by-step implementation
App Types
Single-Click Apps
Apps installed from the BigCommerce App Marketplace:
- User clicks "Install" in the marketplace or admin panel
- BigCommerce initiates OAuth flow with your server
- Your app receives a permanent API token for that store
- Load your app UI in an iframe within BigCommerce admin
Connector Apps
Simplified apps that don't embed UI in BigCommerce:
- OAuth install flow only — get an API token
- No admin panel iframe
- Typically background data sync services (ERP, shipping, marketing)
Scripts-Only Apps
Inject JavaScript into the storefront without a full app:
- Use the Script Manager API after OAuth install
- No admin panel UI
- For analytics, chat widgets, A/B testing, etc.
OAuth Flow
Installation Flow
- Merchant clicks "Install" — BigCommerce sends GET to your Auth Callback URL with
code, scope, context
- Your server exchanges
code for a permanent access_token via POST to https://login.bigcommerce.com/oauth2/token
- Store the
access_token, store_hash, and scope for future API calls
- Return HTML that BigCommerce renders in the admin iframe
Load Callback
When the merchant opens your app in BigCommerce admin:
- BigCommerce sends GET to your Load Callback URL with a signed JWT
- Verify JWT signature using your Client Secret
- Extract
store_hash and user from the JWT payload
- Return your app's UI HTML
Uninstall Callback
When the merchant uninstalls:
- BigCommerce sends GET to your Uninstall Callback URL with a signed JWT
- Clean up stored tokens and data for that store
Remove User Callback
When a specific user is removed from a multi-user store:
- Clean up user-specific data
OAuth Token Exchange
Request
POST to https://login.bigcommerce.com/oauth2/token:
{
"client_id": "your_client_id",
"client_secret": "your_client_secret",
"code": "temporary_auth_code",
"scope": "store_v2_products store_v2_orders",
"grant_type": "authorization_code",
"redirect_uri": "https://your-app.com/auth/callback",
"context": "stores/{store_hash}"
}
Response
{
"access_token": "permanent_token",
"scope": "store_v2_products store_v2_orders",
"user": { "id": 123, "email": "merchant@example.com" },
"context": "stores/abc123",
"account_uuid": "..."
}
App Scopes
| Scope |
Access |
store_v2_products |
Products, categories, brands |
store_v2_orders |
Orders, shipments |
store_v2_customers |
Customer data |
store_v2_content |
Pages, blog, redirects |
store_v2_marketing |
Coupons, gift certificates |
store_v2_information |
Store metadata |
store_channel_settings |
Channel/multi-storefront |
store_cart |
Cart operations |
store_checkout |
Checkout operations |
store_payments |
Payment processing |
store_themes_manage |
Theme operations |
Request minimum scopes necessary — principle of least privilege.
Control Panel Integration
Embedding in Admin
Your app loads in an iframe within the BigCommerce admin panel:
- Set
Content-Security-Policy headers to allow framing by *.bigcommerce.com
- Handle the Load callback JWT to authenticate the session
- Use the BigCommerce admin design patterns for consistent UX
BigDesign Component Library
BigCommerce provides a React component library for admin UIs:
@bigcommerce/big-design — buttons, forms, tables, modals
- Matches the BigCommerce admin panel design language
- Install:
npm install @bigcommerce/big-design
App Marketplace Submission
Requirements
- Valid OAuth flow (install, load, uninstall callbacks)
- HTTPS for all endpoints
- Privacy policy and terms of service
- App description, screenshots, icon
- Handle multi-user stores (different users on same store)
- Rate limit compliance
Best Practices
- Store tokens securely — encrypted at rest
- Handle rate limits gracefully with exponential backoff
- Verify JWT signatures on all callbacks using your Client Secret
- Request minimum OAuth scopes
- Handle the uninstall callback — clean up data
- Support multi-user stores (multiple admin users)
- Use BigDesign components for admin panel UIs
- Never hardcode store hashes or tokens
Fetch the BigCommerce apps guide and OAuth documentation for exact callback parameters, JWT structure, and submission requirements before implementing.
1---2name: bc-app-dev3description: Build BigCommerce apps — single-click apps, OAuth flow, app callbacks, connector apps, control panel integration, and App Marketplace submission. Use when creating integrations that install via the BigCommerce App Marketplace.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/bc-app-dev7---89# BigCommerce App Development1011## Before writing code1213**Fetch live docs**:141. Fetch `https://docs.bigcommerce.com/developer/docs/integrations/apps/introduction` for the apps guide152. Web-search `site:developer.bigcommerce.com apps guide auth` for OAuth patterns163. Web-search `bigcommerce single-click app tutorial` for step-by-step implementation1718## App Types1920### Single-Click Apps2122Apps installed from the BigCommerce App Marketplace:23- User clicks "Install" in the marketplace or admin panel24- BigCommerce initiates OAuth flow with your server25- Your app receives a permanent API token for that store26- Load your app UI in an iframe within BigCommerce admin2728### Connector Apps2930Simplified apps that don't embed UI in BigCommerce:31- OAuth install flow only — get an API token32- No admin panel iframe33- Typically background data sync services (ERP, shipping, marketing)3435### Scripts-Only Apps3637Inject JavaScript into the storefront without a full app:38- Use the Script Manager API after OAuth install39- No admin panel UI40- For analytics, chat widgets, A/B testing, etc.4142## OAuth Flow4344### Installation Flow45461. Merchant clicks "Install" — BigCommerce sends GET to your **Auth Callback URL** with `code`, `scope`, `context`472. Your server exchanges `code` for a permanent `access_token` via POST to `https://login.bigcommerce.com/oauth2/token`483. Store the `access_token`, `store_hash`, and `scope` for future API calls494. Return HTML that BigCommerce renders in the admin iframe5051### Load Callback5253When the merchant opens your app in BigCommerce admin:54- BigCommerce sends GET to your **Load Callback URL** with a signed JWT55- Verify JWT signature using your Client Secret56- Extract `store_hash` and `user` from the JWT payload57- Return your app's UI HTML5859### Uninstall Callback6061When the merchant uninstalls:62- BigCommerce sends GET to your **Uninstall Callback URL** with a signed JWT63- Clean up stored tokens and data for that store6465### Remove User Callback6667When a specific user is removed from a multi-user store:68- Clean up user-specific data6970## OAuth Token Exchange7172### Request7374POST to `https://login.bigcommerce.com/oauth2/token`:75```json76{77 "client_id": "your_client_id",78 "client_secret": "your_client_secret",79 "code": "temporary_auth_code",80 "scope": "store_v2_products store_v2_orders",81 "grant_type": "authorization_code",82 "redirect_uri": "https://your-app.com/auth/callback",83 "context": "stores/{store_hash}"84}85```8687### Response8889```json90{91 "access_token": "permanent_token",92 "scope": "store_v2_products store_v2_orders",93 "user": { "id": 123, "email": "merchant@example.com" },94 "context": "stores/abc123",95 "account_uuid": "..."96}97```9899## App Scopes100101| Scope | Access |102|-------|--------|103| `store_v2_products` | Products, categories, brands |104| `store_v2_orders` | Orders, shipments |105| `store_v2_customers` | Customer data |106| `store_v2_content` | Pages, blog, redirects |107| `store_v2_marketing` | Coupons, gift certificates |108| `store_v2_information` | Store metadata |109| `store_channel_settings` | Channel/multi-storefront |110| `store_cart` | Cart operations |111| `store_checkout` | Checkout operations |112| `store_payments` | Payment processing |113| `store_themes_manage` | Theme operations |114115Request minimum scopes necessary — principle of least privilege.116117## Control Panel Integration118119### Embedding in Admin120121Your app loads in an iframe within the BigCommerce admin panel:122- Set `Content-Security-Policy` headers to allow framing by `*.bigcommerce.com`123- Handle the Load callback JWT to authenticate the session124- Use the BigCommerce admin design patterns for consistent UX125126### BigDesign Component Library127128BigCommerce provides a React component library for admin UIs:129- `@bigcommerce/big-design` — buttons, forms, tables, modals130- Matches the BigCommerce admin panel design language131- Install: `npm install @bigcommerce/big-design`132133## App Marketplace Submission134135### Requirements136137- Valid OAuth flow (install, load, uninstall callbacks)138- HTTPS for all endpoints139- Privacy policy and terms of service140- App description, screenshots, icon141- Handle multi-user stores (different users on same store)142- Rate limit compliance143144## Best Practices145146- Store tokens securely — encrypted at rest147- Handle rate limits gracefully with exponential backoff148- Verify JWT signatures on all callbacks using your Client Secret149- Request minimum OAuth scopes150- Handle the uninstall callback — clean up data151- Support multi-user stores (multiple admin users)152- Use BigDesign components for admin panel UIs153- Never hardcode store hashes or tokens154155Fetch the BigCommerce apps guide and OAuth documentation for exact callback parameters, JWT structure, and submission requirements before implementing.