Declare HPOS compatibility in your plugin by calling `\Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility('custom_order_tables', __FILE__, true)` inside the `before_woocommerce_init` action hook.
Audit all code that reads or writes order data: replace direct `$wpdb` queries on `wp_posts` and `wp_postmeta` with WooCommerce CRUD methods (`get_meta`, `update_meta_data`, `save`) on `WC_Order` objects.
Replace any code using `get_post_meta` / `update_post_meta` with order-specific equivalents: `$order->get_meta()` and `$order->update_meta_data()` followed by `$order->save()`.
Test the integration on a staging site with HPOS enabled (WooCommerce > Settings > Advanced > Features) and compatibility mode temporarily active to catch issues during migration.
Disable compatibility mode (which syncs data between old posts table and new HPOS tables) only after verifying the integration works correctly with HPOS-only storage.
If third-party plugins in the stack have not declared HPOS compatibility, WooCommerce will prevent enabling HPOS; coordinate upgrades across all plugins before switching production stores.
Known gotchas
Direct SQL queries on `wp_postmeta` for order data will return empty results when HPOS is active without compatibility mode, causing silent data loss in integrations that do not check for null returns.
WooCommerce 8.2+ has HPOS enabled by default for new installs; existing stores migrated from posts storage require a one-time data migration that can take hours for large order volumes.
Compatibility mode (dual-write to both tables) creates a performance overhead and is intended only as a transitional state — do not leave it enabled permanently.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp