Core Concepts

WooCommerce is built upon (and operates within) the WordPress platform. Because of this, building an extension for WooCommerce is similar to building plugins for WordPress, but WooCommerce provides a subset of tools and features that developers can use and extend to build any type of eCommerce solution merchants need.

Actions and Filters

At a fundamental level, WooCommerce extensions modify the behavior of WooCommerce by injecting custom functionality using WordPress hooks. If you’re unfamiliar with the concept of WordPress hooks, you can read about them in this article from the WordPress Plugin Handbook. To paraphrase:

  • Actions let developers add data or change how WordPress handles a given request.
  • Filters let developers modify data and pass it back to WordPress for further processing.

There are a number of hooks built in to WordPress Core, but because the platform lets developers create their own hooks, there are also a number of specialized WordPress hooks that WooCommerce introduces. When you build an extension, in the majority of cases, hooking into these WordPress and WooCommerce actions and filters is how you will knit your code into a merchant’s user experience.

If you’re curious about what hooks and filters are available in WordPress and WooCommerce, you can read through these reference docs:

Critical Flows

There are hundreds of available actions and filters, so when you’re building an extension, it can be challenging to know exactly which ones you need to use to augment a merchant’s store. One of the best ways to start is to consider the most common functions that happen in a store. We call these Critical Flows, and they include all the most common actions that merchants and customers tend to take when interacting with a WooCommerce store.

While critical flows don’t represent the entirety of WooCommerce’s extensibility, they account for a majority of typical activity in a store. You can use them as a starting point to examine available extensibility hooks that directly affect the interaction customers and merchants are having with a store. These critical flows are also a valuable point of reference when crafting tests for your extension.

Best Practices for Extensions

While the extensibility of the WordPress platform makes it possible to build WooCommerce extensions in a number of different ways, there are some general best practices that we recommend to help ensure merchants have a seamless experience when augmenting the platform with third-party extensions. In general, here are a few things all extensions should have:

  • Basic plugin lifecycle management with proper namespacing
  • Guided merchant onboarding using set-up steps and notices
  • First-class navigation via the immersive WooCommerce menu
  • An administrative experience for merchants that uses modern React-powered components
  • Proper clean-up upon deactivation and uninstallation

Curated Extensibility

For extensions that are, themselves, extensible, we recommend developers adhere to what we refer to as curated extensibility. In practical terms, this means:

  • Favor explicit APIs and interfaces for integrations instead of hooks. Among other benefits, this helps abstract the implementation details away from consumers to help your code remain flexible over time.
  • When hooks must be used, keep the surface area of impact as small as possible. Minimize the number of arguments exposed to hooks. This helps prevent unexpected side effects from extensions that might mutate data without your extension knowing. It may also be helpful to refer to our guidance concerning the addition and placement of hooks.
  • Encapsulate and protect against catastrophic errors. There are a number of techniques that you can use, but the objective is to design your extensibility points in a way that if anything extending your code breaks, the breakage is isolated as much as possible.

Further Reading

The articles in this guide are designed to help you build extensions that adhere to these best practices. Because the WooCommerce platform is comprised of a number of different projects that are under constant development, however, it is possible this guide may not always reflect the newest features or functionality. We aim to curate these articles frequently, but for the most up-to-date documentation, we recommend developers read through the developer documentation that is maintained alongside these projects:

Back: Table of Contents

Next: Getting Started