// 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.
| name | bigcommerce-api |
| description | 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>
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.
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.
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.
Always include channel_id when working with multi-storefront stores.
</essential_principles>
What would you like to do with BigCommerce APIs?Wait for response before proceeding.
| Response | Workflow | |----------|----------| | 1, "integration", "sync", "connect" | `workflows/build-integration.md` | | 2, "headless", "storefront", "next.js", "catalyst", "graphql" | `workflows/build-headless-storefront.md` | | 3, "app", "marketplace", "single-click" | `workflows/build-app.md` | | 4, "catalog", "orders", "customers", "payments", "specific" | `workflows/work-with-api.md` | | 5, "debug", "error", "fix", "troubleshoot", "401", "422" | `workflows/debug-api-issue.md` | | 6, "webhook", "webhooks", "events", "subscribe" | `workflows/setup-webhooks.md` | | 7, other | Clarify intent, then route to appropriate workflow |After reading the workflow, follow it exactly.
<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>
Analyze environment variables in JavaScript/TypeScript projects. Identifies unused variables, infers permission scopes, detects specific services (Stripe, AWS, Supabase), and documents code paths. Includes optional cleanup of unused variables with regression detection. Use when auditing .env files, reviewing security, or documenting project configuration.
Transcribes audio/video files using ElevenLabs Scribe v2 API. Use when transcribing audio files, generating transcripts, or converting speech to text.
Extracts frames and timestamped audio segments from video files (GIF, MP4, MOV) at configurable intervals and stores them in a directory with a manifest file. Use when analyzing video content, preparing frames for visual review, extracting audio for transcription, or creating frame+audio sequences for another agent to process.
Chokidar-based file watcher that triggers `claude -p` on changes. Useful for automated AI reactions to file changes — design sync, code validation, config regeneration, etc.
Safely identifies and removes dead code in TypeScript/JavaScript projects using multi-agent analysis with automatic backup branches. Use when cleaning up unused exports, orphaned files, dead imports, unreachable functions, or unused dependencies.
Configure agent-tail log aggregation for the current project. Auto-detects framework (Vite, Next.js, plain Node, monorepo) and sets up CLI runner, browser log plugins, and output destinations. Use when setting up agent-tail, configuring dev server logging, or piping logs for AI agent consumption.