Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 39 ยท Hooks, Templates and Settings

The WooCommerce Hook Map

Learn how WooCommerce names its hooks, where to find them, the product, cart, checkout and order hooks you will use, and how to remove core callbacks safely.

Hooks are the front door of every WooCommerce extension. The plugin fires hundreds of actions and filters, and good extension development is mostly knowing which one to attach to, at which priority, and how to detach a built-in callback without breaking the page. If you have not used hooks before, read Actions and Filters and Priorities and Removing Callbacks first; this lesson applies those ideas to a shop.

You will learn the naming patterns, how to locate the hook you need in a template or class, the groups of hooks around products, the cart, checkout and orders, and the rules for removing a core callback. Then you build a small hook dispatcher to see priorities and removal working. Real WooCommerce code stays read-only here; the dispatcher is a plain-PHP stand-in for WordPress's hook system.

How WooCommerce names its hooks

Almost every WooCommerce hook starts with woocommerce_. The rest follows a few predictable patterns:

Pattern Meaning Example
woocommerce_before_<thing> / woocommerce_after_<thing> Output before or after a block of markup (actions) woocommerce_before_cart, woocommerce_after_single_product
woocommerce_<thing>_<verb> Something happened or is about to woocommerce_add_to_cart, woocommerce_payment_complete
woocommerce_<thing>_get_<field> style filters Change a value returned by a getter woocommerce_product_get_price
woocommerce_<noun>_classes, _args, _fields Change a configuration array woocommerce_checkout_fields
woocommerce_order_status_<status> Dynamic: the status is part of the name woocommerce_order_status_completed

Actions run code (usually printing markup or reacting to an event) and return nothing. Filters receive a value, may change it, and must return it. A very common beginner bug is a filter callback that forgets to return, which turns the value into null.

Dynamic names are worth recognizing. woocommerce_order_status_{$status} and woocommerce_order_status_{$from}_to_{$to} fire for specific order status changes, and woocommerce_settings_{$id} fires for a settings tab. When you search the source for them you will see a variable inside the string.

Finding the hook you need

