Template Overrides

Template overrides are how you customize WooCommerce’s PHP templates without editing the plugin itself. Every front-end view (shop/archive, single product, cart, checkout, emails, My Account, etc.) is rendered by PHP files inside the WooCommerce plugin’s /templates/ directory. To change markup or move hooks, you copy a template file from the plugin into your theme or child theme under a mirrored path—typically /yourtheme/woocommerce/...—and edit your copy.

WooCommerce’s loader looks for a file in your child theme, then parent theme, and finally falls back to the plugin’s default. This lets you safely customize markup while still inheriting updates when you haven’t overridden a file. Each template declares an @version header; when WooCommerce updates a template, the Status → System Status screen flags your copy as outdated so you can diff and adjust.

Use overrides sparingly: they’re powerful but increase maintenance. Prefer action/filter hooks to inject or reposition content when possible. Also note that some areas (e.g., Cart & Checkout Blocks) are block-based; classic PHP overrides won’t affect those screens—you’ll use the Blocks extensibility APIs instead.

Where files live & how to map paths

  • Plugin source (don’t edit):
    wp-content/plugins/woocommerce/templates/...
  • Theme override (edit here):
    wp-content/themes/yourtheme/woocommerce/...
    (Use a child theme so parent updates don’t wipe your edits.)

Examples

  • templates/archive-product.php → yourtheme/woocommerce/archive-product.php
  • templates/single-product/add-to-cart/simple.php → yourtheme/woocommerce/single-product/add-to-cart/simple.php
  • templates/emails/customer-processing-order.php → yourtheme/woocommerce/emails/customer-processing-order.php

Load order: child theme → parent theme → plugin default.

Prefer hooks when you can (less maintenance)

You can often avoid copying files by adding/removing actions:

remove_action('woocommerce_single_product_summary', 'woocommerce_template_single_price', 10);
add_action('woocommerce_single_product_summary', function () {
    echo '<p class="price-with-note">';
    woocommerce_template_single_price();
    echo ' <small>(incl. VAT)</small></p>';
}, 10);

This keeps you aligned with upstream template changes.

When you really need an override

  • You must change structural markup that hooks can’t reach.
  • You’re replacing a chunk of HTML for design/system constraints.
  • You’re customizing email templates (headers, footers, tone).

Tips

  • Keep diffs minimal; don’t remove core hooks unless necessary.
  • Preserve escaping/translation functions and security nonces.
  • After WooCommerce updates, compare your copy with the new original.

Versioning & “outdated template” warnings

Each template starts with a docblock like:

<?php
/**
 * Single Product Price
 *
 * @version x.x.x
 */

If WooCommerce bumps that version, your overridden file may be flagged as outdated. Review changes upstream and update your copy accordingly. Failing to do so can break layouts or miss accessibility/security fixes.

Blocks vs classic templates

  • Classic templates (PHP in /templates/): overridden via theme copies.
  • Cart/Checkout/My Account Blocks: customized via block filters, slots, or block template parts—not by copying old PHP templates. If you still use the classic shortcode pages, then overrides apply.

Creating override-friendly plugin templates (for your own plugins)

If you ship templates in a custom plugin, load them via wc_get_template() so themes can override them:

wc_get_template(
  'my-plugin/box.php',                 // template name
  ['title' => 'Hello'],               // args
  'my-plugin/',                       // theme folder prefix: /yourtheme/my-plugin/
  plugin_dir_path(__FILE__).'templates/' // plugin fallback
);

Then a site can place yourtheme/my-plugin/box.php to override yours.

Common pitfalls

  • Editing plugin files directly → changes vanish on update.
  • Overriding too much → larger diffs, harder merges later.
  • Breaking hooks → removing core actions can disable features/emails.
  • No child theme → parent updates overwrite overrides.
  • Ignoring warnings → outdated copies cause subtle bugs.

Quick checklist

  • Use a child theme.
  • Try hooks first; override only when necessary.
  • Mirror the exact path under /woocommerce/.
  • Keep core hooks/escapes intact.
  • After updates, diff and refresh your overrides.
  • Test classic vs block pages depending on your setup.