bigcommerce-api

<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>

1. Build a new integration (REST API, webhooks, data sync)
2. Create a headless storefront (GraphQL Storefront, Next.js/Catalyst)
3. Develop a BigCommerce app (single-click app, marketplace)
4. Work with specific API (Catalog, Orders, Customers, Payments)
5. Debug an API issue (errors, authentication, rate limits)
6. Set up webhooks and event handling
7. 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 state

Report 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/json

GraphQL Storefront Auth:

Authorization: Bearer {storefront_token}

</quick_reference>