Custom WooCommerce Email Template: The Complete Code-First Guide

A custom WooCommerce email template is a PHP file that overrides WooCommerce’s default transactional email output — giving you full control over design, content, and structure without touching core files or paying for a plugin. Copy the template, edit it in your child theme, and you own it.

What Is a Custom WooCommerce Email Template?

WooCommerce ships with a full set of transactional email templates — order confirmation, shipping notice, refund notification, and more. A custom WooCommerce email template is what you get when you copy one of those files into your own theme and take control of it. You write the HTML, you define the structure, you own the output.

This is not about clicking a color picker inside a settings panel. This is about PHP files, template hierarchy, and real code ownership. Every serious store owner building for the long term should understand how a custom WooCommerce email template actually works under the hood.

WooCommerce powers over 36% of all online stores worldwide. Most of them are sending generic, out-of-the-box order emails that look like every other store. A custom WooCommerce email template is how you stop looking like everyone else.

How the WooCommerce Email System Works

WooCommerce manages all transactional emails through a class-based system built on top of WC_Email. Each email type — new order, processing order, completed order — is its own class registered in the WooCommerce core. These classes pull in PHP template files to render the actual HTML.

Those template files live at plugins/woocommerce/templates/emails/. WooCommerce checks your theme first before loading from that path — that’s the override system. If it finds the same file in your-theme/woocommerce/emails/, it uses yours. You get full control without modifying core.

On top of templates, WooCommerce fires a set of action hooks at specific points during email rendering. woocommerce_email_header, woocommerce_email_footer, woocommerce_email_order_details, woocommerce_email_before_order_table, and woocommerce_email_after_order_table are the heavy hitters. Learn to use those hooks and you can inject content into any custom WooCommerce email template without touching a template file at all. Check the WooCommerce template structure docs for the full hierarchy.

The Template Hierarchy in Plain English

WooCommerce looks for templates in this order: your child theme first, your parent theme second, the WooCommerce plugin itself last. That means a custom WooCommerce email template placed correctly in your child theme will always win. Always. Set up a child theme first if you haven’t already — editing a parent theme directly is a beginner mistake that wipes your work on every update.

Each email also has a plain text version alongside the HTML version. If you’re building a custom WooCommerce email template for HTML, build the plain text version too. Some inboxes and corporate email clients strip HTML completely.

Override a Custom WooCommerce Email Template in Your Theme

This is the most common approach, and it’s the right first move. Navigate to wp-content/plugins/woocommerce/templates/emails/ and find the template file you want to customize. Order confirmation is email-order-details.php. Customer new order is customer-processing-order.php. Copy the file you need.

Now paste it into wp-content/themes/your-child-theme/woocommerce/emails/. You may need to create the woocommerce/emails/ folder structure manually. Once the file is in place, WooCommerce will use your version automatically — no registration, no configuration needed.

Open your copied file and start editing. You’re working with standard PHP and HTML. You can restructure the layout, add custom variables, pull in order meta, or completely redesign the markup. This is your custom WooCommerce email template now — treat it accordingly.

Available Variables Inside Email Templates

Inside most WooCommerce email template files, you have access to $order (the WC_Order object), $email_heading, $sent_to_admin, and $plain_text. The $order object is gold — you can pull billing data, line items, totals, meta fields, and customer notes directly from it.

If you’ve added WooCommerce custom fields to your checkout or products, you can surface that data here too. Custom order meta shows up beautifully in a well-crafted custom WooCommerce email template when you call $order->get_meta('your_field_key').

Customize WooCommerce Email Styles Without Editing Templates

WooCommerce has a built-in way to change email colors and logo through WooCommerce > Settings > Emails. It handles base color, background color, body text color, and header image. For quick branding alignment, use it. For real control, go deeper.

The CSS for WooCommerce emails is generated by email-styles.php, located in plugins/woocommerce/templates/emails/. Copy it to your child theme at woocommerce/emails/email-styles.php and you control every rule. This is still a valid custom WooCommerce email template override — same hierarchy, same rules.

