I recently inherited a project for a high-volume apparel shop that was losing money on every European order. Tax was not being calculated for certain VAT-exempt zones. The previous developer, bless his heart, had hardcoded a massive switch statement straight into a modified core file to handle it. WooCommerce updated, the “fix” evaporated, and the client spent three days refunding tax by hand.
The cause ran deeper than sloppy code. The WooCommerce developer documentation gave no clear path for this at the time, and when the docs leave you without a route, you start guessing. Guessing in production is how sites break and clients stop trusting you.
The danger of guesswork in WooCommerce
I made a version of the same mistake early on. I needed a custom delivery date picker on the checkout, and instead of hunting down the right hook I decided to be clever and overrode the checkout/form-checkout.php template in my theme. It held up for about a month. Then WooCommerce shipped a major update to the checkout blocks and the fragments API, and my clever solution took the whole payment gateway with it. I spent a weekend reverting changes and doing it the right way.
That is why I am a stickler for official documentation. Guessing costs weekends, and reading costs an afternoon. If the docs are thin, we as a community need to fix them, which is what the upcoming December Office Hours are about. The agenda is the roadmap for 2026 and how to make the technical guides useful to the people who actually ship stores.
That is ordinary open-source collaboration, the kind the WordPress ecosystem runs on. It also pays off in a practical way: the better the docs, the fewer 3:00 AM emergency calls you get.
Doing it the right way with hooks
Instead of hacking core or overriding templates, go looking for the specific filter or action that solves your problem. If you need to add data to the checkout, use the hooks listed in the WooCommerce developer documentation. Adding a simple custom fee properly looks like this:
/**
* Add a custom processing fee to the WooCommerce cart.
* Always use hooks, never hack core.
*/
add_action( 'woocommerce_cart_calculate_fees', 'bbioon_add_custom_processing_fee', 10, 1 );
function bbioon_add_custom_processing_fee( $cart ) {
if ( is_admin() && ! defined( 'DOING_AJAX' ) ) {
return;
}
$fee_amount = 5.00; // This should ideally be a setting
$cart->add_fee( __( 'Processing Fee', 'bbioon-textdomain' ), $fee_amount, true );
}This approach survives upgrades. It does not care whether you switch themes or WooCommerce rewrites its template structure, because it goes through the established API.
Why the 2026 roadmap matters to you
The WooCommerce team is running a session on December 17 about how to prioritize documentation needs. That is the chance to point at the gaps. Maybe the REST API docs lost you, or the High-Performance Order Storage (HPOS) documentation skips the edge cases you keep hitting. Say so while someone is listening.
- Contribute: fix the typos you keep tripping over, or add a code snippet of your own.
- Feedback: tell the team which parts of the current documentation are confusing.
- Prioritize: help decide what lands on the 2026 roadmap.
This gets complicated quickly. If you would rather not spend your week debugging someone else’s mess, drop my team a line. We have probably seen it before.
What it comes down to
Do not be the dev who hardcodes logic into core. Be the one who reads the API and sends a fix back to the documentation everyone else relies on. See you on Slack on the 17th.
