Hooks & Filters Reference

Commerce Connect provides WordPress® hooks and filters to customize plugin behavior and extend functionality.

Overview

Hooks and filters allow developers to:

• Modify plugin behavior without editing core files
• Add custom functionality at specific points in execution
• Customize settings, templates, and integrations
• Extend product sync and data processing

All Commerce Connect hooks use the commerce_connect_ prefix for consistency.

Plugin Lifecycle Hooks

commerce_connect_plugin_init

Fires after the plugin instance is initialized.

Parameters:

• $instance (Plugin) - The plugin singleton instance

Use Case: Register additional services or modify plugin behavior after initialization.

Example:

add_action('commerce_connect_plugin_init', function($instance) {
    // Add custom initialization logic
    error_log('Commerce Connect initialized');

    // Register custom post meta or taxonomies
    register_post_meta('product', 'custom_field', [
        'type' => 'string',
        'single' => true,
    ]);
});

commerce_connect_install

Fires on first plugin installation (not on reactivation).

Parameters: None

Use Case: One-time setup tasks like creating custom database tables or default content.

Example:

add_action('commerce_connect_install', function() {
    // Create custom table or seed default data
    global $wpdb;
    $table_name = $wpdb->prefix . 'commerce_custom_data';

    $charset_collate = $wpdb->get_charset_collate();
    $sql = "CREATE TABLE $table_name (
        id mediumint(9) NOT NULL AUTO_INCREMENT,
        product_id bigint(20) NOT NULL,
        custom_data text NOT NULL,
        PRIMARY KEY  (id)
    ) $charset_collate;";

    require_once(ABSPATH . 'wp-admin/includes/upgrade.php');
    dbDelta($sql);
});

commerce_connect_activate

Fires every time the plugin is activated.

Parameters: None

Use Case: Tasks that should run on each activation (flush rewrite rules, refresh data).

Example:

add_action('commerce_connect_activate', function() {
    // Flush rewrite rules to register product permalinks
    flush_rewrite_rules();

    // Schedule recurring tasks
    if (!wp_next_scheduled('commerce_connect_daily_sync')) {
        wp_schedule_event(time(), 'daily', 'commerce_connect_daily_sync');
    }
});

commerce_connect_deactivate

Fires when the plugin is deactivated.

Parameters: None

Use Case: Clean up scheduled tasks or temporary data.

Example:

add_action('commerce_connect_deactivate', function() {
    // Remove scheduled events
    wp_clear_scheduled_hook('commerce_connect_daily_sync');

    // Clear transient caches
    delete_transient('commerce_connect_product_cache');
});

commerce_connect_uninstall

Fires when the plugin is completely uninstalled.

Parameters: None

Use Case: Complete cleanup of plugin data (only if user chooses to remove data).

Example:

add_action('commerce_connect_uninstall', function() {
    // Remove all plugin options
    delete_option('commerce_connect_settings');
    delete_option('commerce_connect_sync_sequence_id');

    // Remove custom tables
    global $wpdb;
    $wpdb->query("DROP TABLE IF EXISTS {$wpdb->prefix}commerce_custom_data");
});

Product Sync Hooks

commerce_connect_product_synced

Fires after a product has been synced from BigCommerce.

Parameters:

• $productId (int) - The WordPress® post ID of the synced product

Use Case: Trigger custom actions after product sync (update related data, send notifications).

Example:

add_action('commerce_connect_product_synced', function($productId) {
    // Log sync event
    error_log("Product {$productId} synced from BigCommerce");

    // Update custom meta or trigger external API
    $product_data = get_post($productId);
    update_post_meta($productId, 'last_sync_time', current_time('mysql'));

    // Trigger cache warming or search index update
    do_action('update_product_search_index', $productId);
});

Product Meta Migration

wpe_mustang_product_meta_migrated

Fires after product metadata has been successfully migrated from a WooCommerce® product to a BigCommerce-synced product.

Parameters:

• $bcPostId (int) - WordPress® post ID of the BigCommerce-synced product that received the migrated data
• $wcPostId (int) - WordPress® post ID of the source WooCommerce® product

When it fires: Once per successfully matched product (by SKU), after ACF fields have been copied and _wc_source_post_id meta has been written to the BigCommerce post.

Does not fire for:

• Products skipped due to duplicate SKUs
• Products not found in WooCommerce®
• Migration errors or timeouts

