bc-app-dev git:20260309.786511cA

Immutable. This exact content is served forever at /api/v1/blob/9ce1e2acf83efe74.

---
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.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch
---

# 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`:
```json
{
  "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

```json
{
  "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.