---
name: bc-app-dev-39a0f8d62651
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://docs.bigcommerce.com/developer/docs/integrations/apps/introduction` 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.


---
Source attribution: OrcaQubits
Original project: https://github.com/OrcaQubits/agentic-commerce-skills-plugins/blob/30cd25c74c8aa7dc49b3ec4847d463f6104439f6/dist/codex/bigcommerce-commerce/skills/bc-app-dev/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2024-2026 OrcaQubits AI (https://orcaqubits-ai.com)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: OrcaQubits
Original project: https://github.com/OrcaQubits/agentic-commerce-skills-plugins/blob/30cd25c74c8aa7dc49b3ec4847d463f6104439f6/dist/codex/bigcommerce-commerce/skills/bc-app-dev/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering, Marketing, Sales
Roles: Backend Developer, Business Development, Growth Marketer, Product Marketer, Sales Development Rep (SDR)
Specialties: API, Backend
Tools: Bigcommerce
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 4dd8de97f1aec629a8365696b8079a99e3c414d50c94bd0395e1a242aaf30660