Always check which version supports your specific endpoint.
Never embed credentials in client-side code. Use environment variables.
Monitor 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.
- Build a new integration (REST API, webhooks, data sync)
- Create a headless storefront (GraphQL Storefront, Next.js/Catalyst)
- Develop a BigCommerce app (single-click app, marketplace)
- Work with specific API (Catalog, Orders, Customers, Payments)
- Debug an API issue (errors, authentication, rate limits)
- Set up webhooks and event handling
- Something else
Wait for response before proceeding.
After reading the workflow, follow it exactly.
# 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:
- "API call: [status]"
- "Rate limit remaining: [X]"
- "Data verified: [confirmation]"
Authentication & Security:
- references/authentication.md - OAuth, tokens, scopes, credentials
- references/security-best-practices.md - API keys, PCI compliance, headers
Core APIs:
- references/catalog-api.md - Products, categories, brands, variants
- references/orders-api.md - Orders, shipments, transactions, fulfillment
- references/customers-api.md - Customers, addresses, groups, segments
- references/payments-api.md - Payment processing, gateways, checkout
Storefront & Content:
- references/graphql-storefront.md - GraphQL queries, carts, checkout
- references/widgets-scripts.md - Widgets API, Scripts API, content injection
- references/stencil-themes.md - Theme development, Handlebars, CLI
Platform Features:
- references/webhooks.md - Events, subscriptions, retry logic
- references/multi-storefront.md - MSF, channels, site routing
- references/headless-commerce.md - Next.js Commerce, Catalyst, React
Development:
- references/app-development.md - Single-click apps, Developer Portal
- references/rate-limits-pagination.md - Throttling, cursor pagination, batching
- references/error-handling.md - Status codes, troubleshooting, debugging
Base URLs:
- REST API:
https://api.bigcommerce.com/stores/{store_hash}/v3/
- Payments:
https://payments.bigcommerce.com/stores/{store_hash}/payments
- GraphQL Storefront:
https://{store_domain}/graphql
- OAuth Token:
https://login.bigcommerce.com/oauth2/token
Essential Headers:
X-Auth-Token: {access_token}
Content-Type: application/json
Accept: application/json
GraphQL Storefront Auth:
Authorization: Bearer {storefront_token}
1---2name: bigcommerce-api3description: 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.4---5
6<essential_principles>
7
8<principle name="api-versioning">
9BigCommerce maintains V2 and V3 APIs concurrently. V3 is preferred for most operations:
10- **Catalog, Customers, Carts**: Use V3 (better pagination, metafields support)
11- **Orders**: V2 for CRUD operations, V3 for transactions/refunds
12- **Customer Groups**: Still V2 only (V3 migration planned)
13
14Always check which version supports your specific endpoint.
15</principle>
16
17<principle name="authentication-model">
18BigCommerce uses OAuth exclusively for V3 APIs:
19- **X-Auth-Token header**: REST APIs and GraphQL Admin
20- **Bearer token**: GraphQL Storefront API
21- **Store-level credentials**: Single store integrations
22- **App-level credentials**: Marketplace apps (OAuth flow)
23- **Account-level credentials**: Multi-store management
24
25Never embed credentials in client-side code. Use environment variables.
26</principle>
27
28<principle name="rate-limits">
29Respect rate limits to avoid blocking:
30- **Standard REST API**: 20,000 requests/hour
31- **Payments API**: 50 requests/4 seconds
32- **B2B Edition**: 150 requests/minute
33- **GraphQL**: Query complexity limits apply
34
35Monitor headers: `X-Rate-Limit-Requests-Left`, `X-Rate-Limit-Time-Reset-Ms`
36Implement exponential backoff with jitter for retries.
37</principle>
38
39<principle name="channel-awareness">
40All storefronts and sales channels have a `channel_id`:
41- Default storefront channel_id is always `1`
42- MSF stores have multiple channels
43- Products must be explicitly assigned to channels
44- Orders, carts, and checkouts should specify channel_id
45
46Always include channel_id when working with multi-storefront stores.
47</principle>
48
49</essential_principles>
50
51<intake>
52What would you like to do with BigCommerce APIs?
53
541. Build a new integration (REST API, webhooks, data sync)
552. Create a headless storefront (GraphQL Storefront, Next.js/Catalyst)
563. Develop a BigCommerce app (single-click app, marketplace)
574. Work with specific API (Catalog, Orders, Customers, Payments)
585. Debug an API issue (errors, authentication, rate limits)
596. Set up webhooks and event handling
607. Something else
61
62**Wait for response before proceeding.**
63</intake>
64
65<routing>
66| Response | Workflow |
67|----------|----------|
68| 1, "integration", "sync", "connect" | `workflows/build-integration.md` |
69| 2, "headless", "storefront", "next.js", "catalyst", "graphql" | `workflows/build-headless-storefront.md` |
70| 3, "app", "marketplace", "single-click" | `workflows/build-app.md` |
71| 4, "catalog", "orders", "customers", "payments", "specific" | `workflows/work-with-api.md` |
72| 5, "debug", "error", "fix", "troubleshoot", "401", "422" | `workflows/debug-api-issue.md` |
73| 6, "webhook", "webhooks", "events", "subscribe" | `workflows/setup-webhooks.md` |
74| 7, other | Clarify intent, then route to appropriate workflow |
75
76**After reading the workflow, follow it exactly.**
77</routing>
78
79<verification_loop>
80After every API operation:
81
82```bash
83# 1. Check response status
84# 200/201 = Success
85# 4xx = Client error (check request)
86# 5xx = Server error (retry with backoff)
87
88# 2. Verify rate limit headers
89X-Rate-Limit-Requests-Left: [remaining]
90X-Rate-Limit-Time-Reset-Ms: [reset time]
91
92# 3. For mutations, verify the change
93GET the resource to confirm state
94```
95
96Report to user:
97- "API call: [status]"
98- "Rate limit remaining: [X]"
99- "Data verified: [confirmation]"
100</verification_loop>
101
102<reference_index>
103
104**Authentication & Security:**
105- references/authentication.md - OAuth, tokens, scopes, credentials
106- references/security-best-practices.md - API keys, PCI compliance, headers
107
108**Core APIs:**
109- references/catalog-api.md - Products, categories, brands, variants
110- references/orders-api.md - Orders, shipments, transactions, fulfillment
111- references/customers-api.md - Customers, addresses, groups, segments
112- references/payments-api.md - Payment processing, gateways, checkout
113
114**Storefront & Content:**
115- references/graphql-storefront.md - GraphQL queries, carts, checkout
116- references/widgets-scripts.md - Widgets API, Scripts API, content injection
117- references/stencil-themes.md - Theme development, Handlebars, CLI
118
119**Platform Features:**
120- references/webhooks.md - Events, subscriptions, retry logic
121- references/multi-storefront.md - MSF, channels, site routing
122- references/headless-commerce.md - Next.js Commerce, Catalyst, React
123
124**Development:**
125- references/app-development.md - Single-click apps, Developer Portal
126- references/rate-limits-pagination.md - Throttling, cursor pagination, batching
127- references/error-handling.md - Status codes, troubleshooting, debugging
128
129</reference_index>
130
131<workflows_index>
132| Workflow | Purpose |
133|----------|---------|
134| build-integration.md | Create data sync, connect external systems |
135| build-headless-storefront.md | Next.js/Catalyst headless frontend |
136| build-app.md | Single-click marketplace app |
137| work-with-api.md | Use specific BigCommerce API |
138| debug-api-issue.md | Fix errors and authentication problems |
139| setup-webhooks.md | Configure webhook subscriptions |
140</workflows_index>
141
142<quick_reference>
143
144**Base URLs:**
145- REST API: `https://api.bigcommerce.com/stores/{store_hash}/v3/`
146- Payments: `https://payments.bigcommerce.com/stores/{store_hash}/payments`
147- GraphQL Storefront: `https://{store_domain}/graphql`
148- OAuth Token: `https://login.bigcommerce.com/oauth2/token`
149
150**Essential Headers:**
151```
152X-Auth-Token: {access_token}
153Content-Type: application/json
154Accept: application/json
155```
156
157**GraphQL Storefront Auth:**
158```
159Authorization: Bearer {storefront_token}
160```
161
162</quick_reference>
aibot88