WooCommerce Email Placeholders Reference
Which order status change triggers which WooCommerce email, every placeholder each one supports, and a checklist for a missing email.
Find an email
11 default emails
New order
AdminSent on: pending → processing · pending → completed · pending → on-hold · failed → processing · failed → completed · failed → on-hold · cancelled → processing · cancelled → completed · cancelled → on-hold
{site_title}{site_address}{site_url}{store_email}
Cancelled order
AdminSent on: processing → cancelled · on-hold → cancelled · pending → cancelled
{site_title}{site_address}{site_url}{store_email}{order_number}
Failed order
AdminSent on: pending → failed · on-hold → failed
{site_title}{site_address}{site_url}{store_email}{order_number}
Processing order
CustomerSent on: cancelled → processing · failed → processing · on-hold → processing · pending → processing
{site_title}{site_address}{site_url}{store_email}
Order on-hold
CustomerSent on: pending → on-hold · failed → on-hold · cancelled → on-hold
{site_title}{site_address}{site_url}{store_email}
Completed order
CustomerSent on: any status → completed
{site_title}{site_address}{site_url}{store_email}
Refunded order
CustomerSent on: a full refund is recorded on the order · a partial refund is recorded on the order
Subject wording differs for a full vs. partial refund.
{site_title}{site_address}{site_url}{store_email}{order_number}
Customer note
CustomerSent on: a note marked “Note to customer” is added to the order
{site_title}{site_address}{site_url}{store_email}
Order details (invoice)
CustomerSent on: sent manually from the order screen, or by a “Resend order” action
{site_title}{site_address}{site_url}{store_email}{order_number}
New account
CustomerSent on: an account is created at checkout or registration
{site_title}{site_address}{site_url}{store_email}
Reset password
CustomerSent on: the customer requests a password reset
{site_title}{site_address}{site_url}{store_email}
Why didn't it send: a checklist
- WooCommerce → Settings → Emails → that email is toggled “Enable this email notification”.
- The order actually made the exact status transition that email listens for, not just any change that ends on that status.
- The recipient is correct: admin emails go to that email's Recipient(s) field, customer emails go to the order's billing email.
- The status change went through $order->set_status() / update_status(), not a direct database or import change that skips WooCommerce's hooks.
- Your host or SMTP setup is actually delivering mail; check spam, and consider an SMTP plugin if WooCommerce shows the email as sent but it never arrives.
How WooCommerce decides which email to send
Each default email listens for specific order status transitions, not just "order is now X". For example, the customer "Processing order" email fires on the transitions on-hold→processing, pending→processing, failed→processing and cancelled→processing, using hooks named like woocommerce_order_status_{from}_to_{to}_notification. That's why an order created directly as "processing" by a gateway (with no "from" status) can behave differently from one that moves there manually.
Placeholders like {site_title}, {site_address}, {site_url} and {store_email} work in every email's subject, heading and footer text field. A few emails add their own, most commonly {order_number}, in their own default subject line, listed in the table below.
Checklist: why didn't an email send
- Check WooCommerce → Settings → Emails → the specific email is toggled "Enable this email notification".
- Check the exact status transition. Some emails only fire on specific "from → to" transitions, not on every order that reaches that status (see the table below).
- Check your recipient. Admin emails go to the address in that email's Recipient(s) field (defaults to the site's admin email); customer emails go to the order's billing email.
- Check whether the change happened programmatically. A plugin or import that changes
post_status/order status directly in the database (instead of calling$order->set_status()/$order->update_status()) skips WooCommerce's transition hooks entirely, so no email fires. - Check your host's outgoing mail. WordPress's default mail() function is blocked or filtered by many hosts; an SMTP plugin (WP Mail SMTP, FluentSMTP) with a real provider is the most common fix for emails that WooCommerce tried to send but never arrived.
- Check spam and any "gray listing" delay on the receiving side, especially for the customer's own address.
Questions people ask
Why did the customer get "Order on hold" but not "Processing order" later?
If the order moved on-hold → processing (a common path when a manual payment method, like bank transfer, gets confirmed), the processing email should fire. If it moved on-hold → completed directly (skipped processing), only the completed email fires, since there's no on-hold→processing transition to trigger it.
What does {order_number} actually show?
Whatever get_order_number() returns, which is the order ID by default, or your own custom prefix/format if you've applied the woocommerce_order_number filter.
Can I add my own placeholder to an email?
Not through settings alone. You'd filter that specific email's woocommerce_email_format_string output, or hook the relevant woocommerce_email_before_order_table type action to inject your own content into the template.
Does the New order email fire for every order?
It fires on several transitions into processing, completed or on-hold (from pending, failed or cancelled), but not on every possible path. A manually created admin order, for instance, doesn't go through a status transition and won't trigger it.
Why does the refunded order email say "partially refunded" when I refunded everything?
WooCommerce only sends the full-refund subject line when the refunded amount exactly matches the order total at the time of refund; a manual adjustment or a refund that doesn't add up to the full total is treated as partial.
Related tools
Last reviewed 30 September 2026.
Sources: WooCommerce source: default email classes · WooCommerce source: class-wc-email.php · WooCommerce source: class-wc-order.php