Keep in mind that email CSS is not browser CSS. Inline styles rule email clients. Gmail strips <style> blocks. Write styles that can survive inlining or use the woocommerce_email_styles filter to inject additional CSS that WooCommerce inlines automatically. Learn more about adding custom CSS in WordPress to understand when each approach applies.

Add Custom Content to WooCommerce Emails Using Hooks

You don’t always need to touch a template file. If you want to add a block of content above or below the order table, hooks are the cleanest solution. No file copying, no merge conflicts on updates, no drift from WooCommerce core.

Here’s a real example. Add a custom message below the order table in every customer email:

add_action( 'woocommerce_email_after_order_table', 'aiordienow_custom_email_message', 10, 4 );
function aiordienow_custom_email_message( $order, $sent_to_admin, $plain_text, $email ) {
    if ( $plain_text ) return;
    echo '<p style="color: #333; font-size: 14px;">Thanks for sailing with us. Questions? Reply to this email.</p>';
}

The four hook arguments give you everything — the order object, whether it’s going to an admin, whether it’s plain text, and the email object itself. You can conditionally fire logic based on email type using $email->id. A targeted custom WooCommerce email template experience, built entirely through hooks.

The woocommerce_email_before_order_table hook fires in the same way. Use woocommerce_email_header and woocommerce_email_footer hooks to wrap your entire email in custom structure if you’re building a fully branded experience. Pair this with our WooCommerce Hooks and Filters Guide and you’ll have the full picture. The WordPress Plugin Handbook on hooks covers the underlying system in depth.

Build a Custom WooCommerce Email Class From Scratch

Sometimes you need an entirely new email type — not just a restyled version of an existing one. Maybe you want to send a custom notification when an order hits a specific status, or fire an email based on a product attribute. This is where you extend WC_Email and build your own class.

Create the Email Class

Create a new PHP file in your child theme’s includes/ folder — something like class-aiordienow-custom-email.php. Extend WC_Email and define your class properties in the constructor:

if ( ! defined( 'ABSPATH' ) ) exit;

class AiorDieNow_Custom_Email extends WC_Email {

    public function __construct() {
        $this->id             = 'aiordienow_custom_order_email';
        $this->title          = 'Custom Pirate Order Email';
        $this->description    = 'Sent when a pirate order reaches battle-ready status.';
        $this->heading        = 'Your Order Is Battle-Ready';
        $this->subject        = 'Your Order Is Ready, Captain';
        $this->template_html  = 'emails/aiordienow-custom-email.php';
        $this->template_plain = 'emails/plain/aiordienow-custom-email.php';
        $this->template_base  = get_stylesheet_directory() . '/woocommerce/';

        parent::__construct();
    }

    public function trigger( $order_id ) {
        $this->object = wc_get_order( $order_id );
        $this->recipient = $this->object->get_billing_email();
        $this->send( $this->get_recipient(), $this->get_subject(), $this->get_content(), $this->get_headers(), $this->get_attachments() );
    }

    public function get_content_html() {
        return wc_get_template_html( $this->template_html, array(
            'order'         => $this->object,
            'email_heading' => $this->get_heading(),
            'email'         => $this,
        ), '', $this->template_base );
    }
}

Register the Custom Email Class

Register your new class with WooCommerce using the woocommerce_email_classes filter. Drop this in your child theme’s functions.php:

add_filter( 'woocommerce_email_classes', 'aiordienow_register_custom_email' );

function aiordienow_register_custom_email( $email_classes ) {
    require_once get_stylesheet_directory() . '/includes/class-aiordienow-custom-email.php';
    $email_classes['AiorDieNow_Custom_Email'] = new AiorDieNow_Custom_Email();
    return $email_classes;
}

Now create the corresponding custom WooCommerce email template PHP file at woocommerce/emails/aiordienow-custom-email.php inside your child theme. That file is your canvas — full HTML, full PHP, full control. Trigger the email anywhere with WC()->mailer()->emails['AiorDieNow_Custom_Email']->trigger( $order_id ).

