Use the WooCommerce API to Customize Your Online Store

WooCommerce is the world’s most popular eCommerce platform. That’s partly because it’s built on the world’s most popular content management system (WordPress), and also partly because it’s free.

But it’s also because WooCommerce, like WordPress itself, is incredibly flexible. If you install WooCommerce on your site, not only can you use it to quickly set up and run an online store, but you can also customize it to run exactly the way you need it to.

The reason WooCommerce is so flexible is because of its API. It has a vast range of action and filter hooks, functions and classes that you can use to modify the way your store works and create a custom store that could work in a way very different to a standard, off-the-shelf WooCommerce store.

All this means that it’s possible for you to build a completely custom WooCommerce store, or to create and share or sell plugins that add to WooCommerce’s functionality, such as those available on CodeCanyon.

If you’re running an online store, chances are you’re using WooCommerce. It happens to be the world’s favorite ecommerce solution—and there are innumerable…

If you use a WooCommerce plugin to manage your online store, these 20 terrific shipping and pricing plugins can help make running your online store a whole…

WooCommerce is an excellent platform for selling digital and physical products. Adding an affiliate system is an excellent way to increase your reach around…

WordPress locator plugins are an easy way to give customers the ability to find your nearest store and the shortest way to get there. Find the five best…

In this post, I’m going to introduce you to that API. I’ll give you an overview of the way WooCommerce is structured, and I’ll outline the classes, hooks, and functions that let you customize your store.

I can’t possibly cover every aspect of the WooCommerce API in detail—if you need that, I recommend the WooCommerce documentation—but I can give you the information you need to understand what’s possible and to get started.

So let’s kick off by looking at how the WooCommerce plugin is structured.

The Structure of the WooCommerce Plugin

WooCommerce is a big plugin. All in all, it’s got hundreds of files in dozens of folders. All this could make things a bit daunting, but the good news is that it isn’t actually hard to understand or modify. Because WooCommerce is structured clearly and logically, and because it has comments throughout the code, it doesn’t take too much effort to work out what’s going on.

I often end up diving into the WooCommerce plugin source code when I’m customizing WooCommerce sites for clients.

At the top level, there are four files and five folders.

The files are fairly self-explanatory from their names, and standard to a lot of plugins: license.txt, readme.txt, uninstall.php, and woocommerce.php. The last of those files is the most important: woocommerce.php is the file that drives the plugin and calls all of the other files in those folders, whether directly or indirectly.

As well as those files, there are folders for different kinds of files:

assets, which contains subfolders for CSS, fonts, images, and scripts.

i18n, which includes internationalization files.

sample-data, which is empty by default but can be used for dummy data.

includes, which includes the classes, functions etc. that make WooCommerce work. Most of the files you’ll be looking at when customizing WooCommerce are in this folder.

templates, which includes the template files that output content on your site.

I’m not going to delve into the folder structure in detail, as that would take a long time. But if you’re planning on customizing WooCommerce, I recommend taking some time to look through the files and get to grips with how they’re structured.

Warning: If you’re planning on customizing WooCommerce, you should never directly edit the plugin itself. Instead, write your own plugin or add customizations to your theme.

WooCommerce Classes

I’m going to start with the classes in WooCommerce, as it’s a class that kicks everything off from the main plugin file.

Here are the contents of the woocommerce.php file:

<?php
/**
 * Plugin Name: WooCommerce
 * Plugin URI: https://woocommerce.com/
 * Description: An eCommerce toolkit that helps you sell anything. Beautifully.
 * Version: 3.6.4
 * Author: Automattic
 * Author URI: https://woocommerce.com
 * Text Domain: woocommerce
 * Domain Path: /i18n/languages/
 *
 * @package WooCommerce
 */

defined( 'ABSPATH' ) || exit;

// Define WC_PLUGIN_FILE.
if ( ! defined( 'WC_PLUGIN_FILE' ) ) {
    define( 'WC_PLUGIN_FILE', __FILE__ );   
}

// Include the main WooCommerce class.
if ( ! class_exists( 'WooCommerce' ) ) {
    include_once dirname( __FILE__ ) . '/includes/class-woocommerce.php';
}

/**
 * Returns the main instance of WC.
 *
 * @since  2.1
 * @return WooCommerce
 */

function WC() { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionNameInvalid
    return WooCommerce::instance();
}

// Global for backwards compatibility.
$GLOBALS['woocommerce'] = WC();

The key line here is this one:

if ( ! class_exists( 'WooCommerce' ) ) {
    include_once dirname( __FILE__ ) . '/includes/class-woocommerce.php';
}

This will call the WooCommerce class and start to run WooCommerce in your site.

You can find all of the classes in the /includes folder. For some reason, they aren’t in a subfolder called classes (which would make things so much more logical to my organized mind), but they’re directly inside this folder. One of these files is the class-woocommerce.php file, called from that opening file.

This isn’t the only file with classes; you’ll find the rest of them in the same /includes folder. You’ll also find a guide to all of the classes in the WooCommerce documentation.

You can use the classes in WooCommerce by creating your own classes in your plugins or theme, and then modifying or extending what those classes do. This is probably the most complex aspect of WooCommerce to customize, and you’ll need to be familiar with object-oriented programming to do it. If you want to do something simpler, you may find that working with functions or hooks is enough for your needs.

Which leads me to:

WooCommerce Functions

WooCommerce, like most plugins, uses a number of functions to run your store. You can override some of these functions or you can create alternative functions of your own to override or add to them, making sure you attach them to the relevant hooks in WooCommerce.

You can find details of functions in WooCommerce in the WooCommerce documentation, including details of how each function is fired. The functions themselves are all in the various functions files in the /includes folder, which are all named wc-xxx-functions.php, where the xxx tells you what kind of functions they are (e.g. wc-template-functions.php for functions in the template files, wc-cart-functions.php for functions relating to the cart).

