BigCommerce Integration

ScentLok uses a custom fork of BigCommerce for WordPress (BC4WP) to integrate BigCommerce's e-commerce platform with WordPress content management.

Overview

Plugin: BigCommerce for WordPress (Suma Fork)
Version: 5.0.7.17
Base: Official BC4WP with Rhino Group enhancements

Key Features

Bi-Directional Sync Control

The Suma fork includes enhanced sync controls that allow selective synchronization:

// Enable bi-directional sync for specific fields
add_filter( 'bigcommerce/sync/products/direction', function( $direction, $product_id ) {
    // 'pull' = BC to WP only (default)
    // 'push' = WP to BC only
    // 'both' = Bi-directional
    return 'both';
}, 10, 2 );

// Skip specific product fields during sync
add_filter( 'bigcommerce/sync/products/skip_fields', function( $skip_fields ) {
    return array_merge( $skip_fields, [
        'description', // Don't overwrite WP description
        'custom_url',  // Preserve WP URLs
    ]);
});

Pricing Nonce Bypass

Custom enhancement to handle pricing display without excessive nonce generation:

// Bypass nonce for cached pricing
add_filter( 'bigcommerce/pricing/cache_enabled', '__return_true' );
add_filter( 'bigcommerce/pricing/cache_duration', function() {
    return 15 * MINUTE_IN_SECONDS; // 15-minute cache
});

Gift Certificate Support

Enhanced gift certificate creation and redemption:

// Gift certificate post type
register_post_type( 'bc_gift_cert', [
    'public'       => false,
    'show_ui'      => true,
    'show_in_menu' => 'bigcommerce',
    'supports'     => [ 'title', 'editor' ],
    'labels'       => [
        'name' => 'Gift Certificates',
        'singular_name' => 'Gift Certificate',
    ],
]);

// Create gift certificate in BigCommerce
function create_gift_certificate( $amount, $recipient_email, $message ) {
    $api = new \BigCommerce\Api\v3\Api\GiftCertificatesApi();
    
    $certificate = [
        'amount'        => $amount,
        'to_email'      => $recipient_email,
        'to_name'       => '',
        'from_name'     => '',
        'message'       => $message,
        'template'      => 'General',
        'status'        => 'active',
    ];
    
    try {
        $response = $api->createGiftCertificate( $certificate );
        return $response['data'];
    } catch ( Exception $e ) {
        error_log( 'Gift Certificate Error: ' . $e->getMessage() );
        return false;
    }
}

Product Synchronization

Webhook Configuration

BigCommerce webhooks trigger product updates:

// Register product webhooks
add_action( 'bigcommerce/settings/webhooks/register', function() {
    $webhooks = [
        'store/product/created',
        'store/product/updated',
        'store/product/deleted',
        'store/product/inventory/updated',
    ];
    
    foreach ( $webhooks as $scope ) {
        register_webhook( $scope, get_rest_url( null, '/bigcommerce/v1/webhook' ) );
    }
});

// Process webhook
add_action( 'rest_api_init', function() {
    register_rest_route( 'bigcommerce/v1', '/webhook', [
        'methods'  => 'POST',
        'callback' => 'process_bigcommerce_webhook',
        'permission_callback' => 'validate_webhook_signature',
    ]);
});

function process_bigcommerce_webhook( $request ) {
    $scope = $request->get_param( 'scope' );
    $data  = $request->get_param( 'data' );
    
    switch ( $scope ) {
        case 'store/product/updated':
            $product_id = $data['id'];
            queue_product_import( $product_id );
            break;
            
        case 'store/product/inventory/updated':
            $product_id = $data['product_id'];
            update_product_inventory( $product_id );
            break;
    }
    
    return new WP_REST_Response( [ 'success' => true ], 200 );
}

Import Queue System

Products are imported via a queue system to avoid timeout issues:

// Queue product for import
function queue_product_import( $bc_product_id ) {
    global $wpdb;
    
    $wpdb->insert(
        $wpdb->prefix . 'bc_import_queue',
        [
            'bc_product_id' => $bc_product_id,
            'status'        => 'pending',
            'attempts'      => 0,
            'created_at'    => current_time( 'mysql' ),
        ]
    );
}

