HPOS Compatibility

High-Performance Order Storage (HPOS) is WooCommerce's modern order data architecture that replaces the legacy post-based storage with dedicated wc_orders and wc_orders_meta database tables. Fakturownia Pro for WooCommerce is fully compatible with HPOS and has been tested against both storage modes.

HPOS compatibility status indicator in Fakturownia Pro settings

What HPOS Is and Why It Matters

Prior to HPOS, WooCommerce stored orders as WordPress posts in the wp_posts table and order metadata in wp_postmeta. This architecture was not designed for high order volume — wp_postmeta can grow to millions of rows on busy stores, causing slow order queries and performance bottlenecks.

HPOS introduces purpose-built tables:

| Table | Purpose | |---|---| | wc_orders | Order header data (status, dates, totals, customer ID) | | wc_orders_meta | Order metadata (replaces wp_postmeta for order data) | | wc_order_addresses | Billing and shipping address data | | wc_order_operational_data | Operational fields (payment method, transaction ID, etc.) | | wc_order_items | Order line items | | wc_order_item_meta | Line item metadata |

For stores with tens of thousands of orders, HPOS query times are dramatically faster than the legacy wp_posts approach. WooCommerce has been transitioning toward HPOS as the default since version 7.1 and it is the required storage mode for WooCommerce 9.x and later.

How the Plugin Stores Invoice Data with HPOS

When HPOS is active, Fakturownia Pro stores all invoice-related metadata in wc_orders_meta using WooCommerce's CRUD abstraction layer. The plugin never writes directly to wp_postmeta for order data when HPOS is enabled.

Metadata Keys Stored

| Meta key | Table (HPOS active) | Table (legacy) | Purpose | |---|---|---|---| | _fakturownia_invoice_id | wc_orders_meta | wp_postmeta | Internal Fakturownia document ID | | _fakturownia_invoice_number | wc_orders_meta | wp_postmeta | Human-readable invoice number | | _fakturownia_invoice_status | wc_orders_meta | wp_postmeta | generated, failed, skipped, pending | | _fakturownia_nip | wc_orders_meta | wp_postmeta | NIP captured at checkout | | _fakturownia_document_type | wc_orders_meta | wp_postmeta | invoice, receipt, correction, proforma | | _fakturownia_generated_at | wc_orders_meta | wp_postmeta | Timestamp of document generation | | _fakturownia_pdf_cache_path | wc_orders_meta | wp_postmeta | Local PDF cache path (if caching enabled) |

All reads and writes use $order->get_meta() and $order->update_meta_data() — the WooCommerce ORM methods that automatically target the correct table depending on the active storage mode. There are no direct $wpdb->postmeta queries in the plugin code.

Reading Order Data

The plugin accesses order data exclusively through WooCommerce's order object API:

// Reading billing address
$order->get_billing_company();
$order->get_billing_first_name();
$order->get_billing_email();
 
// Reading order totals
$order->get_total();
$order->get_total_tax();
 
// Reading line items
foreach ($order->get_items() as $item) {
    $item->get_name();
    $item->get_total();
}

None of these calls touch wp_posts or wp_postmeta when HPOS is active — they are routed to the HPOS tables automatically.

Migration from Legacy to HPOS

WooCommerce provides a built-in migration tool to move from the legacy storage to HPOS. Running the migration while Fakturownia Pro is active requires no special handling — the plugin's metadata migrates automatically as part of WooCommerce's migration process.

Before Migrating

Confirm your WooCommerce version is 7.1 or later
Create a full database backup — a migration failure on a large store without a backup is difficult to recover from
Verify Fakturownia Pro is on version 1.2.0 or later (check Plugins → Installed Plugins)
Confirm WP-Cron is functional — the migration runs as background tasks via cron

Running the Migration

Go to WooCommerce → Settings → Advanced → Features
Under Order data storage, select "High-Performance Order Storage"
WooCommerce shows a prompt: "Migration required. X orders need to be migrated."
Click "Migrate" to begin

The migration runs in batches of 25 orders per WP-Cron event. For a store with 50,000 orders, migration takes approximately 30–45 minutes on shared hosting (longer if WP-Cron fires infrequently) and 5–10 minutes on a VPS with a real cron trigger.

What Happens to Existing Invoice Metadata

When an order is migrated from wp_postmeta to wc_orders_meta:

All _fakturownia_* meta keys are copied to wc_orders_meta
The original entries in wp_postmeta remain as a backup until WooCommerce completes the migration cleanup phase
The invoice numbers, invoice IDs, and generation timestamps are preserved exactly

After migration, $order->get_meta('_fakturownia_invoice_id') returns the same value it returned before migration — the plugin sees no difference.

Verifying Metadata Migration

After migration completes, spot-check a few orders:

-- Confirm invoice meta exists in HPOS table
SELECT orders.order_key, meta.meta_key, meta.meta_value
FROM wc_orders orders
JOIN wc_orders_meta meta ON orders.id = meta.order_id
WHERE meta.meta_key IN ('_fakturownia_invoice_id', '_fakturownia_invoice_number')
ORDER BY orders.date_created_gmt DESC
LIMIT 20;

Expected output: rows for orders that had invoices generated, with their Fakturownia invoice IDs and document numbers.

