Skip to content
Cobalz Affiliate

BigCommerce integration

Cobalz connects to BigCommerce via the Apps Marketplace OAuth flow. We subscribe to order and refund webhooks and store the per-store access token in Supabase Vault.

Install

  • From your merchant dashboard: Settings → Store connection → Install BigCommerce.
  • BigCommerce shows the standard app permission screen.
  • Approve. BigCommerce redirects to /api/bigcommerce/oauth/callback.
  • We exchange the code for an access token, subscribe webhooks, redirect to your dashboard.

Scopes

  • store_v2_orders_read_only
  • store_v2_customers_read_only
  • store_v2_marketing (for coupon creation on affiliate approval)

Webhook contract

Inbound webhooks land at /api/bigcommerce/webhook/<store_hash> with the BigCommerce-standard X-Auth-Hmac-Sha256 header. We verify against the per-merchant signing secret, confirm producer matches the canonical store hash, dedupe via webhook_events.

# Webhook scope subscriptions we register on install
store/order/created
store/order/updated
store/order/statusUpdated
store/order/refund/created

Required env vars

  • BIGCOMMERCE_CLIENT_ID, BIGCOMMERCE_CLIENT_SECRET — from your BigCommerce Devtools app.
  • BIGCOMMERCE_REDIRECT_URI — must match what your app declares.

Tracker

Drop the t.js snippet into Storefront → Script Manager (BigCommerce's equivalent of Google Tag Manager). Set the location to Footer, the type to Script, paste the tracker snippet from your dashboard.

Note:BigCommerce's checkout is sometimes hosted on a separate subdomain (checkout.yourstore.com). The first-party cookie won't cross unless you set the cookie domain explicitly. Use the BigCommerce Customer Account Hook to forward the _cobz_ref value to the checkout page; or rely on coupon-based attribution instead.