// Process import queue (cron job)
add_action( 'bigcommerce/import/queue', function() {
    global $wpdb;
    
    $queue_items = $wpdb->get_results(
        "SELECT * FROM {$wpdb->prefix}bc_import_queue 
         WHERE status = 'pending' 
         AND attempts < 3 
         LIMIT 10"
    );
    
    foreach ( $queue_items as $item ) {
        try {
            import_product_from_bigcommerce( $item->bc_product_id );
            
            // Mark as complete
            $wpdb->update(
                $wpdb->prefix . 'bc_import_queue',
                [ 'status' => 'complete' ],
                [ 'id' => $item->id ]
            );
        } catch ( Exception $e ) {
            // Increment attempts
            $wpdb->update(
                $wpdb->prefix . 'bc_import_queue',
                [ 'attempts' => $item->attempts + 1 ],
                [ 'id' => $item->id ]
            );
            
            error_log( "Import failed for BC product {$item->bc_product_id}: " . $e->getMessage() );
        }
    }
});

// Schedule cron
add_action( 'init', function() {
    if ( ! wp_next_scheduled( 'bigcommerce/import/queue' ) ) {
        wp_schedule_event( time(), 'every_5_minutes', 'bigcommerce/import/queue' );
    }
});

Product Data Mapping

BigCommerce products map to WordPress custom post types:

// Product post type
register_post_type( 'bigcommerce_product', [
    'public'       => true,
    'has_archive'  => true,
    'rewrite'      => [ 'slug' => 'products' ],
    'supports'     => [ 'title', 'editor', 'thumbnail', 'custom-fields' ],
    'taxonomies'   => [ 'bc_category', 'bc_brand' ],
]);

// Store BigCommerce data as post meta
function save_product_meta( $post_id, $bc_product ) {
    update_post_meta( $post_id, 'bc_id', $bc_product['id'] );
    update_post_meta( $post_id, 'bc_sku', $bc_product['sku'] );
    update_post_meta( $post_id, 'bc_price', $bc_product['price'] );
    update_post_meta( $post_id, 'bc_sale_price', $bc_product['sale_price'] );
    update_post_meta( $post_id, 'bc_inventory_level', $bc_product['inventory_level'] );
    update_post_meta( $post_id, 'bc_inventory_tracking', $bc_product['inventory_tracking'] );
    update_post_meta( $post_id, 'bc_variants', $bc_product['variants'] );
}

Cart & Checkout

Cart Management

// Add product to cart
add_action( 'wp_ajax_add_to_cart', 'handle_add_to_cart' );
add_action( 'wp_ajax_nopriv_add_to_cart', 'handle_add_to_cart' );

function handle_add_to_cart() {
    $product_id = intval( $_POST['product_id'] );
    $variant_id = intval( $_POST['variant_id'] );
    $quantity   = intval( $_POST['quantity'] );
    
    // Get or create cart
    $cart_id = get_cart_id();
    
    // Add item via BigCommerce API
    $api = new \BigCommerce\Api\v3\Api\CartsApi();
    
    try {
        $response = $api->addCartLineItem( $cart_id, [
            'line_items' => [
                [
                    'product_id' => $product_id,
                    'variant_id' => $variant_id,
                    'quantity'   => $quantity,
                ],
            ],
        ]);
        
        wp_send_json_success( $response['data'] );
    } catch ( Exception $e ) {
        wp_send_json_error( $e->getMessage() );
    }
}

// Get cart ID from session or create new
function get_cart_id() {
    $cart_id = WC()->session->get( 'bc_cart_id' );
    
    if ( ! $cart_id ) {
        $api      = new \BigCommerce\Api\v3\Api\CartsApi();
        $response = $api->createCart([]);
        $cart_id  = $response['data']['id'];
        
        WC()->session->set( 'bc_cart_id', $cart_id );
    }
    
    return $cart_id;
}

Checkout Redirect

// Redirect to BigCommerce checkout
add_action( 'template_redirect', function() {
    if ( is_page( 'checkout' ) ) {
        $cart_id = get_cart_id();
        
        // Generate checkout URL
        $api          = new \BigCommerce\Api\v3\Api\CheckoutsApi();
        $checkout     = $api->createCheckout( $cart_id );
        $checkout_url = $checkout['data']['url'];
        
        // Add SLoyalty tracking
        $checkout_url = add_query_arg( 'sloyalty_track', 'true', $checkout_url );
        
        wp_redirect( $checkout_url );
        exit;
    }
});

Order Processing

