Friday, 9:15 AM
Yesterday the client enabled HPOS: WooCommerce recommends it, orders open faster. Today couriers didn't get a single address. The delivery plugin reads get_post_meta( $order_id, '_delivery_slot', true ), and orders are no longer in wp_posts.
The plugin had worked for three years, and nobody changed a single line in it.
Goal
After the lesson you write code that works both with and without HPOS, declare your plugin's compatibility and know how to move a store to the new tables safely.
Key concepts
- HPOS (High-Performance Order Storage) — orders in dedicated tables instead of
wp_posts - The default on new sites since WooCommerce 8.2; existing stores switch manually
- Sync mode (compatibility mode): data is written to both storages during the transition
- Declaring plugin compatibility:
FeaturesUtil::declare_compatibility( 'custom_order_tables', ... ) OrderUtil::custom_orders_table_usage_is_enabled()— checks which storage is active- The orders screen changes:
admin.php?page=wc-ordersinstead ofedit.php?post_type=shop_order
Diagram
flowchart TB
A["Existing store<br/>wp_posts"] --> B["Enable sync"]
B --> C["Background migration<br/>wp wc hpos sync"]
C --> D["Verify<br/>wp wc hpos verify_cot_data"]
D --> E["HPOS as primary storage"]
E --> F["Disable sync<br/>after testing"]
Code
Declaring compatibility in the main plugin file:
<?php
add_action( 'before_woocommerce_init', static function () {
if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
\Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility(
'custom_order_tables',
__FILE__,
true
);
}
} );
An orders list column for both screens:
<?php
use Automattic\WooCommerce\Utilities\OrderUtil;
$screen = OrderUtil::custom_orders_table_usage_is_enabled()
? 'woocommerce_page_wc-orders'
: 'edit-shop_order';
add_filter( "manage_{$screen}_columns", static function ( array $columns ): array {
$columns['erp_id'] = __( 'ERP ID', 'my-plugin' );
return $columns;
} );
// HPOS passes the order object, the legacy screen passes the post ID.
add_action( 'manage_woocommerce_page_wc-orders_custom_column', 'my_render_erp_column', 10, 2 );
add_action( 'manage_shop_order_posts_custom_column', 'my_render_erp_column', 10, 2 );
function my_render_erp_column( string $column, $order_or_id ): void {
if ( 'erp_id' !== $column ) {
return;
}
$order = $order_or_id instanceof WC_Order ? $order_or_id : wc_get_order( $order_or_id );
echo esc_html( $order ? $order->get_meta( '_erp_id' ) : '' );
}
Common mistakes
| Symptom | Cause | Fix |
|---|---|---|
| The plugin is marked incompatible in WooCommerce → Settings → Advanced → Features | No declare_compatibility | Declare compatibility after reviewing the code |
| A column disappeared after HPOS was enabled | Hooks only for edit-shop_order | Hook into both screens |
| An SQL report shows zeros | A direct query to wp_posts with post_type = shop_order | wc_get_orders() or a query to the HPOS tables that checks the mode |
Weak and strong answer
Question: What do you need to do to make a plugin support HPOS?
Weak answer. Add
declare_compatibilityto the plugin.
Strong answer. First remove direct access to orders:
get_post_meta,WP_Queryonshop_order, SQL againstwp_posts. Replace it withwc_get_order(),wc_get_orders()and CRUD meta. Adapt the admin screen hooks. Test with and without HPOS, and only then declare compatibility.
Why the second is stronger: The declaration is the result of testing, not compatibility itself. The candidate knows what exactly breaks.
Practice
Rewrite the delivery plugin from the start of the lesson: remove get_post_meta and WP_Query on shop_order, read orders via wc_get_order() / wc_get_orders() and add declare_compatibility. Run it in the IDE below.
Then do the same with your own plugin and test it in both modes: with and without HPOS.
Interview Questions
Orders get their own tables with the needed columns and indexes (status, date, customer, total). No thousands of wp_postmeta rows per order and no heavy JOINs. Order search and reports don't compete with posts and pages.
During the transition WooCommerce writes orders to both storages. You can roll back, and old plugins that read wp_posts still get data. After the transition sync is turned off because it doubles every write.
\Automattic\WooCommerce\Utilities\OrderUtil::custom_orders_table_usage_is_enabled().