WooCommerce: Order Meta with HPOS and API

In a recent Business Bloomer Club Slack thread, a member raised an important question about WooCommerce HPOS (High-Performance Order Storage) and API compatibility.

Their developer had built a custom integration using the legacy WooCommerce API, and one of the key operations was saving metadata to orders. This metadata was used to associate internal order numbers from a third-party system.

With WooCommerce shifting toward HPOS for order management, the member wanted to confirm if their integration would require changes — especially when saving order meta. If the current implementation uses functions like $order->update_meta_data(), would that still work seamlessly with HPOS?

This is a common concern for developers who rely on programmatic access to orders, especially when orders are linked to external systems. The good news is that HPOS is designed with backward compatibility in mind, but certain practices need a closer look. Let’s go through what changes, what stays the same, and how to future-proof your API integrations.

What is WooCommerce HPOS?

HPOS (High-Performance Order Storage) moves order data from WordPress’s posts and postmeta tables to custom database tables (wc_orders, wc_order_meta, etc.). This improves performance and scalability, especially for stores with a large number of orders.

However, it introduces implications for developers interacting with order data — especially those using direct SQL queries or legacy APIs.

Storing Metadata with $order->update_meta_data()

If your API integration uses the standard WooCommerce method:

$order = wc_get_order( $order_id );
$order->update_meta_data( 'custom_key', 'value' );
$order->save();

Then you’re in good shape. This method works the same way with HPOS enabled. WooCommerce abstracts the storage layer, so whether the data goes to postmeta or the new wc_order_meta, the function call remains identical.

This makes your code compatible with both the legacy storage and HPOS.

What You Should Avoid

If your integration uses direct SQL queries to write to the wp_postmeta table, those will not work with HPOS. For example:

INSERT INTO wp_postmeta (post_id, meta_key, meta_value)
VALUES (123, 'custom_key', 'value');

This kind of logic bypasses WooCommerce’s internal methods and will not store meta in the correct place when HPOS is active.

Similarly, legacy APIs that assume post-based orders might not support HPOS unless explicitly updated.

What About the REST API?

WooCommerce’s modern REST API (not the deprecated legacy one) is HPOS-compatible out of the box. If you’re using PUT /wp-json/wc/v3/orders/{id} and including meta data as part of the request, it will be stored correctly with HPOS.

If you’re still relying on the legacy API, support is limited. You might still be able to save meta, but it’s strongly recommended to migrate to the latest REST API endpoints.

Preparing for HPOS Migration

To ensure a smooth switch to HPOS:

1. Audit your code for direct database access.
2. Use WooCommerce’s native CRUD functions (update_meta_data, add_meta_data, get_meta_data, etc.).
3. Migrate to the latest REST API endpoints if you’re still using the legacy API.
4. Test on a staging site with HPOS enabled (WooCommerce > Settings > Advanced > Features).

Conclusion

If your WooCommerce API integration saves order metadata using $order->update_meta_data(), you’re likely already compatible with HPOS. But be cautious of legacy APIs and direct SQL queries — these may require adjustments to work with the new storage structure.

Staying within WooCommerce’s official methods is the safest way to ensure future compatibility and performance improvements.