WC_Order class Explained

This article is a quick Overview of the WC_Order class. In it, you can find its methods, examples, arguments, and overall usage.

The WC_Order class is a great way to interact with the WooCommerce orders. It allows you to get information, manipulate data and even delete elements. But given how complex WooCommerce is, it’s easy to get lost in so many options.

Therefore, our goal for today is to elaborate on how you can use the most common methods of the WC_Order class. In addition, we add examples and list the expected arguments.

Let’s dive into it!

Overview

In general, you can initiate the WC_Order class by passing the order ID you want to retrieve. Therefore, you can find an order by loading it like this:

$order = new WC_Order( $order_id );

WooCommerce get order meta data

Although this code works, the WooCommerce team recommends using the wrapper function wc_get_order( $id ). This function loads the WC_Order_Factory, which creates the right order objects

$order = wc_get_order( $order_id );

This function can’t be used to create an order though. If you don’t pass an ID or if you pass an invalid ID, it will return false. Therefore, you need to use the wc_create_order function. Here’s a quick overview of what you can do with it:

$args = array(
  'status'      => 'wc-completed',
  'customer_id'  => null,
  'customer_note' => null,
  'parent'      => null,
  'created_via'  => null,
  'cart_hash'    => null,
  'order_id'    => 0,
);

$order = wc_create_order( $args );

 

Main Order Details

Now that we have the $order instance, let’s explore some common actions that we can perform with it via the methods provided by the WC_Order class:

$order_id = $order->get_id();

This method returns the post ID for the current order.

$status = $order->get_status();

The get_status method allows you to get the current order status, but without the wc- prefix. Therefore, an order with status wc-completed, for example, returns completed with this method.

You can set or update an order status with these methods:

// METHOD 1
$order->set_status( 'completed' );
$order->save();

 
// METHOD 2
$order->update_status( 'pending' );

The set_status and update_status methods have the same end result. The difference is that the set_status method is not immediate. Therefore, you still need to run $order->save();. The update_status fires the $order->save() method automatically.

In terms of usage, the set_status is better when you are editing multiple order attributes, while the update_status method is more suitable to places where you just need to update the status and nothing else.

$date_completed = $order->get_date_completed();

$date_created = $order->get_date_created();

$date_modified = $order->get_date_modified();

$date_paid = $order->get_date_paid();

The date methods can be used to get the different order dates for each of these changes in your order. They all return a WC_DateTime class. In addition to these you can manually set dates for these methods with the corresponding set_ methods.

$customer_id = $order->get_customer_id();

$customer = new WC_Customer( $customer_id );

$order_count = $customer->get_order_count();

The get_customer_id method returns the user ID for the customer associated to the current order. In our example we use the ID to get the customer data using the wc_customer class.

$total_spent = $order->get_total();

The get_total method returns the total amount of an order as a float, including taxes and shipping.

$refunds = $order->get_refunds();

The get_refunds method returns all refunds associated to an order as WC_Order objects

Order Products

The WooCommerce order contains product lines. Each line is an object in itself, the WC_Order_Item. This allows them to include the product that is added in this line, the product variation, quantity, taxes, and more.

Therefore, when we talk about editing or removing items from an order, we are actually editing the product lines.

Let’s go over each of the methods that we can use.

$items = $order->get_items($type);

This snippet loads all the items of the order. You can optionally pass a $type parameter defining the product type – the default value for it is ‘line_item’. This method returns either an array with all WC_Order_Item classes or false. Here is an example:

$items = array(
  $line_id => $wc_order_item_object,
  $line_id => $wc_order_item_object,
  $line_id => $wc_order_item_object
);

As you can see above, each line in a WooCommerce order is made of a class, that you can manipulate by accessing the WC_Order or even the WC_Order_Item directly.

$count = $order->get_item_count( $type );

This method returns the number of items for a certain type. Just like the previous method, by default you get the line_items. WooCommerce has these options for item types:

• line_items (default if $type is empty)
• fee_lines
• shipping_lines
• tax_lines
• coupon_lines

In addition, keep in mind that this method returns the item counts, not the line counts. Thus, if a customer buys 2 of the same t-shirt, it returns 2 not 1. Even though you have one product line you have 2 products (line_items), and that’s what you are getting when you run the get_item_count.

If you want to count the product lines, you can use something like:

$lines = count( $order->get_items( $type ) );

As we saw above, this method returns all the lines for an order of a specific type as an array. Therefore, if we use the count function, we get how many line_items this order has.

$result = $order->add_item( $wc_order_item_object );

This method allows you to add an item to your order. You need to pass a WC_Order_Item class to it and save afterwards.

If you want to add a product, maybe a simpler way to do it is using the add_product method.

$order->remove_item( $item_line_id );

This function allows you to remove an item, as long as you pass its ID. The same ID can be seen in the return array of our $order->get_items() method.

$order->remove_order_items( $type );

This method deletes all items of a specific type from an order. Therefore, you can remove all products by passing no arguments. And you can remove all shipping methods by calling $order->remove_order_items(‘shipping_lines’). The same goes for taxes, fees and coupons.

