BigCommerce API expert for building integrations, apps, headless storefronts, and automations. Full lifecycle - REST APIs, GraphQL Storefront, webhooks, authentication, app development, and multi-storefront. Use when working with BigCommerce platform APIs.
<essential_principles>
<principle name="api-versioning"> BigCommerce maintains V2 and V3 APIs concurrently. V3 is preferred for most operations: - **Catalog, Customers, Carts**: Use V3 (better pagination, metafields support) - **Orders**: V2 for CRUD operations, V3 for transactions/refunds - **Customer Groups**: Still V2 only (V3 migration planned)Always check which version supports your specific endpoint. </principle>
<principle name="authentication-model"> BigCommerce uses OAuth exclusively for V3 APIs: - **X-Auth-Token header**: REST APIs and GraphQL Admin - **Bearer token**: GraphQL Storefront API - **Store-level credentials**: Single store integrations - **App-level credentials**: Marketplace apps (OAuth flow) - **Account-level credentials**: Multi-store managementNever embed credentials in client-side code. Use environment variables. </principle>
<principle name="rate-limits"> Respect rate limits to avoid blocking: - **Standard REST API**: 20,000 requests/hour - **Payments API**: 50 requests/4 seconds - **B2B Edition**: 150 requests/minute - **GraphQL**: Query complexity limits applyMonitor headers: X-Rate-Limit-Requests-Left, X-Rate-Limit-Time-Reset-Ms
Implement exponential backoff with jitter for retries.
</principle>
Always include channel_id when working with multi-storefront stores. </principle>
</essential_principles>
Wait for response before proceeding. </intake>
After reading the workflow, follow it exactly. </routing>
<verification_loop> After every API operation:
# 1. Check response status
# 200/201 = Success
# 4xx = Client error (check request)
# 5xx = Server error (retry with backoff)
# 2. Verify rate limit headers
X-Rate-Limit-Requests-Left: [remaining]
X-Rate-Limit-Time-Reset-Ms: [reset time]
# 3. For mutations, verify the change
GET the resource to confirm state
Report to user:
<reference_index>
Authentication & Security:
Core APIs:
Storefront & Content:
Platform Features:
Development:
</reference_index>
<workflows_index>
| Workflow | Purpose |
|---|---|
| build-integration.md | Create data sync, connect external systems |
| build-headless-storefront.md | Next.js/Catalyst headless frontend |
| build-app.md | Single-click marketplace app |
| work-with-api.md | Use specific BigCommerce API |
| debug-api-issue.md | Fix errors and authentication problems |
| setup-webhooks.md | Configure webhook subscriptions |
| </workflows_index> |
<quick_reference>
Base URLs:
https://api.bigcommerce.com/stores/{store_hash}/v3/https://payments.bigcommerce.com/stores/{store_hash}/paymentshttps://{store_domain}/graphqlhttps://login.bigcommerce.com/oauth2/tokenEssential Headers:
X-Auth-Token: {access_token}
Content-Type: application/json
Accept: application/json
GraphQL Storefront Auth:
Authorization: Bearer {storefront_token}
</quick_reference>