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

Related Skills

• 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