How can I change the emails that get sent when an order is placed?

Email configuration

To manage the configuration of the email (including the email addresses to use and their template), you use the status workflow system.

With the default status workflow that is created during the Commerce installation, you'll find pre-configured emails in the " Payment Received" status change. Navigate to Extras > Commerce > Configuration > Statuses, and click on "Payment Received" in the middle column. It should have the bold text "Used on payment received" below the name.

In the status workflow, you configure the email status change actions to control what emails are sent. By default there are 2 emails pre-configured, one for the customer and one for the merchant. The following can be configured on each action:

  • the email subject
  • the recipient email address - if left empty the email is sent to the customer. For the order notification to merchant, this is set to the emailsender when Commerce is first installed. 
  • the from and reply-to email addresses. If empty, this falls back to commerce.email_from, commerce.email_reply_to, and finally the emailsender system setting.
  • the email content; this usually is a twig template.

These two emails are pre-configured with Commerce and can be changed to fit you rneeds:

  • Confirmation Email to Customer. This email is configured to go to the customer (recipient is empty means it goes to the customer) and uses the template emails/order-received.twig.
  • Order Notification for Merchant. This email is configured to go to the email address that was set in the emailsender system setting when Commerce was installed, and uses the emails/order-to-merchant.twig template.

You can add email status actions to any part of your status workflow. There is for example an emails/shipping-confirmation.twig template included in Commerce that can be used as part of an "Order Shipped" status change.

The from name uses the site_name system setting to be your shop's name.

Add header image and footer text

You can easily add a header image to all outgoing emails by setting the commerce.email_header_url to a fully qualified URL of the image to use for the header or logo. This should be a full URL, including your site url. The default template (emails/wrapper.twig) assumes the image to be 500x120px.

The text in the commerce.email_footer_text system setting will be added to the footer of all outgoing emails and would typically need to include information about your registered address or terms and conditions. This setting can include HTML. If not set it will show the site name instead.


If you're happy with the basic configuration, you can change the text used in lexicons. By default Commerce is translated into many languages, so you should hopefully find the emails are already translated, but if you want to change the text you can do so from the MODX manager.

  1. Go to System > Lexicons in MODX.
  2. Choose "commerce" for the namespace and leave the topic set to "default". Choose the language if you want to change it for a language other than English.
  3. Enter "email" in the search field on the right of the toolbar. This will give you most (if not all) email-related lexicons used by Commerce. Look at the name; if it includes order_rcvd it is part of the email to the customer, and order_rcvdmerch is for the email notification to the merchant.
  4. Once you've found the text you want to change, double click its value to edit it.

Changes made to lexicons in this way are persisted across updates.


The templates for emails are emails/order-received.twig (for the customer) and emails/order-to-merchant.twig (for the merchant). Learn more about templating in Commerce here.

Still need help? Send us an email Send us an email