wc_get_orders() and order queries

wc_get_orders() and WC_Order_Query provide a standard way of retrieving orders from the database, similar to WordPress' get_posts() and WP_Query but specifically for orders.

プラグインやテーマの開発者は、WordPressやWooCommerceのデータベースが変更されると破損する可能性があるため、WordPressのカスタムクエリや直接SQLを書くことをお勧めしません。これらのAPIは、WooCommerceで注文を取得するためのベストプラクティスと将来を保証する方法を提供します。

Basic usage

Examples

いくつか例を挙げよう：

// Get orders from people named John paid in 2016.
$orders = wc_get_orders(
    array(
        'billing_first_name' => 'John',
        'date_paid'          => '2016-01-01...2016-12-31',
    )
);

// Get 10 most recent order IDs.
$query = new WC_Order_Query(
    array(
        'limit'   => 10,
        'orderby' => 'date',
        'order'   => 'DESC',
        'return'  => 'ids',
    )
);
$orders = $query->get_orders();

// Get orders from the customer with email 'woocommerce@woocommerce.com'.
$query = new WC_Order_Query();
$query->set( 'customer', 'woocommerce@woocommerce.com' );
$orders = $query->get_orders();

Note that wc_get_orders() is mostly a shortcut to WC_Order_Query::get_orders().

Best practices

• Avoid direct base queries and rely on wc_get_orders() instead.
• If your code needs to support legacy setups, test thoroughly with HPOS enabled and disabled.
• Use specific parameters to limit results and improve performance.
• Consider pagination for large result sets using limit and offset.
• Cache results when appropriate.
• For complex filtering requirements, leverage the new query arguments meta_query, field_query and date_query available since 8.2 on sites running HPOS.

API reference

Method	Description
wc_get_orders ( $args )	Retrieve orders matching query $args.
WC_Order_Query::get_query_vars()	Get an array of all of the current query variables set on the query object.
WC_Order_Query::get( string $key, mixed $default = '' )	Get the value of a query variable or the default if the query variable is not set.
WC_Order_Query::set( string $key, mixed $value )	Set a query variable.
WC_Order_Query::get_orders()	Get all orders matching the current query variables.

これらの関数で使用できるクエリ・パラメータ／引数を以下に示す。

Query parameters reference

General

Parameter	Description
status	Accepts an array of strings: by default is set to the keys of wc_get_order_statuses().
type	Accepts a string: 'shop_order', 'shop_order_refund', or a custom order type.
version	Accepts a string: WooCommerce version number the order was created in.
created_via	Accepts a string: 'checkout', 'rest-api', or a custom creation method slug.
parent	Accepts an integer: post ID of the order parent.
parent_exclude	Accepts an array of integers: Excludes orders with parent ids in the array.
exclude	Accepts an array of integers: excludes orders that have the ids.
order	Accepts a string: 'DESC' or 'ASC'. Use with 'orderby'. Default: 'DESC'.
orderby	Accepts a string: 'none', 'ID', 'name', 'type', 'rand', 'date', 'modified'. Default: 'date'.
return	Return type. Accepts a string: 'ids' or 'objects'. Default: 'objects'.

Examples

// Get most recently modified orders.
$args = array(
    'orderby' => 'modified',
    'order' => 'DESC',
);
$orders = wc_get_orders( $args );

// Get some random orders.
$orders = wc_get_orders( array( 'orderby' => 'rand' ) );

// Return only order ids.
$orders = wc_get_orders( array( 'return' => 'ids' ) );

// Get orders processing and on-hold.
$args = array(
    'status' => array( 'wc-processing', 'wc-on-hold' ),
);
$orders = wc_get_orders( $args );

// Get refunds in the last 24 hours.
$args = array(
    'type'         => 'shop_order_refund',
    'date_created' => '>' . ( time() - DAY_IN_SECONDS ),
);
$orders = wc_get_orders( $args );

// Get orders created during WooCommerce 2.6.14 and through site checkout.
$args = array(
    'version'     => '2.6.14',
    'created_via' => 'checkout',
);
$orders = wc_get_orders( $args );

// Get orders with post parent ID of 20 that aren't order 12.
$args = array(
    'parent'  => 20,
    'exclude' => array( 12 ),
);
$orders = wc_get_orders( $args );

Pagination

Parameter	Description
limit	Accepts an integer: Maximum number of results to retrieve or -1 for unlimited. Default: Site 'posts_per_page' setting.
paged	Accepts an integer: Page of results to retrieve. Does nothing if 'offset' is used.
offset	Accepts an integer: Amount to offset order results.
paginate	Accepts a boolean: True for pagination, or false for not (default: false). If enabled, modifies the return results to give an object with fields: orders (array of found orders), total (number of found orders) and max_num_pages (total number of pages).

Examples

// Get latest 3 orders.
$orders = wc_get_orders( array( 'limit' => 3 ) );

// First 3 orders.
$args = array(
    'limit' => 3,
    'paged' => 1,
);
$page_1_orders = wc_get_orders( $args );