If you want to modify a WooCommerce function in your plugin, you’ll need to unhook the WooCommerce function from the action or filter hook it’s attached to and then write your own function to replace it. So let’s imagine you wanted to modify the wc_setup_loop() function, which is attached to the woocommerce_before_shop_loop hook. You would write something like this:

function tutsplus_remove_wc_setup_loop() {
    remove action( ‘woocommerce_before_shop_loop’, ‘wc_setup_loop’ );
}
add_action( ‘init’, ‘tutsplus_remove_wc_setup_loop’ )

That would unhook the action from the WooCommerce plugin. You’d then write your own modified version of that wc_setup_loop() function and fire it like this:

function tutsplus_wc_setup_loop() {
    // contents of function here
}
add action( ‘woocommerce_before_shop_loop’, ‘tutsplus_wc_setup_loop’ );

Sometimes you’ll want to add a function in addition to the existing WooCommerce functions, in which case you’ll need to familiarize yourself with the action and filter hooks in WooCommerce. Hook your function to the relevant hook, and make sure you use priority to fire it before or after the existing ones.

Alternatively, some of the functions in WooCommerce are pluggable, meaning you can override them by writing your own function with the same name. We’ll come to that shortly.

WooCommerce Action and Filter Hooks

WooCommerce uses a large number of action and filter hooks to run its code, instead of coding functions directly into template files, for example.

This gives you much more flexibility and means you can customize WooCommerce’s output without having to create duplicates of the template files.

Let’s imagine you want to modify the code output on the single product page. This is contained in the content-single-product.php file, which is in the /templates folder.

Most of the code in this template file consists of hooks, to which functions are attached. The file contains commented-out text that tells you exactly which functions are attached to which hooks.

Here’s an example: the woocommerce_before_single_product_summary hook. In the template file, there is commented-out text listing the functions attached to this hook, and then the hook itself is fired using do_action().

<?php
/**
* Hook: woocommerce_before_single_product_summary.
*
* @hooked woocommerce_show_product_sale_flash - 10
* @hooked woocommerce_show_product_images - 20
*/
do_action( 'woocommerce_before_single_product_summary' );
?>

You then need to find the functions hooked to this action hook if you want to modify or override them. You can find a full list of these functions in the WooCommerce documentation.

You’ll find the code for the functions in a range of files inside the /includes folder. The functions tend to be in files that are named logically. So, for example, the woocommerce_show_product_images() function in the example code above, hooked to the woocommerce_before_single_product_summary hook in the content-single-product.php file, is in the wc-template-functions.php file, which contains functions directly attached to hooks in the template files.

As you can see, getting to grips with the WooCommerce API can mean a bit of exploration through the file structure, but once you’ve familiarized yourself with this, you’ll find that the structure is pretty logical and that most of the time, it’s easy to pinpoint where a piece of code is. If you can’t find it, simply search for it in the WooCommerce documentation, and that will tell you where to find it.

The woocommerce_show_product_images() function mentioned above is pluggable, which means you can override it in your own plugin or in your theme.

if ( ! function_exists( 'woocommerce_show_product_images' ) ) {
    /**
    * Output the product image before the single product summary.
    */
    function woocommerce_show_product_images() {
        wc_get_template( 'single-product/product-image.php' );

    }
}

Simply write another function with the same name. When WordPress comes across the pluggable function in WooCommerce, it will check if there’s another function with the same name, and because there is, it won’t run the WooCommerce version of the function: instead it’ll run yours. Make sure you give your function exactly the same name.

WooCommerce Template Files

Much of the customization my clients ask me to do for WooCommerce relates to the output of the template files. WooCommerce makes it easy to alter the code output by each template file, and so add your own custom code. This could be a modified version of the code already in WooCommerce (as we’ve seen above), or it could be something completely new.

If you want to radically customize a WooCommerce template file, you can create a new version of that file in your theme, and WordPress will use that file instead of the file in the plugin.

So if you wanted to override the content-single-product.php file, you would create a /woocommerce folder in your theme, and then inside that you would create a file called content-single-product.php. If the template file you wanted to override is further down in the WooCommerce file structure, you need to mirror that in your theme. So if you wanted to override the woocommerce/templates/emails/admin-cancelled-order.php file, you would create a file at mytheme/woocommerce/emails/admin-cancelled-order.php.

The easiest way to create the file is to create a duplicate of the original file from WooCommerce and then edit that, so you can be sure the file will work correctly.

Alternatively, if you only want to modify one of the functions called in that template file, you would create a new function and then remove the existing one from the relevant action hook, as detailed above. Or if the function is pluggable, you just write a new version!

Writing Your Own WooCommerce Plugin

Now that you understand the WooCommerce classes, hooks, functions and template files and how to customize them, it’s time to write your own WooCommerce plugin.

If all you want to do is override a template file from WooCommerce, you won’t need to write a plugin: simply add the file to your theme instead. But if you want to add functional customizations, you should do it via a plugin.

The WooCommerce Plugin Developer Handbook provides guidance on how to go about doing this correctly. It includes advice on checking if WooCommerce is active, on text domains, on file naming, and more.

Before creating your plugin, you should run through the tips in the handbook and make sure you’re coding your plugin correctly.

The WooCommerce API Gives You Endless Flexibility

Understanding the WooCommerce API will help you to customize your WooCommerce store and create plugins that you can use to enhance the functionality of various stores or that other people can use to do so.

It pays to take some time to explore the WooCommerce file structure and the documentation to get to grips with how this complex but well-structured and logical plugin operates, so you can get the most from it. Happy customizing!