How to get WooCommerce orders using wc_get_orders

This article provides a detailed guide on how to use the wc_get_orders function in WooCommerce to programmatically retrieve orders. We’ll focus specifically on the different search parameters available with wc_get_orders, explaining how each can be used to filter and sort your WooCommerce order data. This guide is designed to be practical and easy to understand, offering clear instructions for both beginners and experienced users looking to optimize their order management process in WooCommerce.

How to use the wc_get_orders function

To use the wc_get_orders function in WooCommerce, you need to pass an array of arguments ($args) that specify the criteria for searching orders. These arguments can include details like order status, customer ID, date range, and more, allowing you to filter and retrieve orders that match specific attributes.

For example, you can use $args = array('status' => 'completed'); to fetch all completed orders. Once you’ve set your search parameters, wc_get_orders returns an array of order objects based on your criteria. Each order object is an instance of WC_Order class. You can then iterate over this array to access and manipulate individual order details. Here’s a simple example:

$args = array('status' => array('wc-completed'), 'limit' => -1, 'type' => 'shop_order');
$orders = wc_get_orders($args);
foreach ($orders as $order) {
  // Access order details here
  echo 'Order ID: ' . $order->get_id();
}

This code snippet demonstrates how to search for all completed orders and then loop through the results, printing the ID of the order. You can also use the WC_Order class to access almost any aspect of the order data, such as the order item, date, customer details, etc.

It’s also important to note that when the limit argument is set to -1, the result will return all orders; otherwise, if not specified, only the most recent orders will be returned. For more information about using the limit argument you can refer to the limit parameter section below.

Order type argument

The type argument in the wc_get_orders function is crucial for specifying the kind of orders you want to retrieve in WooCommerce. By default, this argument is set to include all order types. The core WooCommerce order types are ‘shop_order’ and ‘shop_order_refund’, meaning that if the type argument is not specified, wc_get_orders() will fetch standard orders and their associated refunds. However, if your intention is to retrieve only the orders without the refunds, you need to explicitly specify this in the type argument. For instance, setting the type argument to just ‘shop_order’ will ensure that the function returns only the actual orders and excludes any refunds:

$args = array('type' => 'shop_order');
$orders = wc_get_orders($args);

As you can see in the example above, when querying orders by a single order type, we can set the type as a string. If you need to filter by multiple types, you can pass an array of types instead:

$args = array('type' => array('shop_order', 'shop_order_refund'));
$orders = wc_get_orders($args);

Limit argument – how many orders to return

The limit argument plays a key role in controlling the number of orders returned by the wc_get_orders() function. By default, this argument is set to the value of the posts_per_page setting (defaults to 10), meaning that when you execute the function without specifying this parameter, it will retrieve only the first 10 orders that meet your search criteria. This default setting is useful for managing performance, especially in stores with a large number of orders. However, if your requirement is to load all orders without any restriction on the count, you need to set the limit parameter to -1.

Here is how you can load all orders:

$orders = wc_get_orders(array('limit' => -1));

And if you need to load only a specific number of orders, you can set that in the limit argument as well:

$orders = wc_get_orders(array('limit' => 20));

Setting the sorting order

In WooCommerce, the wc_get_orders function uses the orderby and order arguments to determine the sorting of the retrieved orders. By default, orderby is set to “date”, which means orders are sorted based on their creation date. The order argument, on the other hand, defaults to “DESC” (descending), indicating that the most recent orders are listed first. However, these defaults can be adjusted to suit different requirements. For orderby, you have options like “none”, “ID”, “name”, “type”, “rand”, “date”, and “modified”, allowing you to sort orders by various attributes such as order ID, name, order type, randomly, by creation date, or by the date they were last modified. The order argument accepts either “ASC” (ascending) or “DESC” (descending), providing flexibility in how the order list is ordered.

The following example demonstrates how to query orders by their ID in ascending order:

$args = array('orderby' => 'ID', 'order' => 'ASC');
$orders = wc_get_orders($args);

