WooCommerce Customer / Order CSV Export developer documentation

Overview ↑ Back to top

This extension was designed to be as flexible as possible. To that end, filters are used to allow you to customize the generated CSV or replace it entirely.

We do have one major recommendation: We strongly recommend that you do not rely on the column ordering for the generated CSV. While we do our best to not change column ordering for default formats, sometimes we must do so and this will break any integrations that rely on a specific order. Instead, use the column names / keys, which are guaranteed to never change.

Please be aware that this document is meant for developers to use as a reference, and some of these code samples are structural samples rather than working snippets. We do not support or do plugin customizations as per our support policy. You can get in touch with an expert for help with customizations.

If you need help changing this code or extending it, we recommend getting in touch with a Woo Expert or a developer at Codeable.

Customization Best Practices ↑ Back to top

While you can use the filters / actions referenced in this document for doing basic customizations within your theme’s functions.php file, we strongly recommend creating a custom plugin so that if you switch themes you don’t lose your customizations.

For more information on creating a custom plugin for your WooCommerce store, read this article.

We also have several snippet examples available for reference that show you several filters in action.

File Name / Format Filters ↑ Back to top

File Name ↑ Back to top

apply_filters( 'wc_customer_order_csv_export_filename', $post_replace_filename, $pre_replace_filename, $ids );

Use this filter to change the generated file name for the CSV. This affects the file name for both downloads and uploads, but not HTTP POST (which has no file name). Here’s some sample code for changing the date/time format of the %%timestamp%% variable:

Here’s some sample code for adding a %%order_numbers%% filename variable so the order numbers support Sequential Order Numbers:

File Format ↑ Back to top

apply_filters( 'wc_customer_order_csv_export_download_content_type', 'Content-Type: text/csv; charset=' . get_option( 'blog_charset' ) ); 

Use this filter to change the content type sent to the browser before download. This is most useful if you’ve changed the output format to something other than CSV, e.g. TXT and still want single order downloads to work correctly.

Output Format ↑ Back to top

The format of the CSV is defined by two things: an array the sets the column headers for the CSV file, and another array that sets the data for each row of the CSV. All output-related filters pass in the WC_Customer_Order_CSV_Export_Generator class instance (as $this) which has a $ids member which is an array of order or customer IDs. You can use this to conditionally modify the format for specific customers or orders.

CSV Delimiter ↑ Back to top

apply_filters( 'wc_customer_order_csv_export_delimiter', ',', $this );

Use this filter to change the CSV delimiter. This is a comma (,) by default.

CSV Enclosure ↑ Back to top

apply_filters( 'wc_customer_order_csv_export_enclosure', '"', $this );

