WooCommerce is one of the most popular eCommerce platforms on WordPress, offering a comprehensive set of features for selling products and managing orders. As a developer, interacting with the WooCommerce Order Object enables you to create powerful custom functionalities within your WordPress plugins. Whether it’s customizing admin data views, adding metadata, or sending custom emails based on order status, understanding how to access and manipulate orders programmatically is essential for plugin development.
This step-by-step tutorial walks you through the process of accessing the WooCommerce Order Object and modifying its data safely and effectively within your custom plugins. Follow along to unlock the full potential of WooCommerce from a development standpoint.
Table of Contents
1. Hook into WooCommerce with a Plugin
To get started, you’ll need a plugin where this functionality will reside. If you don’t already have one set up:
- Create a new folder inside the
wp-content/plugins/directory, for example, custom-order-handler. - Create a main plugin file, e.g.,
custom-order-handler.php, with the following plugin header:
/*
Plugin Name: Custom Order Handler
Description: A plugin to interact with WooCommerce orders.
Version: 1.0
Author: Your Name
*/
Ensure the plugin is activated via the WordPress admin panel.
2. Access the Order Object
Accessing order data depends on the context in which you are operating—in the admin panel, in response to an event hook, or on the frontend. Here’s a reliable way to load the WC_Order object using the order ID:
$order_id = 123; // Replace with a valid order ID
$order = wc_get_order( $order_id );
The wc_get_order() function returns a WC_Order object which gives you access to a wide array of order methods and properties. For example, to get the customer’s billing email:
$email = $order->get_billing_email();
3. Example: Triggering on Order Completion
Let’s create a function that triggers when an order is marked as completed. WooCommerce offers numerous hooks, and for this case, we’ll use the woocommerce_order_status_completed action:
add_action( 'woocommerce_order_status_completed', 'my_custom_order_completed_action' );
function my_custom_order_completed_action( $order_id ) {
$order = wc_get_order( $order_id );
// Example: Log some details
error_log( 'Order #' . $order->get_id() . ' has been completed.' );
error_log( 'Customer email: ' . $order->get_billing_email() );
}
This action is automatically fired by WooCommerce, providing a safe and appropriate place to interact with the order.
4. Retrieving Order Details
The WC_Order object offers a robust structure and large number of methods to access key order information. Below are some commonly used methods:
- Billing Name:
$order->get_billing_first_name() - Shipping City:
$order->get_shipping_city() - Total Amount:
$order->get_total() - Payment Method:
$order->get_payment_method()
Each method returns sanitized data directly from the order’s metadata or post meta. You can use these values in functions such as generating custom emails or redirecting logic based on payment types.
5. Looping Through Order Items
If you need to retrieve detailed information about products purchased in an order, you can loop through the line items:
foreach ( $order->get_items() as $item_id => $item ) {
$product = $item->get_product(); // WC_Product object
$product_name = $item->get_name();
$quantity = $item->get_quantity();
$total = $item->get_total();
// Do something with the product info
}
This can be useful for analytics, inventory management plugins, or custom shipping labels.
6. Modifying Order Metadata
WooCommerce allows developers to store and retrieve custom fields on orders using metadata APIs. This is helpful if you want to store custom tracking numbers, customer preferences, or any other bespoke data:
// Adding metadata
$order->update_meta_data( '_custom_tracking_number', 'TRK12345678' );
$order->save();
// Retrieving metadata
$tracking = $order->get_meta( '_custom_tracking_number' );
Remember to use an underscore prefix for private meta fields to prevent them from showing in the WordPress custom fields interface.
7. Updating Order Status
You can programmatically update the order status using the update_status() method:
$order->update_status( 'completed', 'Order completed by custom plugin.', true );
The parameters include the new status, an optional note, and a flag to notify the customer. This is particularly useful for integrations with external systems like CRMs or fulfillment APIs.
8. Sending Custom Emails Based on Orders
You might want to send a custom email when a customer purchases a specific product or enters a certain billing state. Here’s how to integrate such logic:
add_action( 'woocommerce_order_status_processing', 'send_custom_email_on_order' );
function send_custom_email_on_order( $order_id ) {
$order = wc_get_order( $order_id );
foreach ( $order->get_items() as $item ) {
if ( $item->get_product_id() == 456 ) {
wp_mail(
$order->get_billing_email(),
'Thank you for ordering our special product!',
'Custom email message here.'
);
break;
}
}
}
WooCommerce filters and actions allow you to integrate custom email templates, use HTML content, and even hook into transactional email sending functionality for better control.
9. Best Practices
- Always validate order IDs before calling
wc_get_order(). - Use WordPress and WooCommerce hooks when modifying behavior to ensure compatibility with future updates.
- Sanitize and escape all custom meta fields to prevent security vulnerabilities.
- Optimize queries by avoiding unnecessary calls to
wc_get_order()inside loops. Cache order objects if needed.
10. Debugging and Logging
While developing plugins that modify WooCommerce orders, constant debugging is necessary. Use simple tools like error_log() to review what your hook is doing. For longer-term logging, consider using WordPress loggers like WC_Logger:
$logger = wc_get_logger();
$logger->info( 'My plugin processed order: ' . $order_id, array( 'source' => 'custom-order-plugin' ) );
Conclusion
Interacting with WooCommerce order data allows you to build flexible, high-performing, and smart WordPress plugins tailored to your business or your client’s store. By understanding how to retrieve, modify, and extend the WC_Order object safely, you unlock potential that goes far beyond the standard WooCommerce setup.
Keep in mind the best practices for plugin development such as using hooks, writing secure code, and adhering to WordPress standards to ensure that your changes are forward-compatible and secure.
Whether you’re building automation tools, third-party integrations, or custom administrative features, this tutorial gives you the groundwork to navigate WooCommerce order objects confidently and professionally.