BigCommerce Integration

Overview

Walkers Game Ear uses the BigCommerce for WordPress plugin (Suma customized) v5.0.7.20 to integrate BigCommerce's headless commerce platform with WordPress. This custom fork includes Rhino Group-specific enhancements and optimizations not present in the official BigCommerce plugin.

Plugin Details

Plugin Name: BigCommerce for WordPress (Suma)
Version: 5.0.7.20
Location: wp-content/plugins/bigcommerce-suma/
Main File: bigcommerce.php
Namespace: BigCommerce\

Suma Customizations (v5.0.7+)

The Suma fork includes these custom features beyond the official BigCommerce plugin:

Version 5.0.7.20

• Bi-directional sync control: Setting to disable WordPress → BigCommerce product data sync (prevents post_status changes from syncing back)

Version 5.0.7.19

• Webhook bug fixes: Corrected webhook name and PHP error handling

Version 5.0.7.18

• Cart/Checkout injection control: Setting to control on-the-fly injection of BigCommerce shortcodes into cart/checkout pages

Version 5.0.7.17

• Product delete behavior: Selection-based deletion instead of boolean (trash vs permanent delete)
• Bi-directional sync toggle: Disable sync of WordPress changes back to BigCommerce

Version 5.0.7.16

• Image cleanup: Remove WordPress attachments when images deleted in BigCommerce

Version 5.0.7.14

• Performance: Disabled user groups cache flushing (not used, causes cron lockup)

Version 5.0.7.12

• Auto-add to channel removed: Disabled flawed logic that inadvertently disabled products

Version 5.0.7.11

• Cron schedule options: Additional import frequency options

Version 5.0.7.8 - 5.0.7.9

• Nonce bypass: Customizer setting to disable pricing nonce field for sites using full-page caching

Version 5.0.7.6

• REST API price refresh toggle: Disable real-time product price refreshes via REST API

Version 5.0.7.5

• Force refresh settings: Checkboxes to force update all products/categories without BC changes

Version 5.0.7.3

• Image reimport: Ability to switch from image URL import to full image download

Configuration

API Connection Settings

Location: BigCommerce → Settings → API Credentials

Required fields:

• Store URL: https://{store-hash}.mybigcommerce.com
• Client ID: OAuth application client ID
• Client Secret: OAuth application secret
• Access Token: API access token
• Store Hash: BigCommerce store identifier

Channel Configuration:

• Multi-storefront channel support
• Channel ID mapped to WordPress site

Product Import Settings

Location: BigCommerce → Settings → Import

Setting	Default	Purpose
Import Schedule	Daily	How often to sync products
Batch Size	5	Products to process per chunk
Image Import Method	Full Import	Download images vs URL linking
Delete Old Images	No	Remove orphaned attachments
Force Product Refresh	No	Update all products regardless of changes
Force Category Refresh	No	Update all categories regardless of changes
Bi-Directional Sync	Enabled	Sync WordPress changes back to BC

Available Schedules:

• Hourly
• Twice Daily
• Daily (default)
• Weekly

WP-CLI Command:

wp bigcommerce import products

Cart Settings

Location: BigCommerce → Settings → Cart

• Cart Enabled: Yes
• Cart Page: Auto-created page with [bigcommerce_cart] shortcode
• Mini Cart: Displayed in header navigation
• Buy Now Mode: Disabled (cart is enabled)

Important: Cart page must be excluded from page caching.

Checkout Settings

Location: BigCommerce → Settings → Checkout

• Checkout Type: BigCommerce-hosted checkout (embedded)
• Checkout Page: Auto-created page with [bigcommerce_checkout] shortcode
• Complete Page: Order confirmation page post-checkout

Nonce Security:

• Pricing Nonce: Can be disabled via customizer for full-page caching compatibility

Account Settings

Location: BigCommerce → Settings → Accounts

