Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 39 ยท Emails, Notifications and Admin

Admin Order Screens and Analytics Data

Extend the WooCommerce order list under HPOS: columns, filters, bulk actions, meta boxes, notes, Analytics lookup tables and safe CSV exports with SQL examples.

Shop owners spend much of their day on two screens: the order list and the single order screen. Extensions that add useful information there (a delivery date, a risk flag, a "send to warehouse" action) feel like part of the product. Extensions that get it wrong break when the store moves to High-Performance Order Storage (HPOS), because the list and edit screens changed their hooks when orders left the posts table.

This lesson shows how to add columns, filters, bulk actions and meta boxes in a way that works with HPOS, how order notes behave, where WooCommerce Analytics keeps its numbers, and how to export data safely. Hook code is read-only because it needs WordPress. The runnable stand-ins use SQLite to aggregate orders and to export them in chunks. If you need the storage background first, read Orders and High-Performance Order Storage, and keep the WooCommerce Hook Map at hand.

Two screens, two sets of hooks

flowchart TD
    A["Order admin screen"] --> B{"HPOS enabled?"}
    B -- yes --> C["Screen id: woocommerce_page_wc-orders"]
    B -- no --> D["Screen id: edit-shop_order (posts)"]
    C --> E["Hooks named for the wc-orders screen"]
    D --> F["Legacy post-type hooks"]

An extension that supports both storage modes registers hooks for both screens, or reads the screen id from a helper.

With HPOS the order list lives at admin.php?page=wc-orders. With the older storage it is the shop_order post list. The hooks differ by name, so a robust plugin registers both. Always declare HPOS compatibility, as shown in Your First WooCommerce Extension, and avoid get_post_meta() or WP_Query on orders (CRUD Classes and Data Stores explains why).

Adding a column

Read-only code for both storage modes:

PHP
<?php
// Header: HPOS screen and legacy screen.
add_filter( 'manage_woocommerce_page_wc-orders_columns', 'acme_add_slot_column' );
add_filter( 'manage_edit-shop_order_columns', 'acme_add_slot_column' );

function acme_add_slot_column( array $columns ): array {
    $new = [];
    foreach ( $columns as $key => $label ) {
        $new[ $key ] = $label;
        if ( 'order_status' === $key ) {
            $new['acme_slot'] = __( 'Delivery slot', 'acme' );
        }
    }
    return $new;
}

// Cell: HPOS passes the order object, legacy passes the post id.
add_action( 'manage_woocommerce_page_wc-orders_custom_column', 'acme_render_slot_column', 10, 2 );
add_action( 'manage_shop_order_posts_custom_column', 'acme_render_slot_column', 10, 2 );

function acme_render_slot_column( string $column, $order_or_id ): void {
    if ( 'acme_slot' !== $column ) {
        return;
    }
    $order = $order_or_id instanceof WC_Order ? $order_or_id : wc_get_order( $order_or_id );
    echo $order ? esc_html( (string) $order->get_meta( '_acme_slot' ) ) : '';
}

Why the extra check? In the legacy list WordPress hands you an id, in the HPOS list you get an order object. wc_get_order() accepts either, so normalizing at the top keeps the cell code simple. Reading the value through $order->get_meta() works in both modes and avoids one query per row when the list has primed the meta cache. Avoid expensive work in a cell: a call to an external API per row will make the list crawl.

Filtering the list

Two parts: a control in the filter bar and a change to the query. For HPOS, the action woocommerce_order_list_table_restrict_manage_orders renders extra controls, and the filter woocommerce_order_list_table_prepare_items_query_args lets you add arguments that wc_get_orders() understands:

PHP
<?php
add_filter( 'woocommerce_order_list_table_prepare_items_query_args', function ( array $args ): array {
    $slot = isset( $_GET['acme_slot'] ) ? sanitize_text_field( wp_unslash( $_GET['acme_slot'] ) ) : '';
    if ( '' !== $slot ) {
        $args['meta_query'][] = [
            'key'   => '_acme_slot',
            'value' => $slot,
        ];
    }
    return $args;
} );