Use Case: Migrate custom meta fields that aren’t handled by the default GPF (Google Product Feed) migration.

Example: Copy Single Meta Key

add_action('wpe_mustang_product_meta_migrated', function(int $bcPostId, int $wcPostId): void {
    // Copy a single custom meta field from WooCommerce® to BigCommerce
    $value = get_post_meta($wcPostId, 'custom_shipping_class', true);

    if ($value !== '' && $value !== false) {
        update_post_meta($bcPostId, 'custom_shipping_class', $value);
    }
});

Example: Migrate Multiple Custom Fields

add_action('wpe_mustang_product_meta_migrated', function(int $bcPostId, int $wcPostId): void {
    // Define custom fields to migrate
    $meta_keys = [
        'supplier_id',
        'warehouse_location',
        'reorder_threshold',
        'product_certification',
    ];

    foreach ($meta_keys as $key) {
        $value = get_post_meta($wcPostId, $key, true);

        if ($value !== '' && $value !== false) {
            update_post_meta($bcPostId, $key, $value);
        }
    }
});

Example: Transform Data During Migration

add_action('wpe_mustang_product_meta_migrated', function(int $bcPostId, int $wcPostId): void {
    // Get WooCommerce® custom field
    $legacy_category = get_post_meta($wcPostId, 'legacy_category_id', true);

    if (!empty($legacy_category)) {
        // Transform to new taxonomy term
        $term = get_term_by('slug', $legacy_category, 'product-categories');

        if ($term) {
            wp_set_post_terms($bcPostId, [$term->term_id], 'product-categories', true);
        }
    }

    // Migrate and normalize pricing data
    $msrp = get_post_meta($wcPostId, 'msrp_price', true);
    if (!empty($msrp)) {
        // Store as ACF field on BC product
        update_field('field_msrp', floatval($msrp), $bcPostId);
    }
});

Example: Migrate ACF Field Group

add_action('wpe_mustang_product_meta_migrated', function(int $bcPostId, int $wcPostId): void {
    // Migrate entire ACF field group
    $field_group = [
        'product_dimensions' => 'field_dimensions',
        'product_weight_class' => 'field_weight_class',
        'product_origin_country' => 'field_origin_country',
        'hazmat_shipping' => 'field_hazmat',
    ];

    foreach ($field_group as $wc_key => $bc_field_key) {
        $value = get_field($wc_key, $wcPostId);

        if ($value !== false && $value !== '') {
            update_field($bc_field_key, $value, $bcPostId);
        }
    }
});

Example: Log Migration for Audit

add_action('wpe_mustang_product_meta_migrated', function(int $bcPostId, int $wcPostId): void {
    // Create audit log entry
    $bc_sku = get_post_meta($bcPostId, '_bigcommerce_sku', true);
    $wc_sku = get_post_meta($wcPostId, '_sku', true);

    error_log(sprintf(
        '[Product Meta Migration] Migrated WC Product #%d (SKU: %s) to BC Product #%d (SKU: %s) at %s',
        $wcPostId,
        $wc_sku,
        $bcPostId,
        $bc_sku,
        current_time('mysql')
    ));

    // Store migration timestamp on BC product
    update_post_meta($bcPostId, '_migration_completed_at', current_time('timestamp'));
});

Best Practices:

1. Check for empty values - Always verify meta exists before copying
2. Use type safety - Cast values to expected types (int, float, string)
3. Handle arrays carefully - WooCommerce® serialized data may need transformation
4. Log failures - Track which products had migration issues
5. Idempotent operations - Re-running migration should be safe

Related:

• Product Meta Migration Guide - User documentation for migration feature
• Custom Fields Compatibility - Custom fields plugin support details

Settings & Configuration Filters

commerce_connect_plugin_settings

Filter the plugin settings array.

Parameters:

• $settings (array) - Complete plugin settings configuration

Return: Modified settings array

Use Case: Add custom settings sections or modify default values.

Example:

add_filter('commerce_connect_plugin_settings', function($settings) {
    // Add custom settings section
    $settings['customSection'] = [
        'enabled' => true,
        'apiKey' => '',
        'webhook_url' => '',
    ];

    // Modify existing settings
    $settings['checkout']['applyThemeToCheckout'] = false;

    return $settings;
});

commerce_connect_client_settings

