Skip to main content

BigCommerce Integration

Detailed documentation for the BigCommerce for WordPress (Suma Fork) integration powering StealthCam's e-commerce functionality.

Overview​

StealthCam uses BigCommerce for WordPress v5.0.7.18, a custom Suma fork of the official BigCommerce plugin that provides headless commerce capabilities with enhanced features and performance optimizations.

Suma Fork Enhancements​

The Suma custom fork includes 20+ enhancements over the base BigCommerce plugin:

Sync Control Features​

1. Bi-Directional Sync Control

  • Purpose: Prevent WordPress post status changes from syncing back to BigCommerce
  • Use Case: Allows WP scheduling/drafts without affecting BC product status
  • Setting: Customizer option to disable WP → BC sync

2. Product Delete Behavior

  • Purpose: Consolidated product removal logic
  • Options:
    • Delete WP post when removed from BC channel
    • Keep WP post but mark as unavailable
    • Custom action hooks for override
  • Setting: Configurable via plugin settings

3. Force Refresh Products/Categories

  • Purpose: Manual re-sync trigger for troubleshooting
  • Function: Clears cached product/term data and forces full re-import
  • Access: Settings page button

Performance Optimizations​

4. Pricing Nonce Bypass

  • Purpose: Enable full-page caching (WP Rocket, CloudFlare)
  • Issue Solved: Cart REST API requires nonce validation, breaks caching
  • Solution: Optional nonce bypass for anonymous users
  • Customizer Setting: "Bypass Pricing Nonce" checkbox

5. Disable REST API Price Refresh

  • Purpose: Reduce server load and API calls
  • Behavior: Uses cached prices from product import instead of real-time API
  • Trade-off: Slightly stale prices (updated on product import cron)
  • Setting: Customizer option

6. Disable User Groups Cache Flushing

  • Purpose: Prevent cron lockups during import
  • Issue Solved: Cache flush operations block import process
  • Setting: Disabled by default in Suma fork

Import Enhancements​

7. Image Import Options

  • Fast Mode: Store BigCommerce image URLs only (no local copy)
  • Full Mode: Download images to WordPress media library
  • Benefit: Faster imports, reduced storage with Fast Mode
  • Setting: Import configuration option

8. Advanced Image Cleanup

  • Purpose: Remove orphaned WordPress attachments when BC images are deleted
  • Behavior: Automatically cleans up media library on product update
  • Setting: Enabled by default

9. Additional Cron Timeframes

  • Purpose: Flexible scheduling beyond default "daily"
  • Options: Twice daily, hourly, every 15 minutes (for testing)
  • Setting: Import settings page

10. Extended Product/Term Update Logging

  • Purpose: Better debugging of sync issues
  • Logs: Product ID, update type, field changes, API responses
  • Access: WP_DEBUG_LOG file when debugging enabled

Multi-Storefront Features​

11. MSF (Multi-Storefront) Support

  • Purpose: Manage products across multiple BC channels
  • Features:
    • Channel-aware product import
    • Per-channel visibility
    • Channel-specific webhooks
  • Configuration: Settings > Channels tab

12. Channel Status Management

  • Purpose: Control product visibility per channel
  • States: Pre-launch, Active, Inactive
  • Setting: Product-level channel assignment

Custom Field Handling​

13. Enhanced Custom Fields Import

  • Purpose: Import all BigCommerce custom product fields
  • Storage: WordPress post meta
  • Display: Accessible via custom Elementor widgets
  • Examples: Warranty info, spec sheets, comparison data

14. Sale Price Range Display

  • Purpose: Show "from $X" for products with multiple sale prices
  • Calculation: Finds min/max across variants
  • Display: Product cards and listings

15. Variant Metadata Filtering

  • Purpose: Hide unavailable variants from variant selector
  • Logic: Filters out of stock or disabled variants
  • Setting: Configurable per product

Installation & Configuration​

Initial Setup​

1. Install Plugin

# Via WordPress admin
Plugins > Add New > Upload bigcommerce-for-wordpress-suma-5.0.7.18.zip