// Second 3 orders.
$args = array(
    'limit' => 3,
    'paged' => 2,
);
$page_2_orders = wc_get_orders( $args );

// Get orders with extra info about the results.
$results = wc_get_orders( array( 'paginate' => true ) );
echo $results->total . " orders found\n";
echo 'Page 1 of ' . $results->max_num_pages . "\n";
echo 'First order id is: ' . $results->orders[0]->get_id() . "\n";

Payment & amounts

パラメータ	ディスクリプション
通貨	currency
prices_include_tax	文字列: 'yes'または'no'を指定します。
**支払い方法のスラッグ：使用される支払い方法のスラッグ。
payment_method_title	文字列を指定します：使用される支払い方法の完全なタイトル。
discount_total	浮動小数点数で指定: 四捨五入されていない金額。
discount_tax	浮動小数点: 四捨五入されない金額を指定します。
shipping_total	浮動小数点数で指定。
shipping_tax	浮動小数点: 四捨五入されない金額を指定します。
cart_tax	浮動小数点(四捨五入なし)で指定。
合計(total)*	浮動小数点(四捨五入なし)を入力してください。

Examples

// Get orders paid in USD.
$orders = wc_get_orders( array( 'currency' => 'USD' ) );

// Get orders paid by check.
$orders = wc_get_orders( array( 'payment_method' => 'cheque' ) );

// Get orders with 20.00 discount total.
$orders = wc_get_orders( array( 'discount_total' => 20.00 ) );

Customer

パラメータ	ディスクリプション
customer	文字列または整数を指定します：注文の請求先メールアドレスまたは顧客ID。
customer_id	整数を指定します：顧客ID。
customer_ip_address	文字列を受け取ります：マッチする値。

Examples

// Get orders by customer with email 'woocommerce@woocommerce.com'.
$orders = wc_get_orders( array( 'customer' => 'woocommerce@woocommerce.com' ) );

// Get orders by customer with ID 12.
$orders = wc_get_orders( array( 'customer_id' => 12 ) );

Billing & shipping

パラメータ	ディスクリプション
姓｜*billing_first_name**｜文字列で指定。
姓	***名: 文字列で指定。
billing_company	文字列で指定します。
billing_address_1*	文字列を指定します。
billing_address_2*	文字列を指定します。
billing_city*	文字列を指定します。
billing_state*	文字列を指定します。
billing_postcode	文字列を指定します。
billing_country*	文字列を指定します。
billing_email*	文字列を指定します。
billing_phone	文字列を指定します。
*shipping_first_name｜文字列を指定します。
姓(last_name)	文字列を指定します。
会社名：文字列で指定。
発送先住所_1｜文字列を指定します。
発送先住所2：文字列で指定。
配送先市町村名:文字列を指定します。
発送先郵便番号***｜shipping_state*｜文字列を指定します。
配送先郵便番号：文字列で指定。
配送先国名｜*shipping_country**｜文字列で指定。

Examples

// Get orders from the US.
$orders = wc_get_orders( array( 'billing_country' => 'US' ) );

// Get orders from people named Bill Evans.
$args = array(
    'billing_first_name' => 'Bill',
    'billing_last_name'  => 'Evans',
);
$orders = wc_get_orders( $args );

Date

日付の引数は、以下に説明する標準的な書式に従って値を受け取るので、より柔軟なクエリが可能になる。

パラメータ	ディスクリプション
date_created注文の作成日にマッチします。標準形式の文字列を受け付けます。
date_modified	注文の変更日にマッチします。標準書式の文字列を指定します。
**注文の完了日。標準書式の文字列を受け付けます。
date_paid*注文の支払日にマッチします。標準書式の文字列を受け付けます。

Standard format

• YYYY-MM-DD – Matches on orders during that one day in site timezone.
• >YYYY-MM-DD – Matches on orders after that one day in site timezone.
• >=YYYY-MM-DD – Matches on orders during or after that one day in site timezone.
• <YYYY-MM-DD – Matches on orders before that one day in site timezone.
• <=YYYY-MM-DD – Matches on orders during or before that one day in site timezone.
• YYYY-MM-DD...YYYY-MM-DD – Matches on orders during or in between the days in site timezone.
• TIMESTAMP – Matches on orders during that one second in UTC timezone.
• >TIMESTAMP – Matches on orders after that one second in UTC timezone.
• >=TIMESTAMP – Matches on orders during or after that one second in UTC timezone.
• <TIMESTAMP – Matches on orders before that one second in UTC timezone.
• <=TIMESTAMP – Matches on orders during or before that one second in UTC timezone.
• TIMESTAMP...TIMESTAMP – Matches on orders during or in between the seconds in UTC timezone.

Examples

// Get orders paid February 12, 2016.
$orders = wc_get_orders( array( 'date_paid' => '2016-02-12' ) );

// Get orders created before the last hour.
$args = array(
    'date_created' => '<' . ( time() - HOUR_IN_SECONDS ),
);
$orders = wc_get_orders( $args );

