Introducing canonical WooCommerce abilities for products and orders

WooCommerce 10.9 introduces an initial set of canonical WooCommerce domain abilities for common product and order operations. These abilities are backed directly by WooCommerce product and order APIs and are designed as a stable, transport-neutral capability contract.

That contract can support the WordPress Abilities API, MCP, admin tooling, CLI workflows, automation systems, and future agent surfaces.

What is shipping

The first canonical set covers products and orders:

• woocommerce/products-query
• woocommerce/product-create
• woocommerce/product-update
• woocommerce/product-delete
• woocommerce/orders-query
• woocommerce/order-update-status
• woocommerce/order-add-note

Each ability includes strict input and output schemas, WooCommerce-aware enums, permission callbacks, and metadata that describes how projections can expose the ability. Query abilities are marked as readonly and idempotent. Write abilities declare whether they are destructive and whether repeated execution should be treated as idempotent.

Why domain abilities

The WooCommerce MCP beta, announced in the WooCommerce 10.3 release post and expanded in the Call for Testing post, first exposed product and order operations through a REST-derived bridge. Releasing that surface early gave us a practical way to test MCP integration and learn what is most useful when WooCommerce operations are represented as abilities. It now remains as a deprecated transition path for existing MCP consumers while WooCommerce moves toward canonical domain abilities.

The experiment clarified an important distinction: REST-shaped abilities are not the same as domain abilities. Agents that need raw WooCommerce REST behavior can already call the WooCommerce REST API directly. A one-to-one ability wrapper around the same endpoint adds another name, schema, response shape, and permission boundary for clients to discover and for WooCommerce to keep in sync, without adding a new domain capability.

This iteration applies that learning by starting from the business operation instead: query products, create, update, or delete a product, query orders, update an order status, or add an order note. That gives MCP, the Abilities REST API, Command Palette workflows, admin screens, CLI, and agent runtimes a semantic WooCommerce contract they can project in their own way, without making the canonical ability model mirror REST. It also gives extensions a clearer pattern for adding their own abilities into the WooCommerce context.

Product ability details

Product create, update, and query support these agent-facing product type aliases:

• physical
• virtual
• digital
• affiliate
• grouped

The aliases map to WooCommerce product types and fields. For example, physical, virtual, and digital map to simple products with the corresponding virtual/downloadable settings; affiliate maps to external products; and grouped maps to grouped products.

Product delete defaults to a soft delete by moving the product to trash. Permanent deletion requires force: true. If trash is disabled for the site and force is not set, the ability returns an error instead of silently hard-deleting.

Order ability details

woocommerce/orders-query can query by ID or common order filters such as status, customer ID, billing email, parent order, excluded IDs, created date range, modified date range, sort direction, and sort field. Line items are omitted by default and can be requested with include_line_items: true.

woocommerce/order-update-status updates order status and can include a status change note. It rejects no-op status updates. To add a note without changing the status, use woocommerce/order-add-note. Order notes added through the ability are attributed to the acting user when a user is available.

Where abilities are exposed

The canonical domain abilities are registered with the WordPress Abilities API on every request. They declare meta.show_in_rest = true, so authenticated callers can discover and execute them through the standard Abilities REST API routes:

/wp-json/wp-abilities/v1/abilities
/wp-json/wp-abilities/v1/abilities/{name}
/wp-json/wp-abilities/v1/abilities/{name}/run

The list and get routes require an authenticated user with WordPress read capability. The run route is registered for all HTTP methods because the expected method is derived from each ability’s annotations at request time: readonly abilities use GET, destructive idempotent abilities use DELETE, and other writes use POST. Each ability remains protected by its own permission_callback. Product and order permissions are checked through WooCommerce’s existing permission model, and schema validation rejects unknown fields and unsupported enum values before execution.

The canonical abilities are also marked for public MCP projection through the shared WordPress MCP adapter. WooCommerce currently includes the official wordpress/mcp-adapter Composer package, backed by the WordPress MCP Adapter project, as a dependency instead of owning a separate MCP protocol implementation:

'meta' => array(
    'show_in_rest' => true,
    'mcp'          => array(
        'public' => true,
        'type'   => 'tool',
    ),
)

With the WooCommerce MCP integration feature flag enabled, the bundled WordPress MCP adapter registers the shared adapter endpoint at:

/wp-json/mcp/mcp-adapter-default-server

In the current bundled adapter, that MCP server exposes adapter tools for ability discovery, ability detail lookup, and ability execution. It does not register one top-level MCP tool per WooCommerce domain ability on the shared adapter endpoint. The public MCP metadata is what allows those adapter tools to discover and execute the canonical WooCommerce abilities.

mcp-adapter/discover-abilities
mcp-adapter/get-ability-info
mcp-adapter/execute-ability

The WooCommerce MCP integration feature flag controls whether the bundled WordPress MCP adapter endpoints are initialized. It does not gate ability registration and it does not gate the Abilities REST API surface.