-- Confirm the count matches expectations
SELECT COUNT(*) as orders_with_invoices
FROM wc_orders_meta
WHERE meta_key = '_fakturownia_invoice_id';

This count should match the count of orders with invoices in your legacy wp_postmeta:

SELECT COUNT(*) as legacy_count
FROM wp_postmeta
WHERE meta_key = '_fakturownia_invoice_id';

If the HPOS count is lower, some orders did not migrate. Re-run the migration from WooCommerce settings or contact WooCommerce support.

Compatibility Mode During Migration

WooCommerce offers a Compatibility Mode that writes order data to both wp_posts and wc_orders simultaneously. This is designed for stores where third-party plugins have not yet been tested with HPOS.

Fakturownia Pro does not require compatibility mode — it is fully HPOS-native. However, if other plugins in your store do require compatibility mode, the plugin operates correctly in compatibility mode as well. In compatibility mode:

WooCommerce writes order data to both tables on every save
The plugin reads from whichever table WooCommerce routes it to
Invoice metadata is written to both tables (via the CRUD layer)

Once all plugins in your store support native HPOS, disable compatibility mode. Running in compatibility mode long-term doubles the write load on order saves.

Verifying HPOS Compatibility in Your Store

Via Plugin Settings

The General tab shows an HPOS status indicator:

| Status | Meaning | |---|---| | HPOS Active — Compatible | HPOS is enabled and Fakturownia Pro is operating in HPOS mode | | Legacy Storage Active | HPOS is not enabled — plugin uses wp_postmeta | | Compatibility Mode Active | Both storage modes are active during migration |

If the status shows "HPOS Active — Compatible", no further action is needed.

Via WP-CLI

# Check HPOS status
wp option get woocommerce_custom_orders_table_enabled
# "yes" = HPOS active
 
# Check compatibility mode
wp option get woocommerce_use_legacy_orders_table_for_data_reading
# "yes" = compatibility mode (both tables in use)

Via Database

wp eval '
$order_table = \Automattic\WooCommerce\Utilities\OrderUtil::get_table_for_orders();
echo "Orders table: " . $order_table . "\n";
$using_hpos = \Automattic\WooCommerce\Utilities\OrderUtil::custom_orders_table_usage_is_enabled();
echo "HPOS active: " . ($using_hpos ? "yes" : "no") . "\n";
'

Troubleshooting HPOS-Specific Issues

Invoice Meta Box Missing After HPOS Migration

Symptom: The Fakturownia Pro meta box is absent from the order detail page after migrating to HPOS.

Cause: The meta box is registered via add_meta_box() targeting the shop_order post type, which does not exist as a page when HPOS is active (orders are now under wc-orders, not shop_order).

Fix: Ensure you are running Fakturownia Pro 1.2.0 or later. This version registers the meta box for both shop_order (legacy) and wc-orders (HPOS). Update the plugin from plugkit.io if needed.

Existing Invoice Numbers Not Showing After Migration

Symptom: Orders that had invoices before migration show as "No invoice" in the admin after enabling HPOS.

Cause: Migration is incomplete — the meta keys have not yet been copied to wc_orders_meta.

Fix:

Check migration status in WooCommerce → Status → HPOS Migration Status
If migration is stalled, re-trigger it:

wp eval '
\Automattic\WooCommerce\Database\Migrations\CustomOrderTable\PostsToOrdersMigrationController::get_instance()->migrate_pending_orders();
'

After migration completes, verify using the SQL queries in the Migration section above.

NIP Not Appearing on Invoices Generated After HPOS Migration

Symptom: New invoices generated after HPOS migration are missing the buyer NIP even for orders where the customer entered a NIP at checkout.

Cause: The NIP checkout field was saving to wp_postmeta using a direct update_post_meta() call in an older plugin version. After HPOS migration, new orders are saved to wc_orders_meta, but the checkout save hook targeted the wrong table.

Fix: Update Fakturownia Pro to version 1.2.0 or later. The NIP field save now uses $order->update_meta_data('_fakturownia_nip', $nip) which correctly targets the active storage table.

Order Status Transition Hook Not Firing

Symptom: Invoice rules based on order status changes (e.g., pending → processing) are not triggering after HPOS migration.

Cause: The plugin was hooking into woocommerce_order_status_{status} which fires for both legacy and HPOS orders. Some older store configurations used post_updated hooks that do not fire for HPOS orders.

Fix: Verify the plugin is on version 1.2.0 or later. Check for other plugins that may be intercepting the status transition before it fires. To test:

wp eval '
$order = wc_get_order(YOUR_ORDER_ID);
$order->set_status("processing");
$order->save();
echo "Status set, invoice should have been triggered.";
'

Performance: Orders Grid Slow After HPOS Migration

This is not a Fakturownia Pro issue — slow orders grid after HPOS migration is typically caused by missing database indexes on the HPOS tables. Run:

bin/wp wc tool run verify_db_tables

Or in Magento equivalent, check WooCommerce → Status → System Status → Database for any flagged table issues.

Next Steps

WP-CLI Reference — CLI commands for queue management and bulk operations
Configuration — full settings documentation
Troubleshooting — general troubleshooting guide