// Get orders completed 16 May 2017 21:46:17 UTC to 17 May 2017 12:46:17 UTC.
$args = array(
    'date_completed' => '1494938777...1494971177',
);
$orders = wc_get_orders( $args );

Metadata

Parameter	Description
meta_query	One or more arrays with keys key (meta key), value (optional, string or array) and optionally type and compare. This parameter is analogous to WP_Query's meta_query, supporting various comparison operators and levels of queries joined by AND/OR relations.

詳細と例については、HPOS order querying ガイドを参照してください。

:::warning

Support for meta_query is only available when HPOS is the configured order data storage (the default since WooCommerce 8.2).

Check if it's enabled with OrderUtil::custom_orders_table_usage_is_enabled() before using.
:::

Examples

// Orders with metadata 'custom_field' set to 'some_value' and metadata 'weight' higher than '50'.
$orders = wc_get_orders(
    array(
        'meta_query' => array(
            array(
                'key'     => 'custom_field',
                'value'   => 'some_value',
                'compare' => '='
            ),
            array(
                'key'     => 'weight',
                'value'   => '50',
                'compare' => '>='
            ),
            'relation' => 'AND'
        )
    )
);

Order fields

Parameter	Description
field_query	One or more arrays with keys field (any order property), value and optionally type and compare. This parameter is analogous to those of meta_query described in the previous section, supporting various comparison operators and levels of queries joined by AND/OR relations.

詳細と例については、HPOS order querying ガイドを参照してください。

:::warning

Support for field_query is only available when HPOS is the configured order data storage (the default since WooCommerce 8.2).

Check if it's enabled with OrderUtil::custom_orders_table_usage_is_enabled() before using.
:::

Examples

// Obtain orders with a total greater than 100 or from New York city.
$orders = wc_get_orders(
    array(
        'field_query' => array(
            array(
                'field' => 'total',
                'value' => 100,
                'compare' => '>'
            ),
            array(
                'field' => 'billing_city',
                'value' => 'New York',
                'compare' => '='
            ),
            'relation' => 'OR'
        )
    )
);

Advanced date queries

Parameter	Description
date_query	One or more arrays with keys column (an order date: date_completed, date_created, date_updated or date_paid, optionally followed by _gmt for UTC dates), value and optionally type and compare. This parameter is analogous to WP_Query's date_query, supporting various comparison operators and levels of queries joined by AND/OR relations.

詳細と例については、HPOS order querying ガイドを参照してください。

:::warning

Support for date_query is only available when HPOS is the configured order data storage (the default since WooCommerce 8.2).

Check if it's enabled with OrderUtil::custom_orders_table_usage_is_enabled() before using.
:::

Examples

// Example: Orders paid in the last month that were created before noon (on any date).

$orders = wc_get_orders(
    array(
        'date_query' => array(
            'relation' => 'AND',
            array(
                'column'  => 'date_created_gmt',
                'hour'    => 12,
                'compare' => '<'
            ),
            array(
                'column'  => 'date_paid_gmt',
                'after'   => '1 month ago',
            ),
        ),
    )
);

Adding support for custom parameters

Developers can extend the query capabilities by filtering the generated query to add support for custom parameters to both wc_get_orders() and WC_Order_Query.

WooCommerceは現在2つの注文保存メカニズムをサポートしています：HPOS(デフォルト)とレガシー(WordPressの投稿とメタデータを使用)です：

• (HPOS) woocommerce_order_query_args to translate a parameter into an existing one, or woocommerce_orders_table_query_clauses to write your own SQL.
• (Legacy) woocommerce_order_data_store_cpt_get_orders_query to translate a parameter into a WP_Query parameter.

/**
 * Example: Handle a custom 'customvar' query var to get orders with the 'customvar' meta.
 */
use Automattic\WooCommerce\Utilities\OrderUtil;

// HPOS version.
function handle_custom_query_var_hpos( $query_args ) {
    if ( ! empty( $query_args['customvar'] ) ) {
        if ( ! isset( $query_args['meta_query'] ) ) {
            $query_args['meta_query'] = array();
        }

        $query_args['meta_query'][] = array(
            'key'   => 'customvar',
            'value' => esc_attr( $query_args['customvar'] ),
        );

        unset( $query_args['customvar'] );
    }


    return $query_args;
}

// Legacy version.
function handle_custom_query_var_legacy( $query, $query_vars ) {
    if ( ! empty( $query_vars['customvar'] ) ) {
        $query['meta_query'][] = array(
            'key'   => 'customvar',
            'value' => esc_attr( $query_vars['customvar'] ),
        );
    }

    return $query;
}

if ( OrderUtil::custom_orders_table_usage_is_enabled() ) {
    // HPOS.
    add_filter(
        'woocommerce_order_query_args',
        'handle_custom_query_var_hpos'
    );
} else {
    // Legacy support.
    add_filter(
        'woocommerce_order_data_store_cpt_get_orders_query',
        'handle_custom_query_var_legacy',
        10,
        2
    );
}

Usage:

$orders = wc_get_orders( array( 'customvar' => 'somevalue' ) );