Get WooCommerce orders by status

The status argument in the wc_get_orders function in WooCommerce can accept an array of statuses, allowing for a more targeted retrieval of orders. This flexibility means you can specify multiple order statuses in your search criteria, such as ['wc-completed', 'wc-processing', 'wc-on-hold'], to fetch orders that match any of these conditions. By default, if you don’t specify a status, wc_get_orders will return orders of all statuses that are available in your WooCommerce store. These default statuses are those returned by the wc_get_order_statuses() function, including:

• wc-pending
• wc-processing
• wc-on-hold
• wc-completed
• wc-cancelled
• wc-refunded
• wc-failed
• wc-checkout-draft

In the following example, you can see how to get orders with status Completed and On Hold:

$args = array('status' => array('wc-completed', 'wc-on-hold'));
$orders = wc_get_orders($args);

Get WooCommerce orders by date

To retrieve orders by date, you have the option to use various date parameters. These parameters allow for precise control over the date and time range for the orders you wish to query. Here’s a breakdown of the available date arguments and how they can be used:

• date_created: Filters orders by the date they were created
• date_modified: Targets orders based on the date they were last modified
• date_completed: Focuses on orders that were completed on a specific date
• date_paid: Filters orders by the date payment was received.

Each of these arguments accepts a string in several formats to match orders:

• YYYY-MM-DD: Retrieves orders from a specific day according to the site’s timezone
• >YYYY-MM-DD: Fetches orders placed after the specified day
• >=YYYY-MM-DD: Includes orders from the specified day and later
• <YYYY-MM-DD: Gets orders placed before the specified day
• <=YYYY-MM-DD: Fetches orders up to and including the specified day
• YYYY-MM-DD...YYYY-MM-DD: Filters orders between two specific dates

The same operators are available to use with timestamps in case you need a more specific filter including an order time search:

• • TIMESTAMP: Matches orders from a specific second in UTC
  • >TIMESTAMP: Retrieves orders after a specific second in UTC
  • >=TIMESTAMP: Includes orders from a specific second in UTC and later
  • <TIMESTAMP: Gets orders before a specific second in UTC
  • <=TIMESTAMP: Fetches orders up to and including a specific second in UTC
  • TIMESTAMP...TIMESTAMP: Filters orders between two specific seconds in UTC

The following example illustrates how to retrieve orders that were created in 2023:

$args = array('date_created' => '2023-01-01...2023-12-31');
$orders = wc_get_orders($args);

Here, you can see how to query orders that were paid after a given date:

$args = array('date_paid' => '>2024-01-01');
$orders = wc_get_orders($args);

Get WooCommerce orders by customer

The customer argument in the wc_get_orders function is a versatile tool for filtering orders based on the customer’s data in WooCommerce. This argument accepts either a string or a number, allowing you to search for orders based on different kinds of customer information.

When provided as a string, it represents the billing email associated with the order. This feature is particularly useful as it allows for the inclusion of both guest customers and registered users.

$orders = wc_get_orders(array('customer' =>'johndoe@example.com'));

When the customer argument is used as an integer, it refers to the customer ID, which is essentially the WordPress user ID for registered users:

$orders = wc_get_orders(array('customer' => 123));

Retrieving orders based on billing and shipping details

When using the wc_get_orders function, you have a range of arguments at your disposal to filter orders based on specific billing and shipping details. These include:

• billing_first_name, billing_last_name, billing_company, billing_address_1, billing_address_2, billing_city, billing_state, billing_postcode, billing_country, billing_email, and billing_phone for billing information
• shipping_first_name, shipping_last_name, shipping_company, shipping_address_1, shipping_address_2, shipping_city, shipping_state, shipping_postcode, and shipping_country for shipping details.

These arguments allow you to refine your order search based on the corresponding billing or shipping field. For instance, you can search for all orders shipped to a particular city:

$orders = wc_get_orders(array('shipping_city' => 'Some city'));

Or you can search by the customer’s billing first name and last name:

