BigCommerce platform help — open SaaS commerce platform for makers and growing DTC/B2B stores: products, orders, customers, carts, checkout, and headless storefronts via REST Management APIs (v3 plus legacy v2 Orders), GraphQL Storefront and Admin APIs, and thin notification-style webhooks. Use when building a BigCommerce REST or webhook integration, a webhook fired but its payload only has a resource id so orders or products aren't syncing, webhooks silently deactivated after repeated failures or inactivity, hitting 429 rate limits (150 req/30s on Standard/Plus, 450 on Pro) and needing backoff, a request 403s from a trailing slash or missing OAuth scope, syncing orders or customers into a CRM or data warehouse, or comparing BigCommerce plans and transaction fees. Do NOT use for checkout-conversion strategy across carts (use /sales-checkout) or picking a Merchant of Record for global tax (use /sales-merchant-of-record).
Instrucciones de origen · Vista previa de solo lectura
name
sales-bigcommerce
description
BigCommerce platform help — open SaaS commerce platform for makers and growing DTC/B2B stores: products, orders, customers, carts, checkout, and headless storefronts via REST Management APIs (v3 plus legacy v2 Orders), GraphQL Storefront and Admin APIs, and thin notification-style webhooks. Use when building a BigCommerce REST or webhook integration, a webhook fired but its payload only has a resource id so orders or products aren't syncing, webhooks silently deactivated after repeated failures or inactivity, hitting 429 rate limits (150 req/30s on Standard/Plus, 450 on Pro) and needing backoff, a request 403s from a trailing slash or missing OAuth scope, syncing orders or customers into a CRM or data warehouse, or comparing BigCommerce plans and transaction fees. Do NOT use for checkout-conversion strategy across carts (use /sales-checkout) or picking a Merchant of Record for global tax (use /sales-merchant-of-record).
argument-hint
[describe what you need help with in BigCommerce — e.g. 'webhook only sends an id, how do I get the order' or 'sync orders to my CRM']
license
MIT
version
1.0.0
tags
["sales","checkout","ecommerce","platform"]
github
https://github.com/bigcommerce
BigCommerce Platform Help
Step 1 — Gather context
If references/learnings.md exists, read it first for accumulated platform knowledge.
Figure out what the user actually needs before diving in:
Goal — building/debugging an API or webhook integration, choosing a plan, a checkout/conversion question, or a store-ops task?
Surface — REST Management API (v3 / legacy v2), GraphQL Storefront API, GraphQL Admin API, webhooks, or the no-code control panel?
Account type — store-level API account (token from control panel), app-level (OAuth, Dev Portal), or account-level (GraphQL Account API across stores)?
Plan — Standard, Plus, Pro, or Enterprise? (Rate limits and a few features scale by tier; some plan names appear as Core/Growth/Scale/Performance on the current pricing page.)
Skip-ahead rule: if the prompt already says what they need, go straight to Step 2.
Step 2 — Route or answer directly
If the question is really a cross-platform strategy, hand off with the exact command:
If the user wants…
Route to
Checkout conversion / order bumps / cart-abandonment tactics across carts
/sales-checkout {question}
Whether to use a Merchant of Record for global VAT/sales tax
/sales-merchant-of-record {question}
Digital-product pricing & launch strategy
/sales-digital-products {question}
Wiring BigCommerce into another tool via iPaaS
/sales-integration {question}
Post-purchase email / abandoned-cart sequences
/sales-email-marketing {question}
Otherwise it's a BigCommerce-specific question — answer it here.
Step 3 — BigCommerce platform reference
Read references/platform-guide.md for the full reference — capabilities and what's API vs webhook vs UI-only, pricing/plan gates, data model with JSON shapes, and quick-start recipes. For raw endpoint/auth/rate-limit/webhook detail, read references/bigcommerce-api-reference.md.
Answer using only the relevant section — don't dump the whole guide.
Step 4 — Actionable guidance
Treat webhooks as a doorbell, not a delivery. Every callback carries only , , and — fetch the real record with a follow-up REST call. Budget for that extra call against your rate limit; consider de-duping on the resource id + .
scope
store_id
data.{type,id}
created_at
Know the version split. Most resources are v3 (/v3/catalog/products, /v3/customers, /v3/carts, /v3/hooks), but the classic Orders API is v2 (/v2/orders). New work should prefer v3 where it exists.
Pace requests to the 30-second window. Standard/Plus get ~150 requests/30s, Pro ~450; read X-Rate-Limit-Requests-Left and sleep for X-Rate-Limit-Time-Reset-Ms on a 429.
Use the minimum OAuth scopes. A missing scope returns 403, not empty data; and a stray trailing slash on a path also 403s.
If you discover a gotcha or fix not in references/learnings.md, append it there with today's date.
Gotchas
Best-effort from research (2026-06) — re-verify plan gates, fees, rate limits, and API versions against live docs.
Thin webhook payloads. Callbacks never include the changed object — only the id. You must call the API to get the data, which effectively doubles API usage per event.
No webhook delivery logs. There is no activity dashboard or delivery-history endpoint; if an event goes missing you can't trace it on BigCommerce's side. Log everything you receive and reconcile against the API.
Webhooks auto-deactivate. Repeated 4XX/5XX responses (or long inactivity) deactivate a subscription — respond 2XX fast (do work async) and re-check is_active.
No HMAC signing. Unlike Shopify/Stripe, BigCommerce does not sign payloads. Secure the callback with a secret in a custom header you set at creation, and only accept HTTPS on port 443 (custom ports are rejected).
403 traps. A trailing slash on an endpoint, or a missing OAuth scope, both return 403 — not a 404 or empty body.
Transaction fees. $0 on embedded payment providers, but using an "open"/third-party gateway adds a per-GMV fee (e.g. ~2% on entry tier, scaling down by plan).
/sales-shopify — The other leading hosted commerce backend; compare if you're choosing a platform.
/sales-merchant-of-record — Whether to use a MoR (Paddle, Lemon Squeezy) for global tax instead of self-managing.
/sales-digital-products — Pricing, packaging, and launch strategy for digital products.
/sales-do — Not sure which skill to use? The router matches any sales objective to the right skill. Install: npx skills add sales-skills/sales --skill sales-do -a claude-code
Examples
Example 1: Webhook only sends an id (developer/automation)
User: "My BigCommerce store/order/created webhook fires but the payload has no order details — orders aren't syncing to my CRM."
Approach: Explain that BigCommerce webhooks are intentionally thin — the payload is just {scope, store_id, data:{type, id}, hash, created_at, producer}. In the handler, read data.id and make a follow-up GET /v2/orders/{id} (Orders is v2) to fetch the full record, then upsert into the CRM. Respond 2XX immediately and do the fetch async so the subscription doesn't deactivate; de-dupe on data.id since redelivery is possible.
Example 2: Bulk-syncing the catalog without 429s (developer/automation)
User: "How do I pull every product into my warehouse without getting rate-limited?"
Approach: Page GET /v3/catalog/products?limit=250&page=N using the meta.pagination cursor, and pace to the 30-second quota — on a 429, sleep for X-Rate-Limit-Time-Reset-Ms and resume. Show watching X-Rate-Limit-Requests-Left. Standard/Plus ≈150 req/30s, Pro ≈450; for very large/ongoing sync prefer incremental store/product/updated webhooks over full re-crawls.
Example 3: Choosing a plan
User: "I'm starting a store and on the entry plan a gateway is charging me extra — is upgrading worth it?"
Approach: Explain the $0 fee on embedded payment providers vs the open-gateway per-GMV surcharge that drops by tier, that GMV thresholds auto-upgrade you, and that API rate limits rise with the plan (Standard/Plus ~150 → Pro ~450 req/30s). Map their actual order volume and gateway choice to the breakeven rather than upgrading by default.
Troubleshooting
"My webhook fires but I get no order/product data"
By design — payloads carry only the resource id. Fetch the object with a follow-up REST call (/v2/orders/{id}, /v3/catalog/products/{id}, /v3/customers?id:in={id}). Respond 2XX within a few seconds and do the fetch asynchronously, or the subscription will deactivate after repeated slow/failed responses.
"Getting 429 Too Many Requests"
Rate limits are a quota per 30-second window (≈150 on Standard/Plus, ≈450 on Pro, custom on Enterprise). Read X-Rate-Limit-Requests-Left to throttle proactively and, on a 429, sleep for the X-Rate-Limit-Time-Reset-Ms value before retrying with incremental backoff. Spread bulk imports across windows.
"I'm getting a 403 on a request that looks correct"
Two common causes: a trailing slash on the endpoint path (remove it), or an OAuth scope your token wasn't granted (regenerate the store-level API account with the right read/modify scopes). 403 — not 404 — is BigCommerce's signal for both.
