How to build a WooCommerce plugin: structure, hooks and security
A practical walkthrough of how a well-built WooCommerce plugin is organised, which hooks to use, and the security and compatibility checks that matter before release.
Most WooCommerce plugins start small: a discount rule, a custom field, a new shipping option. The ones that survive years of WooCommerce and WordPress updates share a few habits. This is the structure and set of checks I rely on when building plugins, including the ones on my GitHub.
Start with a clean plugin skeleton
A WooCommerce plugin is a WordPress plugin that depends on WooCommerce. Keep the entry file small and put real code in classes.
- A main file with the plugin header, a version constant and a bootstrap that loads everything else.
- A check that WooCommerce is active before any of your code runs, with an admin notice if it is not.
- Classes in their own files, loaded through Composer autoloading or a simple autoloader, organised by responsibility: admin, frontend, data, integrations.
- Assets (CSS and JavaScript) in their own folder, enqueued only on the pages that need them.
- A text domain and translation-ready strings from the first commit, so internationalisation is not a rewrite later.
Use hooks, never core edits
WooCommerce is built around actions and filters. A filter changes a value as it passes through, such as a price, a label or a list of fields. An action runs your code at a defined moment, such as when an order status changes or before the cart totals are calculated.
- Pick the narrowest hook that does the job, and read the source to confirm the arguments it receives.
- Keep hook callbacks small. They should call a method on a class that does the work and can be tested.
- Mind priority and order. When several plugins filter the same value, the priority number decides who goes last.
- Never edit WooCommerce core or a theme to change behaviour. Your change will be lost on the next update.
Store data the right way
Use WooCommerce's own functions and data objects, such as the product and order classes, rather than reading and writing database tables directly. For your own data, choose the storage to match its shape.
- Settings go in options, with a settings page built on the WordPress Settings API.
- Small facts about a product or order go in metadata, using the object's methods.
- Data with its own structure, volume or relationships, such as bookings or rule sets, belongs in custom tables created on activation with a versioned upgrade routine.
Be compatible with HPOS and the block checkout
Two changes in recent WooCommerce versions affect most plugins. High-Performance Order Storage moves orders out of the posts tables, so plugins must read and write orders through WooCommerce's order functions and declare their compatibility. The block-based cart and checkout render differently from the classic shortcodes, so a plugin that adds fields or logic to checkout needs to support both or say clearly which it supports. Test on a store with HPOS enabled and with the block checkout before you release.
Security is not optional
A plugin runs inside a store that handles customer data and payments, so security work is part of the build, not a finishing touch.
- Check capabilities. Use current_user_can before any privileged action, and never rely on a hidden button as protection.
- Verify nonces on every form submission and AJAX request, and check the capability as well.
- Sanitise input as it enters, with the sanitising function that matches the data type.
- Escape output as it leaves, with the escaping function that matches the context: HTML, attribute, URL or JavaScript.
- Use $wpdb->prepare for every custom query, and never build SQL by concatenating request data.
- Do not expose sensitive data through AJAX or REST endpoints without a permission callback.
Performance habits
- Load scripts and styles only where they are used, not on every page.
- Cache expensive results with transients or the object cache, and invalidate them when the underlying data changes.
- Avoid queries inside loops, and avoid loading all products or orders into memory.
- Index custom table columns that you filter or join on.
- Defer slow work, such as calling an external API, to a background job instead of the page request. WooCommerce ships with Action Scheduler for this.
Test before you release
- Test with a clean WooCommerce install and with the plugins your customers commonly run: a page builder, a caching plugin, a payment gateway.
- Test the unhappy paths: empty cart, expired session, out-of-stock items, failed payment, a very large order.
- Turn on WP_DEBUG and fix every notice and deprecation.
- Run PHP_CodeSniffer with the WordPress coding standards to catch security and style problems early.
- Write automated tests for the logic that costs money when it is wrong, such as pricing and stock.
Where to see real examples
I build and maintain WooCommerce plugins, including NivoSearch, Hexa Grid and DiscountKit, and the code is public on my GitHub profile. If you need a custom plugin, or an existing one reviewed or repaired, describe the problem and I will propose an approach.
Frequently asked questions
How do I start building a WooCommerce plugin?
Create a standard WordPress plugin with a main file and plugin header, check that WooCommerce is active before running any code, and attach your logic to WooCommerce actions and filters instead of editing core files or the theme.
Which WooCommerce hooks should a plugin use?
Use the narrowest hook that does the job. Filters change a value, such as a price or a label, and actions run your code at a point in the flow, such as when an order status changes. Check the WooCommerce documentation or source for the exact hook name and arguments.
What is HPOS and does my plugin need to support it?
High-Performance Order Storage keeps orders in dedicated database tables instead of the WordPress posts tables. Plugins that touch orders should use WooCommerce's order functions and declare HPOS compatibility, because direct post queries for orders can break.
How do I keep a WooCommerce plugin secure?
Check permissions with capability checks, verify nonces on every form and AJAX request, sanitise all input, escape all output and use prepared statements for any custom database query.