WooCommerce HPOS Migration Checklist: Preparing Your Store for Custom Order Tables

WooCommerce High-Performance Order Storage (HPOS) replaces the legacy WordPress posts table architecture with dedicated order tables, delivering significant performance gains. Official benchmarks show up to 5x faster order creation, 40x faster order filtering on indexed columns, and 1.5x faster checkout processing. With WooCommerce 10.x making HPOS the standard architecture, migration is no longer optional for stores planning long-term growth.

This 12-step checklist guides you through a safe migration with built-in rollback procedures at each phase.

Phase 1: Pre-Migration Preparation

Step 1: Update WooCommerce and Extensions

Ensure WooCommerce and all order-related extensions (Subscriptions, Bookings, Points and Rewards) are running the latest stable versions. Recent releases include critical HPOS compatibility fixes.

Step 2: Create Complete Backup

Back up your entire database and WordPress files. Test the backup restoration process in a staging environment before proceeding. This backup becomes your safety net for rollback scenarios.

Step 3: Audit Plugin Compatibility

Navigate to WooCommerce > Settings > Advanced > Features and click “View and manage” next to the HPOS option. This displays plugins that have declared HPOS compatibility status.

For plugins showing as incompatible:

• Check the plugin’s changelog for HPOS updates
• Contact the developer about timeline for HPOS support
• Consider alternatives if the plugin is unmaintained

Step 4: Review External Integrations

Audit external systems that interact with your order data. Data warehouses, shipping platforms, ERP systems, and accounting software may query WordPress posts tables directly. These integrations need verification before switching datastores.

Phase 2: Enable Compatibility Mode

Step 5: Enable Compatibility Mode

In WooCommerce > Settings > Advanced > Features, enable “Enable compatibility mode (synchronizes orders to the posts table).” This maintains data in both HPOS tables and legacy posts tables simultaneously.

Keep “WordPress posts storage” selected as the authoritative datastore initially. This ensures all new orders write to posts tables first while HPOS tables stay synchronized.

Step 6: Run Migration

For stores with fewer than 50,000 orders, the WooCommerce Action Scheduler handles synchronization automatically. Monitor progress at WooCommerce > Status > Scheduled Actions.

For larger stores, use WP-CLI for faster, more reliable migration:

wp wc hpos sync

This command migrates orders in batches. For a store with 9 million orders, expect approximately one week for full synchronization.

Step 7: Verify Data Integrity

After sync completes, verify data consistency between datastores:

wp wc hpos verify_data

This command compares order data across both storage systems. If discrepancies exist, add the --re-migrate flag to automatically fix them:

wp wc hpos verify_data --re-migrate

Phase 3: Switch to HPOS

Step 8: Switch Authoritative Datastore

Once verification passes, return to WooCommerce > Settings > Advanced > Features and change the datastore selection to “Use the WooCommerce orders tables.”

Keep compatibility mode enabled at this stage. This allows instant rollback if issues emerge.

Step 9: Test Critical Workflows

Run through essential order operations:

• Process a test purchase through checkout
• Issue a refund
• If using WooCommerce Subscriptions, verify renewal processing
• Check that order analytics display correctly
• Confirm email notifications trigger properly

Step 10: Monitor for 48-72 Hours

Watch for issues before proceeding:

• Review PHP error logs for database-related errors
• Verify order data appears correctly in admin
• Confirm third-party integrations receive order data
• Check that reports and analytics remain accurate

Phase 4: Post-Migration

Step 11: Disable Compatibility Mode

After confirming stability, disable compatibility mode to stop writing to legacy tables. This improves write performance since orders no longer sync to both datastores.

For cautious deployments, first disable sync-on-read via a filter in your theme’s functions.php:

add_filter( 'woocommerce_hpos_enable_sync_on_read', '__return_false' );

After further monitoring, uncheck “Enable compatibility mode” in the Features settings.

Step 12: Optional Legacy Cleanup

Once you’re confident in HPOS stability (recommended minimum: 30 days), you can remove legacy order data from posts tables:

wp wc hpos cleanup all

Warning: This operation is destructive and cannot be undone without a backup. Only proceed after extended stability verification.

Rollback Procedures

Scenario 1: Rollback During Compatibility Mode

If issues arise while compatibility mode is enabled, rollback is instant:

1. Navigate to WooCommerce > Settings > Advanced > Features
2. Switch from “WooCommerce orders tables” back to “WordPress posts storage”
3. Changes take effect immediately with no data loss

Scenario 2: Rollback After HPOS-Only

If you’ve disabled compatibility mode but need to rollback:

1. Re-enable compatibility mode in Features settings
2. Wait for synchronization to complete (verify with wp wc hpos status)
3. Switch authoritative datastore back to posts storage

Scenario 3: Rollback After Cleanup

If you ran wp wc hpos cleanup and need to restore:

• Option 1: Restore from your pre-migration database backup
• Option 2: Use backfill to repopulate posts tables from HPOS:

  wp wc hpos backfill --from=hpos --to=posts

Moving Forward

HPOS represents WooCommerce’s strategic direction for order storage. While no official deprecation date exists for legacy tables, future performance improvements and features will build on the HPOS architecture. Stores migrating now position themselves for long-term scalability.

The key to successful migration: backup first, use compatibility mode as your safety net, and only disable sync after confirming stability. With these precautions, the performance gains are worth the effort.