<essential_principles>
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.
</essential_principles>
- 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.
<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 stateReport to user:
- "API call: [status]"
- "Rate limit remaining: [X]"
- "Data verified: [confirmation]" </verification_loop>
<reference_index>
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
</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:
- 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/jsonGraphQL Storefront Auth:
Authorization: Bearer {storefront_token}</quick_reference>