Custom WooCommerce Email Template for Specific Order Statuses

WooCommerce fires email triggers on order status transitions. The hook pattern is woocommerce_order_status_{old}_to_{new}. You can hook your custom email class trigger into any status transition without touching WooCommerce core.

For example, to fire your custom email when an order moves from processing to a custom battle-ready status:

add_action( 'woocommerce_order_status_processing_to_battle-ready', 'aiordienow_trigger_custom_email', 10, 2 );

function aiordienow_trigger_custom_email( $order_id, $order ) {
    WC()->mailer()->emails['AiorDieNow_Custom_Email']->trigger( $order_id );
}

If you need to override the existing completed order email with a custom WooCommerce email template that looks totally different from the default, copy customer-completed-order.php to your child theme and go to town. That file controls the HTML email your customer receives when you mark an order complete — it’s high-visibility and worth the effort. Pair this with a solid customized checkout for a fully branded customer journey.

Transactional emails are the most-read emails your store sends. If your brand stops at the checkout page, you’re leaving trust on the table.— AI Or Die Now

Test Your Custom WooCommerce Email Templates

Never assume a custom WooCommerce email template renders correctly without testing it. Email clients are a disaster zone — Outlook uses a Word-based rendering engine, Gmail clips long emails, Apple Mail handles dark mode differently. Test across all of them.

Use WooCommerce’s built-in email preview inside WooCommerce > Settings > Emails for a quick sanity check. For real testing, use a tool like Litmus or Email on Acid to preview across clients. For deliverability testing, set up proper SMTP — we’ve covered WordPress SMTP setup in full detail.

Enable WordPress debug logging to catch PHP errors in your templates before they reach customers. See our guide on how to debug WordPress for the full process. A broken custom WooCommerce email template that throws a fatal error on order completion is a critical failure — not an aesthetic inconvenience.

Send Test Emails During Development

The WooCommerce email settings panel has a “Send test email” link next to each email type. Use it every time you make a change to your custom WooCommerce email template. It fires a real email to your admin address with real template rendering — not a mock preview.

Also test the plain text version explicitly. Check your email deliverability setup before launch if you want those order emails to actually land in inboxes. A beautifully crafted custom WooCommerce email template that lands in spam is worse than the default.

Custom WooCommerce Email Template Best Practices

Keep your custom WooCommerce email template files inside a child theme — always. Parent theme edits get nuked on update. Never edit files in the WooCommerce plugin directory itself. That’s core modification and it’s a time bomb.

Use the woocommerce_locate_template filter if you need to load templates from a non-standard location — like a custom plugin. This gives your custom WooCommerce email template a clean override path without breaking the normal hierarchy. For a deeper understanding of how hooks power all of this, see our WordPress Hooks Explained guide.

Keep transactional email templates focused. Every custom WooCommerce email template should serve a single clear purpose — confirm an order, announce shipping, notify a refund. Don’t stuff marketing content into transactional emails. It kills trust and may violate CAN-SPAM rules. Well-branded, clean order emails reduce customer support tickets by up to 30% — keep them clear and they pay for themselves.

If typography is part of your brand, use web-safe fonts in email or reference system fonts explicitly. Custom web fonts in email are unreliable across clients. Check out Typography Pro if you want a system for font consistency that works across your whole store, not just email.

Custom WooCommerce Email Template FAQ

Conclusion

A custom WooCommerce email template is not a luxury — it’s the difference between a store that looks professional and one that looks like it’s running someone else’s software. The tools are already in WooCommerce. The override system, the hooks, the email class architecture — all of it is sitting there waiting for you to use it.

Start with the template override in your child theme. Add hooks for dynamic content. Build a custom email class when you need something entirely new. Test everything before it hits a real customer inbox. Your custom WooCommerce email template stack should be as tight and intentional as the rest of your store — code you own, behavior you control, zero subscriptions required.

You built the store. Own the emails too.