bc-app-dev

name	bc-app-dev
description	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.

BigCommerce App Development

Before writing code

Fetch live docs:

1. Fetch https://developer.bigcommerce.com/docs/integrations/apps for the apps guide
2. Web-search site:developer.bigcommerce.com apps guide auth for OAuth patterns
3. 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

1. Merchant clicks "Install" — BigCommerce sends GET to your Auth Callback URL with code, scope, context
2. Your server exchanges code for a permanent access_token via POST to https://login.bigcommerce.com/oauth2/token
3. Store the access_token, store_hash, and scope for future API calls
4. 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": "[e-mail]" },
  "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.