Use this filter to change the CSV enclosure. This is a double-quote (") by default.

Enabling BOM (byte-order mark) ↑ Back to top

apply_filters( 'wc_customer_order_csv_export_enable_bom', false, $this );

Use this filter to add a BOM at the start of every generated CSV file. This is disabled by default.

Here’s some example code:

Customizing Customer CSV Output ↑ Back to top

The output of the CSV file can be customized easily using the built-in custom format builder (version 4.0+). However, you may want to conditionally change a default format, for which the built-in filters are helpful.

Adjust Included Customers ↑ Back to top

By default, all non-employee purchasers are included in the customer export (if using WordPress 4.4+) — administrators and shop managers are excluded from the customer export. However, you could customize this to only include certain roles using this filter:

apply_filters( 'wc_customer_order_csv_export_user_query_args', $query_args );

Here’s an example to limit the customer export to certain roles.

Add New Columns ↑ Back to top

You can add customer data to the exported customer CSV as well so long as this data is part of the WooCommerce customer data or accessible as part of the WP User object.

You’d use the wc_customer_order_csv_export_customer_headers filter to add the column header / name, and the wc_customer_order_csv_export_customer_row to populate the data for that column. Here’s an example snippet for adding customer columns.

Add Customer Role

You can also add columns in a particular location or to add additional information. View this code snippet to add both username and customer role in the exported CSV in particular locations.

Rename, Re-order, or Remove Columns ↑ Back to top

You can customize which columns are included and their order in the exported CSV. You can also remove unnecessary columns. Here are some form samples that can be used to remove, rename, or re-order customer CSV columns:

Customizing Order CSV Output ↑ Back to top

The output of the CSV file can be customized easily using the built-in custom format builder (version 4.0+). However, you may want to conditionally change a default format, for which the built-in filters are helpful.

Adjust Included Orders ↑ Back to top

All orders will be included in your export, or the export query can be adjusted based on order status, products in the order, categories in the order, or the order date. If you need to make further adjustments to the orders included in the export, the query arguments can be filtered further:

apply_filters( 'wc_customer_order_csv_export_query_args', $query_args, $export_type );

Be sure to check that 'orders' === $export_type if scoping your code to order exports.

Here’s an example to limit the order export to only orders that have at least one refund associated with them.

Adding Additional Columns ↑ Back to top

If you need to add additional columns the order CSV export, you’ll use two filters — one to add the column headers and another to set the data for the columns for each row. Here’s a structural sample:

Since custom formats were added in version 4.0+, these may have a one row per item format. If you maintain a plugin that has compatibility with this format, you’ll want a way to check if this format is in use. Here’s an example:

You can then use this check within your plugin or custom code to ensure you’ve added your custom data correctly:

if ( sv_wc_csv_export_is_one_row( $csv_generator ) ) {
    foreach ( $order_data as $data ) {
        $new_order_data[] = array_merge( (array) $data, $custom_data );
    }
} else {
    $new_order_data = array_merge( $order_data, $custom_data );
}

However, this would only apply if you already have access to the WC_Customer_Order_CSV_Export_Generator instance in your filter / code. If for some reason you need to check the row type for a custom format outside of a filter that gives you access to this, you can check the format definition this way:

$format_definition = wc_customer_order_csv_export()->get_formats_instance()->get_format( 'orders', 'custom' );

The $format_definition['row_type'] will be ‘item’ or ‘order’ for the custom format, letting you then act on the format from there.

Other Samples

Separating coupons into multiple columns

The ‘coupons’ column contains all coupon data, but this data could be expanded into individual columns with the Default formats. This sample code snippet will separate the ‘coupons’ column into 3 columns per coupon used: ‘coupon_{$count}name’, ‘coupon{$count}description’, and ‘coupon{$count}_amount’

Renaming / Removing / Reordering Columns ↑ Back to top

You can rename or reorder the columns using this filter:

apply_filters( 'wc_customer_order_csv_export_order_headers', $column_headers, $this );

Here’s a collection of some samples:

Modifying line items ↑ Back to top

When using the default format, you can add / remove / modify line item entries using the

apply_filters( 'wc_customer_order_csv_export_order_line_item', $line_item, $item );

filter. This passes in the existing line item entries along with the WC Order Item array.

Here’s some sample code for adding the product’s weight as item meta in the CSV export.

If you wanted to modify existing data, you can do so for the line items and columns using the column header keys. Here’s a working example that will change all prices from machine-readable values to localized price output for currency.

Changing the generated CSV ↑ Back to top

Occasionally you might need to change the CSV after it’s already been generated (e.g. removing the header line). To do this, use this filter:

apply_filters( 'wc_customer_order_csv_export_generated_csv', $csv, $this );

Exporting each order individually ↑ Back to top

You can change the plugin settings to export orders individually as they’re paid. However, if you’d like to export each order individually based on the export method, the following code is a good starting point:

function sv_wc_csv_export_export_order_on_payment( $order_id ) {

    $export = new WC_Customer_Order_CSV_Export_Handler( $order_id );

    // for FTP
    $export->upload();

    // uncomment for HTTP POST
    // $export->http_post();
}
add_action( 'woocommerce_payment_complete', 'sv_wc_csv_export_export_order_on_payment' );

Updating order status after export ↑ Back to top

You can update an order’s status after export by hooking into the wc_customer_order_csv_export_order_exported action. Here are a couple examples of updating the status on every export, or only for paid orders.

HTTP POST Filters ↑ Back to top

If you’re using the automatic export over HTTP POST, there is a filter available to change the arguments used for wp_remote_post().

$args = apply_filters( 'wc_customer_order_csv_export_http_post_args', array(
        'timeout'     => 60,
        'redirection' => 0,
        'httpversion' => '1.0',
        'sslverify'   => false,
        'blocking'    => true,
        'headers'     => array(
            'accept'       => 'text/csv',
            'content-type' => 'text/csv' ),
        'body'        => $csv,
        'cookies'     => array(),
        'user-agent'  => "WordPress " . $GLOBALS['wp_version'],
) );

For example, if the web service you’re posting to requires authentication, you could use this filter to add HTTP basic auth to the headers:

Admin Filters ↑ Back to top

If you’d like to customize the query arguments that are used for selecting orders to export on the CSV Export > Export screen, use:

apply_filters( 'wc_customer_order_csv_export_admin_query_args', $query_args, $export_type, $this );

You can also customize query arguments used for the customer export on the CSV Export > Export Screen using:

apply_filters( 'wc_customer_order_csv_export_user_query_args', $query_args );

Here’s an example that lets you determine which user roles are included as customers in the export.

You can also add or remove settings from the CSV Export > Settings screen using:

apply_filters( 'wc_customer_order_csv_export_settings', $settings[ $tab_id ], $tab_id );

Resources & Links ↑ Back to top

WooCommerce - the most customizable eCommerce platform for building your online business.

Back to the top