/wp-woocommerce

name: wp-woocommerce
description: "Use when building, extending, or debugging a WooCommerce plugin — custom product types, payment gateways (WC_Payment_Gateway, process_payment(), process_refund()), shipping methods (WC_Shipping_Method, calculate_shipping()), CRUD via WC_Product / WC_Order / WC_Customer (wc_get_product, wc_create_order, wc_get_orders, get_meta, update_meta_data), HPOS compatibility (FeaturesUtil::declare_compatibility, wc_get_orders instead of WP_Query on posts), REST API extensions (woocommerce_rest_prepare, woocommerce_rest_pre_insert, Store API woocommerce_store_api_register_endpoint_data), cart/checkout blocks (registerCheckoutFilters, extensionCartUpdate, SlotFills), key hooks (woocommerce_cart_calculate_fees, woocommerce_checkout_fields, woocommerce_order_status_changed, woocommerce_payment_gateways), or WooCommerce subscription/coupon/webhook logic. Triggers: \"WooCommerce extension\", \"custom product type\", \"payment gateway\", \"hook into WooCommerce checkout\", \"WC_Order\", \"wc_create_order()\", \"wc_get_product()\", \"add a shipping method\", \"WooCommerce REST API\", \"HPOS compatible\", \"FeaturesUtil::declare_compatibility\", \"cart block\", \"checkout block filter\", \"woocommerce_payment_gateways\", \"WC_Product CRUD\", \"Store API endpoint\", \"extend WooCommerce\", \"woocommerce_cart_calculate_fees\", \"woocommerce_checkout_fields\", \"process_payment()\", \"process_refund()\", \"woocommerce_rest_prepare_product\", \"registerCheckoutFilters\", \"WC webhook HMAC\", \"WC coupon CRUD\", \"wc_get_orders HPOS\". Not for: Freemius monetisation — use `wp-freemius`; plain WordPress post/taxonomy work without WooCommerce."

WooCommerce Extension Development

> **Model note:** Complex — payment gateways, HPOS compatibility, and block cart/checkout require multi-file reasoning. Use `sonnet` or `opus`. `haiku` for isolated CRUD or hook lookups only.

Guide for building WooCommerce extensions: custom product types, payment gateways, hooks, CRUD, REST, and admin UI. Assumes the host plugin passes the `wp-plugin-audit` baseline and the official `wp-plugin-development` security conventions.

When to use

• "Add a custom product type", "create a payment gateway", "add a shipping method".
• "Extend the WooCommerce REST API", "add fields to WC orders/products".
• "Build a WooCommerce admin tab", "add product meta", "custom checkout field".
• "Hook into WC cart/checkout", "add a fee", "apply a discount programmatically".
• "Debug WooCommerce order status flow", "fix a WC hook not firing".

**Not for:** General WordPress plugin architecture — use `wp-plugin-development`. PHPStan types for WC — use `wp-phpstan-stubs` to scaffold WC stubs.

Method

1. Identify extension point category

Determine which WC subsystem applies before writing code:

| Goal | Subsystem | |---|---| | Custom product type | `WC_Product` subclass + `product_type_query` filter | | Payment gateway | `WC_Payment_Gateway` subclass + `woocommerce_payment_gateways` filter | | Shipping method | `WC_Shipping_Method` subclass + `woocommerce_shipping_methods` filter | | Custom order status | `wc_register_order_status` + `wc_order_statuses` filter | | Cart/checkout field | `woocommerce_checkout_fields` filter or block integration API | | Admin product tab | `woocommerce_product_data_tabs` + `woocommerce_product_data_panels` | | Order list column | `manage_edit-shop_order_columns` + `manage_shop_order_posts_custom_column` | | REST API extension | `woocommerce_rest_*` hooks or custom endpoint on `WC_REST_Controller` |

2. CRUD — use WC classes, not direct `$wpdb`

Always use WC CRUD methods; they fire the correct hooks and invalidate caches.

// Orders
$order = wc_create_order( [ 'status' => 'pending', 'customer_id' => $user_id ] );
$order->add_product( wc_get_product( $product_id ), 1 );
$order->calculate_totals();
$order->save();

// Products
$product = new WC_Product_Simple();
$product->set_name( 'My Product' );
$product->set_regular_price( '19.99' );
$product->set_status( 'publish' );
$product->save();

// Reading
$order   = wc_get_order( $order_id );       // returns WC_Order or false
$product = wc_get_product( $product_id );   // returns WC_Product subclass or false

For meta, use `$order->get_meta()` / `$order->update_meta_data()` + `$order->save()` — never `update_post_meta()` on orders (breaks HPOS).

3. HPOS compatibility

WooCommerce 8.2+ ships **High-Performance Order Storage** (HPOS). Extensions must declare compatibility or they're disabled in HPOS stores.

add_action( 'before_woocommerce_init', function() {
    if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility(
            'custom_order_tables', __FILE__, true
        );
    }
} );

Rules under HPOS:

• Never read/write orders via `get_post_meta()` / `update_post_meta()` — use `WC_Order` getters/setters.
• Never query orders via `WP_Query` with `post_type=shop_order` — use `wc_get_orders()`.
• Avoid `$wpdb` queries directly on `{prefix}posts` for order data.

4. Payment gateway skeleton

class My_Payment_Gateway extends WC_Payment_Gateway {
    public function __construct() {
        $this->id                 = 'my_gateway';
        $this->method_title       = __( 'My Gateway', 'my-plugin' );
        $this->method_description = __( 'Pay via My Gateway.', 'my-plugin' );
        $this->supports           = [ 'products', 'refunds' ];
        $this->init_form_fields();
        $this->init_settings();
        $this->title   = $this->get_option( 'title' );
        $this->enabled = $this->get_option( 'enabled' );
        add_action( 'woocommerce_update_options_payment_gateways_' . $this->id,
            [ $this, 'process_settings' ] );
    }

    public function process_payment( $order_id ) {
        $order = wc_get_order( $order_id );
        // ... call payment API ...
        $order->pay