WooCommerce Extension Architecture

Reference for WooCommerce extension setup, plugin headers, compatibility declarations, and architecture fundamentals.

For specific topics see the related skills:

woocommerce-payments — Payment gateways, block checkout integration
woocommerce-data — Order/product/customer CRUD, HPOS, Store API, REST API
woocommerce-hooks — Hooks, settings pages, custom emails, WP-CLI, testing

1. Check WooCommerce Is Active

Always gate your plugin on WooCommerce availability:

add_action( 'plugins_loaded', 'mce_init' );

function mce_init(): void {
    if ( ! class_exists( 'WooCommerce' ) ) {
        add_action( 'admin_notices', function (): void {
            echo '<div class="error"><p>' .
                esc_html__( 'My Extension requires WooCommerce.', 'my-extension' ) .
                '</p></div>';
        } );
        return;
    }
    // Safe to use WooCommerce APIs from here.
}

2. Plugin Header

/**
 * Plugin Name: My WooCommerce Extension
 * Plugin URI:  https://example.com/my-extension
 * Description: Extends WooCommerce with custom features.
 * Version:     1.0.0
 * Author:      Your Name
 * Requires Plugins: woocommerce
 * WC requires at least: 8.0
 * WC tested up to: 10.4
 * Requires PHP: 7.4
 */

Header	Purpose
`Requires Plugins: woocommerce`	WordPress 6.5+ enforces the dependency automatically
`WC requires at least`	Minimum WooCommerce version
`WC tested up to`	Latest tested WooCommerce version (shows in admin)

3. Declaring Feature Compatibility

add_action( 'before_woocommerce_init', function (): void {
    if ( class_exists( '\Automattic\WooCommerce\Utilities\FeaturesUtil' ) ) {
        // Declare HPOS compatibility.
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility(
            'custom_order_tables',
            __FILE__,
            true
        );
        // Declare Block Checkout compatibility.
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility(
            'cart_checkout_blocks',
            __FILE__,
            true
        );
    }
} );

Feature key	What it declares
`custom_order_tables`	HPOS (High-Performance Order Storage) compatibility
`cart_checkout_blocks`	Block Checkout compatibility

4. Interactivity API Stores Are Private

All WooCommerce Interactivity API stores use lock: true — they are not extensible. Removing or changing store state/selectors is not a breaking change. Do not depend on WC store internals in your extension.

5. Common Mistakes

Mistake	Fix
Not checking if WooCommerce is active	Wrap init in `class_exists('WooCommerce')` check
Not declaring HPOS compatibility	Add `FeaturesUtil::declare_compatibility('custom_order_tables', ...)`
Not declaring Block Checkout compatibility	Add `FeaturesUtil::declare_compatibility('cart_checkout_blocks', ...)`
Using `new` for DI-managed WC classes	Use `wc_get_container()->get( ClassName::class )` for `src/` singletons
Depending on WC Interactivity API stores	All WC stores are `lock: true` (private) — can change without notice
Missing `Requires Plugins: woocommerce` header	Add it — WordPress 6.5+ enforces the dependency

woocommerce-payments — Payment gateways, block checkout integration, tokenization
woocommerce-data — HPOS, order/product/customer CRUD, Store API, REST API
woocommerce-hooks — Hooks, settings pages, custom emails, WP-CLI, testing