$args = array('billing_first_name' => 'John', 'billing_last_name' => 'Doe');
$orders = wc_get_orders($args);

Get WooCommerce orders by total price

The total argument in the wc_get_orders function in WooCommerce is used to filter orders by their exact total value. This means when you specify a monetary amount in the total argument, the function will return only those orders whose total value matches the amount you’ve set precisely. For instance, setting total to a specific figure like 100 will retrieve all orders that have a total value of exactly $100.

$orders = wc_get_orders(array('total' => 100));

Excluding orders

By specifying an array of order IDs in the exclude parameter, the wc_get_orders() function will return all orders except those identified by these IDs. This is particularly handy when you need to process or analyze a majority of orders while deliberately leaving out a few by order_id, such as test orders or orders with unique conditions. For instance, if you want to retrieve all orders except for order IDs 10 and 20, you would use exclude like this:

$orders = wc_get_orders(array('exclude' => array(10, 20)));

Get WooCommerce orders by payment method

The wc_get_orders function allows querying orders by a payment method, allowing you to find orders paid via PayPal, credit card, or any other payment gateway configured in your WooCommerce store. The following arguments are available:

• payment_method – allows you to specify one or more payment method slugs and retrieve orders that were processed through those specific channels. For example, to find all orders paid via cash on delivery, you can use the following code snippet:

$args = array('payment_method' => 'cod');
$orders = wc_get_orders($args);

• payment_method_title – allows you to specify one or more payment method titles to retrieve orders by. For example:

$args = array('payment_method_title' => array('PayPal', 'Cash on Delivery'));
$orders = wc_get_orders($args);

Paginating the orders result

The paged and offset arguments in the wc_get_orders function control the pagination of order results in WooCommerce, working in conjunction with the limit argument.

The paged argument accepts an integer representing the page number of results you wish to retrieve. This is useful when you have a large number of orders and want to view them in a segmented, page-by-page manner. For example, if you set limit to 20 and paged to 2, you will retrieve the second set of 20 orders:

$args = array('limit' => 20, 'paged' => 2);
$orders = wc_get_orders($args);

The offset argument also accepts an integer, but it specifies the number of orders to skip before starting to retrieve the orders. It’s useful for skipping a certain number of recent orders. Note that if offset is used, the paged argument is ignored.

$args = array('limit' => 20, 'offset' => 10);
$orders = wc_get_orders($args);

In the first example with paged, you get a specific page of results, which is great for displaying orders in a paginated format on a UI. In the second example with offset, you skip a certain number of orders from the beginning, which can be useful for scenarios where you need to process orders in batches but want to skip a specific number at the start.

Searching customers by order attributes

If you need to search your customers by their order information, you can use the Users Insights plugin WooCommerce order filters. These filters allow you to find the users who have placed an order with a given product, status, date, and value. You can also add many additional filters to further segment the customer list, such as lifetime value, number of orders, and all available features and data from the supported plugins:

wc_get_orders() vs WC_Order_Query

wc_get_orders() and WC_Order_Query in WooCommerce serve similar purposes but differ mainly in their implementation and ease of use. Essentially, wc_get_orders() is a simplified, more accessible interface that utilizes the WC_Order_Query class behind the scenes. This means they are interchangeable in functionality, with wc_get_orders() being more straightforward for general use. While wc_get_orders() provides a quick and easy way to retrieve orders with a simple array of arguments, WC_Order_Query offers a more object-oriented approach, giving advanced users additional flexibility and control over the query.

For example, to retrieve completed orders using WC_Order_Query, you would write:

$query = new WC_Order_Query(array('status' => 'wc-completed'));
$orders = $query->get_orders();

Conclusion

Using the wc_get_orders function in WooCommerce allows you to manage and access your orders efficiently. We’ve discussed how to customize your order search and organization, focusing on practical aspects like filtering by customer details, status, date, and order value. These functionalities are crucial for effective order handling and analysis in your WooCommerce store.