Notes: sanitize everything read from $_GET; filtering on meta is slow on large stores unless the meta is indexed or stored in a dedicated table, which is why heavy filters often deserve their own table (see Performance and Scaling Large Stores). The legacy list is filtered with pre_get_posts or request.

Bulk actions

A bulk action has three parts: add the menu entry, handle the request, show a notice.

PHP
<?php
add_filter( 'bulk_actions-woocommerce_page_wc-orders', 'acme_register_bulk_action' );
add_filter( 'bulk_actions-edit-shop_order', 'acme_register_bulk_action' );

function acme_register_bulk_action( array $actions ): array {
    $actions['acme_mark_packed'] = __( 'Mark as packed', 'acme' );
    return $actions;
}

add_filter( 'handle_bulk_actions-woocommerce_page_wc-orders', 'acme_handle_bulk_action', 10, 3 );
add_filter( 'handle_bulk_actions-edit-shop_order', 'acme_handle_bulk_action', 10, 3 );

function acme_handle_bulk_action( string $redirect_to, string $action, array $ids ): string {
    if ( 'acme_mark_packed' !== $action ) {
        return $redirect_to;
    }
    if ( ! current_user_can( 'edit_shop_orders' ) ) {
        return $redirect_to;
    }
    $done = 0;
    foreach ( array_map( 'absint', $ids ) as $id ) {
        $order = wc_get_order( $id );
        if ( $order ) {
            $order->update_meta_data( '_acme_packed', 'yes' );
            $order->add_order_note( __( 'Marked as packed.', 'acme' ), 0, true );
            $order->save();
            ++$done;
        }
    }
    return add_query_arg( 'acme_packed', $done, $redirect_to );
}

WordPress checks the bulk-action nonce before your handler runs, but you still check the capability. Notice save() once per order, which keeps change tracking and data stores consistent, and the $added_by_user = true flag on the note so the note shows who did it. For thousands of orders, do not loop inside the request: schedule a job (Background Processing With Action Scheduler).

Meta boxes and notes on the order screen

An order edit screen has meta boxes just like a post. The screen id changes with the storage mode, so ask WooCommerce for it:

PHP
<?php
use Automattic\WooCommerce\Utilities\OrderUtil;

add_action( 'add_meta_boxes', function (): void {
    add_meta_box(
        'acme_slot_box',
        __( 'Delivery slot', 'acme' ),
        'acme_render_slot_box',
        OrderUtil::get_order_admin_screen(),
        'side',
        'default'
    );
} );

function acme_render_slot_box( $post_or_order ): void {
    $order = $post_or_order instanceof WC_Order ? $post_or_order : wc_get_order( $post_or_order->ID );
    wp_nonce_field( 'acme_save_slot', 'acme_slot_nonce' );
    printf( '<input type="text" name="acme_slot" value="%s">', esc_attr( (string) $order->get_meta( '_acme_slot' ) ) );
}

add_action( 'woocommerce_process_shop_order_meta', function ( int $order_id ): void {
    if ( ! isset( $_POST['acme_slot_nonce'] ) || ! wp_verify_nonce( sanitize_text_field( wp_unslash( $_POST['acme_slot_nonce'] ) ), 'acme_save_slot' ) ) {
        return;
    }
    if ( ! current_user_can( 'edit_shop_order', $order_id ) ) {
        return;
    }
    $order = wc_get_order( $order_id );
    $order->update_meta_data( '_acme_slot', sanitize_text_field( wp_unslash( $_POST['acme_slot'] ?? '' ) ) );
    $order->save();
} );

woocommerce_process_shop_order_meta fires when the order is saved from the admin in either storage mode. The field is escaped on output, validated by nonce and capability on input, and saved through the order object. The same discipline applies to the product panel in Custom Product Fields and Tabs.