# Via WP-CLI
wp plugin install /path/to/bigcommerce-for-wordpress-suma-5.0.7.18.zip --activate

2. BigCommerce API Connection Navigate to: Settings > BigCommerce > Account

Required Credentials:

  • Store URL: https://store-HASH.mybigcommerce.com (replace HASH with store ID)
  • Client ID: From BC store API account
  • Client Secret: From BC store API account
  • Access Token: From BC store API account

3. Channel Configuration Settings > BigCommerce > Channels

  • Create WordPress channel in BigCommerce
  • Select channel in plugin settings
  • Configure channel-specific behavior

4. Import Settings Settings > BigCommerce > Import

  • Import Type: Fast Headless (recommended) or Full
  • Schedule: Daily at 3:00 AM (default)
  • Batch Size: 100 products per batch
  • Image Import: URL mode (recommended)

Advanced Configuration​

Customizer Settings Appearance > Customize > BigCommerce

  • Bypass pricing nonce: Enable for caching
  • Disable REST API price refresh: Enable for performance
  • Bi-directional sync: Disable to prevent WP → BC updates

Product Template Settings

  • Default template: Single product page
  • Alternative templates: Custom Elementor templates
  • Shortcode support: [bigcommerce_product id="123"]

Product Import Process​

Automatic Import (Cron)​

Schedule:

// Default schedule
wp_schedule_event(strtotime('03:00:00'), 'daily', 'bigcommerce/import/run');

// Custom schedules (Suma fork)
'twice_daily'  // 12-hour interval
'hourly'       // Every hour
'every_15min'  // For testing/development

Import Steps:

  1. Fetch products from BigCommerce API (paginated, 100 per request)
  2. Check for existing WordPress posts (by BC product ID)
  3. Create/update bigcommerce_product posts
  4. Import product images (URL or full download)
  5. Import variants and modifiers
  6. Set taxonomies (categories, brands)
  7. Update meta fields (price, SKU, inventory, custom fields)
  8. Trigger post-save hooks (Algolia re-index, FacetWP index)

Import Logs:

# View import log
tail -f wp-content/debug.log | grep "BigCommerce"

# Successful import
[BigCommerce] Imported product ID 123: "Trail Camera X"
[BigCommerce] Updated 15 variants for product 123

# Errors
[BigCommerce] Failed to import product 456: API timeout
[BigCommerce] Image download failed for product 789: 404 Not Found

Manual Import (WP-CLI)​

Commands:

# Full product import
wp bigcommerce import products

# Import specific products
wp bigcommerce import products --product_ids=123,456,789

# Import with force refresh
wp bigcommerce import products --force

# Import categories only
wp bigcommerce import categories

# Clear cache and re-import
wp bigcommerce flush
wp bigcommerce import products

Product Data Structure​

WordPress Post Structure​

Post Type: bigcommerce_product

Post Fields:

[
  'ID' => 123,
  'post_title' => 'Trail Camera X',
  'post_name' => 'trail-camera-x',
  'post_content' => 'Full product description HTML',
  'post_excerpt' => 'Short description',
  'post_status' => 'publish',
  'post_type' => 'bigcommerce_product'
]

Taxonomies:

  • bigcommerce_brand: Product brand
  • bigcommerce_category: Product categories (hierarchical)

Post Meta:

'bigcommerce_id' => 123,                    // BC product ID
'bigcommerce_sku' => 'TC-X-001',
'bigcommerce_price' => 199.99,              // Calculated price
'bigcommerce_retail_price' => 249.99,       // MSRP
'bigcommerce_sale_price' => 179.99,         // Sale price
'bigcommerce_inventory_level' => 50,
'bigcommerce_inventory_tracking' => 'product',
'bigcommerce_weight' => 1.5,
'bigcommerce_dimensions' => [
  'width' => 4,
  'height' => 6,
  'depth' => 3
],
'bigcommerce_custom_fields' => [
  'Warranty' => '3 Years',
  'Resolution' => '20MP',
  'Battery Life' => '6 Months'
]