$has_free = $order->has_free_items();

This function returns whether or not an order has free products in it.

Billing and Shipping Details

In WooCommerce orders, billing and shipping details come from the user’s custom fields, but they are attached to orders as well. You can get and set specific billing/shipping details to an order.

Here’s a quick overview of all methods available. All methods have the billing and shipping version, so we add them together here.

The following methods return the address formatted as a single block with HTML code to correctly output the address:

$billing_address = $order->get_formatted_billing_address();

$shipping_address = $order->get_formatted_shipping_address();

And these methods return the shipping or billing details individually:

$billing_address_1 = $order->get_billing_address_1();

$billing_address_2 = $order->get_billing_address_2();

$billing_city = $order->get_billing_city();

$billing_company = $order->get_billing_company();

$billing_country = $order->get_billing_country();

$billing_email = $order->get_billing_email();

$billing_first_name = $order->get_billing_first_name();

$billing_last_name = $order->get_billing_last_name();

$billing_phone = $order->get_billing_phone();

$billing_postcode = $order->get_billing_postcode();

$billing_state = $order->get_billing_state();

 

$shipping_address_1 = $order->get_shipping_address_1();

$shipping_address_2 = $order->get_shipping_address_2();

$shipping_city = $order->get_shipping_city();

$shipping_company = $order->get_shipping_company();

$shipping_country = $order->get_shipping_country();

$shipping_email = $order->get_shipping_email();

$shipping_first_name = $order->get_shipping_first_name();

$shipping_last_name = $order->get_shipping_last_name();

$shipping_phone = $order->get_shipping_phone();

$shipping_postcode = $order->get_shipping_postcode();

$shipping_state = $order->get_shipping_state();

You can use the following method to retrieve the shipping method title:

$shipping_title = $order->get_shipping_method();

And this method returns an array containing all the WC_Order_Item_Shipping classes attached to this order:

$methods = $order->$order->get_shipping_methods()

 

Order amount and totals

In most cases, after you manipulate an WooCommerce order, you need to update the order lines for totals, shipping, taxes. You need to do this, because each of these elements are in their own lines and classes.

Here are the methods that you can use to manipulate the totals.

// retrieve order total
$price = $order->get_total();

// set order total
$order->set_total(100);
$order->save();

You can use these methods to get or set the total value of an order, including shipping and taxes. The set_total method doesn’t have autosave, so you still need to save the order.

The set_total method is not a reliable solution to edit order values though. It’s better to use other methods that actually change the order value, such as setting a discount or a fee. That’s because the order totals are recalculated in any case of changes in the order products and quantity. Therefore, the real value replaces your overwrite with new calculations.

The get_total_tax method returns the total paid in taxes for the current order. You can use the set_total_tax to overwrite it. Just like the previous methods, these edits will be overwritten in case a calculation happens.

$taxes = $order->get_total_tax();

$order->set_total_tax(15);

The following method returns an array with WC_Order_Tax_Item classes in the current order:

$taxes = $order->get_taxes();

And the get_subtotal method returns a float value for the order subtotals. The subtotal is the sum of the products only, excluding taxes, shipping, discounts and fees:

$subtotal = $order->get_subtotal();

This method returns the number value without currency formatting for the shipping totals:

$shipping_value = $order->get_shipping_total();

You can use get_shipping_tax() to get taxes added to the shipping fee:

$shipping_tax = $order->get_shipping_tax();

The following method returns a float value of the sum of all discounts in the current order. You can pass a boolean (default is true) for whether or not to exclude taxes from the discount sum:

$discount_value = $order->get_total_discount( $excl_taxes );

This method returns a number without currency formatting for the discount tax:

$discount_taxes = $order->get_discount_tax();

The get_fees() method retrieves an array of all WC_Order_Item_Fee items in the current order:

$fees_array = $order->get_fees();

You can use this method to get a number without currency formatting for the total amount refunded in this order:

$value_refunded = $order->get_total_refunded();

This allows you to get a float for all taxes refunds within the current WC_Order:

$tax_refunded = $order->get_total_tax_refunded();

Payment details

Now let’s explore how you can retrieve the payment methods and details in a WC_Order.

You can use get_payment_method() to get the payment method slug:

$slug_payment_method = $order->get_payment_method();

And you can use this method to get the transaction ID for a WC_Order payment:

$payment_id = $order->get_transaction_id();

 

Coupons usage

WooCommerce Orders allow multiple coupons. Therefore, you can manipulate them programmatically using the following methods.

This method returns the coupon codes used in the current WC_Order:

$coupon_codes = $order->get_coupon_codes();

You can use this method to apply a specific coupon code to a WC_order and recalculate totals. It returns true if the coupon code works and a WP_Error object in case there’s an error:

$result = $order->apply_coupon('CODE');

This method allows you to remove a specific coupon code from the WC_Order and recalculate the totals:

$order->remove_coupon('CODE');

 

Conclusion

Today we saw how you can use the WC_Order class and its methods. We saw different ways to read and manipulate data, including customer-related methods. We hope you enjoyed the different examples and comments on each method, and see you again next time!