// Process order webhook
add_action( 'bigcommerce/webhook/order_created', function( $order_data ) {
    $order_id       = $order_data['id'];
    $customer_email = $order_data['billing_address']['email'];
    $total          = $order_data['total_inc_tax'];
    
    // Create WordPress order record
    $post_id = wp_insert_post([
        'post_type'   => 'bc_order',
        'post_title'  => "Order #{$order_id}",
        'post_status' => 'publish',
        'meta_input'  => [
            'bc_order_id'      => $order_id,
            'customer_email'   => $customer_email,
            'order_total'      => $total,
            'order_status'     => $order_data['status'],
            'payment_method'   => $order_data['payment_method'],
            'created_at'       => $order_data['date_created'],
        ],
    ]);
    
    // Trigger SLoyalty points
    do_action( 'sloyalty/order_complete', $customer_email, $total );
    
    // Send to Narvar for tracking
    do_action( 'narvar/order_created', $order_id );
});

API Configuration

Store Connection

// wp-config.php
define( 'BIGCOMMERCE_CLIENT_ID', 'your-client-id' );
define( 'BIGCOMMERCE_CLIENT_SECRET', 'your-client-secret' );
define( 'BIGCOMMERCE_ACCESS_TOKEN', 'your-access-token' );
define( 'BIGCOMMERCE_STORE_HASH', 'your-store-hash' );

API Client Setup

// Initialize BigCommerce API client
function get_bigcommerce_client() {
    $config = new \BigCommerce\Api\v3\Configuration();
    $config->setHost( 'https://api.bigcommerce.com/stores/' . BIGCOMMERCE_STORE_HASH );
    $config->setAccessToken( BIGCOMMERCE_ACCESS_TOKEN );
    
    return $config;
}

// Example API usage
$api = new \BigCommerce\Api\v3\Api\CatalogApi( null, get_bigcommerce_client() );
$products = $api->getProducts();

Performance Optimizations

API Response Caching

// Cache API responses
function get_bc_product_cached( $product_id ) {
    $cache_key = "bc_product_{$product_id}";
    $product   = wp_cache_get( $cache_key, 'bigcommerce' );
    
    if ( false === $product ) {
        $api     = new \BigCommerce\Api\v3\Api\CatalogApi( null, get_bigcommerce_client() );
        $product = $api->getProductById( $product_id );
        
        wp_cache_set( $cache_key, $product, 'bigcommerce', 15 * MINUTE_IN_SECONDS );
    }
    
    return $product;
}

Lazy Loading Variants

// Load variants on demand
add_action( 'wp_ajax_get_product_variants', 'get_product_variants_ajax' );
add_action( 'wp_ajax_nopriv_get_product_variants', 'get_product_variants_ajax' );

function get_product_variants_ajax() {
    $product_id = intval( $_GET['product_id'] );
    $variants   = get_bc_product_variants_cached( $product_id );
    
    wp_send_json_success( $variants );
}

Troubleshooting

Common Issues

Products not syncing:

# Check webhook status
wp eval "var_dump( get_option( 'bigcommerce_webhooks' ) );"

# Manual product import
wp bigcommerce import products --limit=100

Cart errors:

# Clear cart cache
wp cache flush

# Check cart ID
wp eval "echo WC()->session->get( 'bc_cart_id' );"

API authentication errors:

// Verify credentials
$client = new \BigCommerce\Api\v3\Api\CatalogApi( null, get_bigcommerce_client() );
try {
    $test = $client->getProducts([ 'limit' => 1 ]);
    echo "Connection successful\n";
} catch ( Exception $e ) {
    echo "Error: " . $e->getMessage() . "\n";
}

Testing

Unit Tests

class BigCommerce_Integration_Test extends WP_UnitTestCase {
    
    public function test_product_import() {
        $bc_product_id = 123;
        $post_id = import_product_from_bigcommerce( $bc_product_id );
        
        $this->assertIsInt( $post_id );
        $this->assertEquals( $bc_product_id, get_post_meta( $post_id, 'bc_id', true ) );
    }
    
    public function test_cart_creation() {
        $cart_id = get_cart_id();
        
        $this->assertNotEmpty( $cart_id );
        $this->assertEquals( $cart_id, WC()->session->get( 'bc_cart_id' ) );
    }
}

Hooks & Filters

Available Filters

// Modify sync direction
apply_filters( 'bigcommerce/sync/products/direction', 'pull', $product_id );

// Skip product fields during sync
apply_filters( 'bigcommerce/sync/products/skip_fields', [], $product_id );

// Modify cart redirect URL
apply_filters( 'bigcommerce/cart/redirect_url', $url, $cart_id );

// Customize checkout URL
apply_filters( 'bigcommerce/checkout/url', $url, $cart_id );

Available Actions

// After product imported
do_action( 'bigcommerce/product/imported', $post_id, $bc_product );

// Before cart item added
do_action( 'bigcommerce/cart/before_add_item', $product_id, $variant_id );

// After order created
do_action( 'bigcommerce/order/created', $order_id, $order_data );