Order notes are small records attached to an order. $order->add_order_note( $note, $is_customer_note, $added_by_user ) creates one; a customer note is also emailed to the shopper. wc_get_order_notes( [ 'order_id' => $id ] ) reads them. Notes are an audit trail, so write facts ("Label printed for slot 14:00"), never secrets, and remember they are visible to every user who can see the order.

Where Analytics numbers come from

The Analytics section of WooCommerce (formerly WooCommerce Admin) does not scan orders on every page view. It keeps lookup tables that are updated when orders change and queried with plain SQL:

Table (prefixed with wc_) Holds
order_stats One row per order: date, status, totals, net revenue, customer id
order_product_lookup One row per order line: product, variation, quantity, revenue
order_coupon_lookup Coupons applied to each order
order_tax_lookup Tax amounts per order and rate
customer_lookup Aggregated customer records

The tables are filled by background tasks run by Action Scheduler, which is why a brand-new order may take a moment to show up and why an import of historical data is a separate step in the Analytics settings. Analytics also excludes certain order statuses from its totals (configurable in the settings). If you add a custom order status, decide whether it counts as revenue, or reports will silently include or exclude it. For hooks and classes, read the plugin source for your installed version, because these internals evolve more quickly than the public CRUD API; when a number looks wrong, run the SQL against the lookup tables and compare it with the raw orders.

Aggregating and exporting data

The stand-in below mimics the lookup-table idea in SQLite: one narrow stats table, one query with GROUP BY, excluded statuses, and average order value computed from integer cents. It is not the real Analytics schema.

PHP Daily revenue report over an order-stats table

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Notice three habits: a half-open date range (>= start AND < end) so no order on the boundary is counted twice, excluded statuses as bound parameters (never string-built SQL), and money in integer cents. Day 2026-03-03 has no orders and therefore no row; a chart needs to fill the gap itself.

Exports

An export streams rows to a CSV file. Do it in chunks (never load every order at once), through the CRUD query API, and protect the file from CSV injection: a cell that starts with =, +, - or @ can run as a formula in a spreadsheet. Prefix such cells with an apostrophe or a space, and be strict about who may download the file (manage_woocommerce, a nonce, and files stored where the public cannot guess their URL).

PHP Chunked CSV export with formula-injection guard

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The loop uses keyset pagination (WHERE id > last) rather than OFFSET, which stays fast on large tables. With real orders you would use wc_get_orders() with limit and a paged or date cursor instead of raw SQL, because HPOS tables and legacy tables differ.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why do plugins register order-list hooks for two different screens?

    With HPOS the list uses the wc-orders screen and its own hooks; without HPOS it is the shop_order post list. Supporting both keeps the plugin working everywhere.
  2. 2. In a custom column callback, why call wc_get_order() on the argument?

    Normalizing the argument to an order object lets one function serve both screens.
  3. 3. Which three checks protect saving a custom order meta box value?

    The nonce proves the request came from your form, the capability proves the user may edit the order and sanitizing makes the stored value safe.
  4. 4. Why does a cell starting with an equals sign matter in an exported CSV?

    Customer-controlled text can contain formulas. Prefixing such cells prevents them from executing when the file is opened.
  5. 5. Where does WooCommerce Analytics read its revenue numbers from?

    Dedicated lookup tables make reports fast. Because they are filled by background jobs, new orders can take a moment to appear.

Summary

  • Register order-list columns, filters and bulk actions for both the HPOS screen (woocommerce_page_wc-orders) and the legacy post list, and normalize ids or objects with wc_get_order().
  • Save meta box data with a nonce, a capability check, sanitizing and $order->save(); use OrderUtil::get_order_admin_screen() to pick the screen.
  • Bulk actions must check capabilities themselves, and large batches belong in background jobs.
  • Order notes are an audit trail: record facts, never secrets.
  • Analytics reads lookup tables filled by Action Scheduler; custom statuses need an explicit decision about whether they count.
  • Export in chunks with keyset pagination, bind SQL parameters, keep money in integers and neutralize spreadsheet formulas.

Next: The REST API and the Store API