WooCommerce Email Placeholders Reference

Which order status change triggers which WooCommerce email, every placeholder each one supports, and a checklist for a missing email.

Describe the result you need. AI will set up the tool and ask for any missing details.

Configure with AI

Enter to submit · Shift + Enter for a new line

Sent to AI. Leave out passwords and private customer data.

Find an email

11 default emails

New order

Admin

Sent 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

Admin

Sent on: processing → cancelled · on-hold → cancelled · pending → cancelled

{site_title}{site_address}{site_url}{store_email}{order_number}

Failed order

Admin

Sent on: pending → failed · on-hold → failed

{site_title}{site_address}{site_url}{store_email}{order_number}

Processing order

Customer

Sent on: cancelled → processing · failed → processing · on-hold → processing · pending → processing

{site_title}{site_address}{site_url}{store_email}

Order on-hold

Customer

Sent on: pending → on-hold · failed → on-hold · cancelled → on-hold

{site_title}{site_address}{site_url}{store_email}

Completed order

Customer

Sent on: any status → completed

{site_title}{site_address}{site_url}{store_email}

Refunded order

Customer

Sent 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

Customer

Sent on: a note marked “Note to customer” is added to the order

{site_title}{site_address}{site_url}{store_email}

Order details (invoice)

Customer

Sent 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

Customer

Sent on: an account is created at checkout or registration

{site_title}{site_address}{site_url}{store_email}

Reset password

Customer

Sent 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.

Want this builtinto your store?

I'm Emmanuel, a Shopify and WooCommerce developer. If this tool pointed at something you'd rather have fixed for you (a faster store, cleaner product data, a migration, a custom feature), send me a note.

Emmanuel Asika

Emmanuel Asika

Shopify & WooCommerce developer, Dublin

I build and fix online stores: new builds, migrations, speed, SEO and the custom bits apps can't do.

hello@emmanuelasika.com