• User Registration: Enabled (synced with WP settings)
• Login Page: [bigcommerce_signin_form]
• Registration Page: [bigcommerce_registration_form]
• Account Profile: [bigcommerce_account_profile]
• Order History: [bigcommerce_order_history]
• Address Management: [bigcommerce_shipping_address_list]
• Support Email: Displayed on order pages

Currency Settings

Location: BigCommerce → Settings → Currency

• Default Currency: Imported from BigCommerce API
• PHP intl Extension: Used for formatting if available
• Manual Format Settings: Available if intl not present

Product Synchronization

Import Process Flow

┌──────────────────────────────────────────────────────────┐
│ 1. Pre-Import: Add unlisted products to channel         │
└─────────────────┬────────────────────────────────────────┘
                  ▼
┌──────────────────────────────────────────────────────────┐
│ 2. Fetch: Get all product IDs from BC channel           │
└─────────────────┬────────────────────────────────────────┘
                  ▼
┌──────────────────────────────────────────────────────────┐
│ 3. Queue: Add products to import queue                  │
└─────────────────┬────────────────────────────────────────┘
                  ▼
┌──────────────────────────────────────────────────────────┐
│ 4. Mark Deletions: Flag removed products                │
└─────────────────┬────────────────────────────────────────┘
                  ▼
┌──────────────────────────────────────────────────────────┐
│ 5. Process Queue: Import products in batches (5/batch)  │
│    - Create/update WordPress posts                      │
│    - Import product images                              │
│    - Sync variants and modifiers                        │
│    - Update categories and brands                       │
└─────────────────┬────────────────────────────────────────┘
                  ▼
┌──────────────────────────────────────────────────────────┐
│ 6. Finalize: Update store settings, flush cache         │
└──────────────────────────────────────────────────────────┘

Product Data Mapping

BigCommerce Field	WordPress Equivalent	Notes
Product ID	post_meta: bigcommerce_id	BigCommerce product ID
Name	post_title	Editable in WordPress
Description	post_content	Editable in WordPress
SKU	post_meta: sku	Searchable
Price	post_meta: price_range	Calculated price range
Images	wp_postmeta + attachments	Downloadable or URL-linked
Categories	bigcommerce_category taxonomy	Synced as terms
Brand	bigcommerce_brand taxonomy	Synced as terms
Variants	post_meta: variants	JSON data
Custom Fields	post_meta: custom_fields	BigCommerce custom fields

Post Type: bigcommerce_product

Supports:

• Title (editable)
• Editor (editable)
• Thumbnail
• Custom fields

Taxonomies:

• bigcommerce_category — Product categories
• bigcommerce_brand — Product brands
• bigcommerce_availability — Stock availability
• bigcommerce_condition — Product condition
• bigcommerce_flag — Custom product flags

Meta Keys:

• bigcommerce_id — BigCommerce product ID
• bigcommerce_sku — Product SKU
• price_range — Calculated price range (min/max)
• variants — Product variant data
• modifiers — Product option modifiers
• custom_fields — BigCommerce custom fields

Bi-Directional Sync (Configurable)

When enabled, WordPress changes sync back to BigCommerce:

• Post Title → Product Name
• Post Content → Product Description
• Post Status (draft/publish) → Product Visibility

Note: Can be disabled via Suma customization setting to prevent accidental overwrites.

Shortcodes

Product Display

[bigcommerce_product] — Embed products on any page

Attributes:

• id — Comma-separated BigCommerce product IDs
• post_id — Comma-separated WordPress post IDs
• sku — Comma-separated SKUs
• category — Category slug(s)
• brand — Brand slug(s)
• featured — 1 to show only featured products
• sale — 1 to show only sale products
• recent — 1 to show recently imported (last 2 days)
• search — Search string
• paged — 0 to disable pagination
• per_page — Products per page
• order — ASC or DESC
• orderby — Sort field (e.g., title, date, price)

Example:

[bigcommerce_product category="ear-muffs" sale="1" per_page="12"]

Cart & Checkout

• [bigcommerce_cart] — Shopping cart page
• [bigcommerce_checkout] — Checkout initiation (redirects to BC hosted)

Account Management

• [bigcommerce_signin_form] — Login form
• [bigcommerce_registration_form] — User registration
• [bigcommerce_account_profile] — Profile editor
• [bigcommerce_order_history] — Past orders
• [bigcommerce_shipping_address_list] — Saved addresses

Theme Template Overrides

BigCommerce templates can be overridden in the theme:

Plugin Templates: plugins/bigcommerce-suma/templates/
Theme Overrides: themes/suma-elementor/bigcommerce/components/

Overridden Templates

Located in suma-elementor/bigcommerce/components/:

• accounts/ — Account page templates
• cart/ — Cart display templates
• option-types/ — Product option rendering
• orders/ — Order history templates
• products/ — Product card and single templates

Example Override:

// Theme override at: bigcommerce/components/products/product-card.php
// Original at: bigcommerce-suma/templates/public/components/products/product-card.php

REST API Endpoints

Custom Endpoints (Suma)

Pricing Refresh Control:

• Endpoint: /wp-json/bigcommerce/v1/pricing/refresh
• Purpose: Toggle real-time pricing updates
• Setting: Configurable via Customizer

Product Sync Triggers:

• Endpoint: /wp-json/bigcommerce/v1/import/trigger
• Purpose: Manually trigger product sync

Webhooks

BigCommerce webhooks notify WordPress of product changes:

Registered Webhooks:

• store/product/updated — Product data changed
• store/product/deleted — Product removed
• store/product/inventory/updated — Stock levels changed

Webhook Handler: wp-admin/admin-ajax.php?action=bigcommerce_webhook

Suma v5.0.7.19 Fix: Corrected webhook subscription to proper channel events.

Performance Optimizations

Image Handling

Full Import Mode (recommended):

• Downloads images to WordPress media library
• Enables WP Smush Pro compression
• Local image serving

URL Mode:

• Links to BigCommerce CDN URLs
• Faster imports, no local storage
• Dependent on BC CDN availability

Pricing API Toggle

Real-time pricing (default):

• REST API calls to BigCommerce for current prices
• Accurate but adds HTTP overhead

Cached pricing (Suma setting):

• Use synced prices from database
• Faster page loads
• Updates on daily import

Nonce Bypass for Caching

For sites using full-page caching (WP Rocket, Varnish):

Problem: Nonce fields prevent page caching
Solution: Disable nonce via Customizer setting
Trade-off: Reduced CSRF protection on cart actions

Troubleshooting

Common Issues

Products not syncing:

1. Check API credentials: BigCommerce → Settings
2. Verify channel configuration
3. Check WordPress cron: Plugins → WP Crontrol
4. Run manual import: wp bigcommerce import products

Images not displaying:

1. Verify image import mode (Full vs URL)
2. Check for orphaned attachments
3. Run "Delete Old Images" setting toggle

Cart not working:

1. Ensure cart page exists with shortcode
2. Verify cart is excluded from caching
3. Check nonce setting if using page cache

Checkout redirect fails:

1. Verify BigCommerce API connection
2. Check SSL certificate validity
3. Ensure customer tokens are syncing

Debug Mode

Enable debug logging:

// wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

Log location: wp-content/debug.log

WP-CLI Commands

# Import products
wp bigcommerce import products

# Flush cache
wp cache flush

# Check product count
wp post list --post_type=bigcommerce_product --format=count

Security Considerations

• API Credentials: Store in WordPress options (encrypted at rest)
• OAuth Tokens: Auto-refresh via BigCommerce OAuth flow
• Customer Data: Synced securely between WP and BC
• PCI Compliance: Checkout handled by BigCommerce (PCI-compliant)

Next Steps

• Theme Customizations — Custom product display widgets