Filter client-side settings passed to JavaScript.

Parameters:

• $settings (array) - Settings object passed to frontend JavaScript

Return: Modified settings array

Use Case: Add custom configuration for frontend blocks and components.

Example:

add_filter('commerce_connect_client_settings', function($settings) {
    // Add custom frontend configuration
    $settings['customFeature'] = [
        'enabled' => get_option('custom_feature_enabled', true),
        'apiEndpoint' => rest_url('commerce-connect/v1/custom'),
    ];

    // Inject nonce for AJAX requests
    $settings['security'] = [
        'nonce' => wp_create_nonce('custom_action'),
    ];

    return $settings;
});

Integration Filters

commerce_connect_ga4_enabled

Control whether GA4 integration is enabled.

Parameters:

• $enabled (bool) - Current enabled state

Return: Boolean indicating if GA4 should be enabled

Example:

add_filter('commerce_connect_ga4_enabled', function($enabled) {
    // Disable GA4 in development environments
    if (defined('WP_ENVIRONMENT_TYPE') && WP_ENVIRONMENT_TYPE === 'development') {
        return false;
    }

    return $enabled;
});

commerce_connect_ga4_settings_schema

Filter GA4 settings schema.

Parameters:

• $schema (array) - GA4 settings schema definition

Return: Modified schema array

Example:

add_filter('commerce_connect_ga4_settings_schema', function($schema) {
    // Add custom GA4 property
    $schema['customDimension'] = [
        'type' => 'string',
        'default' => '',
    ];

    return $schema;
});

commerce_connect_ga4_client_settings

Filter GA4 client-side settings.

Parameters:

• $settings (array) - GA4 settings passed to frontend

Return: Modified settings array

Example:

add_filter('commerce_connect_ga4_client_settings', function($settings) {
    // Add custom tracking parameters
    $settings['customEvents'] = [
        'productViewed' => true,
        'categoryBrowsed' => true,
    ];

    return $settings;
});

commerce_connect_ga4_enqueue_scripts

Action hook when GA4 scripts are enqueued.

Parameters: None

Use Case: Enqueue additional analytics scripts or tracking code.

Example:

add_action('commerce_connect_ga4_enqueue_scripts', function() {
    // Enqueue custom tracking script
    wp_enqueue_script(
        'custom-analytics',
        get_template_directory_uri() . '/js/analytics.js',
        ['commerce-connect-ga4'],
        '1.0.0',
        true
    );
});

commerce_connect_consent_enabled

Control whether consent management is enabled.

Parameters:

• $enabled (bool) - Current enabled state

Return: Boolean

Example:

add_filter('commerce_connect_consent_enabled', function($enabled) {
    // Enable consent for EU visitors only
    if (function_exists('geoip_detect2_get_info_from_current_ip')) {
        $info = geoip_detect2_get_info_from_current_ip();
        return $info->continent->code === 'EU';
    }

    return $enabled;
});

commerce_connect_consent_settings_schema

Filter consent settings schema.

Parameters:

• $schema (array) - Consent settings schema

Return: Modified schema

commerce_connect_consent_client_settings

Filter consent client-side settings.

Parameters:

• $settings (array) - Consent settings for frontend

Return: Modified settings

commerce_connect_consent_enqueue_scripts

Action when consent scripts are enqueued.

Parameters: None

commerce_connect_banner_enabled

Control whether promotional banner is enabled.

Parameters:

• $enabled (bool) - Current enabled state

Return: Boolean

Example:

add_filter('commerce_connect_banner_enabled', function($enabled) {
    // Disable banner for specific user roles
    if (current_user_can('administrator')) {
        return false;
    }

    return $enabled;
});

commerce_connect_banner_settings_schema

Filter banner settings schema.

Parameters:

• $schema (array) - Banner settings schema

Return: Modified schema

commerce_connect_banner_client_settings

Filter banner client-side settings.

Parameters:

• $settings (array) - Banner settings for frontend

Return: Modified settings

commerce_connect_banner_enqueue_scripts

Action when banner scripts are enqueued.

Parameters: None

commerce_connect_seo_enabled

Control whether SEO integration is enabled.

Parameters:

• $enabled (bool) - Current enabled state (default: true)

Return: Boolean

Example:

add_filter('commerce_connect_seo_enabled', function($enabled) {
    // Disable SEO features if using custom implementation
    if (defined('CUSTOM_SEO_ACTIVE') && CUSTOM_SEO_ACTIVE) {
        return false;
    }

    return $enabled;
});

Product & Taxonomy Filters

commerce_connect_product_category_taxonomy

Filter the taxonomy used for product categories.

Parameters:

• $taxonomy (string) - Default: ‘product-categories’

Return: Taxonomy slug string

Use Case: Use custom taxonomy for product categorization.

Example:

add_filter('commerce_connect_product_category_taxonomy', function($taxonomy) {
    // Use custom taxonomy instead
    return 'custom_product_category';
});

commerce_connect_use_product_single_template

Control whether to use the Commerce Connect single product template.

Parameters:

• $use_template (bool) - Default: true

Return: Boolean

Use Case: Use theme’s custom product template instead of plugin default.

Example:

add_filter('commerce_connect_use_product_single_template', function($use_template) {
    // Use theme's custom product template
    if (is_child_theme()) {
        return false;
    }

    return $use_template;
});

commerce_connect_product_visibility_service

Filter the product visibility service instance.

Parameters:

• $service (ProductVisibilityService|null) - Visibility service instance

Return: ProductVisibilityService instance

Use Case: Replace with custom visibility logic.

Example:

add_filter('commerce_connect_product_visibility_service', function($service) {
    // Return custom visibility service
    return new CustomProductVisibilityService();
});

Webhook & API Filters

commerce_connect_webhook_dedup_ttl

Filter the webhook deduplication time-to-live in seconds.

Parameters:

• $ttl (int) - Default: 120 seconds

Return: TTL in seconds

Use Case: Adjust deduplication window for webhook processing.

Example:

add_filter('commerce_connect_webhook_dedup_ttl', function($ttl) {
    // Extend dedup window to 5 minutes
    return 300;
});

CSS & Styling Filters

commerce-connect.plugin.cssVariables

Filter CSS custom properties/variables.

Parameters:

• $variables (string) - CSS variables string

Return: Modified CSS variables

Use Case: Inject custom CSS variables for theming.

Example:

add_filter('commerce-connect.plugin.cssVariables', function($variables) {
    // Add custom CSS variables
    $custom_vars = "
        --custom-primary: #ff6b6b;
        --custom-secondary: #4ecdc4;
    ";

    return $variables . $custom_vars;
});

WordPress® Core Filters

wp_list_pages_excludes

Standard WordPress® filter used by Commerce Connect for page exclusion.

Use Case: Exclude specific pages from navigation.

Best Practices

Hook Naming Convention

All Commerce Connect hooks follow these patterns:

• commerce_connect_{context}_{action} for action hooks
• commerce_connect_{context}_{property} for filter hooks
• Integration-specific: commerce_connect_{integration_name}_{property}

Performance Considerations

1. Cache Results: Store expensive computations in transients
2. Conditional Execution: Check context before heavy operations
3. Early Return: Exit hooks quickly when conditions aren’t met
4. Avoid Infinite Loops: Don’t trigger the same hook recursively

Example: Efficient Hook Usage

add_filter('commerce_connect_client_settings', function($settings) {
    // Check if we need to modify settings
    if (!is_user_logged_in()) {
        return $settings; // Early return
    }

    // Use transient cache for expensive operations
    $cached = get_transient('custom_user_settings');
    if ($cached !== false) {
        $settings['user'] = $cached;
        return $settings;
    }

    // Perform expensive operation
    $user_data = expensive_user_lookup();
    set_transient('custom_user_settings', $user_data, HOUR_IN_SECONDS);

    $settings['user'] = $user_data;
    return $settings;
});

Debugging Hooks

View Active Hooks

// List all Commerce Connect hooks
global $wp_filter;
foreach ($wp_filter as $hook_name => $hook) {
    if (strpos($hook_name, 'commerce_connect_') === 0) {
        error_log("Hook: {$hook_name}");
    }
}

Log Hook Execution

add_action('commerce_connect_product_synced', function($productId) {
    error_log(sprintf(
        '[Commerce Connect] Product synced: ID=%d, Time=%s',
        $productId,
        current_time('mysql')
    ));
}, 10, 1);

Related Resources

• Custom Blocks Guide - Extend block functionality
• API Reference - REST API endpoints
• WordPress® Plugin API - Official hooks documentation