GraphQL Variant Data​

Injected into product page template for JavaScript access:

window.bigcommerce_config = {
  product_id: 123,
  variants: [
    {
      variant_id: 456,
      sku: 'TC-X-001-BLK',
      price: 199.99,
      sale_price: 179.99,
      inventory: 25,
      options: [
        { name: 'Color', value: 'Black' },
        { name: 'Memory', value: '32GB' }
      ],
      image: {
        url: 'https://cdn.example.com/image.jpg',
        alt: 'Trail Camera X - Black'
      }
    }
  ]
};

REST API Endpoints​

Cart Operations​

Add to Cart:

POST /wp-json/bigcommerce/v1/cart/{cart_id}/items
Content-Type: application/json

{
  "product_id": 123,
  "variant_id": 456,
  "quantity": 1
}

Update Cart Item:

PUT /wp-json/bigcommerce/v1/cart/{cart_id}/items/{item_id}

{
  "quantity": 2
}

Remove from Cart:

DELETE /wp-json/bigcommerce/v1/cart/{cart_id}/items/{item_id}

Get Cart:

GET /wp-json/bigcommerce/v1/cart/{cart_id}

Response:
{
  "cart_id": "abc123",
  "items": [...],
  "subtotal": 199.99,
  "tax": 15.00,
  "total": 214.99
}

Pricing​

Get Product Price:

GET /wp-json/bigcommerce/v1/products/{product_id}/pricing

Response:
{
  "price": {
    "as_entered": 199.99,
    "entered_inclusive": false,
    "tax_exclusive": 199.99,
    "tax_inclusive": 214.99
  },
  "retail_price": 249.99,
  "sale_price": 179.99
}

Shortcodes​

Product Card:

[bigcommerce_product id="123" size="large"]

Product Grid:

[bigcommerce_product_grid category="trail-cameras" limit="12"]

Buy Button:

[bc_product_buy_button id="123"]

Product Components:

[bc_product_title id="123"]
[bc_product_price id="123"]
[bc_product_image id="123" size="medium"]
[bc_product_description id="123"]
[bc_product_form id="123"]

Webhooks​

Configured Webhooks:

store/product/created          → Update WP: Create product post
store/product/updated          → Update WP: Update product post
store/product/deleted          → Update WP: Delete/mark unavailable
store/product/inventory/updated → Update WP: Sync stock levels
store/order/created            → Analytics: Track conversion

Webhook Handler URL:

https://stealthcam.com/wp-json/bigcommerce/v1/webhooks

Webhook Validation:

  • HMAC signature verification (required)
  • IP whitelist (BigCommerce IPs only)
  • Retry logic for failed webhooks (3 attempts)

Template Overrides​

Override BigCommerce Templates:

wp-content/themes/suma-elementor/bigcommerce/
├── components/
│   ├── products/
│   │   ├── product-card.php
│   │   ├── product-title.php
│   │   ├── product-price.php
│   │   └── product-form.php
│   └── cart/
│       ├── cart-item.php
│       └── cart-totals.php
└── single-bigcommerce_product.php

Troubleshooting​

Common Issues​

1. Products Not Importing

# Check import status
wp bigcommerce import status

# Check API connection
wp bigcommerce test-connection

# Force re-import
wp bigcommerce import products --force

# Check logs
tail -f wp-content/debug.log | grep BigCommerce

2. Pricing Not Updating

  • Ensure cron is running: wp cron event list
  • Check "Disable REST API price refresh" setting
  • Clear object cache: wp cache flush
  • Force product re-import

3. Cart Not Working

  • Check "Bypass pricing nonce" setting for cached pages
  • Verify cart cookie is being set
  • Test with caching disabled
  • Check browser console for JavaScript errors

4. Images Not Loading

  • Verify image import mode (URL vs. full download)
  • Check BigCommerce CDN accessibility
  • Test image URLs manually in browser
  • Check WordPress media library permissions

Debug Mode​

Enable Debug Logging:

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

View Debug Log:

tail -f wp-content/debug.log