The upstream WordPress AI work is still shaping how the adapter should be distributed. The AI Building Blocks for WordPress post describes the MCP Adapter as part of the official WordPress AI building blocks and explains the broader canonical/feature-plugin direction, while the March 2026 contributor summary notes ongoing discussion about whether the MCP adapter should be a standalone WordPress.org plugin or continue to be bundled as a package. If the adapter moves to a canonical or feature-plugin integration path, WooCommerce will follow that upstream direction as it settles and adjust this integration accordingly.

The deprecated WooCommerce MCP endpoint

WooCommerce is retaining the earlier WooCommerce-specific MCP endpoint at /wp-json/woocommerce/mcp during this transition. This is the endpoint covered by the earlier WooCommerce MCP Beta call for testing, and it remains the compatibility path for existing REST-derived WooCommerce MCP tools. The endpoint authenticates with WooCommerce REST API keys supplied through the X-MCP-API-Key header.

To avoid expanding that deprecated endpoint whenever WooCommerce adds a new woocommerce/* domain ability, the endpoint no longer uses namespace matching as its default inclusion rule. Instead, an ability is included by default only when its metadata contains the strict boolean deprecated-endpoint exposure flag:

'meta' => array(
    'expose_in_deprecated_woocommerce_mcp' => true,
),

REST-derived WooCommerce abilities that support the deprecated endpoint are marked with this metadata automatically. Custom abilities are not included by namespace alone. Values such as 1 or 'true' do not opt in; the metadata value must be the boolean true.

The woocommerce_mcp_include_ability filter remains the final override for the deprecated endpoint:

add_filter(
    'woocommerce_mcp_include_ability',
    function ( bool $include, string $ability_id ): bool {
        if ( 'my-extension/example-action' === $ability_id ) {
            return true;
        }

        return $include;
    },
    10,
    2
);

Shared WordPress MCP adapter exposure and deprecated WooCommerce MCP endpoint exposure are separate decisions. Set mcp.public for abilities that should be discoverable and executable through the shared MCP adapter’s ability tools. Set expose_in_deprecated_woocommerce_mcp only for abilities that must also remain available through the deprecated WooCommerce-specific endpoint during the transition.

Extension guidance

This rollout also includes the registration path for WooCommerce extensions. WooCommerce registers the woocommerce category for core domain abilities, and extensions can register their own ability definition classes through the woocommerce_ability_definition_classes filter. Definition classes should implement:

Automattic\WooCommerce\Abilities\AbilityDefinition

add_filter(
    'woocommerce_ability_definition_classes',
    function ( array $classes ): array {
        $classes[] = MyExtension\Abilities\SyncProducts::class;
        return $classes;
    }
);

The woocommerce/ ability-name prefix is reserved for WooCommerce core abilities. Extensions should use their own ability-name prefix, while setting category => 'woocommerce' when the ability belongs with WooCommerce domain operations.

my-extension/sync-products
my-extension/create-special-order

If a third-party callback registers an ability using a canonical WooCommerce core name before WooCommerce’s loader runs, WooCommerce unregisters that conflicting ability, logs a warning under the woocommerce-abilities log source, and registers the canonical WooCommerce definition.

Migration checklist

• Use the canonical product and order abilities for new integrations that need these operations.
• Move REST-shaped ability usage to the WooCommerce REST API directly when the integration needs raw REST behavior.
• Open an issue in the WooCommerce repository when an integration needs an additional canonical ability.
• Register extension abilities through woocommerce_ability_definition_classes when they belong in the WooCommerce ability context.
• Add mcp.public => true for abilities that should be discoverable and executable through the shared WordPress MCP adapter’s ability tools.
• Add expose_in_deprecated_woocommerce_mcp => true only when an ability must remain available through the deprecated WooCommerce MCP endpoint for compatibility during the transition period.
• Use woocommerce_mcp_include_ability only to override ability inclusion in the deprecated WooCommerce MCP endpoint at runtime; it does not affect the shared MCP adapter or the Abilities REST API.
• Do not register extension abilities under the reserved woocommerce/ ability-name prefix.
• Leave internal or experimental abilities without MCP exposure metadata until they are intentionally designed for an MCP surface.

Looking ahead

Raw REST integrations should continue to use the WooCommerce REST API directly. Canonical abilities are the semantic layer: discoverable, permission-checked WooCommerce capabilities that modern WordPress APIs can expose through REST, MCP, and future surfaces.

This release is the latest iteration in WooCommerce’s adoption of the WordPress Abilities API and the WordPress MCP Adapter, and it establishes the initial set of canonical WooCommerce domain abilities. Products and orders now have a transport-neutral contract that belongs to WooCommerce, and extensions have a path into the same context. This is not the finished ability surface: there are still gaps to close, and future iterations will be shaped in part by the additional WooCommerce capabilities users ask to expose.