sales-skills/sales-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 scope, store_id, and data.{type,id} — 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 + 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).

Related skills

• /sales-checkout — Checkout-conversion strategy across carts (order bumps, upsells, cart-abandonment recovery).
• /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.