WooCommerce HPOS (High-Performance Order Storage)

Order notes remain in wp_comments. Order items retain their dedicated tables. See references/database-schema.md for full column definitions.

Core API Quick Reference

Detect HPOS Status

use Automattic\WooCommerce\Utilities\OrderUtil;

if ( OrderUtil::custom_orders_table_usage_is_enabled() ) {
    // HPOS is active
} else {
    // Legacy CPT storage
}

Get/Create/Update Orders (works with both storage backends)

// Get order -- replaces get_post()
$order = wc_get_order( $order_id );

// Read data
$status = $order->get_status();
$total  = $order->get_total();
$email  = $order->get_billing_email();

// Update metadata -- replaces update_post_meta()
$order->update_meta_data( '_custom_key', 'value' );
$order->save(); // Required! Expensive -- batch changes before calling.

// Delete metadata -- replaces delete_post_meta()
$order->delete_meta_data( '_custom_key' );
$order->save();

Check Order Type

use Automattic\WooCommerce\Utilities\OrderUtil;

// replaces: 'shop_order' === get_post_type( $id )
'shop_order' === OrderUtil::get_order_type( $id );

// replaces: in_array( get_post_type( $id ), wc_get_order_types() )
OrderUtil::is_order( $id, wc_get_order_types() );

Declare Plugin Compatibility (in main plugin file)

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
        );
    }
} );

Pass false as third arg to declare incompatibility. Use 'my-plugin-slug/my-plugin.php' instead of __FILE__ if the declaration is outside the main plugin file.

Register Meta Boxes (dual-compatible)

use Automattic\WooCommerce\Internal\DataStores\Orders\CustomOrdersTableController;

add_action( 'add_meta_boxes', function() {
    $screen = class_exists( CustomOrdersTableController::class )
        && wc_get_container()->get( CustomOrdersTableController::class )
            ->custom_orders_table_usage_is_enabled()
        ? wc_get_page_screen_id( 'shop-order' )
        : 'shop_order';

    add_meta_box( 'my-box', 'Title', 'render_callback', $screen, 'side', 'high' );
} );

function render_callback( $post_or_order ) {
    $order = ( $post_or_order instanceof WP_Post )
        ? wc_get_order( $post_or_order->ID )
        : $post_or_order;
    // Use $order exclusively below this point
}

Query Orders (HPOS-enhanced)

// Basic query (works on both backends)
$orders = wc_get_orders( array(
    'status'    => 'processing',
    'limit'     => 50,
    'orderby'   => 'date',
    'order'     => 'DESC',
) );

// HPOS-enhanced: meta_query
$orders = wc_get_orders( array(
    'meta_query' => array(
        array( 'key' => 'color', 'compare' => 'EXISTS' ),
        array( 'key' => 'size', 'value' => 'small', 'compare' => 'LIKE' ),
    ),
) );

// HPOS-enhanced: field_query
$orders = wc_get_orders( array(
    'field_query' => array(
        'relation' => 'OR',
        array( 'field' => 'total', 'value' => '5.0', 'compare' => '<' ),
        array( 'field' => 'shipping_total', 'value' => '5.0', 'compare' => '<' ),
    ),
) );

// HPOS-enhanced: date_query
$orders = wc_get_orders( array(
    'date_query' => array(
        array( 'column' => 'date_paid_gmt', 'after' => '1 month ago' ),
    ),
) );

See references/querying-apis.md for full query type documentation with advanced examples.

Synchronization Model

When HPOS is enabled with compatibility mode, data is kept in sync between the new tables (authoritative) and legacy posts tables (backup).

Key option: woocommerce_custom_orders_table_enabled (true = HPOS active). Sync option: woocommerce_custom_orders_table_data_sync_enabled.

Placeholder records: When HPOS is authoritative and sync is disabled, creating an order inserts a post with type shop_order_placehold to reserve the ID. This ensures post.ID == order.id invariant.

Conflict resolution (sync on read): Compares timestamps. If CPT update_time < HPOS update_time, assumes failed CPT write and overwrites CPT. If timestamps match, assumes direct CPT write and syncs to HPOS.

CLI Tools (wp wc hpos)

See references/cli-tools.md for full command documentation with examples.

Migration Checklist (Critical Path)

For large stores, follow the 3-phase approach documented in references/migration-guide.md:

1. Phase 1 -- Local testing: Enable HPOS locally, test all checkout flows with every payment method, test refunds, test subscriptions, test with sync on and off.
2. Phase 2 -- Staging: Copy production DB, run wp wc hpos sync, benchmark migration time, verify with wp wc hpos verify_data --verbose, audit third-party systems accessing DB directly.
3. Phase 3 -- Production: Enable sync with posts authoritative -> run CLI sync -> switch HPOS authoritative -> disable read sync via filter -> after 1 week stable, disable write sync.

Common Pitfalls

1. Never use get_post() / update_post_meta() for orders -- these bypass HPOS and write to wrong tables. Always use wc_get_order() and $order->update_meta_data().
2. Always call $order->save() after metadata changes -- but minimize calls (batch changes first). save() is expensive.
3. Direct SQL on wp_posts for orders will break -- use wc_get_orders() or WC_Order_Query. If you must write SQL, check OrderUtil::custom_orders_table_usage_is_enabled() and query the correct table.
4. Plugin compatibility declaration is mandatory -- WooCommerce will block HPOS activation if any active plugin has not declared compatibility.
5. Don't disable sync prematurely in production -- keep sync enabled until confident all flows work, then disable read sync first (via filter), then write sync after 1 week.

Audit Your Code

Search your codebase with these regex patterns to find code that needs HPOS migration:

Direct DB/post access:

wpdb|get_post|get_post_field|get_post_status|get_post_type|get_posts|get_post_meta|update_post_meta|add_post_meta|delete_post_meta|wp_insert_post|wp_update_post|wp_delete_post|wp_trash_post|shop_order

Admin screen functions:

post_updated_messages|do_meta_boxes|enter_title_here|edit_form_before_permalink|manage_shop_order_posts_columns|manage_shop_order_posts_custom_column

Most matches will be false positives. Check each for order-related usage.

Programmatic Synchronization

$synchronizer = wc_get_container()->get(
    Automattic\WooCommerce\Internal\DataStores\Orders\DataSynchronizer::class
);
$order_ids = $synchronizer->get_next_batch_to_process( $batch_size );
if ( count( $order_ids ) ) {
    $synchronizer->process_batch( $order_ids );
}

Disable Read Sync (production optimization)

add_filter( 'woocommerce_hpos_enable_sync_on_read', '__return_false' );

Apply this filter 6+ hours after switching HPOS to authoritative. It reduces overhead while maintaining write sync for safety.

References Guide