There are three reliable ways, listed from fastest to most thorough.

  1. Read the template. Product, cart and checkout markup lives in template files, and the hooks are visible in them as do_action( ... ) calls. Open the relevant file under the plugin's templates/ folder (for example the single-product summary template) and look for the nearest hook to where you want your output.
  2. Search the plugin source for do_action( and apply_filters( plus a keyword. Searching for the function that produces the value you want to change (say, the one that formats the price) leads you to its filters.
  3. Print the hook as it runs. On a development site, the all hook lets you log every hook name for one request. Query Monitor's Hooks & Actions panel does the same without code, which is why it is on the tooling list in Development Environment and Tooling.

A temporary logger, for development only (read-only here):

PHP
<?php
// Development only. Logs every hook that starts with "woocommerce_single_product".
add_action( 'all', function ( string $hook ) {
    if ( str_starts_with( $hook, 'woocommerce_single_product' ) ) {
        error_log( 'hook: ' . $hook );
    }
} );

Remove it before shipping. The all hook runs for every single action and filter, so it is slow.

The hooks you will use most

Product pages

On a classic single-product page, the summary column is assembled from callbacks hooked to woocommerce_single_product_summary. The default priorities, in order, are:

Priority What WooCommerce prints there
5 Title (woocommerce_template_single_title)
10 Rating, then price
20 Short description (excerpt)
30 Add to cart form
40 Meta (SKU, categories, tags)
50 Sharing area (empty by default)

Because each of those is just a callback on the hook, you can insert your own output between two of them by choosing a priority between their numbers (25 puts yours after the excerpt and before the add-to-cart form). Related hooks include woocommerce_before_single_product, woocommerce_before_add_to_cart_button and woocommerce_after_single_product_summary, which carries the product data tabs, upsells and related products on their own priorities.

Archive pages (shop and category listings) follow the same idea: woocommerce_before_shop_loop, then per product woocommerce_before_shop_loop_item, woocommerce_shop_loop_item_title, woocommerce_after_shop_loop_item_title (rating and price) and woocommerce_after_shop_loop_item (the add-to-cart button).

Cart

  • woocommerce_add_to_cart_validation is a filter: return false (and add a notice) to block an item from being added.
  • woocommerce_add_to_cart is an action that fires after an item was added.
  • woocommerce_before_calculate_totals and woocommerce_cart_calculate_fees are where prices and fees are changed; see Dynamic Pricing, Fees and Discounts.
  • woocommerce_before_cart and woocommerce_cart_collaterals print around the classic cart page.

Checkout and orders

  • woocommerce_before_checkout_form and woocommerce_checkout_before_customer_details for markup in the classic checkout.
  • woocommerce_checkout_process for validation, woocommerce_checkout_create_order to copy data onto the order object before it is saved, and woocommerce_checkout_order_processed after.
  • woocommerce_payment_complete, woocommerce_order_status_changed and the dynamic woocommerce_order_status_<status> family for reacting to payments and status moves. The meaning of each status is in Order Statuses and the Order Lifecycle.
  • woocommerce_thankyou prints on the order received page.

The block-based cart and checkout do not run the classic markup hooks; they have their own extension points, covered in Cart and Checkout Blocks Extensibility. Hooks that fire from PHP logic, such as order-status and payment hooks, run in both.

flowchart LR
    A["Add to cart"] -->|"filter: ..._add_to_cart_validation"| B{"Valid?"}
    B -- yes --> C["Cart updated"]
    C -->|"action: woocommerce_add_to_cart"| D["Totals calculated"]
    D -->|"before_calculate_totals<br/>cart_calculate_fees"| E["Checkout"]
    E -->|"checkout_process"| F["Order created"]
    F -->|"order_status_changed"| G["Paid, processing, completed"]

A simplified path through the shop with the hook types you meet along it.

Removing and replacing core callbacks safely

To change what WooCommerce prints, you often remove its callback and add your own. remove_action only works if you match three things exactly: the hook name, the callback, and the priority.

PHP
<?php
// Hide the product meta (SKU, categories) on single product pages.
add_action( 'init', function () {
    remove_action( 'woocommerce_single_product_summary', 'woocommerce_template_single_meta', 40 );
} );

// Move the price below the short description instead of deleting it.
add_action( 'init', function () {
    remove_action( 'woocommerce_single_product_summary', 'woocommerce_template_single_price', 10 );
    add_action( 'woocommerce_single_product_summary', 'woocommerce_template_single_price', 25 );
} );

The rules behind that snippet:

  • Timing. You can only remove a callback after it was added. WooCommerce registers its template hooks when it loads, so removing inside init (or later) works; removing at the top level of your plugin file can run too early and do nothing, silently.
  • Priority must match. Removing priority 10 when the callback was added at 40 removes nothing and reports no error. If it does not work, print the registered callbacks: var_dump( $GLOBALS['wp_filter']['woocommerce_single_product_summary'] ); on a development site shows exact names and priorities.
  • Object callbacks. If a plugin added [ $object, 'method' ] or a closure, you cannot remove it by name. Prefer hooks that the other plugin documents, or use a plugin's own instance accessor to get the object. Anonymous functions cannot be removed unless you kept a reference.
  • Prefer a filter over removal. If a hook offers a value to change (for example the list of product tabs), change it rather than deleting the callback; it survives more WooCommerce updates.
  • A later version can move a hook. Templates are refactored over time. After a major update, check that your removals still do what you expect.

Document your own hooks

Extensions should expose hooks just as WooCommerce does, and the habit is simple: prefix with your plugin slug, document with a DocBlock, and pass the context object that callers need.

PHP
<?php
/**
 * Filters the handling days shown on the product page.
 *
 * @param int         $days    Business days. Default 2.
 * @param WC_Product  $product The product being displayed.
 */
$days = (int) apply_filters( 'acme_sn_handling_days', 2, $product );

Read more on designing your own in Creating Your Own Hooks.

Runnable stand-in: a hook dispatcher

The first stand-in is a tiny version of WordPress's hook system with priorities and removal. It prints a product "summary" the way woocommerce_single_product_summary assembles one, then shows a removal that works and one that silently fails because the priority is wrong.

PHP Priorities, insertion and removal

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

In WordPress, add_action also accepts a number of accepted arguments, and callbacks for the same priority run in the order they were added. The stand-in keeps only the pieces that show ordering and removal.

Runnable stand-in: build your own hook index

Documentation habits scale only if you can list the hooks your code exposes. The second stand-in scans PHP source text and reports every do_action and apply_filters call with its kind and name, which is how many teams build a hook reference. It reads source from a string so it can run anywhere.

PHP Extract hook names from source code

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

A real index would use PHP's tokenizer or a documentation tool to handle every syntax, but even this simple scan is enough to notice a hook that has no DocBlock.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A filter callback computes a new value but forgets the return statement. What happens?

    A filter hands its return value to the next callback and finally to the caller. A missing return gives null, which often breaks prices and markup.
  2. 2. You call remove_action( 'woocommerce_single_product_summary', 'woocommerce_template_single_meta', 10 ) but the meta still shows. What is the most likely cause?

    Core adds that callback at priority 40. A removal with a different priority finds nothing and fails silently.
  3. 3. Where is it safe to call remove_action for a core WooCommerce template callback?

    You can remove a callback only after it has been added. Hooking your removal onto init (or later) makes sure core had its turn first.
  4. 4. Which priority places your output between the short description (20) and the add-to-cart form (30) on the single product summary?

    Callbacks run from the lowest priority number to the highest, so 25 falls between 20 and 30.

Summary

  • WooCommerce hook names follow patterns: before_/after_ for markup, event verbs for actions, getter-style names for filters, and dynamic names that contain a status or id.
  • Find hooks by reading templates, searching the source for do_action and apply_filters, or watching them with Query Monitor.
  • The single product summary is a list of callbacks at priorities 5, 10, 20, 30, 40 and 50, so your own priority decides where your output lands.
  • remove_action needs the same hook, callback and priority, and must run after the callback was added.
  • Prefer documented filters over removing callbacks, and document your own hooks with prefixes and DocBlocks.

Next: Template Overrides and Plugin Templates